Options Reference

Which user the distribution configures. Read by modules/base.nix and modules/ewm.nix to address home-manager.users.<name>.

Do not set it by hand. Pass username to mkHost; it sets this from the same argument, so the option and the composed system cannot disagree.

What shape of box this is. It selects nothing. No module is imported because of it and no behaviour in the distribution branches on it. It is metadata: set by mkHost from its role argument, exported to the shell as EMANIX_ROLE, and interpreted by the consuming flake, which may well gate real things on it.

Like username, this is an argument rather than an opinion — so it is set plainly, not with mkDefault. Overriding it to disagree with the value mkHost was called with produces an incoherent host.

This machine has a graphical session. Gates the cursor theme, the Wayland tools, GUI applications, the screen locker, and terminal config.

The graphics driver to force-load in the initrd, so a compositor started from tty1 does not lose the DRM-master race. null contributes nothing, which is correct for a headless or virtualised host.

Setting it asserts that hardware.enableRedistributableFirmware is true — forcing a driver into the initrd without its firmware blobs is a black screen, and boot.initrd.allowMissingModules hides that at build time. See Architecture for why a distribution ships the capability and not the fact.

This machine's Emacs is the system-owned EWM build. When false, the home layer installs the non-EWM pgtk Emacs (31.1) instead and runs the daemon as a systemd user service.

This is the single switch between "Emacs is my desktop" and "Emacs is an editor with a daemon". Enabling it also means importing nixosModules.ewm from the flake — the option gates the home side; the module supplies the compositor service. See Components.

Active theme. An enum, not a string: the value is a lookup key for the theme plan, and the consumers of that plan degrade silently on a name that matches nothing, so a typo used to build cleanly and surface later as a theme that quietly did not apply. Now it is an eval error naming the valid set. See Theming.

Emacs packages the consuming flake adds to the distribution's Emacs build: home-manager.users.<user>.emanix.emacs.extraPackages = epkgs: [ epkgs.s ];. It takes the package set rather than a plain list, so the consumer never names the Emacs variant — which base a host runs (pwayl/Skia 31.1 under EWM, pgtk 31.1 otherwise) is the distribution's choice.

A package the distribution does not ship is added the same way: epkgs: [ epkgs.weblorg ], for example.

The Emacs derivation this host's Emacs packages are built from. Do not set it in a host config. It is set by whichever module owns the host's Emacs: nixosModules.ewm (the pwayl/Skia build) on EWM hosts, and the home layer's daemon module (pgtk) everywhere else. A consumer reads it when it has to build an Emacs package itself, so that package is byte-compiled by the same Emacs that loads it. There is deliberately no default: a default would be a variant decision nobody made, and a host that sets neither fails to evaluate rather than quietly building the wrong Emacs.

Symlinks the Lisp out of the Nix store, straight from the Emanix checkout, so edits take effect on restart with no rebuild.

Set false on a host with no checkout; the Lisp is then copied into the store and editing it requires a rebuild.

This is a deliberate seam, one of two in the distribution — the other is emanix.emacs.extraPackages: it trades generation-pinning for edit latency on the files that get edited most. The content is still version-controlled — it is simply not content-hashed into the system generation, so a rollback does not roll the Lisp back with it.

It also means moving or renaming the checkout breaks Emacs until the next rebuild, because the symlink target vanishes. Move and rebuild as one step.

Install and configure the GPU-accelerated terminal. Defaults to the GUI flag, which is why it appears automatically on a graphical host — but it is a separate option so a headless-but-terminal host can opt in surgically. A WSL host under WSLg is the usual case: no compositor, but a real terminal is still wanted.

The body of the emanix-firstboot script, as shell. It is built with writeShellApplication, so it is shellchecked at build time and runs with errexit, nounset and pipefail: a broken script fails your build, not the first boot — the one moment nobody is watching a screen they can debug from.

The default stub prints a heading, then No first-boot steps are configured., then Set emanix.firstboot.text in your consuming flake. A distribution cannot know what your first boot needs — a network to join, a configuration repository to clone, secrets to place — and a guessed script is wrong for everyone but its author.

emanix.firstboot = {
  runtimeInputs = [ pkgs.git ];
  text = ''
    git --version
    printf 'first boot done\n'
  '';
};

The packages whose bin/ directories are put at the front of the script's PATH, ahead of the PATH it inherits. The default is empty on purpose: an earlier version listed three tools while the script used one, which is the kind of drift an unused input never announces. List what text calls, and nothing else.

• You run emanix-firstboot yourself, once, after the first boot. Nothing runs it for you.
• A host the installer generated in interactive mode sets neither option, so the command exists and prints the stub message. See Installation: it is for a fleet, not for a machine the installer just invented.
• The installer ISO does not carry it. It runs on the installed system, where your text acts on the machine you built.