5.1.1 emacs.nix ¶

The core build expression. It selects a base package per variant — emacs-overlay’s emacs-git/emacs-unstable/emacs-igc for the git-based variants (unstable is the default), nixpkgs’ default emacs attribute for mainline (the cache-parity canary) — and calls .override { ... } with the supported build flags exposed as file-level arguments. The build matrix is four shipped builds on {x86_64, aarch64} × {Linux, Darwin}: pgtk/Wayland GUI or terminal-only on Linux, patched NS GUI or terminal-only on Darwin; emacs.nix asserts every other GUI configuration away. pgtk honors each backend’s advertised scale (Wayland fractional scale) so a fixed point size tracks the system. When withPgtk = true (the Linux GUI default) the base selection picks the prebuilt *-pgtk sibling (emacs-unstable-pgtk etc.) directly instead of overriding withPgtk on the non-pgtk base, because the two build identical content under different derivation names and the sibling is the one the cache holds. The nix-community/emacs-overlay that supplies the git-based variants is a flake input composed into every overlay consumer in flake.nix; emacs.nix and overlay.nix re-apply it from flake.lock when imported standalone.

Supported:

• Source variants: unstable (emacs-unstable, the Emacs 31.1 release branch; the default), git (emacs-overlay’s emacs-git, current master), igc (emacs-igc, the feature/igc3 Memory Pool System incremental GC branch), mainline (nixpkgs’ default emacs attribute; parity canary, not a flake output).
• GUIs: pgtk (pure GTK / Wayland; the only Linux GUI), NS (Cocoa/NeXTstep; the only macOS GUI, patched by default), or no GUI at all (noGui = true).
• Compilation: native compilation (libgccjit AOT, default when the build platform can execute the host), compressed install, C sources for find-function-C-source, srcRepo (run autoreconf on git-based sources), opt-in useCcache.
• Image formats: WebP (default), optionally ImageMagick.
• Libraries: tree-sitter, SQLite3, dbus, selinux, gpm, ALSA, ACL, mailutils, systemd, GLib networking. The overlay trims mailutils/gpm/selinux from the builds that are already off binary-cache parity (both terminal-only builds and the Darwin GUI); the Linux pgtk build keeps upstream defaults so it stays byte-identical to the cached emacs-unstable-pgtk.
• Darwin patches: system-appearance, round-undecorated-frame, and fix-ns-x-colors applied via overrideAttrs — on by default for the NS GUI, which makes every Darwin GUI build a from-source build. The 31/30 branch patch sets are fetched from nix-giant/nix-darwin-emacs; the master/32+ set (the git/igc variants) from d12frosted/homebrew-emacs-plus, since nix-giant dropped its unstable patch branch in 2026-08.

5.1.2 Cache-parity invariant ¶

emacs.nix is written so that every argument default matches the corresponding default in upstream nixpkgs’ make-emacs.nix (and the explicit args emacs-overlay passes to its prebuilt attrs). As long as that holds,

import ./emacs.nix {}                          # unstable (bare-file default)
import ./emacs.nix { variant = "mainline"; }   # nixpkgs' emacs, the parity canary
import ./emacs.nix { noGui = true; }           # any standard override

produces the exact store path of the matching base attr. On Linux withPgtk is on by default, so each GUI build maps to the prebuilt *-pgtk sibling (emacs-unstable-pgtk, emacs-git-pgtk, emacs-igc-pgtk, or nixpkgs’ emacs-pgtk for mainline); the terminal-only noGui builds map to their own matching attrs. So the nix-community.cachix.org (git/unstable/igc, including the shipped unstable default), Hydra (mainline), and project jylhis binary caches hit and nothing recompiles from source. Only custom rev pins and the Darwin patch flags diverge; those paths run through overrideAttrs and intentionally bust the cache.

Verify after any change to defaults:

