Located at lib/asserts.nix:21 in <nixpkgs>.

Print a trace message if pred is false.

Intended to be used to augment asserts with helpful error messages.

assert lib.asserts.assertMsg ("foo" == "bar") "foo is not bar, silly"
stderr> trace: foo is not bar, silly
stderr> assert failed

Located at lib/asserts.nix:38 in <nixpkgs>.

Specialized asserts.assertMsg for checking if val is one of the elements of xs. Useful for checking enums.

let sslLibrary = "bearssl";
in lib.asserts.assertOneOf "sslLibrary" sslLibrary [ "openssl" "libressl" ];
=> false
stderr> trace: sslLibrary must be one of "openssl", "libressl", but is: "bearssl"
        

Located at lib/attrsets.nix:24 in <nixpkgs>.

Return an attribute from within nested attribute sets.

let set = { a = { b = 3; }; };
in lib.attrsets.attrByPath [ "a" "b" ] 0 set
=> 3

lib.attrsets.attrByPath [ "a" "b" ] 0 {}
=> 0

Located at lib/attrsets.nix:42 in <nixpkgs>.

Determine if an attribute exists within a nested attribute set.

lib.attrsets.hasAttrByPath
  [ "a" "b" "c" "d" ]
  { a = { b = { c = { d = 123; }; }; }; }
=> true

Located at lib/attrsets.nix:57 in <nixpkgs>.

Create a new attribute set with value set at the nested attribute location specified in attrPath.

lib.attrsets.setAttrByPath [ "a" "b" ] 3
=> { a = { b = 3; }; }

Located at lib/attrsets.nix:73 in <nixpkgs>.

Like Section 5.1.2.1, “lib.attrset.attrByPath” except without a default, and it will throw if the value doesn't exist.

lib.attrsets.getAttrFromPath [ "a" "b" ] { a = { b = 3; }; }
=> 3

lib.attrsets.getAttrFromPath [ "x" "y" ] { }
=> error: cannot find attribute `x.y'

Located at lib/attrsets.nix:84 in <nixpkgs>.

Return the specified attributes from a set. All values must exist.

lib.attrsets.attrVals [ "a" "b" "c" ] { a = 1; b = 2; c = 3; }
=> [ 1 2 3 ]

lib.attrsets.attrVals [ "d" ] { }
error: attribute 'd' missing

Located at lib/attrsets.nix:94 in <nixpkgs>.

Get all the attribute values from an attribute set.

Provides a backwards-compatible interface of builtins.attrValues for Nix version older than 1.8.

lib.attrsets.attrValues { a = 1; b = 2; c = 3; }
=> [ 1 2 3 ]

Located at lib/attrsets.nix:113 in <nixpkgs>.

Collect each attribute named `attr' from the list of attribute sets, sets. Sets that don't contain the named attribute are ignored.

Provides a backwards-compatible interface of builtins.catAttrs for Nix version older than 1.9.

catAttrs "a" [{a = 1;} {b = 0;} {a = 2;}]
=> [ 1 2 ]
      

Located at lib/attrsets.nix:124 in <nixpkgs>.

Filter an attribute set by removing all attributes for which the given predicate return false.

filterAttrs (n: v: n == "foo") { foo = 1; bar = 2; }
=> { foo = 1; }

Located at lib/attrsets.nix:135 in <nixpkgs>.

Filter an attribute set recursively by removing all attributes for which the given predicate return false.

lib.attrsets.filterAttrsRecursive
  (n: v: v != null)
  {
    levelA = {
      example = "hi";
      levelB = {
        hello = "there";
        this-one-is-present = {
          this-is-excluded = null;
        };
      };
      this-one-is-also-excluded = null;
    };
    also-excluded = null;
  }
=> {
     levelA = {
       example = "hi";
       levelB = {
         hello = "there";
         this-one-is-present = { };
       };
     };
   }
     

Located at lib/attrsets.nix:154 in <nixpkgs>.

Apply fold function to values grouped by key.

lib.attrsets.foldAttrs
  (n: a: [n] ++ a) []
  [
    { a = 2; b = 7; }
    { a = 3; }
    { b = 6; }
  ]
=> { a = [ 2 3 ]; b = [ 7 6 ]; }

Located at lib/attrsets.nix:178 in <nixpkgs>.

Recursively collect sets that verify a given predicate named pred from the set attrs. The recursion stops when pred returns true.

lib.attrsets.collect isList { a = { b = ["b"]; }; c = [1]; }
=> [["b"] [1]]

collect (x: x ? outPath)
  { a = { outPath = "a/"; }; b = { outPath = "b/"; }; }
=> [{ outPath = "a/"; } { outPath = "b/"; }]

Located at lib/attrsets.nix:212 in <nixpkgs>.

Utility function that creates a {name, value} pair as expected by builtins.listToAttrs.

nameValuePair "some" 6
=> { name = "some"; value = 6; }

Located at lib/attrsets.nix:225 in <nixpkgs>.

Apply a function to each element in an attribute set, creating a new attribute set.

Provides a backwards-compatible interface of builtins.mapAttrs for Nix version older than 2.1.

lib.attrsets.mapAttrs
  (name: value: name + "-" value)
  { x = "foo"; y = "bar"; }
=> { x = "x-foo"; y = "y-bar"; }

Located at lib/attrsets.nix:239 in <nixpkgs>.

Like mapAttrs, but allows the name of each attribute to be changed in addition to the value. The applied function should return both the new name and value as a nameValuePair.

lib.attrsets.mapAttrs' (name: value: lib.attrsets.nameValuePair ("foo_" + name) ("bar-" + value))
   { x = "a"; y = "b"; }
=> { foo_x = "bar-a"; foo_y = "bar-b"; }

    

Located at lib/attrsets.nix:255 in <nixpkgs>.

Call fn for each attribute in the given set and return the result in a list.

lib.attrsets.mapAttrsToList (name: value: "${name}=${value}")
   { x = "a"; y = "b"; }
=> [ "x=a" "y=b" ]

Located at lib/attrsets.nix:272 in <nixpkgs>.

Like mapAttrs, except that it recursively applies itself to attribute sets. Also, the first argument of the argument function is a list of the names of the containing attributes.

mapAttrsRecursive
  (path: value: concatStringsSep "-" (path ++ [value]))
  {
    n = {
      a = "A";
      m = {
        b = "B";
        c = "C";
      };
    };
    d = "D";
  }
=> {
     n = {
       a = "n-a-A";
       m = {
         b = "n-m-b-B";
         c = "n-m-c-C";
       };
     };
     d = "d-D";
   }
    

Located at lib/attrsets.nix:293 in <nixpkgs>.

Like mapAttrsRecursive, but it takes an additional predicate function that tells it whether to recursive into an attribute set. If it returns false, mapAttrsRecursiveCond does not recurse, but does apply the map function. It is returns true, it does recurse, and does not apply the map function.

lib.attrsets.mapAttrsRecursiveCond
  ({ recurse ? false, ... }: recurse)
  (name: value: builtins.toJSON value)
  {
    dorecur = {
      recurse = true;
      hello = "there";
    };
    dontrecur = {
      converted-to- = "json";
    };
  }
