max/nix-super
1
0
Fork 0
mirror of https://github.com/privatevoid-net/nix-super.git synced 2024-11-22 22:16:16 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

Expand derivation examples (#9048)

Browse source 
Also use fancier formatting so the example blocks are easier to discern
from the description.

Co-authored-by: John Ericson <git@JohnEricson.me>
This commit is contained in:
Valentin Gagarin 2023-10-20 21:17:28 +02:00 committed by GitHub
parent 7d3cd54282
commit 97a0c08873
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
2 changed files with 162 additions and 53 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
doc/manual/src/glossary.md
View file

@ -207,6 +207,7 @@
- [output]{#gloss-output} - [output]{#gloss-output}
A [store object] produced by a [derivation]. A [store object] produced by a [derivation].
See [the `outputs` argument to the `derivation` function](@docroot@/language/derivations.md#attr-outputs) for details.
[output]: #gloss-output [output]: #gloss-output

214
doc/manual/src/language/derivations.md
View file

@ -8,8 +8,6 @@ It outputs an attribute set, and produces a [store derivation] as a side effect
[store derivation]: @docroot@/glossary.md#gloss-store-derivation [store derivation]: @docroot@/glossary.md#gloss-store-derivation
<!-- FIXME: add a section on output attributes -->
## Input attributes ## Input attributes
### Required ### Required
@ -17,11 +15,22 @@ It outputs an attribute set, and produces a [store derivation] as a side effect
- [`name`]{#attr-name} ([String](@docroot@/language/values.md#type-string)) - [`name`]{#attr-name} ([String](@docroot@/language/values.md#type-string))
A symbolic name for the derivation. A symbolic name for the derivation.
It is added to the [store derivation]'s [path](@docroot@/glossary.md#gloss-store-path) and its [output paths][output path]. It is added to the [store path] of the corresponding [store derivation] as well as to its [output paths](@docroot@/glossary.md#gloss-output-path).
Example: `name = "hello";` [store path]: @docroot@/glossary.md#gloss-store-path
> **Example**
>
> ```nix
> derivation {
> name = "hello";
> # ...
> }
> ```
>
> The store derivation's path will be `/nix/store/<hash>-hello.drv`.
> The [output](#attr-outputs) paths will be of the form `/nix/store/<hash>-hello[-<output>]`
The store derivation's path will be `/nix/store/<hash>-hello.drv`, and the output paths will be of the form `/nix/store/<hash>-hello[-<output>]`
- [`system`]{#attr-system} ([String](@docroot@/language/values.md#type-string)) - [`system`]{#attr-system} ([String](@docroot@/language/values.md#type-string))
The system type on which the [`builder`](#attr-builder) executable is meant to be run. The system type on which the [`builder`](#attr-builder) executable is meant to be run.
@ -29,77 +38,175 @@ It outputs an attribute set, and produces a [store derivation] as a side effect
A necessary condition for Nix to build derivations locally is that the `system` attribute matches the current [`system` configuration option]. A necessary condition for Nix to build derivations locally is that the `system` attribute matches the current [`system` configuration option].
It can automatically [build on other platforms](../advanced-topics/distributed-builds.md) by forwarding build requests to other machines. It can automatically [build on other platforms](../advanced-topics/distributed-builds.md) by forwarding build requests to other machines.
Examples:
`system = "x86_64-linux";`
`system = builtins.currentSystem;`
[`builtins.currentSystem`](@docroot@/language/builtin-constants.md#builtins-currentSystem) has the value of the [`system` configuration option], and defaults to the system type of the current Nix installation.
[`system` configuration option]: @docroot@/command-ref/conf-file.md#conf-system [`system` configuration option]: @docroot@/command-ref/conf-file.md#conf-system
> **Example**
>
> Declare a derivation to be built on a specific system type:
>
> ```nix
> derivation {
> # ...
> system = "x86_64-linux";
> # ...
> }
> ```
> **Example**
>
> Declare a derivation to be built on the system type that evaluates the expression:
>
> ```nix
> derivation {
> # ...
> system = builtins.currentSystem;
> # ...
> }
> ```
>
> [`builtins.currentSystem`](@docroot@/language/builtin-constants.md#builtins-currentSystem) has the value of the [`system` configuration option], and defaults to the system type of the current Nix installation.
- [`builder`]{#attr-builder} ([Path](@docroot@/language/values.md#type-path) | [String](@docroot@/language/values.md#type-string)) - [`builder`]{#attr-builder} ([Path](@docroot@/language/values.md#type-path) | [String](@docroot@/language/values.md#type-string))
Path to an executable that will perform the build. Path to an executable that will perform the build.
Examples: > **Example**
>
> Use the file located at `/bin/bash` as the builder executable:
>
> ```nix
> derivation {
> # ...
> builder = "/bin/bash";
> # ...
> };
> ```
`builder = "/bin/bash";` <!-- -->
`builder = ./builder.sh;` > **Example**
>
> Copy a local file to the Nix store for use as the builder executable:
>
> ```nix
> derivation {
> # ...
> builder = ./builder.sh;
> # ...
> };
> ```
`builder = "${pkgs.python}/bin/python";` <!-- -->
> **Example**
>
> Use a file from another derivation as the builder executable:
>
> ```nix
> let pkgs = import <nixpkgs> {}; in
> derivation {
> # ...
> builder = "${pkgs.python}/bin/python";
> # ...
> };
> ```
### Optional ### Optional
- [`args`]{#attr-args} ([List](@docroot@/language/values.md#list) of [String](@docroot@/language/values.md#type-string)) Default: `[ ]` - [`args`]{#attr-args} ([List](@docroot@/language/values.md#list) of [String](@docroot@/language/values.md#type-string))
Default: `[ ]`
Command-line arguments to be passed to the [`builder`](#attr-builder) executable. Command-line arguments to be passed to the [`builder`](#attr-builder) executable.
Example: `args = [ "-c" "echo hello world > $out" ];` > **Example**
>
> Pass arguments to Bash to interpret a shell command:
>
> ```nix
> derivation {
> # ...
> builder = "/bin/bash";
> args = [ "-c" "echo hello world > $out" ];
> # ...
> };
> ```
- [`outputs`]{#attr-outputs} ([List](@docroot@/language/values.md#list) of [String](@docroot@/language/values.md#type-string)) Default: `[ "out" ]` - [`outputs`]{#attr-outputs} ([List](@docroot@/language/values.md#list) of [String](@docroot@/language/values.md#type-string))
Default: `[ "out" ]`
Symbolic outputs of the derivation. Symbolic outputs of the derivation.
Each output name is passed to the [`builder`](#attr-builder) executable as an environment variable with its value set to the corresponding [output path]. Each output name is passed to the [`builder`](#attr-builder) executable as an environment variable with its value set to the corresponding [store path].
[output path]: @docroot@/glossary.md#gloss-output-path By default, a derivation produces a single output called `out`.
However, derivations can produce multiple outputs.
By default, a derivation produces a single output path called `out`.
However, derivations can produce multiple output paths.
This allows the associated [store objects](@docroot@/glossary.md#gloss-store-object) and their [closures](@docroot@/glossary.md#gloss-closure) to be copied or garbage-collected separately. This allows the associated [store objects](@docroot@/glossary.md#gloss-store-object) and their [closures](@docroot@/glossary.md#gloss-closure) to be copied or garbage-collected separately.
Examples: > **Example**
>
> Imagine a library package that provides a dynamic library, header files, and documentation.
> A program that links against such a library doesn’t need the header files and documentation at runtime, and it doesn’t need the documentation at build time.
> Thus, the library package could specify:
>
> ```nix
> derivation {
> # ...
> outputs = [ "lib" "dev" "doc" ];
> # ...
> }
> ```
>
> This will cause Nix to pass environment variables `lib`, `dev`, and `doc` to the builder containing the intended store paths of each output.
> The builder would typically do something like
>
> ```bash
> ./configure \
> --libdir=$lib/lib \
> --includedir=$dev/include \
> --docdir=$doc/share/doc
> ```
>
> for an Autoconf-style package.
Imagine a library package that provides a dynamic library, header files, and documentation. The name of an output is combined with the name of the derivation to create the name part of the output's store path, unless it is `out`, in which case just the name of the derivation is used.
A program that links against such a library doesn’t need the header files and documentation at runtime, and it doesn’t need the documentation at build time.
Thus, the library package could specify:
```nix > **Example**
derivation { >
# ... >
outputs = [ "lib" "dev" "doc" ]; > ```nix
# ... > derivation {
} > name = "example";
``` > outputs = [ "lib" "dev" "doc" "out" ];
> # ...
> }
> ```
>
> The store derivation path will be `/nix/store/<hash>-example.drv`.
> The output paths will be
> - `/nix/store/<hash>-example-lib`
> - `/nix/store/<hash>-example-dev`
> - `/nix/store/<hash>-example-doc`
> - `/nix/store/<hash>-example`
This will cause Nix to pass environment variables `lib`, `dev`, and `doc` to the builder containing the intended store paths of each output. You can refer to each output of a derivation by selecting it as an attribute.
The builder would typically do something like The first element of `outputs` determines the *default output* and ends up at the top-level.
```bash > **Example**
./configure \ >
--libdir=$lib/lib \ > Select an output by attribute name:
--includedir=$dev/include \ >
--docdir=$doc/share/doc > ```nix
``` > let
> myPackage = derivation {
for an Autoconf-style package. > name = "example";
> outputs = [ "lib" "dev" "doc" "out" ];
You can refer to each output of a derivation by selecting it as an attribute, e.g. `myPackage.lib` or `myPackage.doc`. > # ...
> };
The first element of `outputs` determines the *default output*. > in myPackage.dev
Therefore, in the given example, `myPackage` is equivalent to `myPackage.lib`. > ```
>
> Since `lib` is the first output, `myPackage` is equivalent to `myPackage.lib`.
<!-- FIXME: refer to the output attributes when we have one --> <!-- FIXME: refer to the output attributes when we have one -->
@ -123,8 +230,7 @@ It outputs an attribute set, and produces a [store derivation] as a side effect
reside in the Nix store. reside in the Nix store.
- A *derivation* causes that derivation to be built prior to the - A *derivation* causes that derivation to be built prior to the
present derivation; its default output path is put in the present derivation. The environment variable is set to the [store path] of the derivation's default [output](#attr-outputs).
environment variable.
- Lists of the previous types are also allowed. They are simply - Lists of the previous types are also allowed. They are simply
concatenated, separated by spaces. concatenated, separated by spaces.
@ -132,6 +238,8 @@ It outputs an attribute set, and produces a [store derivation] as a side effect
- `true` is passed as the string `1`, `false` and `null` are - `true` is passed as the string `1`, `false` and `null` are
passed as an empty string. passed as an empty string.
<!-- FIXME: add a section on output attributes -->
## Builder execution ## Builder execution
The [`builder`](#attr-builder) is executed as follows: The [`builder`](#attr-builder) is executed as follows: