Derivation Outputs and Environment Variables

> 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. 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. > **Example** > > > ```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` You can refer to each output of a derivation by selecting it as an attribute. The first element of `outputs` determines the *default output* and ends up at the top-level. > **Example** > > Select an output by attribute name: > > ```nix > let > myPackage = derivation { > name = "example"; > outputs = [ "lib" "dev" "doc" "out" ]; > # ... > }; > in myPackage.dev > ``` > > Since `lib` is the first output, `myPackage` is equivalent to `myPackage.lib`.  - See [Advanced Attributes](./advanced-attributes.md) for more, infrequently used, optional attributes.  - Every other attribute is passed as an environment variable to the builder. Attribute values are translated to environment variables as follows: - Strings are passed unchanged. - Integral numbers are converted to decimal notation. - Floating point numbers are converted to simple decimal or scientific notation with a preset precision. - A *path* (e.g., `../foo/sources.tar`) causes the referenced file to be copied to the store; its location in the store is put in the environment variable. The idea is that all sources should reside in the Nix store, since all inputs to a derivation should reside in the Nix store. - A *derivation* causes that derivation to be built prior to the present derivation. The environment variable is set to the [store path] of the derivation's default [output](#attr-outputs). - Lists of the previous types are also allowed. They are simply concatenated, separated by spaces. - `true` is passed as the string `1`, `false` and `null` are passed as an empty string.

This section elaborates on the `outputs` attribute of a Nix derivation, explaining how it defines the output paths and how these outputs can be accessed and used. It also explains that all other attributes in a derivation are passed as environment variables to the builder, with specific rules for how different data types (strings, numbers, paths, derivations, lists, booleans, and nulls) are translated into environment variable values. Paths are copied to the store, derivations are built, and lists are concatenated with spaces.