94 lines
5.0 KiB
Markdown
94 lines
5.0 KiB
Markdown
# Project Guide — ZaneyOS
|
||
|
||
Scope
|
||
- A reproducible NixOS flake tailored for desktop systems with per-host overrides, GPU/VM profiles, and an integrated Home Manager layer (Hyprland, Waybar, shells, scripts).
|
||
- Repo location is expected at ~/zaneyos. If you place it elsewhere, update modules/core/nh.nix (programs.nh.flake) to the new path.
|
||
|
||
Quick commands
|
||
- Build and switch (preferred: nh/zcli)
|
||
- fr → nh os switch --hostname <profile> # alias provided by zsh/bash modules
|
||
- fu → nh os switch --hostname <profile> --update
|
||
- zcli rebuild
|
||
- zcli update
|
||
- Build for next boot (safer for larger changes)
|
||
- zcli rebuild-boot
|
||
- or: sudo nixos-rebuild boot --flake .#<profile>
|
||
- Direct NixOS (if you prefer without nh/zcli)
|
||
- sudo nixos-rebuild switch --flake .#<profile>
|
||
- Validate the flake
|
||
- nix flake check
|
||
- Format Nix files (nixfmt-rfc-style is included)
|
||
- find . -name "*.nix" -print0 | xargs -0 nixfmt
|
||
- Host management
|
||
- zcli update-host [hostname] [profile] # edits flake.nix host/profile
|
||
- zcli add-host <hostname> [profile] # copies hosts/default and guides hardware.nix
|
||
- Diagnostics and maintenance
|
||
- zcli diag # writes ~/diag.txt
|
||
- zcli cleanup # prunes older generations (prompts for retention)
|
||
|
||
zcli advanced options (for rebuild/update)
|
||
- --dry (-n) preview only
|
||
- --ask (-a) confirm before proceeding
|
||
- --cores N cap build CPU usage
|
||
- --verbose (-v) more logs
|
||
- --no-nom disable nix-output-monitor
|
||
|
||
Profiles and when to use them
|
||
- amd, intel, nvidia, nvidia-laptop (hybrid), vm
|
||
- Choose with the <profile> argument in nh/nixos-rebuild commands (e.g., .#vm)
|
||
|
||
High-level architecture
|
||
- flake.nix
|
||
- Inputs: nixpkgs 25.05, home-manager 25.05, stylix, nvf, nix-flatpak
|
||
- Local constants: system, host, profile, username
|
||
- nixosConfigurations: one per GPU/VM profile via mkNixosConfig
|
||
- Each configuration imports profiles/<profile>
|
||
- profiles/<profile>/default.nix
|
||
- Imports the active host and the system module stacks:
|
||
- ../../hosts/${host}
|
||
- ../../modules/drivers
|
||
- ../../modules/core
|
||
- Flips toggles: drivers.*.enable and vm.guest-services.enable
|
||
- Hybrid laptops: profiles/nvidia-laptop pulls intel/nvidia Bus IDs from the host’s variables.nix and wires nvidia-prime
|
||
- hosts/<hostname>/
|
||
- default.nix imports hardware.nix and host-packages.nix
|
||
- variables.nix is the control panel for UX + feature toggles:
|
||
- displayManager (greetd vs sddm)
|
||
- terminal/browser defaults (enable per-terminal via flags)
|
||
- waybarChoice, animChoice, stylixImage
|
||
- 24h clock, thunarEnable, printEnable, NFS
|
||
- intelID/nvidiaID for Prime offload
|
||
- modules/core
|
||
- default.nix composes focused NixOS modules: boot, flatpak, fonts, hardware, network, nfs, nh, packages, printing, display manager (conditional greetd/sddm), security, services (PipeWire, SSH, Bluetooth, fstrim; smartd conditional on profile), steam, stylix, syncthing, system (nix settings, locales, env vars), thunar, user (Home Manager), virtualisation, xserver
|
||
- user.nix integrates Home Manager and creates users.${username}; passes extraSpecialArgs { inputs, username, host, profile } to the home layer
|
||
- nh.nix enables nh, configures GC, and pins programs.nh.flake = /home/${username}/zaneyos
|
||
- modules/drivers
|
||
- Aggregates AMD, Intel, NVIDIA, NVIDIA Prime, and VM guest services
|
||
- nvidia-prime-drivers.nix exposes options.drivers.nvidia-prime.{enable,intelBusID,nvidiaBusID} consumed by the nvidia-laptop profile
|
||
- vm-guest-services.nix enables qemu-guest, spice agents when vm.guest-services.enable = true
|
||
- modules/home
|
||
- default.nix composes the user environment (Hyprland, Waybar via waybarChoice, Rofi, Yazi, Kitty/WezTerm/Ghostty/Alacritty toggles, Zsh/Bash config, Git, NVF/Neovim, OBS, swaync, scripts, Stylix, optional Doom Emacs/VSCodium/Helix)
|
||
- scripts/default.nix installs user-space tools including zcli; zcli wraps rebuild/update/boot builds, cleanup, diagnostics, host management, and Doom Emacs lifecycle
|
||
|
||
Where to change what
|
||
- flake.nix: set username, host, profile; add inputs; wire outputs
|
||
- hosts/<hostname>/{variables.nix,hardware.nix,host-packages.nix}: per-machine behavior, theming, and hardware
|
||
- modules/core/*: system-level settings, services, packages
|
||
- modules/home/*: user apps, shell, window manager, UI
|
||
|
||
Common workflows
|
||
- Small UX tweaks: edit hosts/<hostname>/variables.nix → fr
|
||
- Theme swap: edit stylixImage/waybarChoice in variables.nix → fr (or zcli rebuild-boot)
|
||
- GPU/VM switch: choose nixos-rebuild/nh profile (e.g., nh os switch --hostname vm) and optionally update host/profile constants with zcli update-host
|
||
|
||
Validation and troubleshooting
|
||
- nix flake check for a quick sanity test
|
||
- zcli diag to produce a detailed hardware/system report
|
||
- If the repo is not under ~/zaneyos, update modules/core/nh.nix so zcli/nh operate on the correct path
|
||
|
||
Documentation pointers
|
||
- README.md: requirements, first-time install methods, upgrade overview
|
||
- zcli.md: full CLI documentation, commands, options, and examples
|
||
- cheatsheets/: quick-reference guides for Hyprland, terminals, editors, etc.
|
||
|