From 97646f3229f519642ed699e6234676f831e0ac55 Mon Sep 17 00:00:00 2001 From: UGA Innovation Factory Date: Wed, 7 Jan 2026 18:12:39 -0500 Subject: [PATCH] docs: update documentation for refactored structure - Update NAMESPACE.md: filesystem.device and swapSize defaults now null - Update README.md: add 'Using Athenix as a Library' section with lib.mkFleet - Update copilot-instructions.md: reflect new directory structure and defaults - Update EXTERNAL_MODULES.md: correct paths from variants/ and glue/ to hw/ and fleet/ - Update PROXMOX_LXC.md: update hardware type path reference --- .github/copilot-instructions.md | 24 +++++++++++++++++----- README.md | 35 ++++++++++++++++++++++++++++++--- docs/EXTERNAL_MODULES.md | 4 ++-- docs/NAMESPACE.md | 8 ++++---- installer/PROXMOX_LXC.md | 2 +- 5 files changed, 58 insertions(+), 15 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index ddf2e70..539528f 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -26,8 +26,8 @@ This is a **NixOS system configuration repository** that uses: - **`flake.nix`**: Entry point - inputs and outputs only - **`inventory.nix`**: Fleet definitions - host configurations - **`users.nix`**: User account definitions -- **`variants/`**: Hardware type modules (desktop, laptop, surface, lxc, wsl, etc.) -- **`glue/`**: Fleet generation logic and common system configuration +- **`hw/`**: Hardware type modules (desktop, laptop, surface, lxc, wsl, etc.) +- **`fleet/`**: Fleet generation logic and common system configuration - **`sw/`**: Software configurations by system type - **`installer/`**: Build artifact generation (ISO, LXC, etc.) - **`templates/`**: Templates for external configurations @@ -45,9 +45,12 @@ All Innovation Factory-specific options MUST use the `athenix` namespace: ### Host Options (`athenix.host.*`) ```nix athenix.host = { - filesystem.device = "/dev/sda"; # Boot disk - filesystem.swapSize = "32G"; # Swap size - buildMethods = [ "iso" ]; # Artifact types + filesystem.device = "/dev/nvme0n1"; # Boot disk (default: null) + filesystem.swapSize = "32G"; # Swap size (default: null) + buildMethods = [ "installer-iso" ]; # Artifact types (defined in sw/gc.nix) + useHostPrefix = true; # Hostname prefix behavior + wsl.user = "username"; # WSL default user +}; useHostPrefix = true; # Hostname prefix behavior wsl.user = "username"; # WSL default user }; @@ -114,6 +117,17 @@ athenix.forUser = "username"; # Convenience: enable user + set WSL us 3. System modules: Provide `default.nix` that accepts `{ inputs, ... }` 4. Reference in `inventory.nix` or `users.nix` using `builtins.fetchGit` +#### Using Athenix as a Library +External flakes can use Athenix's fleet generator: +```nix +outputs = { athenix, ... }: { + nixosConfigurations = athenix.lib.mkFleet { + fleet = import ./custom-inventory.nix; + hwTypes = import ./custom-hardware.nix; + }; +}; +``` + ## Important Constraints ### What NOT to Do diff --git a/README.md b/README.md index 8e2d0e7..822848a 100644 --- a/README.md +++ b/README.md @@ -54,7 +54,7 @@ users.nix # User account definitions flake.lock # Locked dependency versions -variants/ # Hardware type modules (exportable as nixosModules) +hw/ # Hardware type modules (exportable as nixosModules) ├── default.nix # Auto-exports all variant types ├── nix-desktop.nix # Desktop workstations ├── nix-laptop.nix # Laptop systems @@ -64,8 +64,8 @@ variants/ # Hardware type modules (exportable as nixosModules) ├── nix-zima.nix # ZimaBoard systems └── nix-ephemeral.nix # Diskless/netboot systems -glue/ # Fleet generation and common configuration -├── fleet.nix # Processes inventory.nix to generate all hosts +fleet/ # Fleet generation and common configuration +├── default.nix # Processes inventory.nix to generate all hosts ├── common.nix # Common NixOS configuration (all hosts) ├── boot.nix # Boot and filesystem configuration └── user-config.nix # User account and home-manager integration @@ -233,6 +233,35 @@ nix flake show **See [docs/BUILDING.md](docs/BUILDING.md) for complete guide.** +### Using Athenix as a Library + +Import Athenix in your own flake to use its fleet generation logic with custom inventory: + +```nix +{ + inputs.athenix.url = "git+https://git.factory.uga.edu/UGA-Innovation-Factory/athenix.git"; + + outputs = { self, athenix, ... }: { + # Generate configurations with custom fleet and hardware types + nixosConfigurations = athenix.lib.mkFleet { + fleet = import ./my-inventory.nix; + hwTypes = import ./my-hardware-types.nix; + }; + + # Or use individual modules + nixosConfigurations.myhost = nixpkgs.lib.nixosSystem { + modules = [ + athenix.nixosModules.hw.nix-desktop # Use Athenix hardware configs + athenix.nixosModules.sw # Use Athenix software configs + ./configuration.nix + ]; + }; + }; +} +``` + +**Exported modules:** `nix-desktop`, `nix-laptop`, `nix-surface`, `nix-lxc`, `nix-wsl`, `nix-ephemeral`, `nix-zima`, `sw`, `common` + ## System Types Set via `athenix.sw.type`: diff --git a/docs/EXTERNAL_MODULES.md b/docs/EXTERNAL_MODULES.md index a94dfef..4ba7299 100644 --- a/docs/EXTERNAL_MODULES.md +++ b/docs/EXTERNAL_MODULES.md @@ -115,8 +115,8 @@ server-config/ When a host is built, modules load in this order: -1. Hardware type module (from `variants/nix-*.nix`) -2. Common system configuration (from `glue/common.nix`) +1. Hardware type module (from `hw/nix-*.nix`) +2. Common system configuration (from `fleet/common.nix`) 3. Software type module (from `sw/{type}/`) 4. User NixOS modules (from `users.nix` - `nixos.nix` files) 5. Device-specific overrides (from `inventory.nix`) diff --git a/docs/NAMESPACE.md b/docs/NAMESPACE.md index 118688b..6c55c7d 100644 --- a/docs/NAMESPACE.md +++ b/docs/NAMESPACE.md @@ -17,9 +17,9 @@ Hardware and boot-related settings. Boot disk device path. -**Type:** String +**Type:** String or null -**Default:** `"/dev/sda"` +**Default:** `null` (must be set by hardware type or per-host) **Example:** ```nix @@ -30,9 +30,9 @@ athenix.host.filesystem.device = "/dev/nvme0n1"; Swap partition size. -**Type:** String (size with unit, e.g., `"32G"`, `"2G"`) +**Type:** String (size with unit, e.g., `"32G"`, `"2G"`) or null -**Default:** `"32G"` +**Default:** `null` (must be set by hardware type or per-host) **Example:** ```nix diff --git a/installer/PROXMOX_LXC.md b/installer/PROXMOX_LXC.md index 057e3c9..64d25ef 100644 --- a/installer/PROXMOX_LXC.md +++ b/installer/PROXMOX_LXC.md @@ -46,7 +46,7 @@ Add the host to `inventory.nix` with the `nix-lxc` type or ensure it has the app } ``` -Your host type configuration (`variants/nix-lxc.nix`) should include: +Your host type configuration (`hw/nix-lxc.nix`) should include: ```nix {