nix.dev Documentation

A module in the Nix module system is a function that takes an attribute set and returns an attribute set. It serves two primary purposes:

1. Declaring options: Specifying which attributes are allowed in the final outcome.
2. Defining values: Setting values for options declared by itself or other modules.

When evaluated by the module system, it produces a final attribute set based on these declarations and definitions. The simplest module is a function that accepts any attributes and returns an empty set.

The following terms are fundamental to working with the Nix ecosystem:

• Nix: The build system and package manager.
• Nix language: The programming language used to declare packages and configurations for Nix.
• Nix expression: An expression written in the Nix language.
• Nix file: A file with a .nix extension containing a Nix expression.
• Nixpkgs: The software distribution built with Nix.
• NixOS: A Linux distribution based on Nix and Nixpkgs.

The Nix ecosystem documentation is organized into several interconnected components. When searching for information, distinguish between these domains:

• Nix: The package manager and build tool.
• The Nix language: The syntax and semantics used by Nix.
• nixpkgs: The collection of packages.
• lib: The standard library.
• NixOS: The operating system and its specific configuration options.

Documentation is split into two primary types:

1. Reference documentation: Technical details for users who know what they need (e.g., function signatures, option definitions, environment support).
2. Guides and tutorials: Problem-solving content for learning workflows (e.g., how to accomplish a specific goal using multiple technologies).

Derivations are the core of Nix. The Nix language describes them, and Nix runs them to produce build results.

• The primitive for declaring a derivation is the built-in impure function derivation.
• In practice, you will almost always use stdenv.mkDerivation, which is a wrapper that simplifies complex build procedures.
• When you encounter mkDerivation, it indicates that Nix will eventually build something.
• The evaluation result of a derivation is an attribute set that, when used in string interpolation, evaluates to the Nix store path of its build result.

let
  pkgs = import <nixpkgs> {};
in "${pkgs.nix}"

Nixpkgs stdenv.mkDerivation uses a series of phases to control the build process. During these phases, Nixpkgs executes shell functions known as hooks.

• Phases: Discrete stages of the build (e.g., buildPhase, installPhase).
• Hooks: Functions that run either before or after a phase (e.g., preInstall, postInstall).

Including these hooks in your custom phase definitions facilitates easier overriding of specific parts of the derivation and keeps the code compatible with the standard Nixpkgs environment.

Nix documentation is hosted in two distinct locations depending on the level of authority and stability required:

• docs.nixos.org: The authoritative, curated, and reviewed source of truth. It covers common, important, and stable workflows. Use this for official configuration and standard procedures.
• The Wiki: A community-driven, fast-moving incubator. It covers niche topics, experiments, early ideas, and rapidly evolving information. Use this for experimental features or highly specific community use cases.

Nixpkgs relies on specific architectural patterns that are essential for customization and development:

• Inputs Design Pattern: A single customizable repository with a top-level Nix expression, containing one expression for each package.
• callPackage Design Pattern: A pattern used extensively in Nixpkgs to write and use functions. It utilizes builtins.functionArgs to determine arguments and builtins.intersectAttrs to combine attributes, allowing for argument overrides.
• Override Design Pattern: Used for modifying existing package definitions.

The Nix documentation team can be reached via the GitHub team @NixOS/documentation-team.

For community discussions and monitoring, the team uses:

• Discourse: The Documentation category.
• Matrix: The Nix Documentation room.

A file set is a data type representing a collection of local files. It is provided by the lib.fileset library in Nixpkgs. File sets allow you to compose, manipulate, and filter collections of files before they are added to the Nix store.

Key characteristics:

• Lazy evaluation: Files in a file set are never added to the Nix store unless explicitly requested (e.g., via toSource). This prevents accidental leakage of secrets into the world-readable Nix store.
• Path coercion: Any function expecting a file set can accept a path. Such paths are implicitly converted into file sets containing all files under that path.
• Debugging: Use lib.fileset.trace to pretty-print the contents of a file set during evaluation.

# In nix repl
$ nix repl -f channel:nixos-23.11
nix-repl> fs = lib.fileset
nix-repl> fs.trace ./. 
trace: /home/user (all files in directory)

The Nix module system is a library that allows you to build complex configurations by breaking them down into smaller, manageable pieces. Its core capabilities include:

• Distributed Declaration: Declaring a single attribute set using multiple separate Nix expressions.
• Type Constraints: Imposing type constraints on values within an attribute set.
• Automatic Merging: Defining values for the same attribute across different expressions and having them merged automatically based on their type.

Modules must follow a specific structure to be compatible with the module system.

The NixOS tutorials provide guidance on several key workflows:

Creating NixOS images

• Running NixOS configurations on Virtual Machines (VMs).
• Building bootable ISO images.
• Building and running NixOS-based Docker images.

Testing and deploying NixOS configurations

• Performing integration testing using Virtual Machines.
• Provisioning remote machines.
• Installing NixOS on a Raspberry Pi.
• Deploying NixOS using Terraform.

Scaling up

• Setting up a binary cache.
• Setting up distributed builds.