feat(modules): core option system and shared lib helpers
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
parent
87bfc4cc31
commit
3b21d570e0
3 changed files with 887 additions and 0 deletions
295
modules/README.md
Normal file
295
modules/README.md
Normal file
|
|
@ -0,0 +1,295 @@
|
|||
# Modules Directory
|
||||
|
||||
The `modules/` directory contains the modular NixOS configuration system that makes up Omnixient. Each module is responsible for a specific aspect of the system and can be enabled, disabled, or configured independently.
|
||||
|
||||
## Module Architecture
|
||||
|
||||
Each module follows the standard NixOS module structure:
|
||||
```nix
|
||||
{ config, lib, pkgs, ... }:
|
||||
with lib;
|
||||
{
|
||||
options = {
|
||||
# Configuration options for this module
|
||||
};
|
||||
|
||||
config = mkIf cfg.enable {
|
||||
# Module implementation
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
## Core System Modules
|
||||
|
||||
### `core.nix`
|
||||
**Purpose**: Base system settings and Omnixient-specific options
|
||||
**What it configures**:
|
||||
- Essential system services (NetworkManager, Bluetooth, Audio)
|
||||
- Graphics support (OpenGL/Vulkan)
|
||||
- Font management
|
||||
- Basic security settings
|
||||
- Omnixient module system foundations
|
||||
|
||||
**Key Features**:
|
||||
- Automatic hardware graphics detection
|
||||
- Unified font configuration across the system
|
||||
- Essential service enablement
|
||||
- Module option definitions
|
||||
|
||||
### `packages.nix`
|
||||
**Purpose**: The always-installed **base** package set + fonts
|
||||
**What it manages**:
|
||||
- Core utilities, file/network/archive tools, system monitoring
|
||||
- Text processing, version control, shells, Nix tooling
|
||||
- System + programming + icon fonts
|
||||
|
||||
> The optional category bundles (development, multimedia, productivity,
|
||||
> gaming) that used to live here have moved into **opt-in packs** under
|
||||
> [`modules/packs/`](packs/README.md) — see the
|
||||
> [**Opt-in packs**](#opt-in-packs) section below and
|
||||
> [`docs/packs.md`](../docs/packs.md). `packages.nix` now carries only the
|
||||
> base set everyone gets.
|
||||
|
||||
### `services.nix`
|
||||
**Purpose**: System service configuration and management
|
||||
**What it configures**:
|
||||
- Display manager (GDM)
|
||||
- Audio system (PipeWire)
|
||||
- Network services
|
||||
- Container services (Docker, Podman)
|
||||
- Development services (databases, etc.)
|
||||
|
||||
**Service Categories**:
|
||||
- Desktop services (compositor, display manager)
|
||||
- Audio/media services
|
||||
- Network and connectivity
|
||||
- Development and container services
|
||||
|
||||
### `users.nix`
|
||||
**Purpose**: User account management and configuration
|
||||
**What it manages**:
|
||||
- User account creation and settings
|
||||
- Shell configuration defaults
|
||||
- User group memberships
|
||||
- Home directory setup
|
||||
|
||||
**Features**:
|
||||
- Automatic user creation based on configuration
|
||||
- Shell preferences (zsh as default)
|
||||
- Group membership for hardware access
|
||||
- Integration with home-manager
|
||||
|
||||
## Security and System
|
||||
|
||||
### `security.nix`
|
||||
**Purpose**: Security settings and authentication methods
|
||||
**What it configures**:
|
||||
- Multi-factor authentication
|
||||
- Fingerprint support (fprintd)
|
||||
- FIDO2 security keys
|
||||
- System hardening options
|
||||
- Firewall configuration
|
||||
|
||||
**Authentication Methods**:
|
||||
- Password authentication
|
||||
- Fingerprint recognition
|
||||
- FIDO2/WebAuthn security keys
|
||||
- Two-factor authentication
|
||||
|
||||
### `boot.nix`
|
||||
**Purpose**: Boot system and kernel configuration
|
||||
**What it manages**:
|
||||
- Boot loader configuration (systemd-boot)
|
||||
- Kernel parameters and modules
|
||||
- Plymouth boot theme
|
||||
- Early boot optimizations
|
||||
|
||||
**Boot Features**:
|
||||
- Fast boot configuration
|
||||
- Kernel optimization
|
||||
- Boot splash screen
|
||||
- Hardware initialization
|
||||
|
||||
## User Interface
|
||||
|
||||
### `menus.nix`
|
||||
**Purpose**: Application menus and launchers
|
||||
**What it configures**:
|
||||
- Application launchers (rofi alternatives)
|
||||
- Desktop menu systems
|
||||
- Quick access interfaces
|
||||
- Search functionality
|
||||
|
||||
### `walker.nix`
|
||||
**Purpose**: Walker application launcher configuration
|
||||
**What it manages**:
|
||||
- Walker launcher settings
|
||||
- Search backends and plugins
|
||||
- Keybindings and interface
|
||||
- Theme integration
|
||||
|
||||
### `fastfetch.nix`
|
||||
**Purpose**: System information display tool
|
||||
**What it configures**:
|
||||
- System info formatting
|
||||
- Logo and branding display
|
||||
- Performance metrics
|
||||
- Terminal integration
|
||||
|
||||
## Development Environment
|
||||
|
||||
### `development.nix`
|
||||
**Purpose**: The richer dev module (shells, dev services, helper scripts)
|
||||
**What it provides**:
|
||||
- Multiple language support (Rust, Go, Python, Node.js, C/C++)
|
||||
- Language servers and tools
|
||||
- Development containers and databases
|
||||
|
||||
> Now **gated on `omni.packs.development.enable`** (not `features.coding`)
|
||||
> and part of the *development pack* — see
|
||||
> [**Opt-in packs**](#opt-in-packs). Imported by hosts via the pack, not by
|
||||
> the ISO.
|
||||
|
||||
**Language Support**:
|
||||
- Runtime environments
|
||||
- Package managers
|
||||
- Language-specific tools
|
||||
- IDE and editor integration
|
||||
|
||||
### `scripts.nix`
|
||||
**Purpose**: Omnixient utility script management
|
||||
**What it manages**:
|
||||
- System management scripts
|
||||
- Theme switching utilities
|
||||
- Development helper scripts
|
||||
- Unix philosophy tools
|
||||
|
||||
## Opt-in Packs
|
||||
|
||||
The `packs/` subdirectory implements the **core + opt-in goodies** model:
|
||||
bundles of (packages + services + config) toggled with
|
||||
`omni.packs.<name>.enable`, always imported but inert until enabled.
|
||||
Packs are exposed as reusable `flake.nixosModules.<pack>` outputs, and the
|
||||
`lnbits` / `aiolabs` / `bitcoin` packs are standalone-importable onto a
|
||||
non-Omnixient NixOS.
|
||||
|
||||
| Pack | Provides |
|
||||
|---|---|
|
||||
| `media` | players, image/video editing, screen capture, PDF |
|
||||
| `development` | editors, LSPs, compilers, build tools, container CLIs, `development.nix` |
|
||||
| `gaming` | Steam, Lutris, Wine, performance tools |
|
||||
| `office` | browsers, comms, office suites, notes, backup |
|
||||
| `containers` | Docker + Podman (unified) |
|
||||
| `lnbits` | the LNbits dev environment (`dev-env`) |
|
||||
| `aiolabs` | aiolabs projects/deploy/tmux, on top of `lnbits` |
|
||||
| `bitcoin` | a real bitcoind + lightning node via nix-bitcoin (opt-in import) |
|
||||
|
||||
Legacy `omni.preset` / `omni.features.*` still work — they drive packs
|
||||
via `packs/compat.nix`. Full guide:
|
||||
[`modules/packs/README.md`](packs/README.md) and
|
||||
[`docs/packs.md`](../docs/packs.md).
|
||||
|
||||
## Hardware Support
|
||||
|
||||
The `hardware/` subdirectory contains hardware-specific modules:
|
||||
|
||||
### `default.nix`
|
||||
**Purpose**: Hardware detection and automatic configuration
|
||||
**What it does**:
|
||||
- Detects available hardware
|
||||
- Enables appropriate drivers
|
||||
- Configures hardware-specific settings
|
||||
- Imports relevant hardware modules
|
||||
|
||||
### GPU Support
|
||||
- `amd.nix`: AMD GPU drivers and configuration
|
||||
- `intel.nix`: Intel integrated graphics
|
||||
- `nvidia.nix`: NVIDIA proprietary drivers
|
||||
|
||||
### Audio and Input
|
||||
- `audio.nix`: Audio system configuration
|
||||
- `touchpad.nix`: Laptop touchpad settings
|
||||
- `bluetooth.nix`: Bluetooth device support
|
||||
|
||||
## Theme System
|
||||
|
||||
The `themes/` subdirectory contains complete theme definitions:
|
||||
|
||||
Each theme module (e.g., `tokyo-night.nix`) configures:
|
||||
- Color palette definitions
|
||||
- Terminal color schemes
|
||||
- Editor themes (Neovim, VSCode)
|
||||
- Desktop component theming (Waybar, Hyprland)
|
||||
- GTK/Qt application themes
|
||||
|
||||
## Desktop Environment
|
||||
|
||||
The `desktop/` subdirectory contains desktop-specific configurations:
|
||||
|
||||
### `hyprland.nix`
|
||||
**Purpose**: Hyprland compositor configuration
|
||||
**Sub-modules**:
|
||||
- `bindings.nix`: Keyboard shortcuts and bindings
|
||||
- `autostart.nix`: Applications started with the desktop
|
||||
- `idle.nix`: Idle management and screen locking
|
||||
|
||||
## Utility Modules
|
||||
|
||||
### `lib.nix`
|
||||
**Purpose**: Shared library functions and utilities
|
||||
**What it provides**:
|
||||
- Helper functions used across modules
|
||||
- Common configuration patterns
|
||||
- Utility functions for theme and configuration management
|
||||
|
||||
### `colors.nix`
|
||||
**Purpose**: Color management and palette definitions
|
||||
**What it manages**:
|
||||
- Color space conversions
|
||||
- Palette generation utilities
|
||||
- Theme color validation
|
||||
|
||||
### `helpers.nix`
|
||||
**Purpose**: Additional helper functions
|
||||
**What it provides**:
|
||||
- File and directory utilities
|
||||
- Configuration templating functions
|
||||
- System integration helpers
|
||||
|
||||
## Module Dependencies
|
||||
|
||||
```
|
||||
core.nix (foundation)
|
||||
↓
|
||||
packages.nix + services.nix (system layer)
|
||||
↓
|
||||
security.nix + boot.nix (system hardening)
|
||||
↓
|
||||
themes/*.nix (visual layer)
|
||||
↓
|
||||
desktop/*.nix (user interface)
|
||||
↓
|
||||
development.nix (developer tools)
|
||||
```
|
||||
|
||||
## Adding New Modules
|
||||
|
||||
To add a new module:
|
||||
|
||||
1. Create the module file in the appropriate subdirectory
|
||||
2. Follow the standard NixOS module structure
|
||||
3. Define clear options with types and descriptions
|
||||
4. Import the module in `configuration.nix`
|
||||
5. Document the module's purpose and options
|
||||
6. Test the module in isolation and with others
|
||||
|
||||
## Module Best Practices
|
||||
|
||||
1. **Single Responsibility**: Each module handles one aspect
|
||||
2. **Clear Options**: Well-defined configuration interface
|
||||
3. **Documentation**: Comments and option descriptions
|
||||
4. **Dependencies**: Explicit module dependencies
|
||||
5. **Testing**: Verify module works in isolation
|
||||
6. **Performance**: Efficient evaluation and build times
|
||||
|
||||
This modular architecture makes Omnixient highly customizable while maintaining clean separation of concerns.
|
||||
Loading…
Add table
Add a link
Reference in a new issue