ikuz/nix-notes.md

## nix-notes.md

      
    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


sha256 sum of .drv with empty 'out path' strings ->


echo "output:out:sha256:<sum>:/nix/store:<pkg>" > pkg.str ->


nix-hash --type sha256 --truncate --base32 --flat pkg.str -> outpath hash


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

nix-hash


nix-hash --type sha256 <file>
nix-hash --type sha256 --truncate --base32 --flat <file>
https://nixos.org/guides/nix-pills/nix-store-paths.html

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
No results found