How nixos/nix works
Purpose and entry points
Nix is a C++ package manager implementing the Nix language, dependency evaluation, reproducible builds, and content-addressed store management. The primary executable is the modern nix CLI, rooted at src/nix/main.cc and composed from command implementations in src/nix/. Legacy compatibility executables (nix-build, nix-store, nix-env, etc.) remain separate entry points under src/nix/nix-build/nix-build.cc, src/nix/nix-store/nix-store.cc, and related directories.
Command and runtime layer
libmain provides shared process initialization, logging, progress, common options, and plugin loading; libcmd supplies command registration, installable resolution, REPL integration, store flags, and CLI evaluation arguments.
• src/libmain/shared.cc
• src/libcmd/command.cc
• src/nix/build.cc
Commands convert user arguments, installable/flake references, and configuration into evaluator or store operations. The CLI boundary is also where structured output, progress reporting, and daemon-aware store selection are applied.
Nix language evaluation
libexpr implements the Nix lexer/parser, lazy value model, evaluator, primops, derivation extraction, and evaluation cache. Nix expressions evaluate to values that may describe derivations, paths, or flake outputs; derivation-producing primitives bridge evaluation into the store model.
• src/libexpr/lexer.l
• src/libexpr/parser.y
• src/libexpr/eval.cc
• src/libexpr/primops.cc
The C API layer exposes evaluator functionality to external consumers without requiring direct C++ linkage: src/libexpr-c/nix_api_eval.cc.
Flakes and source acquisition
Flakes add reproducible input resolution and lockfile handling over the evaluator. libflake parses flake references, reads/writes lock files, evaluates flake outputs, and installs flake-specific primops. libfetchers obtains source trees and archives and can materialize them into a store.
• src/libflake/flake.cc
• src/libflake/lockfile.cc
• src/libfetchers/fetchers.cc
• src/libfetchers/fetch-to-store.cc
Fetcher backends cover local paths, Git/Git LFS, Mercurial, tarballs, and GitHub (src/libfetchers/git.cc, src/libfetchers/github.cc). These are network and filesystem trust boundaries.
Store model and persistence
libstore owns store paths, derivations, content addressing, references, realizations, garbage collection, import/export, and the abstract store API. Local-store metadata is backed by SQLite schemas, while store implementations can be local, overlay, HTTP cache, S3, SSH, or remote-daemon based.
• src/libstore/store-api.cc
• src/libstore/local-store.cc
• src/libstore/schema.sql
• src/libstore/derivation/resolution.cc
• src/libstore/s3-binary-cache-store.cc
Store protocols and serialized data are compatibility-critical boundaries: src/libstore/worker-protocol.cc, src/libstore/serve-protocol.cc, and documented JSON schemas under doc/manual/source/protocols/json/schema/.
Build, substitution, and daemon execution
The build worker schedules dependency goals, resolves derivations, tries substituters, and dispatches local or remote building. Platform-specific derivation builders enforce execution isolation; Linux uses chroot/namespaces-oriented machinery, with Darwin, FreeBSD, and Windows implementations separated.
• src/libstore/build/worker.cc
• src/libstore/build/derivation-goal.cc
• src/libstore/build/substitution-goal.cc
• src/libstore/linux/build/linux-derivation-builder.cc
• src/libstore/unix/build/chroot-derivation-builder.cc
The multi-user daemon serves store requests over Unix-domain sockets, with service definitions for systemd, launchd, System V, and Upstart. Relevant paths: src/libstore/daemon.cc, src/nix/unix/daemon.cc, misc/systemd/nix-daemon.service.in.
Build, distribution, and verification
Meson is the native C++ build graph root (meson.build); Nix expressions provide reproducible packaging, development shells, installers, release jobs, and CI integration (flake.nix, packaging/everything.nix, packaging/installer/install.in). The project targets Unix-like systems plus active platform-specific Windows support.
Validation spans library unit tests, protocol/schema checks, and end-to-end functional/NixOS scenarios, particularly around evaluation, daemon behavior, sandboxing, remote builds, fetchers, and binary caches. Core integration suites live in tests/functional/, while deployment-oriented tests live in tests/nixos/.
Main entry points: store-api.cc libstore API · eval.cc libexpr evaluator · build.cc Build command · worker.cc Build worker
Components 20
CLI & APIs
- nix CLI · Modern command-line entry point.
src/nix/main.cc - Legacy CLIs · Compatibility commands such as nix-build and nix-store.
src/nix/nix-build/nix-build.cc - libmain runtime · Initializes processes, logging, options, progress, and plugins.
src/libmain/shared.cc - libcmd · Registers commands and resolves installables.
src/libcmd/command.cc - Build command
src/nix/build.cc - C evaluator API · External evaluator interface.
src/libexpr-c/nix_api_eval.cc
Evaluation & flakes
- Lexer & parser
src/libexpr/parser.y - libexpr evaluator · Values, primops, derivation extraction, and evaluation cache.
src/libexpr/eval.cc - libflake · Resolves inputs and lockfiles, then evaluates flake outputs.
src/libflake/flake.cc - libfetchers · Fetches source trees and materializes them in the store.
src/libfetchers/fetch-to-store.cc
Store & execution
- libstore API · Content-addressed paths, derivations, references, and realizations.
src/libstore/store-api.cc - Local store · Persists local metadata in SQLite.
src/libstore/local-store.cc - Remote store backends · HTTP cache, S3, SSH, overlay, and daemon-backed stores.
src/libstore/s3-binary-cache-store.cc - Build worker · Schedules goals and dispatches builds or substitutions.
src/libstore/build/worker.cc - Substitution goals
src/libstore/build/substitution-goal.cc - Sandboxed builder · Linux build isolation uses chroot and namespace machinery.
src/libstore/linux/build/linux-derivation-builder.cc - Nix daemon · Serves store requests over Unix-domain sockets.
src/libstore/daemon.cc
Build & deployment
- Meson build graph
meson.build - Nix packaging & CI · Defines packages, development shells, installers, releases, and CI.
flake.nix - Daemon service unit
misc/systemd/nix-daemon.service.in
Connections 20
- nix CLI → libmain runtime: initializes with
- nix CLI → libcmd: dispatches
- Legacy CLIs → libstore API: uses
- libcmd → Build command: registers
- Build command → libexpr evaluator: evaluates inputs
- Build command → libstore API: requests builds
- C evaluator API → libexpr evaluator: exposes
- Lexer & parser → libexpr evaluator: parses expressions for
- libflake → libexpr evaluator: evaluates outputs with
- libflake → libfetchers: resolves inputs through
- libfetchers → libstore API: materializes sources in
- libexpr evaluator → libstore API: produces derivations for
- libstore API → Local store: implemented by
- libstore API → Remote store backends: implemented by
- libstore API → Build worker: executes builds via
- Build worker → Substitution goals: tries
- Build worker → Sandboxed builder: dispatches local builds to
- Nix daemon → libstore API: serves
- Daemon service unit → Nix daemon: launches
- Nix packaging & CI → Meson build graph: packages native build