Nix notes

Nix concepts

packages (and derivations)

package: a software package
derivation: a specific version of a software package
- identified by a hash
- the result of a 'derivation expression' that describes:
  - how to get it
  - what its dependencies are
  - how to build it
  - where to put it
- .drv file: key value representation of derivation expression result
- out path: where the built derivation can be found
hash: based on
- derivation (contents of .drv file)
- package specific srcs, scripts, etc.
- dependencies (= input derivations)
- out path hash: hash contents -> string desc of hash -> hash of string desc
- 1. sha256 sum of .drv with empty 'out path' strings ->
- 1. echo "output:out:sha256:<sum>:/nix/store:<pkg>" > pkg.str ->
- 1. nix-hash --type sha256 --truncate --base32 --flat pkg.str -> outpath hash
- 1. replace empty outpaths in .drv with outpath hash
fixed-output derivation
- out path hash based only on 'outputHash' attribute
- typically hash of tar file, etc.

nix store

/nix/store/
store of derivations
- /nix/store/<hash>-<name>/
- each derivation is immutable

nix database

/nix/var/nix/db
keeps track of dependencies between derivations

profiles

working snapshot
collection of derivations that work together
sets user environment: PATH, etc.
versioned: 'generation'
~/.nix-profile/ -> /nix/var/nix/profiles/ -> /nix/store/<hash>-user-environment/
nix.sh - adds nix support to shell: adds ~/.nix-profile/bin to PATH etc.
- ~/.nix-profile/etc/profile.d/nix.sh

derivation expression

specifies the derivation
derivation (built-in) function
d = derivation { name, builder, system, ... }
returns 'derivation set': a set with attributes
creates <hash>-<name>.drv file
- name of .drv file
- outputs: outPath
- inputSRcs
- inputDrvs: dependencies = input derivations
- platform: platform to build for
- builder: program to invoke to build
- args: args to builder
- env: environment passed to builder. contains all attrs in derivation set
"${d}/bin/" -> "<outPath>/bin"
Note: evaluating derivation expression does not build derivation
- Instantiate/Evaluation time: creates derivation set (.drv)
- Realise/Build time: build based on .drv files, install to 'out' paths
inputSrcs, the builder, builder args (files): go into the store
wrappers that simplify, e.g. stdenv.mkDerivation

channels

a set of packages and expressions available for download
a function that produces a set of derivations
~/.nix-channels/ -> TODO

nixpkgs

a channel of all current nix derivations
repo containg all current nix package expressions
~/.nix-defexpr/channels/nixpkgs/
~/.nix-defexpr/channels/nixpkgs/pkgs/top-level/all-packages.nix

Language

structure and punctuation

expression: combination of values, functions, operations
- nix "program" is a single expression, with sub-expressions
comments: /* */ and #
parentheses ( ): delimit (sub-)expressions, force precedence
braces { }: delimit sets and set patterns
semicolon ;: separate parts of expressions, separate elements in attribute set
comma ,: separate elements in argument set
lazy evaluation: expressions are only evaluated when referenced

types

integer, float, boolean, null
path: xxx/yyy
string: "a string ${expression} yes" ''multiline string''
list: [ a "b" true (1+2) ]
attribute set:
- s = { a = 2; b = "s"; "abc" = "123"; }
- s.a, s."abc"
- recursive: rec { a = 3; b = a+4; }
- with: x = { a = 3; b =4; }; with x; a + b
- inherit x adds x = x; in a set definition
- x = "hello"; y = { inherit x; } -> y = { x = "hello"; }
- { a = 1; b = 2; } // { b = 3; c = 4; } -> { a = 1; b = 3; c = 4; }`
function: see below

let

let <assignments>; in <expression> -> value of <expresssion>
cannot re-assign to a variable in the same let block
can shadow variables in nested let blocks

control flow

if a > b then "yes" else "no"

functions

basic function: func = arg1: arg2: arg1 + arg2
- func 1 2 -> 3
partial application: func 1 -> a function: arg2: 1 + arg2
- f = func 1; f 2 -> 3
argument set: func = { a ? 1, b ? 2, ... }: a + b
- func -> 3 func { a = 2; } -> 4 func { a = 2; b = 3; c = 3; } -> 5
- func = s@{ a, b, ... }: a+b+s.c invoke func { a=1; b=2; c=3; }

import

import file: contents of file parsed as expression
typical use:
- file.nix: { a, b }: a*b
- import ./file.nix { a = 5; b = 4; }
- invokes function defined in file.nix
- typically <file>.nix returns a derivation

`<nixpkgs>`

args:
- system: the system for which derivations will be built (e.g. x86_64)
- config: general config that packages can use

config