nix-instantiate --eval --strict -E '
  let lock = builtins.fromJSON (builtins.readFile ./flake.lock);
      n  = lock.nodes.${lock.nodes.root.inputs.nixpkgs}.locked;
      ov = lock.nodes.${lock.nodes.root.inputs.emacs-overlay}.locked;
      nixpkgs = fetchTarball {
        url = "https://github.com/${n.owner}/${n.repo}/archive/${n.rev}.tar.gz";
        sha256 = n.narHash;
      };
      overlay = fetchTarball {
        url = "https://github.com/${ov.owner}/${ov.repo}/archive/${ov.rev}.tar.gz";
        sha256 = ov.narHash;
      };
      pkgs = import nixpkgs { overlays = [ (import overlay) (import ./overlay.nix) ]; };
  in {
    # On this x86_64-linux eval every GUI build maps to a *-pgtk sibling
    # (pgtk is the Linux GUI default in emacs.nix itself); non-pgtk Linux
    # GUIs are asserted away and cannot be evaluated.
    default       = pkgs.jotainEmacs.outPath == pkgs.emacs-unstable-pgtk.outPath;
    bare-default  = (import ./emacs.nix {}).outPath == pkgs.emacs-unstable-pgtk.outPath;
    mainline-pgtk = (import ./emacs.nix { variant = "mainline"; }).outPath == pkgs.emacs-pgtk.outPath;
    git-pgtk      = (import ./emacs.nix { variant = "git"; }).outPath == pkgs.emacs-git-pgtk.outPath;
    igc-pgtk      = (import ./emacs.nix { variant = "igc"; }).outPath == pkgs.emacs-igc-pgtk.outPath;
  }'

The override arg set is filtered through lib.intersectAttrs (lib.functionArgs basePackage.override), so only the flags the base make-emacs.nix actually defines are forwarded. This keeps the build evaluating when a downstream flake overrides nixpkgs with an older release (24.05+): arguments that newer make-emacs.nix versions added are dropped rather than throwing "called with unexpected argument". On the pinned unstable every argument is accepted, so the intersection is a no-op and cache parity is unaffected.

5.1.3 default.nix ¶

The non-flake entry point — a thin flake-compat wrapper, not a distribution layer. It reads the pinned flake-compat rev from flake.lock, evaluates flake.nix, and promotes the current system’s packages to the top level: plain nix-build builds the full distribution (jotainEmacsPackages), nix-build -A emacs the bare Emacs. Variant builds still target emacs.nix directly (e.g. nix-build emacs.nix --arg withPgtk true).

5.1.4 Tree-sitter grammars ¶

Grammar bundling lives in nix/mk-overlay.nix, not in default.nix: the distribution’s withPackages set includes epkgs.treesit-grammars.with-all-grammars (~275 grammars — a linkFarm over per-grammar derivations, so the full set costs closure size, never build time). Discovery is nixpkgs’ own site-start.el, which sets treesit-extra-load-path to the bundled grammar directory — early-init.el deliberately does no TREE_SITTER_DIR handling (see its comment), and init-prog.el propagates treesit-extra-load-path to async native-comp workers, which run without site files.

5.1.5 emacs-packages ¶

legacyPackages.<system>.emacs-packages (nix/emacs-package-set.nix) exposes every Emacs package the configuration bundles — the lisp/ use-package scan with :ensure aliases resolved, the Nix-provided extras (nix/nix-provided-packages.nix), and the full tree-sitter grammar set — each individually buildable:

nix build .#emacs-packages.magit
nix build .#emacs-packages.treesit-grammars

Keys are the use-package head names, so dired-async holds the async derivation its :ensure async resolves to, and ghostel is the Elisp-only rebuild from nix/extra-packages.nix. The set lives in legacyPackages so nix flake check never builds it; the eval-only emacs-packages-eval check verifies every declared name resolves to a derivation. The packages mirror packages.default (the GUI-base scope), not emacs-nox.