=> {
     dorecur = {
       hello = "\"there\"";
       recurse = "true";
     };
     dontrecur = "{\"converted-to\":\"json\"}";
   }
    

Located at lib/attrsets.nix:313 in <nixpkgs>.

Generate an attribute set by mapping a function over a list of attribute names.

lib.attrsets.genAttrs [ "foo" "bar" ] (name: "x_${name}")
=> { foo = "x_foo"; bar = "x_bar"; }
     

Located at lib/attrsets.nix:327 in <nixpkgs>.

Check whether the argument is a derivation. Any set with { type = "derivation"; } counts as a derivation.

lib.attrsets.isDerivation (import <nixpkgs> {}).ruby
=> true
     

lib.attrsets.isDerivation "foobar"
=> false
     

Located at lib/attrsets.nix:330 in <nixpkgs>.

Converts a store path to a fake derivation.

Located at lib/attrsets.nix:353 in <nixpkgs>.

Conditionally return an attribute set or an empty attribute set.

lib.attrsets.optionalAttrs true { my = "set"; }
=> { my = "set"; }
     

lib.attrsets.optionalAttrs false { my = "set"; }
=> { }
     

Located at lib/attrsets.nix:363 in <nixpkgs>.

Merge sets of attributes and use the function f to merge attribute values where the attribute name is in names.

lib.attrsets.zipAttrsWithNames
  [ "a" "b" ]
  (name: vals: "${name} ${toString (builtins.foldl' (a: b: a + b) 0 vals)}")
  [
    { a = 1; b = 1; c = 1; }
    { a = 10; }
    { b = 100; }
    { c = 1000; }
  ]
=> { a = "a 11"; b = "b 101"; }
     

Located at lib/attrsets.nix:378 in <nixpkgs>.

Merge sets of attributes and use the function f to merge attribute values. Similar to Section 5.1.2.22, “lib.attrsets.zipAttrsWithNames” where all key names are passed for names.

lib.attrsets.zipAttrsWith
  (name: vals: "${name} ${toString (builtins.foldl' (a: b: a + b) 0 vals)}")
  [
    { a = 1; b = 1; c = 1; }
    { a = 10; }
    { b = 100; }
    { c = 1000; }
  ]
=> { a = "a 11"; b = "b 101"; c = "c 1001"; }
     

Located at lib/attrsets.nix:385 in <nixpkgs>.

Merge sets of attributes and combine each attribute value in to a list. Similar to Section 5.1.2.23, “lib.attrsets.zipAttrsWith” where the merge function returns a list of all values.

lib.attrsets.zipAttrs
  [
    { a = 1; b = 1; c = 1; }
    { a = 10; }
    { b = 100; }
    { c = 1000; }
  ]
=> { a = [ 1 10 ]; b = [ 1 100 ]; c = [ 1 1000 ]; }
     

Located at lib/attrsets.nix:415 in <nixpkgs>.

Does the same as the update operator // except that attributes are merged until the given predicate is verified. The predicate should accept 3 arguments which are the path to reach the attribute, a part of the first attribute set and a part of the second attribute set. When the predicate is verified, the value of the first attribute set is replaced by the value of the second attribute set.

lib.attrsets.recursiveUpdateUntil (path: l: r: path == ["foo"])
  {
    # first attribute set
    foo.bar = 1;
    foo.baz = 2;
    bar = 3;
  }
  {
    #second attribute set
    foo.bar = 1;
    foo.quz = 2;
    baz = 4;
  }
=> {
  foo.bar = 1; # 'foo.*' from the second set
  foo.quz = 2; #
  bar = 3;     # 'bar' from the first set
  baz = 4;     # 'baz' from the second set
}
     

Located at lib/attrsets.nix:446 in <nixpkgs>.

A recursive variant of the update operator //. The recursion stops when one of the attribute values is not an attribute set, in which case the right hand side value takes precedence over the left hand side value.

recursiveUpdate
  {
    boot.loader.grub.enable = true;
    boot.loader.grub.device = "/dev/hda";
  }
  {
    boot.loader.grub.device = "";
  }
=> {
  boot.loader.grub.enable = true;
  boot.loader.grub.device = "";
}

Located at lib/attrsets.nix:505 in <nixpkgs>.

Make various Nix tools consider the contents of the resulting attribute set when looking for what to build, find, etc.

This function only affects a single attribute set; it does not apply itself recursively for nested attribute sets.

{ pkgs ? import <nixpkgs> {} }:
{
  myTools = pkgs.lib.recurseIntoAttrs {
    inherit (pkgs) hello figlet;
  };
}

Located at lib/attrsets.nix:197 in <nixpkgs>.

Return the cartesian product of attribute set value combinations.

cartesianProductOfSets { a = [ 1 2 ]; b = [ 10 20 ]; }
=> [
     { a = 1; b = 10; }
     { a = 1; b = 20; }
     { a = 2; b = 10; }
     { a = 2; b = 20; }
   ]

Concatenate a list of strings.

concatStrings ["foo" "bar"]
=> "foobar"

Located at lib/strings.nix:43 in <nixpkgs>.

Map a function over a list and concatenate the resulting strings.

concatMapStrings (x: "a" + x) ["foo" "bar"]
=> "afooabar"

Located at lib/strings.nix:53 in <nixpkgs>.

Like `concatMapStrings` except that the f functions also gets the position as a parameter.

concatImapStrings (pos: x: "${toString pos}-${x}") ["foo" "bar"]
=> "1-foo2-bar"

Located at lib/strings.nix:64 in <nixpkgs>.

Place an element between each element of a list

intersperse "/" ["usr" "local" "bin"]
=> ["usr" "/" "local" "/" "bin"].

Located at lib/strings.nix:74 in <nixpkgs>.

Concatenate a list of strings with a separator between each element

concatStringsSep "/" ["usr" "local" "bin"]
=> "usr/local/bin"

Located at lib/strings.nix:91 in <nixpkgs>.

Maps a function over a list of strings and then concatenates the result with the specified separator interspersed between elements.

concatMapStringsSep "-" (x: toUpper x)  ["foo" "bar" "baz"]
=> "FOO-BAR-BAZ"

Located at lib/strings.nix:104 in <nixpkgs>.

Same as `concatMapStringsSep`, but the mapping function additionally receives the position of its argument.

concatImapStringsSep "-" (pos: x: toString (x / pos)) [ 6 6 6 ]
=> "6-3-2"

Located at lib/strings.nix:121 in <nixpkgs>.

Construct a Unix-style, colon-separated search path consisting of the given `subDir` appended to each of the given paths.

makeSearchPath "bin" ["/root" "/usr" "/usr/local"]
=> "/root/bin:/usr/bin:/usr/local/bin"
makeSearchPath "bin" [""]
=> "/bin"

Located at lib/strings.nix:140 in <nixpkgs>.

Construct a Unix-style search path by appending the given `subDir` to the specified `output` of each of the packages. If no output by the given name is found, fallback to `.out` and then to the default.

makeSearchPathOutput "dev" "bin" [ pkgs.openssl pkgs.zlib ]
=> "/nix/store/9rz8gxhzf8sw4kf2j2f1grr49w8zx5vj-openssl-1.0.1r-dev/bin:/nix/store/wwh7mhwh269sfjkm6k5665b5kgp7jrk2-zlib-1.2.8/bin"

Located at lib/strings.nix:158 in <nixpkgs>.

Construct a library search path (such as RPATH) containing the libraries for a set of packages

makeLibraryPath [ "/usr" "/usr/local" ]
=> "/usr/lib:/usr/local/lib"
pkgs = import <nixpkgs> { }
makeLibraryPath [ pkgs.openssl pkgs.zlib ]
=> "/nix/store/9rz8gxhzf8sw4kf2j2f1grr49w8zx5vj-openssl-1.0.1r/lib:/nix/store/wwh7mhwh269sfjkm6k5665b5kgp7jrk2-zlib-1.2.8/lib"

Located at lib/strings.nix:176 in <nixpkgs>.

Construct a binary search path (such as $PATH) containing the binaries for a set of packages.

makeBinPath ["/root" "/usr" "/usr/local"]
=> "/root/bin:/usr/bin:/usr/local/bin"

Located at lib/strings.nix:185 in <nixpkgs>.

Depending on the boolean `cond', return either the given string or the empty string. Useful to concatenate against a bigger string.

optionalString true "some-string"
=> "some-string"
optionalString false "some-string"
=> ""

Located at lib/strings.nix:198 in <nixpkgs>.

Determine whether a string has given prefix.

hasPrefix "foo" "foobar"
=> true
hasPrefix "foo" "barfoo"
=> false

Located at lib/strings.nix:214 in <nixpkgs>.

Determine whether a string has given suffix.

hasSuffix "foo" "foobar"
=> false
hasSuffix "foo" "barfoo"
=> true

Located at lib/strings.nix:230 in <nixpkgs>.

Determine whether a string contains the given infix

hasInfix "bc" "abcd"
=> true
hasInfix "ab" "abcd"
=> true
hasInfix "cd" "abcd"
=> true
hasInfix "foo" "abcd"
=> false

Located at lib/strings.nix:255 in <nixpkgs>.

Convert a string to a list of characters (i.e. singleton strings). This allows you to, e.g., map a function over each character. However, note that this will likely be horribly inefficient; Nix is not a general purpose programming language. Complex string manipulations should, if appropriate, be done in a derivation. Also note that Nix treats strings as a list of bytes and thus doesn't handle unicode.

stringToCharacters ""
=> [ ]
stringToCharacters "abc"
=> [ "a" "b" "c" ]
stringToCharacters "💩"
=> [ "�" "�" "�" "�" ]

Located at lib/strings.nix:279 in <nixpkgs>.

Manipulate a string character by character and replace them by strings before concatenating the results.

stringAsChars (x: if x == "a" then "i" else x) "nax"
=> "nix"

Located at lib/strings.nix:291 in <nixpkgs>.

Escape occurrence of the elements of `list` in `string` by prefixing it with a backslash.

escape ["(" ")"] "(foo)"
=> "\\(foo\\)"

Located at lib/strings.nix:308 in <nixpkgs>.

Quote string to be used safely within the Bourne shell.

escapeShellArg "esc'ape\nme"
=> "'esc'\\''ape\nme'"

Located at lib/strings.nix:318 in <nixpkgs>.

Quote all arguments to be safely passed to the Bourne shell.

escapeShellArgs ["one" "two three" "four'five"]
=> "'one' 'two three' 'four'\\''five'"

Located at lib/strings.nix:328 in <nixpkgs>.

Turn a string into a Nix expression representing that string

escapeNixString "hello\${}\n"
=> "\"hello\\\${}\\n\""

Located at lib/strings.nix:338 in <nixpkgs>.

Turn a string into an exact regular expression

escapeRegex "[^a-z]*"
=> "\\[\\^a-z]\\*"

Located at lib/strings.nix:348 in <nixpkgs>.

Quotes a string if it can't be used as an identifier directly.

escapeNixIdentifier "hello"
=> "hello"
escapeNixIdentifier "0abc"
=> "\"0abc\""

Located at lib/strings.nix:360 in <nixpkgs>.

Converts an ASCII string to lower-case.

toLower "HOME"
=> "home"

Located at lib/strings.nix:391 in <nixpkgs>.

Converts an ASCII string to upper-case.

toUpper "home"
=> "HOME"

Located at lib/strings.nix:401 in <nixpkgs>.

Appends string context from another string. This is an implementation detail of Nix.

Strings in Nix carry an invisible `context` which is a list of strings representing store paths. If the string is later used in a derivation attribute, the derivation will properly populate the inputDrvs and inputSrcs.

pkgs = import <nixpkgs> { };
addContextFrom pkgs.coreutils "bar"
=> "bar"

Located at lib/strings.nix:416 in <nixpkgs>.

Cut a string with a separator and produces a list of strings which were separated by this separator.

splitString "." "foo.bar.baz"
=> [ "foo" "bar" "baz" ]
splitString "/" "/usr/local/bin"
=> [ "" "usr" "local" "bin" ]

Located at lib/strings.nix:427 in <nixpkgs>.

Return a string without the specified prefix, if the prefix matches.

removePrefix "foo." "foo.bar.baz"
=> "bar.baz"
removePrefix "xxx" "foo.bar.baz"
=> "foo.bar.baz"

Located at lib/strings.nix:445 in <nixpkgs>.

Return a string without the specified suffix, if the suffix matches.

removeSuffix "front" "homefront"
=> "home"
removeSuffix "xxx" "homefront"
=> "homefront"

Located at lib/strings.nix:469 in <nixpkgs>.

Return true if string v1 denotes a version older than v2.

versionOlder "1.1" "1.2"
=> true
versionOlder "1.1" "1.1"
=> false

Located at lib/strings.nix:491 in <nixpkgs>.

Return true if string v1 denotes a version equal to or newer than v2.

versionAtLeast "1.1" "1.0"
=> true
versionAtLeast "1.1" "1.1"
=> true
versionAtLeast "1.1" "1.2"
=> false

Located at lib/strings.nix:503 in <nixpkgs>.

This function takes an argument that's either a derivation or a derivation's "name" attribute and extracts the name part from that argument.

getName "youtube-dl-2016.01.01"
=> "youtube-dl"
getName pkgs.youtube-dl
=> "youtube-dl"

Located at lib/strings.nix:515 in <nixpkgs>.

This function takes an argument that's either a derivation or a derivation's "name" attribute and extracts the version part from that argument.

getVersion "youtube-dl-2016.01.01"
=> "2016.01.01"
getVersion pkgs.youtube-dl
=> "2016.01.01"

Located at lib/strings.nix:532 in <nixpkgs>.

Extract name with version from URL. Ask for separator which is supposed to start extension.

nameFromURL "https://nixos.org/releases/nix/nix-1.7/nix-1.7-x86_64-linux.tar.bz2" "-"
=> "nix"
nameFromURL "https://nixos.org/releases/nix/nix-1.7/nix-1.7-x86_64-linux.tar.bz2" "_"
=> "nix-1.7-x86"

Located at lib/strings.nix:548 in <nixpkgs>.

Create an --{enable,disable}-<feat> string that can be passed to standard GNU Autoconf scripts.

enableFeature true "shared"
=> "--enable-shared"
enableFeature false "shared"
=> "--disable-shared"

Located at lib/strings.nix:564 in <nixpkgs>.

Create an --{enable-<feat>=<value>,disable-<feat>} string that can be passed to standard GNU Autoconf scripts.

enableFeatureAs true "shared" "foo"
=> "--enable-shared=foo"
enableFeatureAs false "shared" (throw "ignored")
=> "--disable-shared"

Located at lib/strings.nix:577 in <nixpkgs>.

Create an --{with,without}-<feat> string that can be passed to standard GNU Autoconf scripts.

withFeature true "shared"
=> "--with-shared"
withFeature false "shared"
=> "--without-shared"

Located at lib/strings.nix:588 in <nixpkgs>.

Create an --{with-<feat>=<value>,without-<feat>} string that can be passed to standard GNU Autoconf scripts.

withFeatureAs true "shared" "foo"
=> "--with-shared=foo"
withFeatureAs false "shared" (throw "ignored")
=> "--without-shared"

Located at lib/strings.nix:601 in <nixpkgs>.

Create a fixed width string with additional prefix to match required width.

This function will fail if the input string is longer than the requested length.

fixedWidthString 5 "0" (toString 15)
=> "00015"

Located at lib/strings.nix:615 in <nixpkgs>.

Format a number adding leading zeroes up to fixed width.

fixedWidthNumber 5 15
=> "00015"

Located at lib/strings.nix:632 in <nixpkgs>.

Convert a float to a string, but emit a warning when precision is lost during the conversion

floatToString 0.000001
=> "0.000001"
floatToString 0.0000001
=> trace: warning: Imprecise conversion from float to string 0.000000
"0.000000"

Located at lib/strings.nix:644 in <nixpkgs>.

Check whether a value can be coerced to a string

Located at lib/strings.nix:651 in <nixpkgs>.

Check whether a value is a store path.

isStorePath "/nix/store/d945ibfx9x185xf04b890y4f9g3cbb63-python-2.7.11/bin/python"
=> false
isStorePath "/nix/store/d945ibfx9x185xf04b890y4f9g3cbb63-python-2.7.11"
=> true
isStorePath pkgs.python
=> true
isStorePath [] || isStorePath 42 || isStorePath {} || …
=> false

Located at lib/strings.nix:669 in <nixpkgs>.

Parse a string as an int.

toInt "1337"
=> 1337
toInt "-4"
=> -4
toInt "3.14"
=> error: floating point JSON numbers are not supported

Located at lib/strings.nix:690 in <nixpkgs>.

Read a list of paths from `file`, relative to the `rootPath`. Lines beginning with `#` are treated as comments and ignored. Whitespace is significant.

