nix-playgraound/notes/001-glossary.md

# Glossary

Core vocabulary you'll hit in the first hour of Nix. Skim, don't memorize; come back as needed.

## The Store and Builds

- Nix store: `/nix/store`. Immutable, content-addressed directory where *everything* Nix builds lives. Each entry is prefixed by a hash of its inputs.
- Store path: a single entry under `/nix/store`, e.g. `/nix/store/abc123…-hello-2.12.1`. The hash makes it unique per set of build inputs.
- Derivation (`.drv`): a *recipe* for a build, covering inputs, builder script, env vars, and outputs. Produced by evaluating Nix code. Not the built
  artifact itself.
- Realisation, or "realising a derivation": actually executing the `.drv` to produce the output store path(s). "Build" colloquially means this.
- Output path: the store path a derivation produces. A derivation can have multiple outputs (e.g. `out`, `dev`, `man`, `lib`).
- Closure: a store path plus all its runtime dependencies, transitively. What you need to copy to another machine to actually use something.
- Hash: content/input hash that names store paths. Changing any input changes the hash, which changes the path; this is how Nix guarantees no cache
  collisions.
- Fixed-output derivation (FOD): a derivation whose output hash you declare up front (e.g. source tarballs, `fetchurl`). Allowed network access during
  build; everything else is sandboxed offline.

## Language

- Nix (the language): lazy, purely functional, dynamically typed. Every `.nix` file is one expression.
- Attrset: `{ a = 1; b = "x"; }`. The main data structure.
- Lambda: `x: x + 1` or `{ a, b }: a + b`. Functions take one argument; multi-arg functions are attrset-destructured.
- `let ... in`: local bindings, for example `let x = 1; in x + 1`.
- `with expr; body`: brings `expr`'s attrs into scope for `body`. Common in `with pkgs; [ hello jq ]`. Useful but can shadow bindings, so use
  sparingly.
- `inherit`: shorthand to pull names from outer scope into an attrset: `{ inherit pkgs system; }` ≡ `{ pkgs = pkgs; system = system; }`.
- `import`: evaluate another `.nix` file. `import ./foo.nix { }` imports and calls it.
- `callPackage`: a nixpkgs convention that auto-supplies function arguments from a package set. You'll see it everywhere in nixpkgs.

## Package Management

- nixpkgs: the community-maintained collection of Nix expressions for ~100k packages. Lives at `github:NixOS/nixpkgs`.
- Channel: a named, periodically-updated snapshot of nixpkgs (e.g. `nixos-unstable`, `nixos-25.11`). Pre-flakes way to pin. Flakes mostly replace this
  with lockfiles.
- Overlay: a function that extends or overrides a package set. Lets you patch, pin, or add packages without forking nixpkgs.
- Profile: a symlink tree representing "what's installed" for a user or system. `nix-env`, `nix profile`, NixOS, and home-manager all manage profiles.
- Generation: a versioned snapshot of a profile. Every change creates a new generation; old ones stay until garbage-collected. This is how rollback
  works.
- Garbage collection (`nix-collect-garbage`): deletes store paths not reachable from any "GC root" (profiles, running processes, and `result`
  symlinks).

## Flakes

- Flake: a directory with a `flake.nix`. Has pinned `inputs` and structured `outputs`. Reproducible, composable, and schema-driven.
- `flake.lock`: JSON file pinning the exact revision (and hash) of each input. Commit it.
- Flake reference: URL-like string identifying a flake: `github:NixOS/nixpkgs`, `path:./foo`, `git+https://…`, or `nixpkgs` (registry alias).
- Registry: short-name to flake-ref mapping. `nixpkgs` resolves via the global registry by default.
- Pure evaluation: flakes evaluate in a sandbox with no env vars, no arbitrary filesystem reads, and only declared inputs. This is what makes them
  reproducible.

## NixOS and home-manager

- NixOS module: a function `{ config, lib, pkgs, ... }: { options = …; config = …; }`. The unit of NixOS configuration.
- home-manager: user-level declarative config for dotfiles, per-user packages, and services. Works standalone or as a NixOS module.

## CLI: Old vs. New

| Old (pre-flakes)       | New (flakes)          |
|------------------------|-----------------------|
| `nix-build`            | `nix build`           |
| `nix-shell`            | `nix develop`         |
| `nix-env -iA`          | `nix profile install` |
| `nix-channel`          | `flake.lock` + inputs |
| `<nixpkgs>` (NIX_PATH) | `inputs.nixpkgs`      |

Both still work. Flakes are the direction of travel; old commands aren't going away soon.