Nix

Critical Nix Principles

Purity and Reproducibility

• Builds MUST be pure and reproducible
• MUST NOT access network during build phase
• MUST declare all dependencies explicitly
• Use fetchFromGitHub, fetchurl, etc. in fetchers, not in build phase
• Use nix-hash or nix-prefetch-url to get correct hashes

Immutability

• Derivations are immutable once built
• MUST NOT modify /nix/store contents
• Use overlays for local modifications
• Patches go in patches/ directory, referenced in derivation

Package Development

Derivation Structure

Standard derivation template:

{ lib
, stdenv
, fetchFromGitHub
, buildRustPackage  # or buildPythonPackage, buildGoModule, etc.
, pkg-config
, openssl
, ...
}:

buildRustPackage rec {
  pname = "package-name";
  version = "1.0.0";

  src = fetchFromGitHub {
    owner = "owner-name";
    repo = "repo-name";
    rev = "v${version}";
    hash = "sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=";
  };

  cargoHash = "sha256-BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB=";

  nativeBuildInputs = [ pkg-config ];
  buildInputs = [ openssl ];

  meta = with lib; {
    description = "Short package description";
    homepage = "https://example.com";
    license = licenses.mit;
    maintainers = with maintainers; [ your-handle ];
    mainProgram = "executable-name";
  };
}

Build Input Classification

nativeBuildInputs: Tools needed at build time (run on build platform)

• Examples: pkg-config, cmake, cargo, rustc, makeWrapper
• These execute during the build

buildInputs: Libraries needed at build AND runtime (target platform)

• Examples: openssl, sqlite, postgresql
• Linked into the final binary

propagatedBuildInputs: Dependencies that consumers also need

• Examples: Python/Node libraries that import other libraries
• Automatically added to dependent packages

checkInputs: Dependencies only for running tests

• Examples: pytest, cargo-nextest
• Only needed when doCheck = true

Language-Specific Builders

Rust Packages

buildRustPackage rec {
  pname = "rust-app";
  version = "1.0.0";

  src = fetchFromGitHub { ... };

  cargoHash = "sha256-...";  # Use lib.fakeHash initially, update after first build

  # Optional: Lock file handling
  cargoLock = {
    lockFile = ./Cargo.lock;
    outputHashes = {
      "dependency-0.1.0" = "sha256-...";
    };
  };

  # Build-time flags
  cargoBuildFlags = [ "--all-features" ];
  
  # Skip tests if they require network/special setup
  doCheck = false;
  
  meta = { ... };
}

Python Packages

buildPythonPackage rec {
  pname = "python-pkg";
  version = "1.0.0";
  pyproject = true;  # For pyproject.toml-based projects

  src = fetchPypi {
    inherit pname version;
    hash = "sha256-...";
  };

  build-system = [ setuptools ];  # or hatchling, poetry-core, etc.

  dependencies = [
    requests
    pydantic
  ];

  optional-dependencies = {
    dev = [ pytest black ];
  };

  pythonImportsCheck = [ "module_name" ];

  meta = { ... };
}

Node.js Packages

buildNpmPackage rec {
  pname = "node-app";
  version = "1.0.0";

  src = fetchFromGitHub { ... };

  npmDepsHash = "sha256-...";

  # Optional: Custom build phase
  buildPhase = ''
    npm run build
  '';

  installPhase = ''
    mkdir -p $out/bin
    cp -r dist $out/
    makeWrapper ${nodejs}/bin/node $out/bin/${pname} \
      --add-flags "$out/dist/index.js"
  '';

  meta = { ... };
}

Fetchers

fetchFromGitHub

src = fetchFromGitHub {
  owner = "owner-name";
  repo = "repo-name";
  rev = "v${version}";  # or commit hash
  hash = "sha256-...";  # Use lib.fakeHash initially
  # Optional:
  fetchSubmodules = true;
};

fetchurl

src = fetchurl {
  url = "https://example.com/file-${version}.tar.gz";
  hash = "sha256-...";
};

fetchPypi

src = fetchPypi {
  inherit pname version;
  hash = "sha256-...";
  # Optional:
  extension = "zip";
};

Hash Management

Getting correct hashes:

1. Use lib.fakeHash or lib.fakeSha256 initially
2. Run build, it will fail with actual hash
3. Copy actual hash into derivation
4. Rebuild to verify

# Initial attempt
hash = lib.fakeHash;

# After failure, copy the hash from error message
hash = "sha256-Abc123...";

For Rust crates:

# Prefetch cargo dependencies
nix-prefetch-url --unpack "https://crates.io/api/v1/crates/package/1.0.0/download"

Flakes

Flake Structure

Standard flake template:

{
  description = "Package or system description";

  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    flake-utils.url = "github:numtide/flake-utils";
  };

  outputs = { self, nixpkgs, flake-utils }:
    flake-utils.lib.eachDefaultSystem (system:
      let
        pkgs = nixpkgs.legacyPackages.${system};
      in
      {
        packages.default = pkgs.callPackage ./default.nix { };

        devShells.default = pkgs.mkShell {
          buildInputs = with pkgs; [
            rustc
            cargo
            pkg-config
            openssl
          ];
        };

        # For NixOS modules
        nixosModules.default = import ./module.nix;
      });
}

Flake Updates

# Update all inputs
nix flake update

# Update specific input
nix flake lock --update-input nixpkgs

# Show flake metadata
nix flake metadata

# Check flake for issues
nix flake check

NixOS Configuration

Module Structure

{ config, lib, pkgs, ... }:

with lib;

let
  cfg = config.services.myservice;
in
{
  options.services.myservice = {
    enable = mkEnableOption "myservice";

    package = mkOption {
      type = types.package;
      default = pkgs.myservice;
      description = "Package to use for myservice";
    };

    port = mkOption {
      type = types.port;
      default = 8080;
      description = "Port to listen on";
    };

    settings = mkOption {
      type = types.attrs;
      default = { };
      description = "Additional settings";
    };
  };

  config = mkIf cfg.enable {
    systemd.services.myservice = {
      description = "My Service";
      wantedBy = [ "multi-user.target" ];
      after = [ "network.target" ];

      serviceConfig = {
        ExecStart = "${cfg.package}/bin/myservice --port ${toString cfg.port}";
        Restart = "always";
        User = "myservice";
        Group = "myservice";
      };
    };

    users.users.myservice = {
      isSystemUser = true;
      group = "myservice";
    };

    users.groups.myservice = { };
  };
}

Common NixOS Patterns

Service with configuration file:

config = mkIf cfg.enable {
  environment.etc."myservice/config.json".text = builtins.toJSON cfg.settings;

  systemd.services.myservice = {
    serviceConfig = {
      ExecStart = "${cfg.package}/bin/myservice --config /etc/myservice/config.json";
    };
  };
};

Conditional package installation:

environment.systemPackages = optional cfg.enable cfg.package;

Overlays

Creating Overlays

# overlays/default.nix