191 lines
5.5 KiB
Markdown
191 lines
5.5 KiB
Markdown
# Root Directory Files
|
|
|
|
This document explains the purpose of each file in the root directory of the OmniXY repository.
|
|
|
|
## Configuration Files
|
|
|
|
### `flake.nix`
|
|
**Purpose**: Main Nix flake definition
|
|
- Defines all external dependencies (inputs)
|
|
- Exports system configurations, packages, and development shells
|
|
- Contains the core logic for building OmniXY
|
|
- Manages reproducible builds through flake.lock
|
|
|
|
**Key Sections**:
|
|
- `inputs`: External dependencies (nixpkgs, home-manager, hyprland, etc.)
|
|
- `outputs`: NixOS configuration, packages, development shells, apps
|
|
- `nixosConfigurations.omnixy`: Main system configuration
|
|
- `devShells`: Language-specific development environments
|
|
- `packages`: Custom OmniXY utilities and tools
|
|
- `apps`: Executable applications (installer)
|
|
|
|
### `configuration.nix`
|
|
**Purpose**: Main NixOS system configuration entry point
|
|
- Imports all system modules
|
|
- Defines the current theme selection
|
|
- Sets system-wide options and services
|
|
- Configures hardware-specific settings
|
|
|
|
**What it does**:
|
|
- Enables essential system services
|
|
- Imports modular configurations from `modules/`
|
|
- Sets the active theme (controls entire system appearance)
|
|
- Defines system users and permissions
|
|
- Configures boot settings and hardware
|
|
|
|
### `home.nix`
|
|
**Purpose**: Home Manager configuration for user environment
|
|
- Manages user-specific packages and settings
|
|
- Configures dotfiles and application preferences
|
|
- Handles user services and desktop environment
|
|
- Integrates with the theme system
|
|
|
|
**What it manages**:
|
|
- User package installations
|
|
- Shell configuration (zsh, bash)
|
|
- Git configuration and tools
|
|
- Development environment settings
|
|
- Application configurations that run as user
|
|
|
|
### `flake.lock`
|
|
**Purpose**: Lock file for reproducible builds
|
|
- Pins exact versions of all dependencies
|
|
- Ensures identical builds across different machines
|
|
- Generated automatically by Nix
|
|
- Should be committed to version control
|
|
|
|
### `hardware-configuration.nix`
|
|
**Purpose**: Hardware-specific NixOS configuration
|
|
- Generated by `nixos-generate-config`
|
|
- Contains machine-specific settings
|
|
- Defines boot loader, filesystems, and kernel modules
|
|
- Should be customized per installation
|
|
|
|
**Generated content**:
|
|
- Filesystem mount points
|
|
- Boot loader configuration
|
|
- Hardware-specific kernel modules
|
|
- Network interface settings
|
|
|
|
## Installation Files
|
|
|
|
### `install.sh`
|
|
**Purpose**: Interactive, styled installer script
|
|
- Beautiful terminal UI with colors and animations
|
|
- Guides users through complete installation process
|
|
- Handles system verification, backup, and configuration
|
|
- Includes theme selection and feature configuration
|
|
|
|
**Features**:
|
|
- System requirements checking
|
|
- Automatic configuration backup
|
|
- User account setup
|
|
- Theme selection interface
|
|
- Feature toggles (fingerprint, gaming, etc.)
|
|
- System building with progress indication
|
|
|
|
### `install-simple.sh`
|
|
**Purpose**: Unix philosophy compliant installer
|
|
- Command-line arguments instead of interactive prompts
|
|
- Scriptable and automatable
|
|
- Clean, pipeable output
|
|
- Follows "do one thing well" principle
|
|
|
|
**Usage**:
|
|
```bash
|
|
./install-simple.sh --user alice --theme gruvbox --quiet
|
|
```
|
|
|
|
**Options**:
|
|
- `--user`: Set username
|
|
- `--theme`: Select theme
|
|
- `--quiet`: Minimal output
|
|
- `--dry-run`: Test without applying changes
|
|
|
|
### `boot.sh`
|
|
**Purpose**: Bootstrap script for fresh NixOS installations
|
|
- Downloads OmniXY from GitHub
|
|
- Minimal dependencies (just bash and basic tools)
|
|
- Runs the full installer automatically
|
|
- Can be executed via curl pipe
|
|
|
|
**What it does**:
|
|
1. Verifies NixOS installation
|
|
2. Installs git if needed
|
|
3. Clones the OmniXY repository
|
|
4. Executes the main installer
|
|
|
|
## Documentation Files
|
|
|
|
### `README.md`
|
|
**Purpose**: Main project documentation and introduction
|
|
- Project overview and features
|
|
- Installation instructions
|
|
- Usage examples and configuration
|
|
- Contributing guidelines and links
|
|
|
|
### `CLAUDE.md`
|
|
**Purpose**: Instructions for Claude Code AI assistant
|
|
- Development workflow documentation
|
|
- Command references and examples
|
|
- Architecture explanations
|
|
- Best practices and conventions
|
|
|
|
### `LICENSE`
|
|
**Purpose**: Legal license for the project
|
|
- Defines usage rights and restrictions
|
|
- Currently MIT License
|
|
- Applies to all code in the repository
|
|
|
|
## Asset Files
|
|
|
|
### `logo.svg` / `logo.txt`
|
|
**Purpose**: OmniXY project logos
|
|
- SVG vector logo for web/documentation
|
|
- ASCII art logo for terminal display
|
|
- Used in installers and documentation
|
|
|
|
### `icon.png` / `icon.txt`
|
|
**Purpose**: Project icons
|
|
- PNG icon for applications and desktop
|
|
- ASCII icon for terminal contexts
|
|
|
|
## Development Files
|
|
|
|
### `*.qcow2` files (if present)
|
|
**Purpose**: Virtual machine disk images
|
|
- Pre-built OmniXY system images for testing
|
|
- Used for development and demonstration
|
|
- Can be run with QEMU/KVM
|
|
|
|
## File Organization Principles
|
|
|
|
1. **Configuration First**: Core system files at root level
|
|
2. **Clear Naming**: Descriptive filenames indicate purpose
|
|
3. **Separation of Concerns**: Different aspects in separate files
|
|
4. **Documentation**: Every major file documented
|
|
5. **Reproducibility**: All build inputs tracked and versioned
|
|
|
|
## Relationship Between Files
|
|
|
|
```
|
|
flake.nix
|
|
↓ (imports)
|
|
configuration.nix
|
|
↓ (imports)
|
|
modules/*.nix
|
|
↓ (configures)
|
|
System Services & Packages
|
|
|
|
home.nix
|
|
↓ (configures)
|
|
User Environment & Dotfiles
|
|
|
|
install.sh / install-simple.sh
|
|
↓ (copies and configures)
|
|
All Configuration Files
|
|
↓ (builds)
|
|
Complete OmniXY System
|
|
```
|
|
|
|
This structure provides a clear separation between system configuration, user environment, installation tooling, and documentation, making the project maintainable and understandable. |