NOTE: This function is not performant and should be avoided.

readPathsFromFile /prefix
./pkgs/development/libraries/qt-5/5.4/qtbase/series
=> [ "/prefix/dlopen-resolv.patch" "/prefix/tzdir.patch"
"/prefix/dlopen-libXcursor.patch" "/prefix/dlopen-openssl.patch"
"/prefix/dlopen-dbus.patch" "/prefix/xdg-config-dirs.patch"
"/prefix/nix-profiles-library-paths.patch"
"/prefix/compose-search-path.patch" ]

Located at lib/strings.nix:711 in <nixpkgs>.

Read the contents of a file removing the trailing \n

$ echo "1.0" > ./version

fileContents ./version
=> "1.0"

Located at lib/strings.nix:731 in <nixpkgs>.

Creates a valid derivation name from a potentially invalid one.

sanitizeDerivationName "../hello.bar # foo"
=> "-hello.bar-foo"
sanitizeDerivationName ""
=> "unknown"
sanitizeDerivationName pkgs.hello
=> "-nix-store-2g75chlbpxlrqn15zlby2dfh8hr9qwbk-hello-2.10"

Located at lib/strings.nix:746 in <nixpkgs>.

The identity function For when you need a function that does “nothing”.

Located at lib/trivial.nix:12 in <nixpkgs>.

The constant function

Ignores the second argument. If called with only one argument, constructs a function that always returns a static value.

let f = const 5; in f 10
=> 5

Located at lib/trivial.nix:26 in <nixpkgs>.

Pipes a value through a list of functions, left to right.

pipe 2 [
(x: x + 2)  # 2 + 2 = 4
(x: x * 2)  # 4 * 2 = 8
]
=> 8

# ideal to do text transformations
pipe [ "a/b" "a/c" ] [

# create the cp command
(map (file: ''cp "${src}/${file}" $out\n''))

# concatenate all commands into one string
lib.concatStrings

# make that string into a nix derivation
(pkgs.runCommand "copy-to-out" {})

]
=> <drv which copies all files to $out>

The output type of each function has to be the input type
of the next function, and the last function returns the
final value.

Located at lib/trivial.nix:61 in <nixpkgs>.

note please don’t add a function like `compose = flip pipe`. This would confuse users, because the order of the functions in the list is not clear. With pipe, it’s obvious that it goes first-to-last. With `compose`, not so much.

Located at lib/trivial.nix:80 in <nixpkgs>.

boolean “or”

Located at lib/trivial.nix:83 in <nixpkgs>.

boolean “and”

Located at lib/trivial.nix:86 in <nixpkgs>.

bitwise “and”

Located at lib/trivial.nix:89 in <nixpkgs>.

bitwise “or”

Located at lib/trivial.nix:94 in <nixpkgs>.

bitwise “xor”

Located at lib/trivial.nix:99 in <nixpkgs>.

bitwise “not”

Located at lib/trivial.nix:104 in <nixpkgs>.

Convert a boolean to a string.

This function uses the strings "true" and "false" to represent boolean values. Calling `toString` on a bool instead returns "1" and "" (sic!).

Located at lib/trivial.nix:114 in <nixpkgs>.

Merge two attribute sets shallowly, right side trumps left

mergeAttrs :: attrs -> attrs -> attrs

mergeAttrs { a = 1; b = 2; } { b = 3; c = 4; }
=> { a = 1; b = 3; c = 4; }

Located at lib/trivial.nix:124 in <nixpkgs>.

Flip the order of the arguments of a binary function.

flip concat [1] [2]
=> [ 2 1 ]

Located at lib/trivial.nix:138 in <nixpkgs>.

Apply function if the supplied argument is non-null.

mapNullable (x: x+1) null
=> null
mapNullable (x: x+1) 22
=> 23

Located at lib/trivial.nix:148 in <nixpkgs>.

Returns the current full nixpkgs version number.

Located at lib/trivial.nix:164 in <nixpkgs>.

Returns the current nixpkgs release number as string.

Located at lib/trivial.nix:167 in <nixpkgs>.

Returns the current nixpkgs release code name.

On each release the first letter is bumped and a new animal is chosen starting with that new letter.

Located at lib/trivial.nix:174 in <nixpkgs>.

Returns the current nixpkgs version suffix as string.

Located at lib/trivial.nix:177 in <nixpkgs>.

Attempts to return the the current revision of nixpkgs and returns the supplied default value otherwise.

Located at lib/trivial.nix:188 in <nixpkgs>.

Determine whether the function is being called from inside a Nix shell.

Located at lib/trivial.nix:206 in <nixpkgs>.

Return minimum of two numbers.

Located at lib/trivial.nix:212 in <nixpkgs>.

Return maximum of two numbers.

Located at lib/trivial.nix:215 in <nixpkgs>.

Integer modulus

mod 11 10
=> 1
mod 1 10
=> 1

Located at lib/trivial.nix:225 in <nixpkgs>.

C-style comparisons

a < b, compare a b => -1 a == b, compare a b => 0 a > b, compare a b => 1

Located at lib/trivial.nix:236 in <nixpkgs>.

Split type into two subtypes by predicate `p`, take all elements of the first subtype to be less than all the elements of the second subtype, compare elements of a single subtype with `yes` and `no` respectively.

let cmp = splitByAndCompare (hasPrefix "foo") compare compare; in

cmp "a" "z" => -1
cmp "fooa" "fooz" => -1

cmp "f" "a" => 1
cmp "fooa" "a" => -1
# while
compare "fooa" "a" => 1

Located at lib/trivial.nix:261 in <nixpkgs>.

Reads a JSON file.

Type :: path -> any

Located at lib/trivial.nix:281 in <nixpkgs>.

Reads a TOML file.

Type :: path -> any

Located at lib/trivial.nix:288 in <nixpkgs>.

Add metadata about expected function arguments to a function. The metadata should match the format given by builtins.functionArgs, i.e. a set from expected argument to a bool representing whether that argument has a default or not. setFunctionArgs : (a → b) → Map String Bool → (a → b)

This function is necessary because you can't dynamically create a function of the { a, b ? foo, ... }: format, but some facilities like callPackage expect to be able to query expected arguments.

Located at lib/trivial.nix:325 in <nixpkgs>.

Extract the expected function arguments from a function. This works both with nix-native { a, b ? foo, ... }: style functions and functions with args set with 'setFunctionArgs'. It has the same return type and semantics as builtins.functionArgs. setFunctionArgs : (a → b) → Map String Bool.

Located at lib/trivial.nix:337 in <nixpkgs>.

Check whether something is a function or something annotated with function args.

Located at lib/trivial.nix:345 in <nixpkgs>.

Convert the given positive integer to a string of its hexadecimal representation. For example:

toHexString 0 => "0"

toHexString 16 => "10"

toHexString 250 => "FA"

Located at lib/trivial.nix:357 in <nixpkgs>.

`toBaseDigits base i` converts the positive integer i to a list of its digits in the given base. For example:

toBaseDigits 10 123 => [ 1 2 3 ]

toBaseDigits 2 6 => [ 1 1 0 ]

toBaseDigits 16 250 => [ 15 10 ]

Located at lib/trivial.nix:383 in <nixpkgs>.

Create a list consisting of a single element. `singleton x` is sometimes more convenient with respect to indentation than `[x]` when x spans multiple lines.

singleton "foo"
=> [ "foo" ]

Located at lib/lists.nix:22 in <nixpkgs>.

Apply the function to each element in the list. Same as `map`, but arguments flipped.

forEach [ 1 2 ] (x:
toString x
)
=> [ "1" "2" ]

Located at lib/lists.nix:35 in <nixpkgs>.

“right fold” a binary function `op` between successive elements of `list` with `nul' as the starting value, i.e., `foldr op nul [x_1 x_2 ... x_n] == op x_1 (op x_2 ... (op x_n nul))`.

concat = foldr (a: b: a + b) "z"
concat [ "a" "b" "c" ]
=> "abcz"
# different types
strange = foldr (int: str: toString (int + 1) + str) "a"
strange [ 1 2 3 4 ]
=> "2345a"

Located at lib/lists.nix:52 in <nixpkgs>.

`fold` is an alias of `foldr` for historic reasons

Located at lib/lists.nix:63 in <nixpkgs>.

“left fold”, like `foldr`, but from the left: `foldl op nul [x_1 x_2 ... x_n] == op (... (op (op nul x_1) x_2) ... x_n)`.

lconcat = foldl (a: b: a + b) "z"
lconcat [ "a" "b" "c" ]
=> "zabc"
# different types
lstrange = foldl (str: int: str + toString (int + 1)) "a"
lstrange [ 1 2 3 4 ]
=> "a2345"

Located at lib/lists.nix:80 in <nixpkgs>.

Strict version of `foldl`.

The difference is that evaluation is forced upon access. Usually used with small whole results (in contrast with lazily-generated list or large lists where only a part is consumed.)

Located at lib/lists.nix:96 in <nixpkgs>.

Map with index starting from 0

imap0 (i: v: "${v}-${toString i}") ["a" "b"]
=> [ "a-0" "b-1" ]

Located at lib/lists.nix:106 in <nixpkgs>.

Map with index starting from 1

imap1 (i: v: "${v}-${toString i}") ["a" "b"]
=> [ "a-1" "b-2" ]

Located at lib/lists.nix:116 in <nixpkgs>.

Map and concatenate the result.

concatMap (x: [x] ++ ["z"]) ["a" "b"]
=> [ "a" "z" "b" "z" ]

Located at lib/lists.nix:126 in <nixpkgs>.

Flatten the argument into a single list; that is, nested lists are spliced into the top-level lists.

flatten [1 [2 [3] 4] 5]
=> [1 2 3 4 5]
flatten 1
=> [1]

Located at lib/lists.nix:137 in <nixpkgs>.

Remove elements equal to 'e' from a list. Useful for buildInputs.

remove 3 [ 1 3 4 3 ]
=> [ 1 4 ]

Located at lib/lists.nix:150 in <nixpkgs>.

Find the sole element in the list matching the specified predicate, returns `default` if no such element exists, or `multiple` if there are multiple matching elements.

findSingle (x: x == 3) "none" "multiple" [ 1 3 3 ]
=> "multiple"
findSingle (x: x == 3) "none" "multiple" [ 1 3 ]
=> 3
findSingle (x: x == 3) "none" "multiple" [ 1 9 ]
=> "none"

Located at lib/lists.nix:168 in <nixpkgs>.

Find the first element in the list matching the specified predicate or return `default` if no such element exists.

findFirst (x: x > 3) 7 [ 1 6 4 ]
=> 6
findFirst (x: x > 9) 7 [ 1 6 4 ]
=> 7

Located at lib/lists.nix:193 in <nixpkgs>.

Return true if function `pred` returns true for at least one element of `list`.

any isString [ 1 "a" { } ]
=> true
any isString [ 1 { } ]
=> false

Located at lib/lists.nix:214 in <nixpkgs>.

Return true if function `pred` returns true for all elements of `list`.

all (x: x < 3) [ 1 2 ]
=> true
all (x: x < 3) [ 1 2 3 ]
=> false

Located at lib/lists.nix:227 in <nixpkgs>.

Count how many elements of `list` match the supplied predicate function.

count (x: x == 3) [ 3 2 3 4 6 ]
=> 2

Located at lib/lists.nix:238 in <nixpkgs>.

Return a singleton list or an empty list, depending on a boolean value. Useful when building lists with optional elements (e.g. `++ optional (system == "i686-linux") firefox').

optional true "foo"
=> [ "foo" ]
optional false "foo"
=> [ ]

Located at lib/lists.nix:254 in <nixpkgs>.

Return a list or an empty list, depending on a boolean value.

optionals true [ 2 3 ]
=> [ 2 3 ]
optionals false [ 2 3 ]
=> [ ]

Located at lib/lists.nix:266 in <nixpkgs>.

If argument is a list, return it; else, wrap it in a singleton list. If you're using this, you should almost certainly reconsider if there isn't a more "well-typed" approach.

toList [ 1 2 ]
=> [ 1 2 ]
toList "hi"
=> [ "hi "]

Located at lib/lists.nix:283 in <nixpkgs>.

Return a list of integers from `first' up to and including `last'.

range 2 4
=> [ 2 3 4 ]
range 3 2
=> [ ]

Located at lib/lists.nix:295 in <nixpkgs>.

Splits the elements of a list in two lists, `right` and `wrong`, depending on the evaluation of a predicate.

partition (x: x > 2) [ 5 1 2 3 4 ]
=> { right = [ 5 3 4 ]; wrong = [ 1 2 ]; }

Located at lib/lists.nix:314 in <nixpkgs>.

Splits the elements of a list into many lists, using the return value of a predicate. Predicate should return a string which becomes keys of attrset `groupBy' returns.

`groupBy'` allows to customise the combining function and initial value

groupBy (x: boolToString (x > 2)) [ 5 1 2 3 4 ]
=> { true = [ 5 3 4 ]; false = [ 1 2 ]; }
groupBy (x: x.name) [ {name = "icewm"; script = "icewm &";}
{name = "xfce";  script = "xfce4-session &";}
{name = "icewm"; script = "icewmbg &";}
{name = "mate";  script = "gnome-session &";}
]
=> { icewm = [ { name = "icewm"; script = "icewm &"; }
{ name = "icewm"; script = "icewmbg &"; } ];
mate  = [ { name = "mate";  script = "gnome-session &"; } ];
xfce  = [ { name = "xfce";  script = "xfce4-session &"; } ];
}

groupBy' builtins.add 0 (x: boolToString (x > 2)) [ 5 1 2 3 4 ]
=> { true = 12; false = 3; }

Located at lib/lists.nix:343 in <nixpkgs>.

Merges two lists of the same size together. If the sizes aren't the same the merging stops at the shortest. How both lists are merged is defined by the first argument.

zipListsWith (a: b: a + b) ["h" "l"] ["e" "o"]
=> ["he" "lo"]

Located at lib/lists.nix:363 in <nixpkgs>.

Merges two lists of the same size together. If the sizes aren't the same the merging stops at the shortest.

zipLists [ 1 2 ] [ "a" "b" ]
=> [ { fst = 1; snd = "a"; } { fst = 2; snd = "b"; } ]

Located at lib/lists.nix:382 in <nixpkgs>.

Reverse the order of the elements of a list.

reverseList [ "b" "o" "j" ]
=> [ "j" "o" "b" ]

Located at lib/lists.nix:393 in <nixpkgs>.

Depth-First Search (DFS) for lists `list != []`.

`before a b == true` means that `b` depends on `a` (there's an edge from `b` to `a`).

listDfs true hasPrefix [ "/home/user" "other" "/" "/home" ]
== { minimal = "/";                  # minimal element
visited = [ "/home/user" ];     # seen elements (in reverse order)
rest    = [ "/home" "other" ];  # everything else
}

listDfs true hasPrefix [ "/home/user" "other" "/" "/home" "/" ]
== { cycle   = "/";                  # cycle encountered at this element
loops   = [ "/" ];              # and continues to these elements
visited = [ "/" "/home/user" ]; # elements leading to the cycle (in reverse order)
rest    = [ "/home" "other" ];  # everything else

Located at lib/lists.nix:415 in <nixpkgs>.

Sort a list based on a partial ordering using DFS. This implementation is O(N^2), if your ordering is linear, use `sort` instead.

`before a b == true` means that `b` should be after `a` in the result.

toposort hasPrefix [ "/home/user" "other" "/" "/home" ]
== { result = [ "/" "/home" "/home/user" "other" ]; }

toposort hasPrefix [ "/home/user" "other" "/" "/home" "/" ]
== { cycle = [ "/home/user" "/" "/" ]; # path leading to a cycle
loops = [ "/" ]; }                # loops back to these elements

toposort hasPrefix [ "other" "/home/user" "/home" "/" ]
== { result = [ "other" "/" "/home" "/home/user" ]; }

toposort (a: b: a < b) [ 3 2 1 ] == { result = [ 1 2 3 ]; }

Located at lib/lists.nix:454 in <nixpkgs>.

Sort a list based on a comparator function which compares two elements and returns true if the first argument is strictly below the second argument. The returned list is sorted in an increasing order. The implementation does a quick-sort.

sort (a: b: a < b) [ 5 3 7 ]
=> [ 3 5 7 ]

Located at lib/lists.nix:482 in <nixpkgs>.

Compare two lists element-by-element.

compareLists compare [] []
=> 0
compareLists compare [] [ "a" ]
=> -1
compareLists compare [ "a" ] []
=> 1
compareLists compare [ "a" "b" ] [ "a" "c" ]
=> 1

Located at lib/lists.nix:511 in <nixpkgs>.

Sort list using "Natural sorting". Numeric portions of strings are sorted in numeric order.

naturalSort ["disk11" "disk8" "disk100" "disk9"]
=> ["disk8" "disk9" "disk11" "disk100"]
naturalSort ["10.46.133.149" "10.5.16.62" "10.54.16.25"]
=> ["10.5.16.62" "10.46.133.149" "10.54.16.25"]
naturalSort ["v0.2" "v0.15" "v0.0.9"]
=> [ "v0.0.9" "v0.2" "v0.15" ]

Located at lib/lists.nix:534 in <nixpkgs>.

Return the first (at most) N elements of a list.

take 2 [ "a" "b" "c" "d" ]
=> [ "a" "b" ]
take 2 [ ]
=> [ ]

Located at lib/lists.nix:552 in <nixpkgs>.

Remove the first (at most) N elements of a list.

drop 2 [ "a" "b" "c" "d" ]
=> [ "c" "d" ]
drop 2 [ ]
=> [ ]

Located at lib/lists.nix:566 in <nixpkgs>.

Return a list consisting of at most `count` elements of `list`, starting at index `start`.

sublist 1 3 [ "a" "b" "c" "d" "e" ]
=> [ "b" "c" "d" ]
sublist 1 3 [ ]
=> [ ]

Located at lib/lists.nix:583 in <nixpkgs>.

Return the last element of a list.

This function throws an error if the list is empty.

last [ 1 2 3 ]
=> 3

Located at lib/lists.nix:607 in <nixpkgs>.

Return all elements but the last.

This function throws an error if the list is empty.

init [ 1 2 3 ]
=> [ 1 2 ]

Located at lib/lists.nix:621 in <nixpkgs>.

Return the image of the cross product of some lists by a function.

crossLists (x:y: "${toString x}${toString y}") [[1 2] [3 4]]
=> [ "13" "14" "23" "24" ]

Located at lib/lists.nix:632 in <nixpkgs>.

Remove duplicate elements from the list. O(n^2) complexity.

unique [ 3 2 3 4 ]
=> [ 3 2 4 ]

Located at lib/lists.nix:645 in <nixpkgs>.

Intersects list 'e' and another list. O(nm) complexity.

intersectLists [ 1 2 3 ] [ 6 3 2 ]
=> [ 3 2 ]

Located at lib/lists.nix:653 in <nixpkgs>.

Subtracts list 'e' from another list. O(nm) complexity.

subtractLists [ 3 2 ] [ 1 2 3 4 5 3 ]
=> [ 1 4 5 ]

Located at lib/lists.nix:661 in <nixpkgs>.

Test if two lists have no common element. It should be slightly more efficient than (intersectLists a b == [])

Located at lib/lists.nix:666 in <nixpkgs>.

Conditionally trace the supplied message, based on a predicate.

traceIf true "hello" 3
trace: hello
=> 3

Located at lib/debug.nix:51 in <nixpkgs>.

Trace the supplied value after applying a function to it, and return the original value.

traceValFn (v: "mystring ${v}") "foo"
trace: mystring foo
=> "foo"

Located at lib/debug.nix:69 in <nixpkgs>.

Trace the supplied value and return it.

traceVal 42
# trace: 42
=> 42

Located at lib/debug.nix:84 in <nixpkgs>.

`builtins.trace`, but the value is `builtins.deepSeq`ed first.

trace { a.b.c = 3; } null
trace: { a = <CODE>; }
=> null
traceSeq { a.b.c = 3; } null
trace: { a = { b = { c = 3; }; }; }
=> null

Located at lib/debug.nix:98 in <nixpkgs>.

Like `traceSeq`, but only evaluate down to depth n. This is very useful because lots of `traceSeq` usages lead to an infinite recursion.

traceSeqN 2 { a.b.c = 3; } null
trace: { a = { b = {…}; }; }
=> null

Located at lib/debug.nix:113 in <nixpkgs>.

A combination of `traceVal` and `traceSeq` that applies a provided function to the value to be traced after `deepSeq`ing it.

Located at lib/debug.nix:130 in <nixpkgs>.

A combination of `traceVal` and `traceSeq`.

Located at lib/debug.nix:137 in <nixpkgs>.

A combination of `traceVal` and `traceSeqN` that applies a provided function to the value to be traced.

Located at lib/debug.nix:141 in <nixpkgs>.

A combination of `traceVal` and `traceSeqN`.

Located at lib/debug.nix:149 in <nixpkgs>.

Trace the input and output of a function `f` named `name`, both down to `depth`.

This is useful for adding around a function call, to see the before/after of values as they are transformed.

traceFnSeqN 2 "id" (x: x) { a.b.c = 3; }
trace: { fn = "id"; from = { a.b = {…}; }; to = { a.b = {…}; }; }
=> { a.b.c = 3; }

Located at lib/debug.nix:162 in <nixpkgs>.

Evaluate a set of tests. A test is an attribute set `{expr, expected}`, denoting an expression and its expected result. The result is a list of failed tests, each represented as `{name, expected, actual}`, denoting the attribute name of the failing test and its expected and actual results.

Used for regression testing of the functions in lib; see tests.nix for an example. Only tests having names starting with "test" are run.

Add attr { tests = ["testName"]; } to run these tests only.

Located at lib/debug.nix:188 in <nixpkgs>.

Create a test assuming that list elements are `true`.

{ testX = allTrue [ true ]; }

Located at lib/debug.nix:204 in <nixpkgs>.

Returns true when the given argument is an option

isOption 1             // => false
isOption (mkOption {}) // => true

Located at lib/options.nix:48 in <nixpkgs>.

Creates an Option attribute set. mkOption accepts an attribute set with the following keys:

All keys default to `null` when not given.

mkOption { }  // => { _type = "option"; }
mkOption { defaultText = "foo"; } // => { _type = "option"; defaultText = "foo"; }

Located at lib/options.nix:58 in <nixpkgs>.

Creates an Option attribute set for a boolean value option i.e an option to be toggled on or off:

mkEnableOption "foo"
=> { _type = "option"; default = false; description = "Whether to enable foo."; example = true; type = { ... }; }

Located at lib/options.nix:92 in <nixpkgs>.

This option accepts anything, but it does not produce any result.

This is useful for sharing a module across different module sets without having to implement similar features as long as the values of the options are not accessed.

Located at lib/options.nix:106 in <nixpkgs>.

"Merge" option definitions by checking that they all have the same value.

Located at lib/options.nix:137 in <nixpkgs>.

Extracts values of all "value" keys of the given list.

getValues [ { value = 1; } { value = 2; } ] // => [ 1 2 ]
getValues [ ]                               // => [ ]

Located at lib/options.nix:157 in <nixpkgs>.

Extracts values of all "file" keys of the given list

getFiles [ { file = "file1"; } { file = "file2"; } ] // => [ "file1" "file2" ]
getFiles [ ]                                         // => [ ]

Located at lib/options.nix:167 in <nixpkgs>.

This function recursively removes all derivation attributes from `x` except for the `name` attribute.

This is to make the generation of `options.xml` much more efficient: the XML representation of derivations is very large (on the order of megabytes) and is not actually used by the manual generator.

Located at lib/options.nix:206 in <nixpkgs>.

For use in the `example` option attribute. It causes the given text to be included verbatim in documentation. This is necessary for example values that are not simple values, e.g., functions.

Located at lib/options.nix:218 in <nixpkgs>.

Convert an option, described as a list of the option parts in to a safe, human readable version.

(showOption ["foo" "bar" "baz"]) == "foo.bar.baz"
(showOption ["foo" "bar.baz" "tux"]) == "foo.bar.baz.tux"

Placeholders will not be quoted as they are not actual values:
(showOption ["foo" "*" "bar"]) == "foo.*.bar"
(showOption ["foo" "<name>" "bar"]) == "foo.<name>.bar"

Unlike attributes, options can also start with numbers:
(showOption ["windowManager" "2bwm" "enable"]) == "windowManager.2bwm.enable"

Located at lib/options.nix:240 in <nixpkgs>.

A list of dependencies whose host and target platforms are the new derivation’s build platform. This means a -1 host and -1 target offset from the new derivation’s platforms. These are programs and libraries used at build time that produce programs and libraries also used at build time. If the dependency doesn’t care about the target platform (i.e. isn’t a compiler or similar tool), put it in nativeBuildInputs instead. The most common use of this buildPackages.stdenv.cc, the default C compiler for this role. That example crops up more than one might think in old commonly used C libraries.

Since these packages are able to be run at build-time, they are always added to the PATH, as described above. But since these packages are only guaranteed to be able to run then, they shouldn’t persist as run-time dependencies. This isn’t currently enforced, but could be in the future.

A list of dependencies whose host platform is the new derivation’s build platform, and target platform is the new derivation’s host platform. This means a -1 host offset and 0 target offset from the new derivation’s platforms. These are programs and libraries used at build-time that, if they are a compiler or similar tool, produce code to run at run-time—i.e. tools used to build the new derivation. If the dependency doesn’t care about the target platform (i.e. isn’t a compiler or similar tool), put it here, rather than in depsBuildBuild or depsBuildTarget. This could be called depsBuildHost but nativeBuildInputs is used for historical continuity.

Since these packages are able to be run at build-time, they are added to the PATH, as described above. But since these packages are only guaranteed to be able to run then, they shouldn’t persist as run-time dependencies. This isn’t currently enforced, but could be in the future.

A list of dependencies whose host platform is the new derivation’s build platform, and target platform is the new derivation’s target platform. This means a -1 host offset and 1 target offset from the new derivation’s platforms. These are programs used at build time that produce code to run with code produced by the depending package. Most commonly, these are tools used to build the runtime or standard library that the currently-being-built compiler will inject into any code it compiles. In many cases, the currently-being-built-compiler is itself employed for that task, but when that compiler won’t run (i.e. its build and host platform differ) this is not possible. Other times, the compiler relies on some other tool, like binutils, that is always built separately so that the dependency is unconditional.

This is a somewhat confusing concept to wrap one’s head around, and for good reason. As the only dependency type where the platform offsets are not adjacent integers, it requires thinking of a bootstrapping stage two away from the current one. It and its use-case go hand in hand and are both considered poor form: try to not need this sort of dependency, and try to avoid building standard libraries and runtimes in the same derivation as the compiler produces code using them. Instead strive to build those like a normal library, using the newly-built compiler just as a normal library would. In short, do not use this attribute unless you are packaging a compiler and are sure it is needed.

Since these packages are able to run at build time, they are added to the PATH, as described above. But since these packages are only guaranteed to be able to run then, they shouldn’t persist as run-time dependencies. This isn’t currently enforced, but could be in the future.

A list of dependencies whose host and target platforms match the new derivation’s host platform. This means a 0 host offset and 0 target offset from the new derivation’s host platform. These are packages used at run-time to generate code also used at run-time. In practice, this would usually be tools used by compilers for macros or a metaprogramming system, or libraries used by the macros or metaprogramming code itself. It’s always preferable to use a depsBuildBuild dependency in the derivation being built over a depsHostHost on the tool doing the building for this purpose.

A list of dependencies whose host platform and target platform match the new derivation’s. This means a 0 host offset and a 1 target offset from the new derivation’s host platform. This would be called depsHostTarget but for historical continuity. If the dependency doesn’t care about the target platform (i.e. isn’t a compiler or similar tool), put it here, rather than in depsBuildBuild.

These are often programs and libraries used by the new derivation at run-time, but that isn’t always the case. For example, the machine code in a statically-linked library is only used at run-time, but the derivation containing the library is only needed at build-time. Even in the dynamic case, the library may also be needed at build-time to appease the linker.

A list of dependencies whose host platform matches the new derivation’s target platform. This means a 1 offset from the new derivation’s platforms. These are packages that run on the target platform, e.g. the standard library or run-time deps of standard library that a compiler insists on knowing about. It’s poor form in almost all cases for a package to depend on another from a future stage [future stage corresponding to positive offset]. Do not use this attribute unless you are packaging a compiler and are sure it is needed.

The propagated equivalent of depsBuildBuild. This perhaps never ought to be used, but it is included for consistency [see below for the others].

The propagated equivalent of nativeBuildInputs. This would be called depsBuildHostPropagated but for historical continuity. For example, if package Y has propagatedNativeBuildInputs = [X], and package Z has buildInputs = [Y], then package Z will be built as if it included package X in its nativeBuildInputs. If instead, package Z has nativeBuildInputs = [Y], then Z will be built as if it included X in the depsBuildBuild of package Z, because of the sum of the two -1 host offsets.

The propagated equivalent of depsBuildTarget. This is prefixed for the same reason of alerting potential users.

The propagated equivalent of depsHostHost.

The propagated equivalent of buildInputs. This would be called depsHostTargetPropagated but for historical continuity.

The propagated equivalent of depsTargetTarget. This is prefixed for the same reason of alerting potential users.

A natural number indicating how much information to log. If set to 1 or higher, stdenv will print moderate debugging information during the build. In particular, the gcc and ld wrapper scripts will print out the complete command line passed to the wrapped tools. If set to 6 or higher, the stdenv setup script will be run with set -x tracing. If set to 7 or higher, the gcc and ld wrapper scripts will also be run with set -x tracing.

If set to true, stdenv will pass specific flags to make and other build tools to enable parallel building with up to build-cores workers.

Unless set to false, some build systems with good support for parallel building including cmake, meson, and qmake will set it to true.

This is an attribute set which can be filled with arbitrary values. For example:

passthru = {
  foo = "bar";
  baz = {
    value1 = 4;
    value2 = 5;
  };
}

Values inside it are not passed to the builder, so you can change them without triggering a rebuild. However, they can be accessed outside of a derivation directly, as if they were set inside a derivation itself, e.g. hello.baz.value1. We don’t specify any usage or schema of passthru - it is meant for values that would be useful outside the derivation in other parts of a Nix expression (e.g. in other derivations). An example would be to convey some specific dependency of your derivation which contains a program with plugins support. Later, others who make derivations with plugins can use passed-through dependency to ensure that their plugin would be binary-compatible with built program.

A script to be run by maintainers/scripts/update.nix when the package is matched. It needs to be an executable file, either on the file system:

passthru.updateScript = ./update.sh;

or inside the expression itself:

passthru.updateScript = writeScript "update-zoom-us" ''
  #!/usr/bin/env nix-shell
  #!nix-shell -i bash -p curl pcre common-updater-scripts

  set -eu -o pipefail

  version="$(curl -sI https://zoom.us/client/latest/zoom_x86_64.tar.xz | grep -Fi 'Location:' | pcregrep -o1 '/(([0-9]\.?)+)/')"
  update-source-version zoom-us "$version"
'';

The attribute can also contain a list, a script followed by arguments to be passed to it:

passthru.updateScript = [ ../../update.sh pname "--requested-release=unstable" ];

The script will be run with UPDATE_NIX_ATTR_PATH environment variable set to the attribute path it is supposed to update.

For information about how to run the updates, execute nix-shell maintainers/scripts/update.nix.

These can optionally be compressed using gzip (.tar.gz, .tgz or .tar.Z), bzip2 (.tar.bz2, .tbz2 or .tbz) or xz (.tar.xz, .tar.lzma or .txz).

Zip files are unpacked using unzip. However, unzip is not in the standard environment, so you should add it to nativeBuildInputs yourself.

These are simply copied to the current directory. The hash part of the file name is stripped, e.g. /nix/store/1wydxgby13cz...-my-sources would be copied to my-sources.

Additional file types can be supported by setting the unpackCmd variable (see below).