Want to see more Nix documentation like this in the future, or have requests/suggestions? Fill out this anonymous Google form or submit an issue on GitHub.

derivation

function

The built-in function for creating derivations.

Inputs

Output

derivation

Reference

Inputs

name

string, required

The derivation name.

A name must be a non-empty string consisting only of alphanumeric characters and the symbols +-._?=. Names must not begin with a period.

system

string, required

A platform identifier.

The resulting derivation can only be built on a machine with a matching platform identifier. Platform identifiers should be specified in Clang target-triple format.

Valid platform identifiers include:

• i386-linux

• x86_64-darwin

• armv7-linux-androideabi

The current platform identifier can be retrieved using builtins.currentSystem.

Example

derivation {
  name = "hello";
  system = builtins.currentSystem;
  builder = ./builder.sh;
}

builder

path | derivation, required

An executable file used build the derivation.

When the derivation is built, the builder is executed in an isolated temporary directory.

Arguments

The builder is passed any command-line arguments from args.

Environment Variables

Every input attribute is available to the builder as an environment variable. Each attribute value is translated to a string before it is stored.

Values are translated as follows:

• string, number: copied verbatim.

• path: the referenced file is copied to the store, and the environment variable is set to the resulting store location.

• derivation: the derivation is built and the environment variable is set to the derivation's default output path.

• list[string | number | path | derivation]: each item is translated individually, and the environment variable is set to the space-separated concatenation of the results.

• bool: true is translated to 1 and false: is translated to the empty string.

• null: translated to the empty string.

• For each item of outputs there is an environment variable of the same name that is set to the store path for that output.

Outputs

The builder must create a file or directory for each item in outputs. If outputs is omitted then it will default to ["out"].

Examples

# builder.sh
#! /bin/sh
echo "hello" > $out

derivation {
  name = "hello";
  system = builtins.currentSystem;
  builder = ./builder.sh;
}

# builder.sh
#! /bin/sh
echo "hello" > $one
echo "goodbye" > $two

derivation {
name = "hello-goodbye";
  system = builtins.currentSystem;
  builder = ./builder.sh;
  outputs = ["one" "two"];
}

args

list[string], optional

A list of command line arguments to be passed to the builder.

The list items can be any value that is convertible to a string. See builder for how these values are translated.

Example

# builder.sh
#! /bin/sh
echo $1
echo $2

derivation {
  name = "say-hello-world";
  system = builtins.currentSystem;
  builder = ./builder.sh;
  args = ["hello" "world"];
}

outputs

list[string], optional

A list of outputs from the derivation. Defaults to ["out"].

The derivation will produce one store path per output.This allows the outputs to be downloaded and garbage collected separately.

Example

# builder.sh
#! /bin/sh
echo "hello" > $one
echo "world" > $two

derivation {
  name = "write-hello-world";
  system = builtins.currentSystem;
  builder = ./builder.sh;
  args = ["one" "two"];
}

user-defined attributes

The user may define any number of additional attributes.

Each user-defined attribute is converted to a string and made available to the builder through an environment variable. See builder for how these values are translated.

Example

# builder.sh
#! /bin/sh
echo "$result" > $out
echo "$count"
echo "$word"

derivation {
  name = "42-pelican";
  system = builtins.currentSystem;
  builder = ./builder.sh;
  result = [ "one" "two" 3 ];
  count = 42;
  word = "pelican";
}