~/.nixpkgs/config.nix
config.packageOverrides function that defines any package overrides for nixpkgs
e.g.

packageOverrides = pkgs: {
	graphviz = pkgs.graphviz.override { xorg = null; };
};

builtins

builtins.currentSystem
builtins.attrNames <attribute set>
builtins.intersectAttrs {a="a";b="b"} {b=3;c=5} -> {b=3}
builtins.functionArgs:
- f = {a ? 3, b}: a+b
- buitlins.functionArgs f -> { a = true; b = false; }
builtins.fetchurl <url> -> path of downloaded file
buitlins.fetchurl { url; sha256; } -> path of downloaded file
builtins.fetchTarball <url> -> path of unpacked tree
builtins.fetchTarball { url; sha256; } -> path of unpacked tree
buitlins.fetchGit { url; name; rev; ref; }

stdenv

stdenv.mkDerivation { name = "myname"; src = ./myname.tgz; }

other

writing derivations

basic derivation

with (import <nixpkgs> {});
derivation {
	name = "mypackage";
	builder = ...;
	args = ... ;
	src = ...;
	system = builtins.currentSystem;
}

import <nixpkgs> {} -> set of derivations
fixed output derivation
- extra attributes:
  - outputHashMode
  - outputHashAlgo
  - outputHash
- out hash based on outputHash
  - echo <decorated outhash> > out.str; sha256sum out.str
  - echo <decorated out.str sha> > file.str
  - nix-hash --type sha256 --truncate --base32 --flat file.str
mkDerivation

	with import <nixpkgs> {};
	stdenv.mkDerivation {
		pname = "mypackage";
		version = "1.2.3";
		src = ./path/to/src/tarball
		buildInputs = [ <extra input dependency packages> ];
	}

overrideable phases
$prePhases unpackPhase patchPhase $preConfigurePhases configurePhase $preBuildPhases buildPhase checkPhase $preInstallPhases installPhase fixupPhase installCheckPhase $preDistPhases distPhase $postPhases
callPackage <file> { <derivation overrides> }
- <file> takes package derivations as arguments.
- get default derivations from main set of pkgs.
- allow them to be overridden.
override
- newd = <pkg>.override { <argument overrides> }
- newd = <pkg>.overrideDerivation ( oldAttrs: { <attribute overrides> } )
- newd = <mkDerivation>.overrideAttrs ( oldAttrs: { <attribute overrides> } ) preferred for mkDerivations over overrideDerivation

files and directories

/nix/store
/nix/var
~/.nix-profile
~/.nix-defexpr/
- ~/.nix-defexpr/channels/nixpkgs
- /.nix-defexpr/channels/nixpkgs/pkgs/top-level/all-packages.nix ~/.nixpkgs/
- ~/.nixpkgs/config.nix
- NIXPKGS_CONFIG overrides default config.nix path
NIX_PATH
- searched when using <pkg> in an expression
- /some/path
- pkg=/path/to/pkg

commands

nix-repl

command line interface for nix language

nix-env

manages user environment and profiles
list derivations installed in an environment
nix-env -q
nix-env -q --out-path
create new user environment (aka profile generation)
- <package> is derivation name with or without version
nix-env -i <package>
nix-env --uninstall <package>
nix-env --upgrade <package>
nix-env -u <package+version> --always force up or downgrade to specified version
nix-env -u
nix-env --rollback
nix-env -G <generation>
other
nix-env --list-generations
nix-env -f '<altpkgs>' ... use <altpkgs> instead of <nixpkgs>

nix-store

query and manipulate store
nix-store -q --references <path to file in store>
nix-store -q --referrers <path to file in store>
nix-store -qR <path to file in store>
nix-store -q --tree <path to file in store>
nix-store -r <.drv file> realise (build) a derivation
nix-store --dump <file>

nix-channel

manage channels
nix-channel --list
nix-channel --update

nix-instantiate

instantiate derivation -> .drv file
nix-instantiate <.nix file>
nix-instantiate --eval <.nix file> no .drv
nix show-derivation <.drv file>

nix-build

build derivations from an expression
nix-build <package>.nix -> result: symlink to out path
nix-build -K ... keep build directory (on fail)
working build directory in /tmp. removed on successful build.

nix-shell

shell with env variables needed to (manually) build a derivation
nix-shell <package>.nix
- instantiates <package>.nix -> .drv file
- builds dependencies
- sets env based on .drv file

nix-collect-garbage

garbage collector
GC roots
- all profiles (/nix/var/nix/gcroots/profiles)
- all nix-build result directories (/nix/var/nix/gcroots/auto/)
nix-collect-garbage
nix-collect-garbage -d removes all previous generations
https://nixos.org/guides/nix-pills/garbage-collector.html