Skip to content

Instantly share code, notes, and snippets.

@ikuz

ikuz/nix-notes.md

Last active February 9, 2022 03:30
Show Gist options
  • Star 1 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
  • Save ikuz/72c70193d9d1025e1c48b318eaba0757 to your computer and use it in GitHub Desktop.
Save ikuz/72c70193d9d1025e1c48b318eaba0757 to your computer and use it in GitHub Desktop.
Download ZIP
Nix Notes
Raw
nix-notes.md

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

nix-hash

nix-prefetch-url

  • nix-prefetch-url <url> download into cache, prints hash
  • nix-prefetch-url -A <some.attribute.url> from expression in current dir

Resources

https://nixos.org/learn.html

https://nixos.org/nixos/nix-pills/index.html

https://nixos.wiki/wiki/Nix_Expression_Language

https://nixos.org/nix/manual

https://nixos.org/nixpkgs/manual

https://github.com/NixOS/nixpkgs

https://www.youtube.com/watch?v=m4sv2M9jRLg

Quick Ref: https://github.com/kquick/nix-cheatsheet/blob/master/nix-cheatsheet.org

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment