wroclaw-git-backups/nix
1
0
Fork 0
mirror of https://github.com/NixOS/nix synced 2025-07-07 01:51:47 +02:00
Code Activity

Tagging release 2.27.1

Browse source 
-----BEGIN PGP SIGNATURE-----
 
 iQFHBAABCAAxFiEEtUHVUwEnDgvPFcpdgXC0cm1xmN4FAmfheacTHGVkb2xzdHJh
 QGdtYWlsLmNvbQAKCRCBcLRybXGY3kt2B/4tQvs6iDXA12d409ClHbVQjr1d0FLP
 rv8RxZ7Z4+Jaw8r2ra/I+gpr9juI5ULyEJWqfES72hTvbYPjH1Grsrrjak1tx57E
 +STs21oEPojE8LXsFH1oZamGPPIIpyQdxCvTgZs1N6cqUfCRQ3Jx97X6E6SIGJDR
 VqBM4ruSXCY57yT36HqwYydTkxzZHiNP5wwABGfSb7u9pYW5x3r8W7+fQ3udTnCw
 kCRhA5vnfxIQSlxu4j7dJqSCGzOIPnhYB19bXDV4aPhl4sn3pkBCdMZxPBlCWSwx
 it0ngMITf+TeiMpVl2TtvMBOHtlGrbhusbyKcsqzFYULGyGOC9ngTAY3
 =/JzB
 -----END PGP SIGNATURE-----

Merge tag '2.27.1' into detsys-main

Tagging release 2.27.1
This commit is contained in:
Eelco Dolstra 2025-03-24 21:28:03 +01:00
commit dab0ff4f9e
200 changed files with 4734 additions and 1977 deletions
Download patch file Download diff file Expand all files Collapse all files

4
doc/manual/redirects.js
View file

@ -342,6 +342,9 @@ const redirects = {
"scoping-rules": "scoping.html",
"string-literal": "string-literals.html",
},
"language/derivations.md": {
"builder-execution": "store/drv/building.md#builder-execution",
},
"installation/installing-binary.html": {
"linux": "uninstall.html#linux",
"macos": "uninstall.html#macos",
@ -368,6 +371,7 @@ const redirects = {
"glossary.html": {
"gloss-local-store": "store/types/local-store.html",
"gloss-chroot-store": "store/types/local-store.html",
"gloss-content-addressed-derivation": "#gloss-content-addressing-derivation",
},
};

6
doc/manual/source/SUMMARY.md.in
View file

@ -17,6 +17,11 @@
- [Store Object](store/store-object.md)
- [Content-Addressing Store Objects](store/store-object/content-address.md)
- [Store Path](store/store-path.md)
- [Store Derivation and Deriving Path](store/derivation/index.md)
- [Derivation Outputs and Types of Derivations](store/derivation/outputs/index.md)
- [Content-addressing derivation outputs](store/derivation/outputs/content-address.md)
- [Input-addressing derivation outputs](store/derivation/outputs/input-address.md)
- [Building](store/building.md)
- [Store Types](store/types/index.md)
{{#include ./store/types/SUMMARY.md}}
- [Nix Language](language/index.md)
@ -126,4 +131,5 @@
- [Release 1.0.0 (2025-??-??)](release-notes-determinate/rl-1.0.0.md)
- [Nix Release Notes](release-notes/index.md)
{{#include ./SUMMARY-rl-next.md}}
- [Release 2.27 (2025-03-03)](release-notes/rl-2.27.md)
- [Release 2.26 (2025-01-22)](release-notes/rl-2.26.md)

4
doc/manual/source/advanced-topics/distributed-builds.md
View file

@ -20,7 +20,7 @@ For a local machine to forward a build to a remote machine, the remote machine m
## Testing
To test connecting to a remote Nix instance (in this case `mac`), run:
To test connecting to a remote [Nix instance] (in this case `mac`), run:
```console
nix store info --store ssh://username@mac
@ -106,3 +106,5 @@ file included in `builders` via the syntax `@/path/to/file`. For example,
causes the list of machines in `/etc/nix/machines` to be included.
(This is the default.)
[Nix instance]: @docroot@/glossary.md#gloss-nix-instance

2
doc/manual/source/architecture/architecture.md
View file

@ -69,7 +69,7 @@ It can also execute build plans to produce new data, which are made available to
A build plan itself is a series of *build tasks*, together with their build inputs.
> **Important**
> A build task in Nix is called [derivation](@docroot@/glossary.md#gloss-derivation).
> A build task in Nix is called [store derivation](@docroot@/glossary.md#gloss-store-derivation).
Each build task has a special build input executed as *build instructions* in order to perform the build.
The result of a build task can be input to another build task.

12
doc/manual/source/command-ref/nix-env/install.md
View file

@ -22,11 +22,11 @@ It is based on the current generation of the active [profile](@docroot@/command-
The arguments *args* map to store paths in a number of possible ways:
- By default, *args* is a set of [derivation] names denoting derivations in the default Nix expression.
- By default, *args* is a set of names denoting derivations in the default Nix expression.
These are [realised], and the resulting output paths are installed.
Currently installed derivations with a name equal to the name of a derivation being added are removed unless the option `--preserve-installed` is specified.
[derivation]: @docroot@/glossary.md#gloss-derivation
[derivation expression]: @docroot@/glossary.md#gloss-derivation-expression
[realised]: @docroot@/glossary.md#gloss-realise
If there are multiple derivations matching a name in *args* that
@ -65,11 +65,11 @@ The arguments *args* map to store paths in a number of possible ways:
This can be used to override the priority of the derivations being installed.
This is useful if *args* are [store paths], which don't have any priority information.
- If *args* are [store derivations](@docroot@/glossary.md#gloss-store-derivation), then these are [realised], and the resulting output paths are installed.
- If *args* are [store paths] that point to [store derivations][store derivation], then those store derivations are [realised], and the resulting output paths are installed.
- If *args* are [store paths] that are not store derivations, then these are [realised] and installed.
- If *args* are [store paths] that do not point to store derivations, then these are [realised] and installed.
- By default all [outputs](@docroot@/language/derivations.md#attr-outputs) are installed for each [derivation].
- By default all [outputs](@docroot@/language/derivations.md#attr-outputs) are installed for each [store derivation].
This can be overridden by adding a `meta.outputsToInstall` attribute on the derivation listing a subset of the output names.
Example:
@ -121,6 +121,8 @@ The arguments *args* map to store paths in a number of possible ways:
manifest.nix
```
[store derivation]: @docroot@/glossary.md#gloss-store-derivation
# Options
- `--prebuilt-only` / `-b`

5
doc/manual/source/command-ref/nix-env/query.md
View file

@ -125,7 +125,10 @@ derivation is shown unless `--no-name` is specified.
- `--drv-path`
Print the path of the [store derivation](@docroot@/glossary.md#gloss-store-derivation).
Print the [store path] to the [store derivation].
[store path]: @docroot@/glossary.md#gloss-store-path
[store derivation]: @docroot@/glossary.md#gloss-derivation
- `--out-path`

2
doc/manual/source/command-ref/nix-hash.md
View file

@ -67,7 +67,7 @@ md5sum`.
- `--type` *hashAlgo*
Use the specified cryptographic hash algorithm, which can be one of
`md5`, `sha1`, `sha256`, and `sha512`.
`blake3`, `md5`, `sha1`, `sha256`, and `sha512`.
- `--to-base16`

4
doc/manual/source/command-ref/nix-instantiate.md
View file

@ -42,8 +42,8 @@ standard input.
- `--eval`
Just parse and evaluate the input files, and print the resulting
values on standard output. No instantiation of store derivations
takes place.
values on standard output.
Store derivations are not serialized and written to the store, but instead just hashed and discarded.
> **Warning**
>

2
doc/manual/source/command-ref/nix-prefetch-url.md
View file

@ -42,7 +42,7 @@ the path of the downloaded file in the Nix store is also printed.
- `--type` *hashAlgo*
Use the specified cryptographic hash algorithm,
which can be one of `md5`, `sha1`, `sha256`, and `sha512`.
which can be one of `blake3`, `md5`, `sha1`, `sha256`, and `sha512`.
The default is `sha256`.
- `--print-path`

4
doc/manual/source/command-ref/nix-store/realise.md
View file

@ -15,7 +15,7 @@ Each of *paths* is processed as follows:
1. If it is not [valid], substitute the store derivation file itself.
2. Realise its [output paths]:
- Try to fetch from [substituters] the [store objects] associated with the output paths in the store derivation's [closure].
- With [content-addressed derivations] (experimental):
- With [content-addressing derivations] (experimental):
Determine the output paths to realise by querying content-addressed realisation entries in the [Nix database].
- For any store paths that cannot be substituted, produce the required store objects:
1. Realise all outputs of the derivation's dependencies
@ -32,7 +32,7 @@ If no substitutes are available and no store derivation is given, realisation fa
[store objects]: @docroot@/store/store-object.md
[closure]: @docroot@/glossary.md#gloss-closure
[substituters]: @docroot@/command-ref/conf-file.md#conf-substituters
[content-addressed derivations]: @docroot@/development/experimental-features.md#xp-feature-ca-derivations
[content-addressing derivations]: @docroot@/development/experimental-features.md#xp-feature-ca-derivations
[Nix database]: @docroot@/glossary.md#gloss-nix-database
The resulting paths are printed on standard output.

56
doc/manual/source/development/building.md
View file

@ -11,7 +11,7 @@ This shell also adds `./outputs/bin/nix` to your `$PATH` so you can run `nix` im
To get a shell with one of the other [supported compilation environments](#compilation-environments):
```console
$ nix develop .#native-clangStdenvPackages
$ nix develop .#native-clangStdenv
```
> **Note**
@ -93,11 +93,13 @@ It is useful to perform multiple cross and native builds on the same source tree
for example to ensure that better support for one platform doesn't break the build for another.
Meson thankfully makes this very easy by confining all build products to the build directory --- one simple shares the source directory between multiple build directories, each of which contains the build for Nix to a different platform.
Nixpkgs's `configurePhase` always chooses `build` in the current directory as the name and location of the build.
This makes having multiple build directories slightly more inconvenient.
The good news is that Meson/Ninja seem to cope well with relocating the build directory after it is created.
Here's how to do that:
Here's how to do that
1. Instruct Nixpkgs's infra where we want Meson to put its build directory
```bash
mesonBuildDir=build-my-variant-name
```
1. Configure as usual
@ -105,24 +107,12 @@ Here's how to do that
configurePhase
```
2. Rename the build directory
```bash
cd .. # since `configurePhase` cd'd inside
mv build build-linux # or whatever name we want
cd build-linux
```
3. Build as usual
```bash
buildPhase
```
> **N.B.**
> [`nixpkgs#335818`](https://github.com/NixOS/nixpkgs/issues/335818) tracks giving `mesonConfigurePhase` proper support for custom build directories.
> When it is fixed, we can simplify these instructions and then remove this notice.
## System type
Nix uses a string with the following format to identify the *system type* or *platform* it runs on:
@ -179,7 +169,8 @@ See [supported compilation environments](#compilation-environments) and instruct
To use the LSP with your editor, you will want a `compile_commands.json` file telling `clangd` how we are compiling the code.
Meson's configure always produces this inside the build directory.
Configure your editor to use the `clangd` from the `.#native-clangStdenvPackages` shell. You can do that either by running it inside the development shell, or by using [nix-direnv](https://github.com/nix-community/nix-direnv) and [the appropriate editor plugin](https://github.com/direnv/direnv/wiki#editor-integration).
Configure your editor to use the `clangd` from the `.#native-clangStdenv` shell.
You can do that either by running it inside the development shell, or by using [nix-direnv](https://github.com/nix-community/nix-direnv) and [the appropriate editor plugin](https://github.com/direnv/direnv/wiki#editor-integration).
> **Note**
>
@ -195,6 +186,8 @@ You may run the formatters as a one-off using:
./maintainers/format.sh
```
### Pre-commit hooks
If you'd like to run the formatters before every commit, install the hooks:
```
@ -209,3 +202,30 @@ If it fails, run `git add --patch` to approve the suggestions _and commit again_
To refresh pre-commit hook's config file, do the following:
1. Exit the development shell and start it again by running `nix develop`.
2. If you also use the pre-commit hook, also run `pre-commit-hooks-install` again.
### VSCode
Insert the following json into your `.vscode/settings.json` file to configure `nixfmt`.
This will be picked up by the _Format Document_ command, `"editor.formatOnSave"`, etc.
```json
{
"nix.formatterPath": "nixfmt",
"nix.serverSettings": {
"nixd": {
"formatting": {
"command": [
"nixfmt"
],
},
},
"nil": {
"formatting": {
"command": [
"nixfmt"
],
},
},
},
}
```

11
doc/manual/source/development/debugging.md
View file

@ -2,6 +2,8 @@
This section shows how to build and debug Nix with debug symbols enabled.
Additionally, see [Testing Nix](./testing.md) for further instructions on how to debug Nix in the context of a unit test or functional test.
## Building Nix with Debug Symbols
In the development shell, set the `mesonBuildType` environment variable to `debug` before configuring the build:
@ -13,6 +15,15 @@ In the development shell, set the `mesonBuildType` environment variable to `debu
Then, proceed to build Nix as described in [Building Nix](./building.md).
This will build Nix with debug symbols, which are essential for effective debugging.
It is also possible to build without debugging for faster build:
```console
[nix-shell]$ NIX_HARDENING_ENABLE=$(printLines $NIX_HARDENING_ENABLE | grep -v fortify)
[nix-shell]$ export mesonBuildType=debug
```
(The first line is needed because `fortify` hardening requires at least some optimization.)
## Debugging the Nix Binary
Obtain your preferred debugger within the development shell:

28
doc/manual/source/development/testing.md
View file

@ -87,7 +87,11 @@ A environment variables that Google Test accepts are also worth knowing:
This is used to avoid logging passing tests.
Putting the two together, one might run
3. [`GTEST_BREAK_ON_FAILURE`](https://google.github.io/googletest/advanced.html#turning-assertion-failures-into-break-points)
This is used to create a debugger breakpoint when an assertion failure occurs.
Putting the first two together, one might run
```bash
GTEST_BRIEF=1 GTEST_FILTER='ErrorTraceTest.*' meson test nix-expr-tests -v
@ -95,6 +99,22 @@ GTEST_BRIEF=1 GTEST_FILTER='ErrorTraceTest.*' meson test nix-expr-tests -v
for short but comprensive output.
### Debugging tests
For debugging, it is useful to combine the third option above with Meson's [`--gdb`](https://mesonbuild.com/Unit-tests.html#other-test-options) flag:
```bash
GTEST_BRIEF=1 GTEST_FILTER='Group.my-failing-test' meson test nix-expr-tests --gdb
```
This will:
1. Run the unit test with GDB
2. Run just `Group.my-failing-test`
3. Stop the program when the test fails, allowing the user to then issue arbitrary commands to GDB.
### Characterisation testing { #characaterisation-testing-unit }
See [functional characterisation testing](#characterisation-testing-functional) for a broader discussion of characterisation testing.
@ -144,7 +164,7 @@ $ checkPhase
Sometimes it is useful to group related tests so they can be easily run together without running the entire test suite.
Each test group is in a subdirectory of `tests`.
For example, `tests/functional/ca/meson.build` defines a `ca` test group for content-addressed derivation outputs.
For example, `tests/functional/ca/meson.build` defines a `ca` test group for content-addressing derivation outputs.
That test group can be run like this:
@ -213,10 +233,10 @@ edit it like so:
bar
```
Then, running the test with `./mk/debug-test.sh` will drop you into GDB once the script reaches that point:
Then, running the test with [`--interactive`](https://mesonbuild.com/Unit-tests.html#other-test-options) will prevent Meson from hijacking the terminal so you can drop you into GDB once the script reaches that point:
```shell-session
$ ./mk/debug-test.sh tests/functional/${testName}.sh
$ meson test ${testName} --interactive
...
+ gdb blash blub
GNU gdb (GDB) 12.1

83
doc/manual/source/glossary.md
View file

@ -1,5 +1,13 @@
# Glossary
- [build system]{#gloss-build-system}
Generic term for software that facilitates the building of software by automating the invocation of compilers, linkers, and other tools.
Nix can be used as a generic build system.
It has no knowledge of any particular programming language or toolchain.
These details are specified in [derivation expressions](#gloss-derivation-expression).
- [content address]{#gloss-content-address}
A
@ -13,37 +21,45 @@
- [Content-Addressing File System Objects](@docroot@/store/file-system-object/content-address.md)
- [Content-Addressing Store Objects](@docroot@/store/store-object/content-address.md)
- [content-addressed derivation](#gloss-content-addressed-derivation)
- [content-addressing derivation](#gloss-content-addressing-derivation)
Software Heritage's writing on [*Intrinsic and Extrinsic identifiers*](https://www.softwareheritage.org/2020/07/09/intrinsic-vs-extrinsic-identifiers) is also a good introduction to the value of content-addressing over other referencing schemes.
Besides content addressing, the Nix store also uses [input addressing](#gloss-input-addressed-store-object).
- [derivation]{#gloss-derivation}
- [content-addressed storage]{#gloss-content-addressed-store}
A description of a build task. The result of a derivation is a
store object. Derivations declared in Nix expressions are specified
using the [`derivation` primitive](./language/derivations.md). These are
translated into low-level *store derivations* (implicitly by
`nix-build`, or explicitly by `nix-instantiate`).
[derivation]: #gloss-derivation
The industry term for storage and retrieval systems using [content addressing](#gloss-content-address). A Nix store also has [input addressing](#gloss-input-addressed-store-object), and metadata.
- [store derivation]{#gloss-store-derivation}
A [derivation] represented as a `.drv` file in the [store].
It has a [store path], like any [store object].
It is the [instantiated][instantiate] form of a derivation.
Example: `/nix/store/g946hcz4c8mdvq2g8vxx42z51qb71rvp-git-2.38.1.drv`
See [`nix derivation show`](./command-ref/new-cli/nix3-derivation-show.md) (experimental) for displaying the contents of store derivations.
A single build task.
See [Store Derivation](@docroot@/store/derivation/index.md#store-derivation) for details.
[store derivation]: #gloss-store-derivation
- [derivation path]{#gloss-derivation-path}
A [store path] which uniquely identifies a [store derivation].
See [Referencing Store Derivations](@docroot@/store/derivation/index.md#derivation-path) for details.
Not to be confused with [deriving path].
[derivation path]: #gloss-derivation-path
- [derivation expression]{#gloss-derivation-expression}
A description of a [store derivation] in the Nix language.
The output(s) of a derivation are store objects.
Derivations are typically specified in Nix expressions using the [`derivation` primitive](./language/derivations.md).
These are translated into store layer *derivations* (implicitly by `nix-env` and `nix-build`, or explicitly by `nix-instantiate`).
[derivation expression]: #gloss-derivation-expression
- [instantiate]{#gloss-instantiate}, instantiation
Save an evaluated [derivation] as a [store derivation] in the Nix [store].
Translate a [derivation expression] into a [store derivation].
See [`nix-instantiate`](./command-ref/nix-instantiate.md), which produces a store derivation from a Nix expression that evaluates to a derivation.
@ -55,7 +71,7 @@
This can be achieved by:
- Fetching a pre-built [store object] from a [substituter]
- Running the [`builder`](@docroot@/language/derivations.md#attr-builder) executable as specified in the corresponding [derivation]
- Running the [`builder`](@docroot@/language/derivations.md#attr-builder) executable as specified in the corresponding [store derivation]
- Delegating to a [remote machine](@docroot@/command-ref/conf-file.md#conf-builders) and retrieving the outputs
<!-- TODO: link [running] to build process page, #8888 -->
@ -65,7 +81,7 @@
[realise]: #gloss-realise
- [content-addressed derivation]{#gloss-content-addressed-derivation}
- [content-addressing derivation]{#gloss-content-addressing-derivation}
A derivation which has the
[`__contentAddressed`](./language/advanced-attributes.md#adv-attr-__contentAddressed)
@ -73,7 +89,7 @@
- [fixed-output derivation]{#gloss-fixed-output-derivation} (FOD)
A [derivation] where a cryptographic hash of the [output] is determined in advance using the [`outputHash`](./language/advanced-attributes.md#adv-attr-outputHash) attribute, and where the [`builder`](@docroot@/language/derivations.md#attr-builder) executable has access to the network.
A [store derivation] where a cryptographic hash of the [output] is determined in advance using the [`outputHash`](./language/advanced-attributes.md#adv-attr-outputHash) attribute, and where the [`builder`](@docroot@/language/derivations.md#attr-builder) executable has access to the network.
- [store]{#gloss-store}
@ -84,6 +100,12 @@
[store]: #gloss-store
- [Nix instance]{#gloss-nix-instance}
<!-- ambiguous -->
1. An installation of Nix, which includes the presence of a [store], and the Nix package manager which operates on that store.
A local Nix installation and a [remote builder](@docroot@/advanced-topics/distributed-builds.md) are two examples of Nix instances.
2. A running Nix process, such as the `nix` command.
- [binary cache]{#gloss-binary-cache}
A *binary cache* is a Nix store which uses a different format: its
@ -130,7 +152,7 @@
- [input-addressed store object]{#gloss-input-addressed-store-object}
A store object produced by building a
non-[content-addressed](#gloss-content-addressed-derivation),
non-[content-addressed](#gloss-content-addressing-derivation),
non-[fixed-output](#gloss-fixed-output-derivation)
derivation.
@ -138,7 +160,7 @@
A [store object] which is [content-addressed](#gloss-content-address),
i.e. whose [store path] is determined by its contents.
This includes derivations, the outputs of [content-addressed derivations](#gloss-content-addressed-derivation), and the outputs of [fixed-output derivations](#gloss-fixed-output-derivation).
This includes derivations, the outputs of [content-addressing derivations](#gloss-content-addressing-derivation), and the outputs of [fixed-output derivations](#gloss-fixed-output-derivation).
See [Content-Addressing Store Objects](@docroot@/store/store-object/content-address.md) for details.
@ -188,7 +210,7 @@
>
> The contents of a `.nix` file form a Nix expression.
Nix expressions specify [derivations][derivation], which are [instantiated][instantiate] into the Nix store as [store derivations][store derivation].
Nix expressions specify [derivation expressions][derivation expression], which are [instantiated][instantiate] into the Nix store as [store derivations][store derivation].
These derivations can then be [realised][realise] to produce [outputs][output].
> **Example**
@ -216,7 +238,7 @@
directly or indirectly “reachable” from that store path; that is,
it’s the closure of the path under the *references* relation. For
a package, the closure of its derivation is equivalent to the
build-time dependencies, while the closure of its output path is
build-time dependencies, while the closure of its [output path] is
equivalent to its runtime dependencies. For correct deployment it
is necessary to deploy whole closures, since otherwise at runtime
files could be missing. The command `nix-store --query --requisites ` prints out
@ -230,14 +252,14 @@
- [output]{#gloss-output}
A [store object] produced by a [derivation].
A [store object] produced by a [store derivation].
See [the `outputs` argument to the `derivation` function](@docroot@/language/derivations.md#attr-outputs) for details.
[output]: #gloss-output
- [output path]{#gloss-output-path}
The [store path] to the [output] of a [derivation].
The [store path] to the [output] of a [store derivation].
[output path]: #gloss-output-path
@ -246,14 +268,11 @@
- [deriving path]{#gloss-deriving-path}
Deriving paths are a way to refer to [store objects][store object] that ar not yet [realised][realise].
This is necessary because, in general and particularly for [content-addressed derivations][content-addressed derivation], the [output path] of an [output] is not known in advance.
There are two forms:
Deriving paths are a way to refer to [store objects][store object] that might not yet be [realised][realise].
- *constant*: just a [store path]
It can be made [valid][validity] by copying it into the store: from the evaluator, command line interface or another store.
See [Deriving Path](./store/derivation/index.md#deriving-path) for details.
- *output*: a pair of a [store path] to a [derivation] and an [output] name.
Not to be confused with [derivation path].
- [deriver]{#gloss-deriver}

263
doc/manual/source/language/advanced-attributes.md
View file

@ -99,8 +99,8 @@ Derivations can declare some infrequently used optional attributes.
to make it use the proxy server configuration specified by the user
in the environment variables `http_proxy` and friends.
This attribute is only allowed in *fixed-output derivations* (see
below), where impurities such as these are okay since (the hash
This attribute is only allowed in [fixed-output derivations][fixed-output derivation],
where impurities such as these are okay since (the hash
of) the output is known in advance. It is ignored for all other
derivations.
@ -119,135 +119,6 @@ Derivations can declare some infrequently used optional attributes.
[`impure-env`](@docroot@/command-ref/conf-file.md#conf-impure-env)
configuration setting.
- [`outputHash`]{#adv-attr-outputHash}; [`outputHashAlgo`]{#adv-attr-outputHashAlgo}; [`outputHashMode`]{#adv-attr-outputHashMode}\
These attributes declare that the derivation is a so-called *fixed-output derivation* (FOD), which means that a cryptographic hash of the output is already known in advance.
As opposed to regular derivations, the [`builder`] executable of a fixed-output derivation has access to the network.
Nix computes a cryptographic hash of its output and compares that to the hash declared with these attributes.
If there is a mismatch, the derivation fails.
The rationale for fixed-output derivations is derivations such as
those produced by the `fetchurl` function. This function downloads a
file from a given URL. To ensure that the downloaded file has not
been modified, the caller must also specify a cryptographic hash of
the file. For example,
```nix
fetchurl {
url = "http://ftp.gnu.org/pub/gnu/hello/hello-2.1.1.tar.gz";
sha256 = "1md7jsfd8pa45z73bz1kszpp01yw6x5ljkjk2hx7wl800any6465";
}
```
It sometimes happens that the URL of the file changes, e.g., because
servers are reorganised or no longer available. We then must update
the call to `fetchurl`, e.g.,
```nix
fetchurl {
url = "ftp://ftp.nluug.nl/pub/gnu/hello/hello-2.1.1.tar.gz";
sha256 = "1md7jsfd8pa45z73bz1kszpp01yw6x5ljkjk2hx7wl800any6465";
}
```
If a `fetchurl` derivation was treated like a normal derivation, the
output paths of the derivation and *all derivations depending on it*
would change. For instance, if we were to change the URL of the
Glibc source distribution in Nixpkgs (a package on which almost all
other packages depend) massive rebuilds would be needed. This is
unfortunate for a change which we know cannot have a real effect as
it propagates upwards through the dependency graph.
For fixed-output derivations, on the other hand, the name of the
output path only depends on the `outputHash*` and `name` attributes,
while all other attributes are ignored for the purpose of computing
the output path. (The `name` attribute is included because it is
part of the path.)
As an example, here is the (simplified) Nix expression for
`fetchurl`:
```nix
{ stdenv, curl }: # The curl program is used for downloading.
{ url, sha256 }:
stdenv.mkDerivation {
name = baseNameOf (toString url);
builder = ./builder.sh;
buildInputs = [ curl ];
# This is a fixed-output derivation; the output must be a regular
# file with SHA256 hash sha256.
outputHashMode = "flat";
outputHashAlgo = "sha256";
outputHash = sha256;
inherit url;
}
```
The `outputHash` attribute must be a string containing the hash in either hexadecimal or "nix32" encoding, or following the format for integrity metadata as defined by [SRI](https://www.w3.org/TR/SRI/).
The "nix32" encoding is an adaptation of base-32 encoding.
The [`convertHash`](@docroot@/language/builtins.md#builtins-convertHash) function shows how to convert between different encodings, and the [`nix-hash` command](../command-ref/nix-hash.md) has information about obtaining the hash for some contents, as well as converting to and from encodings.
The `outputHashAlgo` attribute specifies the hash algorithm used to compute the hash.
It can currently be `"sha1"`, `"sha256"`, `"sha512"`, or `null`.
`outputHashAlgo` can only be `null` when `outputHash` follows the SRI format.
The `outputHashMode` attribute determines how the hash is computed.
It must be one of the following values:
- [`"flat"`](@docroot@/store/store-object/content-address.md#method-flat)
This is the default.
- [`"recursive"` or `"nar"`](@docroot@/store/store-object/content-address.md#method-nix-archive)
> **Compatibility**
>
> `"recursive"` is the traditional way of indicating this,
> and is supported since 2005 (virtually the entire history of Nix).
> `"nar"` is more clear, and consistent with other parts of Nix (such as the CLI),
> however support for it is only added in Nix version 2.21.
- [`"text"`](@docroot@/store/store-object/content-address.md#method-text)
> **Warning**
>
> The use of this method for derivation outputs is part of the [`dynamic-derivations`][xp-feature-dynamic-derivations] experimental feature.
- [`"git"`](@docroot@/store/store-object/content-address.md#method-git)
> **Warning**
>
> This method is part of the [`git-hashing`][xp-feature-git-hashing] experimental feature.
- [`__contentAddressed`]{#adv-attr-__contentAddressed}
> **Warning**
> This attribute is part of an [experimental feature](@docroot@/development/experimental-features.md).
>
> To use this attribute, you must enable the
> [`ca-derivations`][xp-feature-ca-derivations] experimental feature.
> For example, in [nix.conf](../command-ref/conf-file.md) you could add:
>
> ```
> extra-experimental-features = ca-derivations
> ```
If this attribute is set to `true`, then the derivation
outputs will be stored in a content-addressed location rather than the
traditional input-addressed one.
Setting this attribute also requires setting
[`outputHashMode`](#adv-attr-outputHashMode)
and
[`outputHashAlgo`](#adv-attr-outputHashAlgo)
like for *fixed-output derivations* (see above).
It also implicitly requires that the machine to build the derivation must have the `ca-derivations` [system feature](@docroot@/command-ref/conf-file.md#conf-system-features).
- [`passAsFile`]{#adv-attr-passAsFile}\
A list of names of attributes that should be passed via files rather
than environment variables. For example, if you have
@ -370,6 +241,134 @@ Derivations can declare some infrequently used optional attributes.
ensures that the derivation can only be built on a machine with the `kvm` feature.
[xp-feature-ca-derivations]: @docroot@/development/experimental-features.md#xp-feature-ca-derivations
## Setting the derivation type
As discussed in [Derivation Outputs and Types of Derivations](@docroot@/store/derivation/outputs/index.md), there are multiples kinds of derivations / kinds of derivation outputs.
The choice of the following attributes determines which kind of derivation we are making.
- [`__contentAddressed`]
- [`outputHash`]
- [`outputHashAlgo`]
- [`outputHashMode`]
The three types of derivations are chosen based on the following combinations of these attributes.
All other combinations are invalid.
- [Input-addressing derivations](@docroot@/store/derivation/outputs/input-address.md)
This is the default for `builtins.derivation`.
Nix only currently supports one kind of input-addressing, so no other information is needed.
`__contentAddressed = false;` may also be included, but is not needed, and will trigger the experimental feature check.
- [Fixed-output derivations][fixed-output derivation]
All of [`outputHash`], [`outputHashAlgo`], and [`outputHashMode`].
<!--
`__contentAddressed` is ignored, becaused fixed-output derivations always content-address their outputs, by definition.
**TODO CHECK**
-->
- [(Floating) content-addressing derivations](@docroot@/store/derivation/outputs/content-address.md)
Both [`outputHashAlgo`] and [`outputHashMode`], `__contentAddressed = true;`, and *not* `outputHash`.
If an output hash was given, then the derivation output would be "fixed" not "floating".
Here is more information on the `output*` attributes, and what values they may be set to:
- [`outputHashMode`]{#adv-attr-outputHashMode}
This specifies how the files of a content-addressing derivation output are digested to produce a content address.
This works in conjunction with [`outputHashAlgo`](#adv-attr-outputHashAlgo).
Specifying one without the other is an error (unless [`outputHash` is also specified and includes its own hash algorithm as described below).
The `outputHashMode` attribute determines how the hash is computed.
It must be one of the following values:
- [`"flat"`](@docroot@/store/store-object/content-address.md#method-flat)
This is the default.
- [`"recursive"` or `"nar"`](@docroot@/store/store-object/content-address.md#method-nix-archive)
> **Compatibility**
>
> `"recursive"` is the traditional way of indicating this,
> and is supported since 2005 (virtually the entire history of Nix).
> `"nar"` is more clear, and consistent with other parts of Nix (such as the CLI),
> however support for it is only added in Nix version 2.21.
- [`"text"`](@docroot@/store/store-object/content-address.md#method-text)
> **Warning**
>
> The use of this method for derivation outputs is part of the [`dynamic-derivations`][xp-feature-dynamic-derivations] experimental feature.
- [`"git"`](@docroot@/store/store-object/content-address.md#method-git)
> **Warning**
>
> This method is part of the [`git-hashing`][xp-feature-git-hashing] experimental feature.
See [content-addressing store objects](@docroot@/store/store-object/content-address.md) for more information about the process this flag controls.
- [`outputHashAlgo`]{#adv-attr-outputHashAlgo}
This specifies the hash alorithm used to digest the [file system object] data of a content-addressing derivation output.
This works in conjunction with [`outputHashMode`](#adv-attr-outputHashAlgo).
Specifying one without the other is an error (unless [`outputHash` is also specified and includes its own hash algorithm as described below).
The `outputHashAlgo` attribute specifies the hash algorithm used to compute the hash.
It can currently be `"blake3"`, "sha1"`, `"sha256"`, `"sha512"`, or `null`.
`outputHashAlgo` can only be `null` when `outputHash` follows the SRI format, because in that case the choice of hash algorithm is determined by `outputHash`.
- [`outputHash`]{#adv-attr-outputHashAlgo}; [`outputHash`]{#adv-attr-outputHashMode}\
This will specify the output hash of the single output of a [fixed-output derivation].
The `outputHash` attribute must be a string containing the hash in either hexadecimal or "nix32" encoding, or following the format for integrity metadata as defined by [SRI](https://www.w3.org/TR/SRI/).
The "nix32" encoding is an adaptation of base-32 encoding.
> **Note**
>
> The [`convertHash`](@docroot@/language/builtins.md#builtins-convertHash) function shows how to convert between different encodings.
> The [`nix-hash` command](../command-ref/nix-hash.md) has information about obtaining the hash for some contents, as well as converting to and from encodings.
- [`__contentAddressed`]{#adv-attr-__contentAddressed}
> **Warning**
>
> This attribute is part of an [experimental feature](@docroot@/development/experimental-features.md).
>
> To use this attribute, you must enable the
> [`ca-derivations`][xp-feature-ca-derivations] experimental feature.
> For example, in [nix.conf](../command-ref/conf-file.md) you could add:
>
> ```
> extra-experimental-features = ca-derivations
> ```
This is a boolean with a default of `false`.
It determines whether the derivation is floating content-addressing.
[`__contentAddressed`]: #adv-attr-__contentAddressed
[`outputHash`]: #adv-attr-outputHash
[`outputHashAlgo`]: #adv-attr-outputHashAlgo
[`outputHashMode`]: #adv-attr-outputHashMode
[fixed-output derivation]: @docroot@/glossary.md#gloss-fixed-output-derivation
[file system object]: @docroot@/store/file-system-object.md
[store object]: @docroot@/store/store-object.md
[xp-feature-dynamic-derivations]: @docroot@/development/experimental-features.md#xp-feature-dynamic-derivations
[xp-feature-git-hashing]: @docroot@/development/experimental-features.md#xp-feature-git-hashing

96
doc/manual/source/language/derivations.md
View file

@ -1,9 +1,10 @@
# Derivations
The most important built-in function is `derivation`, which is used to describe a single derivation:
a specification for running an executable on precisely defined input files to repeatably produce output files at uniquely determined file system paths.
The most important built-in function is `derivation`, which is used to describe a single store-layer [store derivation].
Consult the [store chapter](@docroot@/store/derivation/index.md) for what a store derivation is;
this section just concerns how to create one from the Nix language.
It takes as input an attribute set, the attributes of which specify the inputs to the process.
This builtin function takes as input an attribute set, the attributes of which specify the inputs to the process.
It outputs an attribute set, and produces a [store derivation] as a side effect of evaluation.
[store derivation]: @docroot@/glossary.md#gloss-store-derivation
@ -15,7 +16,7 @@ It outputs an attribute set, and produces a [store derivation] as a side effect
- [`name`]{#attr-name} ([String](@docroot@/language/types.md#type-string))
A symbolic name for the derivation.
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).
See [derivation outputs](@docroot@/store/derivation/index.md#outputs) for what this is affects.
[store path]: @docroot@/store/store-path.md
@ -28,17 +29,12 @@ It outputs an attribute set, and produces a [store derivation] as a side effect
> }
> ```
>
> The store derivation's path will be `/nix/store/<hash>-hello.drv`.
> The 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>]`
- [`system`]{#attr-system} ([String](@docroot@/language/types.md#type-string))
The system type on which the [`builder`](#attr-builder) executable is meant to be run.
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](@docroot@/language/derivations.md#attr-builder) by forwarding build requests to other machines.
[`system` configuration option]: @docroot@/command-ref/conf-file.md#conf-system
See [system](@docroot@/store/derivation/index.md#system).
> **Example**
>
@ -68,7 +64,7 @@ It outputs an attribute set, and produces a [store derivation] as a side effect
- [`builder`]{#attr-builder} ([Path](@docroot@/language/types.md#type-path) | [String](@docroot@/language/types.md#type-string))
Path to an executable that will perform the build.
See [builder](@docroot@/store/derivation/index.md#builder).
> **Example**
>
@ -117,7 +113,7 @@ It outputs an attribute set, and produces a [store derivation] as a side effect
Default: `[ ]`
Command-line arguments to be passed to the [`builder`](#attr-builder) executable.
See [args](@docroot@/store/derivation/index.md#args).
> **Example**
>
@ -239,77 +235,3 @@ It outputs an attribute set, and produces a [store derivation] as a side effect
passed as an empty string.
<!-- FIXME: add a section on output attributes -->
## Builder execution
The [`builder`](#attr-builder) is executed as follows:
- A temporary directory is created under the directory specified by
`TMPDIR` (default `/tmp`) where the build will take place. The
current directory is changed to this directory.
- The environment is cleared and set to the derivation attributes, as
specified above.
- In addition, the following variables are set:
- `NIX_BUILD_TOP` contains the path of the temporary directory for
this build.
- Also, `TMPDIR`, `TEMPDIR`, `TMP`, `TEMP` are set to point to the
temporary directory. This is to prevent the builder from
accidentally writing temporary files anywhere else. Doing so
might cause interference by other processes.
- `PATH` is set to `/path-not-set` to prevent shells from
initialising it to their built-in default value.
- `HOME` is set to `/homeless-shelter` to prevent programs from
using `/etc/passwd` or the like to find the user's home
directory, which could cause impurity. Usually, when `HOME` is
set, it is used as the location of the home directory, even if
it points to a non-existent path.
- `NIX_STORE` is set to the path of the top-level Nix store
directory (typically, `/nix/store`).
- `NIX_ATTRS_JSON_FILE` & `NIX_ATTRS_SH_FILE` if `__structuredAttrs`
is set to `true` for the derivation. A detailed explanation of this
behavior can be found in the
[section about structured attrs](./advanced-attributes.md#adv-attr-structuredAttrs).
- For each output declared in `outputs`, the corresponding
environment variable is set to point to the intended path in the
Nix store for that output. Each output path is a concatenation
of the cryptographic hash of all build inputs, the `name`
attribute and the output name. (The output name is omitted if
it’s `out`.)
- If an output path already exists, it is removed. Also, locks are
acquired to prevent multiple Nix instances from performing the same
build at the same time.
- A log of the combined standard output and error is written to
`/nix/var/log/nix`.
- The builder is executed with the arguments specified by the
attribute `args`. If it exits with exit code 0, it is considered to
have succeeded.
- The temporary directory is removed (unless the `-K` option was
specified).
- If the build was successful, Nix scans each output path for
references to input paths by looking for the hash parts of the input
paths. Since these are potential runtime dependencies, Nix registers
them as dependencies of the output paths.
- After the build, Nix sets the last-modified timestamp on all files
in the build result to 1 (00:00:01 1/1/1970 UTC), sets the group to
the default group, and sets the mode of the file to 0444 or 0555
(i.e., read-only, with execute permission enabled if the file was
originally executable). Note that possible `setuid` and `setgid`
bits are cleared. Setuid and setgid programs are not currently
supported by Nix. This is because the Nix archives used in
deployment have no concept of ownership information, and because it
makes the build result dependent on the user performing the build.

5
doc/manual/source/language/import-from-derivation.md
View file

@ -71,8 +71,9 @@ Boxes are data structures, arrow labels are transformations.
| evaluate | | |
| | | | |
| V | | |
| .------------. | | .------------------. |
| | derivation |----|-instantiate-|->| store derivation | |
| .------------. | | |
| | derivation | | | .------------------. |
| | expression |----|-instantiate-|->| store derivation | |
| '------------' | | '------------------' |
| | | | |
| | | realise |

6
doc/manual/source/language/string-interpolation.md
View file

@ -22,9 +22,9 @@ Rather than writing
"--with-freetype2-library=" + freetype + "/lib"
```
(where `freetype` is a [derivation]), you can instead write
(where `freetype` is a [derivation expression]), you can instead write
[derivation]: @docroot@/glossary.md#gloss-derivation
[derivation expression]: @docroot@/glossary.md#gloss-derivation-expression
```nix
"--with-freetype2-library=${freetype}/lib"
@ -148,7 +148,7 @@ An expression that is interpolated must evaluate to one of the following:
- `__toString` must be a function that takes the attribute set itself and returns a string
- `outPath` must be a string
This includes [derivations](./derivations.md) or [flake inputs](@docroot@/command-ref/new-cli/nix3-flake.md#flake-inputs) (experimental).
This includes [derivation expressions](./derivations.md) or [flake inputs](@docroot@/command-ref/new-cli/nix3-flake.md#flake-inputs) (experimental).
A string interpolates to itself.

21
doc/manual/source/protocols/derivation-aterm.md
View file

@ -1,6 +1,8 @@
# Derivation "ATerm" file format
For historical reasons, [derivations](@docroot@/glossary.md#gloss-store-derivation) are stored on-disk in [ATerm](https://homepages.cwi.nl/~daybuild/daily-books/technology/aterm-guide/aterm-guide.html) format.
For historical reasons, [store derivations][store derivation] are stored on-disk in [ATerm](https://homepages.cwi.nl/~daybuild/daily-books/technology/aterm-guide/aterm-guide.html) format.
## The ATerm format used
Derivations are serialised in one of the following formats:
@ -17,3 +19,20 @@ Derivations are serialised in one of the following formats:
The only `version-string`s that are in use today are for [experimental features](@docroot@/development/experimental-features.md):
- `"xp-dyn-drv"` for the [`dynamic-derivations`](@docroot@/development/experimental-features.md#xp-feature-dynamic-derivations) experimental feature.
## Use for encoding to store object
When derivation is encoded to a [store object] we make the following choices:
- The store path name is the derivation name with `.drv` suffixed at the end
Indeed, the ATerm format above does *not* contain the name of the derivation, on the assumption that a store path will also be provided out-of-band.
- The derivation is content-addressed using the ["Text" method] of content-addressing derivations
Currently we always encode derivations to store object using the ATerm format (and the previous two choices),
but we reserve the option to encode new sorts of derivations differently in the future.
[store derivation]: @docroot@/glossary.md#gloss-store-derivation
[store object]: @docroot@/glossary.md#gloss-store-object
["Text" method]: @docroot@/store/store-object/content-address.md#method-text

1
doc/manual/source/protocols/json/derivation.md
View file

@ -32,6 +32,7 @@ is a JSON object with the following fields:
For an output which will be [content addresed], the name of the hash algorithm used.
Valid algorithm strings are:
- `blake3`
- `md5`
- `sha1`
- `sha256`

4
doc/manual/source/protocols/json/store-object-info.md
View file

@ -35,10 +35,10 @@ In other words, the same store object residing in different store could have dif
* `deriver`:
If known, the path to the [derivation] from which this store object was produced.
If known, the path to the [store derivation] from which this store object was produced.
Otherwise `null`.
[derivation]: @docroot@/glossary.md#gloss-store-derivation
[store derivation]: @docroot@/glossary.md#gloss-store-derivation
* `registrationTime` (optional):

2
doc/manual/source/protocols/store-path.md
View file

@ -53,7 +53,7 @@ where
method of content addressing store objects,
if the hash algorithm is [SHA-256].
Just like in the "Text" case, we can have the store objects referenced by their paths.
Additionally, we can have an optional `:self` label to denote self reference.
Additionally, we can have an optional `:self` label to denote self-reference.
- ```ebnf
| "output:" id

48
doc/manual/source/release-notes/rl-0.8.md
View file

@ -39,29 +39,29 @@ Nix 0.8 has the following improvements:
notion of “closure store expressions” is gone (and so is the notion
of “successors”); the file system references of a store path are now
just stored in the database.
For instance, given any store path, you can query its closure:
$ nix-store -qR $(which firefox)
... lots of paths ...
Also, Nix now remembers for each store path the derivation that
built it (the “deriver”):
$ nix-store -qR $(which firefox)
/nix/store/4b0jx7vq80l9aqcnkszxhymsf1ffa5jd-firefox-1.0.1.drv
So to see the build-time dependencies, you can do
$ nix-store -qR $(nix-store -qd $(which firefox))
or, in a nicer format:
$ nix-store -q --tree $(nix-store -qd $(which firefox))
File system references are also stored in reverse. For instance, you
can query all paths that directly or indirectly use a certain Glibc:
$ nix-store -q --referrers-closure \
/nix/store/8lz9yc6zgmc0vlqmn2ipcpkjlmbi51vv-glibc-2.3.4
@ -92,28 +92,28 @@ Nix 0.8 has the following improvements:
- `nix-channel` has new operations `--list` and `--remove`.
- New ways of installing components into user environments:
- Copy from another user environment:
$ nix-env -i --from-profile .../other-profile firefox
- Install a store derivation directly (bypassing the Nix
expression language entirely):
$ nix-env -i /nix/store/z58v41v21xd3...-aterm-2.3.1.drv
(This is used to implement `nix-install-package`, which is
therefore immune to evolution in the Nix expression language.)
- Install an already built store path directly:
$ nix-env -i /nix/store/hsyj5pbn0d9i...-aterm-2.3.1
- Install the result of a Nix expression specified as a
command-line argument:
$ nix-env -f .../i686-linux.nix -i -E 'x: x.firefoxWrapper'
The difference with the normal installation mode is that `-E`
does not use the `name` attributes of derivations. Therefore,
this can be used to disambiguate multiple derivations with the
@ -127,7 +127,7 @@ Nix 0.8 has the following improvements:
- Implemented a concurrent garbage collector. It is now always safe to
run the garbage collector, even if other Nix operations are
happening simultaneously.
However, there can still be GC races if you use `nix-instantiate`
and `nix-store
--realise` directly to build things. To prevent races, use the
@ -147,13 +147,13 @@ Nix 0.8 has the following improvements:
- The behaviour of the garbage collector can be changed globally by
setting options in `/nix/etc/nix/nix.conf`.
- `gc-keep-derivations` specifies whether deriver links should be
followed when searching for live paths.
- `gc-keep-outputs` specifies whether outputs of derivations
should be followed when searching for live paths.
- `env-keep-derivations` specifies whether user environments
should store the paths of derivations when they are added (thus
keeping the derivations alive).

144
doc/manual/source/release-notes/rl-2.0.md
View file

@ -8,13 +8,13 @@ The following incompatible changes have been made:
It has been superseded by the binary cache substituter mechanism
since several years. As a result, the following programs have been
removed:
- `nix-pull`
- `nix-generate-patches`
- `bsdiff`
- `bspatch`
- The “copy from other stores” substituter mechanism
@ -58,26 +58,26 @@ This release has the following new features:
`nix-build`, `nix-shell -p`, `nix-env -qa`, `nix-instantiate
--eval`, `nix-push` and `nix-copy-closure`. It has the following
major features:
- Unlike the legacy commands, it has a consistent way to refer to
packages and package-like arguments (like store paths). For
example, the following commands all copy the GNU Hello package
to a remote machine:
nix copy --to ssh://machine nixpkgs.hello
nix copy --to ssh://machine /nix/store/0i2jd68mp5g6h2sa5k9c85rb80sn8hi9-hello-2.10
nix copy --to ssh://machine '(with import <nixpkgs> {}; hello)'
By contrast, `nix-copy-closure` only accepted store paths as
arguments.
- It is self-documenting: `--help` shows all available
command-line arguments. If `--help` is given after a subcommand,
it shows examples for that subcommand. `nix
--help-config` shows all configuration options.
- It is much less verbose. By default, it displays a single-line
progress indicator that shows how many packages are left to be
built or downloaded, and (if there are running builds) the most
@ -85,7 +85,7 @@ This release has the following new features:
last few lines of builder output. The full build log can be
retrieved using `nix
log`.
- It
[provides](https://github.com/NixOS/nix/commit/b8283773bd64d7da6859ed520ee19867742a03ba)
all `nix.conf` configuration options as command line flags. For
@ -93,122 +93,122 @@ This release has the following new features:
http-connections 100` you can write `--http-connections 100`.
Boolean options can be written as `--foo` or `--no-foo` (e.g.
`--no-auto-optimise-store`).
- Many subcommands have a `--json` flag to write results to stdout
in JSON format.
> **Warning**
>
>
> Please note that the `nix` command is a work in progress and the
> interface is subject to change.
It provides the following high-level (“porcelain”) subcommands:
- `nix build` is a replacement for `nix-build`.
- `nix run` executes a command in an environment in which the
specified packages are available. It is (roughly) a replacement
for `nix-shell
-p`. Unlike that command, it does not execute the command in a
shell, and has a flag (`-c`) that specifies the unquoted command
line to be executed.
It is particularly useful in conjunction with chroot stores,
allowing Linux users who do not have permission to install Nix
in `/nix/store` to still use binary substitutes that assume
`/nix/store`. For example,
nix run --store ~/my-nix nixpkgs.hello -c hello --greeting 'Hi everybody!'
downloads (or if not substitutes are available, builds) the GNU
Hello package into `~/my-nix/nix/store`, then runs `hello` in a
mount namespace where `~/my-nix/nix/store` is mounted onto
`/nix/store`.
- `nix search` replaces `nix-env
-qa`. It searches the available packages for occurrences of a
search string in the attribute name, package name or
description. Unlike `nix-env -qa`, it has a cache to speed up
subsequent searches.
- `nix copy` copies paths between arbitrary Nix stores,
generalising `nix-copy-closure` and `nix-push`.
- `nix repl` replaces the external program `nix-repl`. It provides
an interactive environment for evaluating and building Nix
expressions. Note that it uses `linenoise-ng` instead of GNU
Readline.
- `nix upgrade-nix` upgrades Nix to the latest stable version.
This requires that Nix is installed in a profile. (Thus it won’t
work on NixOS, or if it’s installed outside of the Nix store.)
- `nix verify` checks whether store paths are unmodified and/or
“trusted” (see below). It replaces `nix-store --verify` and
`nix-store
--verify-path`.
- `nix log` shows the build log of a package or path. If the
build log is not available locally, it will try to obtain it
from the configured substituters (such as
[cache.nixos.org](https://cache.nixos.org/), which now
provides build logs).
- `nix edit` opens the source code of a package in your editor.
- `nix eval` replaces `nix-instantiate --eval`.
- `nix
why-depends` shows why one store path has another in its
closure. This is primarily useful to finding the causes of
closure bloat. For example,
nix why-depends nixpkgs.vlc nixpkgs.libdrm.dev
shows a chain of files and fragments of file contents that cause
the VLC package to have the “dev” output of `libdrm` in its
closure — an undesirable situation.
- `nix path-info` shows information about store paths, replacing
`nix-store -q`. A useful feature is the option `--closure-size`
(`-S`). For example, the following command show the closure
sizes of every path in the current NixOS system closure, sorted
by size:
nix path-info -rS /run/current-system | sort -nk2
- `nix optimise-store` replaces `nix-store --optimise`. The main
difference is that it has a progress indicator.
A number of low-level (“plumbing”) commands are also available:
- `nix ls-store` and `nix
ls-nar` list the contents of a store path or NAR file. The
former is primarily useful in conjunction with remote stores,
e.g.
nix ls-store --store https://cache.nixos.org/ -lR /nix/store/0i2jd68mp5g6h2sa5k9c85rb80sn8hi9-hello-2.10
lists the contents of path in a binary cache.
- `nix cat-store` and `nix
cat-nar` allow extracting a file from a store path or NAR file.
- `nix dump-path` writes the contents of a store path to stdout in
NAR format. This replaces `nix-store --dump`.
- `nix
show-derivation` displays a store derivation in JSON format.
This is an alternative to `pp-aterm`.
- `nix
add-to-store` replaces `nix-store
--add`.
- `nix sign-paths` signs store paths.
- `nix copy-sigs` copies signatures from one store to another.
- `nix show-config` shows all configuration options and their
current values.
@ -224,11 +224,11 @@ This release has the following new features:
`nix-copy-closure`, `nix-push` and substitution are all instances
of the general notion of copying paths between different kinds of
Nix stores.
Stores are specified using an URI-like syntax, e.g.
<https://cache.nixos.org/> or <ssh://machine>. The following store
types are supported:
- `LocalStore` (stori URI `local` or an absolute path) and the
misnamed `RemoteStore` (`daemon`) provide access to a local Nix
store, the latter via the Nix daemon. You can use `auto` or the
@ -236,63 +236,63 @@ This release has the following new features:
whether you have write permission to the Nix store. It is no
longer necessary to set the `NIX_REMOTE` environment variable to
use the Nix daemon.
As noted above, `LocalStore` now supports chroot builds,
allowing the “physical” location of the Nix store (e.g.
`/home/alice/nix/store`) to differ from its “logical” location
(typically `/nix/store`). This allows non-root users to use Nix
while still getting the benefits from prebuilt binaries from
[cache.nixos.org](https://cache.nixos.org/).
- `BinaryCacheStore` is the abstract superclass of all binary
cache stores. It supports writing build logs and NAR content
listings in JSON format.
- `HttpBinaryCacheStore` (`http://`, `https://`) supports binary
caches via HTTP or HTTPS. If the server supports `PUT` requests,
it supports uploading store paths via commands such as `nix
copy`.
- `LocalBinaryCacheStore` (`file://`) supports binary caches in
the local filesystem.
- `S3BinaryCacheStore` (`s3://`) supports binary caches stored in
Amazon S3, if enabled at compile time.
- `LegacySSHStore` (`ssh://`) is used to implement remote builds
and `nix-copy-closure`.
- `SSHStore` (`ssh-ng://`) supports arbitrary Nix operations on a
remote machine via the same protocol used by `nix-daemon`.
- Security has been improved in various ways:
- Nix now stores signatures for local store paths. When paths are
copied between stores (e.g., copied from a binary cache to a
local store), signatures are propagated.
Locally-built paths are signed automatically using the secret
keys specified by the `secret-key-files` store option.
Secret/public key pairs can be generated using `nix-store
--generate-binary-cache-key`.
In addition, locally-built store paths are marked as “ultimately
trusted”, but this bit is not propagated when paths are copied
between stores.
- Content-addressable store paths no longer require signatures —
they can be imported into a store by unprivileged users even if
they lack signatures.
- The command `nix verify` checks whether the specified paths are
trusted, i.e., have a certain number of trusted signatures, are
ultimately trusted, or are content-addressed.
- Substitutions from binary caches
[now](https://github.com/NixOS/nix/commit/ecbc3fedd3d5bdc5a0e1a0a51b29062f2874ac8b)
require signatures by default. This was already the case on
NixOS.
- In Linux sandbox builds, we
[now](https://github.com/NixOS/nix/commit/eba840c8a13b465ace90172ff76a0db2899ab11b)
use `/build` instead of `/tmp` as the temporary build directory.
@ -309,7 +309,7 @@ This release has the following new features:
hash or commit hash is specified. For example, calls to
`builtins.fetchGit` are only allowed if a `rev` attribute is
specified.
The goal of this feature is to enable true reproducibility and
traceability of builds (including NixOS system configurations) at
the evaluation level. For example, in the future, `nixos-rebuild`
@ -367,21 +367,21 @@ This release has the following new features:
log will be shown if a build fails.
- Networking has been improved:
- HTTP/2 is now supported. This makes binary cache lookups [much
more
efficient](https://github.com/NixOS/nix/commit/90ad02bf626b885a5dd8967894e2eafc953bdf92).
- We now retry downloads on many HTTP errors, making binary caches
substituters more resilient to temporary failures.
- HTTP credentials can now be configured via the standard `netrc`
mechanism.
- If S3 support is enabled at compile time, <s3://> URIs are
[supported](https://github.com/NixOS/nix/commit/9ff9c3f2f80ba4108e9c945bbfda2c64735f987b)
in all places where Nix allows URIs.
- Brotli compression is now supported. In particular,
[cache.nixos.org](https://cache.nixos.org/) build logs are now compressed
using Brotli.
@ -431,9 +431,9 @@ The Nix language has the following new features:
- Derivation attributes can now reference the outputs of the
derivation using the `placeholder` builtin function. For example,
the attribute
configureFlags = "--prefix=${placeholder "out"} --includedir=${placeholder "dev"}";
will cause the `configureFlags` environment variable to contain the
actual store paths corresponding to the `out` and `dev` outputs.
@ -444,7 +444,7 @@ The following builtin functions are new or extended:
Nixpkgs, which fetches at build time and cannot be used to fetch Nix
expressions during evaluation. A typical use case is to import
external NixOS modules from your configuration, e.g.
imports = [ (builtins.fetchGit https://github.com/edolstra/dwarffs + "/module.nix") ];
- Similarly, `builtins.fetchMercurial` allows you to fetch Mercurial
@ -485,7 +485,7 @@ The Nix build environment has the following changes:
builder via the file `.attrs.json` in the builder’s temporary
directory. This obviates the need for `passAsFile` since JSON files
have no size restrictions, unlike process environments.
[As a convenience to Bash
builders](https://github.com/NixOS/nix/commit/2d5b1b24bf70a498e4c0b378704cfdb6471cc699),
Nix writes a script named `.attrs.sh` to the builder’s directory

66
doc/manual/source/release-notes/rl-2.27.md Normal file
View file

@ -0,0 +1,66 @@
# Release 2.27.0 (2025-03-03)
- `inputs.self.submodules` flake attribute [#12421](https://github.com/NixOS/nix/pull/12421)
Flakes in Git repositories can now declare that they need Git submodules to be enabled:
```
{
inputs.self.submodules = true;
}
```
Thus, it's no longer needed for the caller of the flake to pass `submodules = true`.
- Git LFS support [#10153](https://github.com/NixOS/nix/pull/10153) [#12468](https://github.com/NixOS/nix/pull/12468)
The Git fetcher now supports Large File Storage (LFS). This can be enabled by passing the attribute `lfs = true` to the fetcher, e.g.
```console
nix flake prefetch 'git+ssh://git@github.com/Apress/repo-with-large-file-storage.git?lfs=1'
```
A flake can also declare that it requires LFS to be enabled:
```
{
inputs.self.lfs = true;
}
```
Author: [**@b-camacho**](https://github.com/b-camacho), [**@kip93**](https://github.com/kip93)
- Handle the case where a chroot store is used and some inputs are in the "host" `/nix/store` [#12512](https://github.com/NixOS/nix/pull/12512)
The evaluator now presents a "union" filesystem view of the `/nix/store` in the host and the chroot.
This change also removes some hacks that broke `builtins.{path,filterSource}` in chroot stores [#11503](https://github.com/NixOS/nix/issues/11503).
- `nix flake prefetch` now has a `--out-link` option [#12443](https://github.com/NixOS/nix/pull/12443)
- Set `FD_CLOEXEC` on sockets created by curl [#12439](https://github.com/NixOS/nix/pull/12439)
Curl created sockets without setting `FD_CLOEXEC`/`SOCK_CLOEXEC`. This could previously cause connections to remain open forever when using commands like `nix shell`. This change sets the `FD_CLOEXEC` flag using a `CURLOPT_SOCKOPTFUNCTION` callback.
# Contributors
This release was made possible by the following 21 contributors:
- Aiden Fox Ivey [**(@aidenfoxivey)**](https://github.com/aidenfoxivey)
- Ben Millwood [**(@bmillwood)**](https://github.com/bmillwood)
- Brian Camacho [**(@b-camacho)**](https://github.com/b-camacho)
- Brian McKenna [**(@puffnfresh)**](https://github.com/puffnfresh)
- Eelco Dolstra [**(@edolstra)**](https://github.com/edolstra)
- Fabian Möller [**(@B4dM4n)**](https://github.com/B4dM4n)
- Illia Bobyr [**(@ilya-bobyr)**](https://github.com/ilya-bobyr)
- Ivan Trubach [**(@tie)**](https://github.com/tie)
- John Ericson [**(@Ericson2314)**](https://github.com/Ericson2314)
- Jörg Thalheim [**(@Mic92)**](https://github.com/Mic92)
- Leandro Emmanuel Reina Kiperman [**(@kip93)**](https://github.com/kip93)
- MaxHearnden [**(@MaxHearnden)**](https://github.com/MaxHearnden)
- Philipp Otterbein
- Robert Hensing [**(@roberth)**](https://github.com/roberth)
- Sandro [**(@SuperSandro2000)**](https://github.com/SuperSandro2000)
- Sergei Zimmerman [**(@xokdvium)**](https://github.com/xokdvium)
- Silvan Mosberger [**(@infinisil)**](https://github.com/infinisil)
- Someone [**(@SomeoneSerge)**](https://github.com/SomeoneSerge)
- Steve Walker [**(@stevalkr)**](https://github.com/stevalkr)
- bcamacho2 [**(@bcamacho2)**](https://github.com/bcamacho2)
- silvanshade [**(@silvanshade)**](https://github.com/silvanshade)
- tomberek [**(@tomberek)**](https://github.com/tomberek)

100
doc/manual/source/store/building.md Normal file
View file

@ -0,0 +1,100 @@
# Building
## Normalizing derivation inputs
- Each input must be [realised] prior to building the derivation in question.
[realised]: @docroot@/glossary.md#gloss-realise
- Once this is done, the derivation is *normalized*, replacing each input deriving path with its store path, which we now know from realising the input.
## Builder Execution
The [`builder`](./derivation/index.md#builder) is executed as follows:
- A temporary directory is created under the directory specified by
`TMPDIR` (default `/tmp`) where the build will take place. The
current directory is changed to this directory.
- The environment is cleared and set to the derivation attributes, as
specified above.
- In addition, the following variables are set:
- `NIX_BUILD_TOP` contains the path of the temporary directory for
this build.
- Also, `TMPDIR`, `TEMPDIR`, `TMP`, `TEMP` are set to point to the
temporary directory. This is to prevent the builder from
accidentally writing temporary files anywhere else. Doing so
might cause interference by other processes.
- `PATH` is set to `/path-not-set` to prevent shells from
initialising it to their built-in default value.
- `HOME` is set to `/homeless-shelter` to prevent programs from
using `/etc/passwd` or the like to find the user's home
directory, which could cause impurity. Usually, when `HOME` is
set, it is used as the location of the home directory, even if
it points to a non-existent path.
- `NIX_STORE` is set to the path of the top-level Nix store
directory (typically, `/nix/store`).
- `NIX_ATTRS_JSON_FILE` & `NIX_ATTRS_SH_FILE` if `__structuredAttrs`
is set to `true` for the derivation. A detailed explanation of this
behavior can be found in the
[section about structured attrs](@docroot@/language/advanced-attributes.md#adv-attr-structuredAttrs).
- For each output declared in `outputs`, the corresponding
environment variable is set to point to the intended path in the
Nix store for that output. Each output path is a concatenation
of the cryptographic hash of all build inputs, the `name`
attribute and the output name. (The output name is omitted if
it’s `out`.)
- If an output path already exists, it is removed. Also, locks are
acquired to prevent multiple [Nix instances][Nix instance] from performing the same
build at the same time.
- A log of the combined standard output and error is written to
`/nix/var/log/nix`.
- The builder is executed with the arguments specified by the
attribute `args`. If it exits with exit code 0, it is considered to
have succeeded.
- The temporary directory is removed (unless the `-K` option was
specified).
## Processing outputs
If the builder exited successfully, the following steps happen in order to turn the output directories left behind by the builder into proper store objects:
- **Normalize the file permissions**
Nix sets the last-modified timestamp on all files
in the build result to 1 (00:00:01 1/1/1970 UTC), sets the group to
the default group, and sets the mode of the file to 0444 or 0555
(i.e., read-only, with execute permission enabled if the file was
originally executable). Any possible `setuid` and `setgid`
bits are cleared.
> **Note**
>
> Setuid and setgid programs are not currently supported by Nix.
> This is because the Nix archives used in deployment have no concept of ownership information,
> and because it makes the build result dependent on the user performing the build.
- **Calculate the references**
Nix scans each output path for
references to input paths by looking for the hash parts of the input
paths. Since these are potential runtime dependencies, Nix registers
them as dependencies of the output paths.
Nix also scans for references to other outputs' paths in the same way, because outputs are allowed to refer to each other.
If the outputs' references to each other form a cycle, this is an error, because the references of store objects much be acyclic.
[Nix instance]: @docroot@/glossary.md#gloss-nix-instance

302
doc/manual/source/store/derivation/index.md Normal file
View file

@ -0,0 +1,302 @@
# Store Derivation and Deriving Path
Besides functioning as a [content-addressed store], the Nix store layer works as a [build system].
Other systems (like Git or IPFS) also store and transfer immutable data, but they don't concern themselves with *how* that data was created.
This is where Nix distinguishes itself.
*Derivations* represent individual build steps, and *deriving paths* are needed to refer to the *outputs* of those build steps before they are built.
<!-- The two concepts need to be introduced together because, as described below, each depends on the other. -->
## Store Derivation {#store-derivation}
A derivation is a specification for running an executable on precisely defined input to produce on more [store objects][store object].
These store objects are known as the derivation's *outputs*.
Derivations are *built*, in which case the process is spawned according to the spec, and when it exits, required to leave behind files which will (after post-processing) become the outputs of the derivation.
This process is described in detail in [Building](@docroot@/store/building.md).
<!--
Some of these things are described directly below, but we envision with more material the exposition will probably want to migrate to separate pages benough this.
See outputs spec for an example of this one that migrated to its own page.
-->
A derivation consists of:
- A name
- An [inputs specification][inputs], a set of [deriving paths][deriving path]
- An [outputs specification][outputs], specifying which outputs should be produced, and various metadata about them.
- The ["system" type][system] (e.g. `x86_64-linux`) where the executable is to run.
- The [process creation fields]: to spawn the arbitrary process which will perform the build step.
[store derivation]: #store-derivation
[inputs]: #inputs
[input]: #inputs
[outputs]: ./outputs/index.md
[output]: ./outputs/index.md
[process creation fields]: #process-creation-fields
[builder]: #builder
[args]: #args
[env]: #env
[system]: #system
[content-addressed store]: @docroot@/glossary.md#gloss-content-addressed-store
[build system]: @docroot@/glossary.md#gloss-build-system
### Referencing derivations {#derivation-path}
Derivations are always referred to by the [store path] of the store object they are encoded to.
See the [encoding section](#derivation-encoding) for more details on how this encoding works, and thus what exactly what store path we would end up with for a given derivation.
The store path of the store object which encodes a derivation is often called a *derivation path* for brevity.
## Deriving path {#deriving-path}
Deriving paths are a way to refer to [store objects][store object] that may or may not yet be [realised][realise].
There are two forms:
- [*constant*]{#deriving-path-constant}: just a [store path].
It can be made [valid][validity] by copying it into the store: from the evaluator, command line interface or another store.
- [*output*]{#deriving-path-output}: a pair of a [store path] to a [store derivation] and an [output] name.
In pseudo code:
```typescript
type OutputName = String;
type ConstantPath = {
path: StorePath;
};
type OutputPath = {
drvPath: StorePath;
output: OutputName;
};
type DerivingPath = ConstantPath | OutputPath;
```
Deriving paths are necessary because, in general and particularly for [content-addressing derivations][content-addressing derivation], the [store path] of an [output] is not known in advance.
We can use an output deriving path to refer to such an output, instead of the store path which we do not yet know.
[deriving path]: #deriving-path
[validity]: @docroot@/glossary.md#gloss-validity
## Parts of a derivation
A derivation is constructed from the parts documented in the following subsections.
### Inputs {#inputs}
The inputs are a set of [deriving paths][deriving path], referring to all store objects needed in order to perform this build step.
The [process creation fields] will presumably include many [store paths][store path]:
- The path to the executable normally starts with a store path
- The arguments and environment variables likely contain many other store paths.
But rather than somehow scanning all the other fields for inputs, Nix requires that all inputs be explicitly collected in the inputs field. It is instead the responsibility of the creator of a derivation (e.g. the evaluator) to ensure that every store object referenced in another field (e.g. referenced by store path) is included in this inputs field.
### System {#system}
The system type on which the [`builder`](#attr-builder) executable is meant to be run.
A necessary condition for Nix to schedule a given derivation on some [Nix instance] is for the "system" of that derivation to match that instance's [`system` configuration option] or [`extra-platforms` configuration option].
By putting the `system` in each derivation, Nix allows *heterogenous* build plans, where not all steps can be run on the same machine or same sort of machine.
Nix can schedule builds such that it automatically builds on other platforms by [forwarding build requests](@docroot@/advanced-topics/distributed-builds.md) to other Nix instances.
[`system` configuration option]: @docroot@/command-ref/conf-file.md#conf-system
[`extra-platforms` configuration option]: @docroot@/command-ref/conf-file.md#conf-extra-platforms
[content-addressing derivation]: @docroot@/glossary.md#gloss-content-addressing-derivation
[realise]: @docroot@/glossary.md#gloss-realise
[store object]: @docroot@/store/store-object.md
[store path]: @docroot@/store/store-path.md
### Process creation fields {#process-creation-fields}
These are the three fields which describe how to spawn the process which (along with any of its own child processes) will perform the build.
You may note that this has everything needed for an `execve` system call.
#### Builder {#builder}
This is the path to an executable that will perform the build and produce the [outputs].
#### Arguments {#args}
Command-line arguments to be passed to the [`builder`](#builder) executable.
Note that these are the arguments after the first argument.
The first argument passed to the `builder` will be the value of `builder`, as per the usual convention on Unix.
See [Wikipedia](https://en.wikipedia.org/wiki/Argv) for details.
#### Environment Variables {#env}
Environment variables which will be passed to the [builder](#builder) executable.
### Placeholders
Placeholders are opaque values used within the [process creation fields] to [store objects] for which we don't yet know [store path]s.
They are strings in the form `/<hash>` that are embedded anywhere within the strings of those fields, and we are [considering](https://github.com/NixOS/nix/issues/12361) to add store-path-like placeholders.
> **Note**
>
> Output Deriving Path exist to solve the same problem as placeholders --- that is, referring to store objects for which we don't yet know a store path.
> They also have a string syntax with `^`, [described in the encoding section](#deriving-path-encoding).
> We could use that syntax instead of `/<hash>` for placeholders, but its human-legibility would cause problems.
There are two types of placeholder, corresponding to the two cases where this problem arises:
- [Output placeholder]{#output-placeholder}:
This is a placeholder for a derivation's own output.
- [Input placeholder]{#input-placeholder}:
This is a placeholder to a derivation's non-constant [input],
i.e. an input that is an [output derived path].
> **Explanation**
>
> In general, we need to realise [realise] a [store object] in order to be sure to have a store object for it.
> But for these two cases this is either impossible or impractical:
>
> - In the output case this is impossible:
>
> We cannot build the output until we have a correct derivation, and we cannot have a correct derivation (without using placeholders) until we have the output path.
>
> - In the input case this is impractical:
>
> If we always build a dependency first, and then refer to its output by store path, we would lose the ability for a derivation graph to describe an entire build plan consisting of multiple build steps.
## Encoding
### Derivation {#derivation-encoding}
There are two formats, documented separately:
- The legacy ["ATerm" format](@docroot@/protocols/derivation-aterm.md)
- The experimental, currently under development and changing [JSON format](@docroot@/protocols/json/derivation.md)
Every derivation has a canonical choice of encoding used to serialize it to a store object.
This ensures that there is a canonical [store path] used to refer to the derivation, as described in [Referencing derivations](#derivation-path).
> **Note**
>
> Currently, the canonical encoding for every derivation is the "ATerm" format,
> but this is subject to change for types derivations which are not yet stable.
Regardless of the format used, when serializing a derivation to a store object, that store object will be content-addressed.
In the common case, the inputs to store objects are either:
- [constant deriving paths](#deriving-path-constant) for content-addressed source objects, which are "initial inputs" rather than the outputs of some other derivation
- the outputs of other derivations
If those other derivations *also* abide by this common case (and likewise for transitive inputs), then the entire closure of the serialized derivation will be content-addressed.
### Deriving Path {#deriving-path-encoding}
- *constant*
Constant deriving paths are encoded simply as the underlying store path is.
Thus, we see that every encoded store path is also a valid encoded (constant) deriving path.
- *output*
Output deriving paths are encoded by
- encoding of a store path referring to a derivation
- a `^` separator (or `!` in some legacy contexts)
- the name of an output of the previously referred derivation
> **Example**
>
> ```
> /nix/store/lxrn8v5aamkikg6agxwdqd1jz7746wz4-firefox-98.0.2.drv^out
> ```
>
> This parses like so:
>
> ```
> /nix/store/lxrn8v5aamkikg6agxwdqd1jz7746wz4-firefox-98.0.2.drv^out
> |------------------------------------------------------------| |-|
> store path (usual encoding) output name
> |--|
> note the ".drv"
> ```
## Extending the model to be higher-order
**Experimental feature**: [`dynamic-derivations`](@docroot@/development/experimental-features.md#xp-feature-dynamic-derivations)
So far, we have used store paths to refer to derivations.
That works because we've implicitly assumed that all derivations are created *statically* --- created by some mechanism out of band, and then manually inserted into the store.
But what if derivations could also be created dynamically within Nix?
In other words, what if derivations could be the outputs of other derivations?
> **Note**
>
> In the parlance of "Build Systems à la carte", we are generalizing the Nix store layer to be a "Monadic" instead of "Applicative" build system.
How should we refer to such derivations?
A deriving path works, the same as how we refer to other derivation outputs.
But what about a dynamic derivations output?
(i.e. how do we refer to the output of a derivation, which is itself an output of a derivation?)
For that we need to generalize the definition of deriving path, replacing the store path used to refer to the derivation with a nested deriving path:
```diff
type OutputPath = {
- drvPath: StorePath;
+ drvPath: DerivingPath;
output: OutputName;
};
```
Now, the `drvPath` field of `OutputPath` is itself a `DerivingPath` instead of a `StorePath`.
With that change, here is updated definition:
```typescript
type OutputName = String;
type ConstantPath = {
path: StorePath;
};
type OutputPath = {
drvPath: DerivingPath;
output: OutputName;
};
type DerivingPath = ConstantPath | OutputPath;
```
Under this extended model, `DerivingPath`s are thus inductively built up from a root `ConstantPath`, wrapped with zero or more outer `OutputPath`s.
### Encoding {#deriving-path-encoding}
The encoding is adjusted in the natural way, encoding the `drv` field recursively using the same deriving path encoding.
The result of this is that it is possible to have a chain of `^<output-name>` at the end of the final string, as opposed to just a single one.
> **Example**
>
> ```
> /nix/store/lxrn8v5aamkikg6agxwdqd1jz7746wz4-firefox-98.0.2.drv^foo.drv^bar.drv^out
> |----------------------------------------------------------------------------| |-|
> inner deriving path (usual encoding) output name
> |--------------------------------------------------------------------| |-----|
> even more inner deriving path (usual encoding) output name
> |------------------------------------------------------------| |-----|
> innermost constant store path (usual encoding) output name
> ```
[Nix instance]: @docroot@/glossary.md#gloss-nix-instance

192
doc/manual/source/store/derivation/outputs/content-address.md Normal file
View file

@ -0,0 +1,192 @@
# Content-addressing derivation outputs
The content-addressing of an output only depends on that store object itself, not any other information external (such has how it was made, when it was made, etc.).
As a consequence, a store object will be content-addressed the same way regardless of whether it was manually inserted into the store, outputted by some derivation, or outputted by a some other derivation.
The output spec for a content-addressed output must contains the following field:
- *method*: how the data of the store object is digested into a content address
The possible choices of *method* are described in the [section on content-addressing store objects](@docroot@/store/store-object/content-address.md).
Given the method, the output's name (computed from the derivation name and output spec mapping as described above), and the data of the store object, the output's store path will be computed as described in that section.
## Fixed-output content-addressing {#fixed}
In this case the content address of the *fixed* in advanced by the derivation itself.
In other words, when the derivation has finished [building](@docroot@/store/building.md), and the provisional output' content-address is computed as part of the process to turn it into a *bona fide* store object, the calculated content address must much that given in the derivation, or the build of that derivation will be deemed a failure.
The output spec for an output with a fixed content addresses additionally contains:
- *hash*, the hash expected from digesting the store object's file system objects.
This hash may be of a freely-chosen hash algorithm (that Nix supports)
> **Design note**
>
> In principle, the output spec could also specify the references the store object should have, since the references and file system objects are equally parts of a content-addressed store object proper that contribute to its content-addressed.
> However, at this time, the references are not not done because all fixed content-addressed outputs are required to have no references (including no self-reference).
>
> Also in principle, rather than specifying the references and file system object data with separate hashes, a single hash that constraints both could be used.
> This could be done with the final store path's digest, or better yet, the hash that will become the store path's digest before it is truncated.
>
> These possible future extensions are included to elucidate the core property of fixed-output content addressing --- that all parts of the output must be cryptographically fixed with one or more hashes --- separate from the particulars of the currently-supported store object content-addressing schemes.
### Design rationale
What is the purpose of fixing an output's content address in advanced?
In abstract terms, the answer is carefully controlled impurity.
Unlike a regular derivation, the [builder] executable of a derivation that produced fixed outputs has access to the network.
The outputs' guaranteed content-addresses are supposed to mitigate the risk of the builder being given these capabilities;
regardless of what the builder does *during* the build, it cannot influence downstream builds in unanticipated ways because all information it passed downstream flows through the outputs whose content-addresses are fixed.
[builder]: @docroot@/store/derivation/index.md#builder
In concrete terms, the purpose of this feature is fetching fixed input data like source code from the network.
For example, consider a family of "fetch URL" derivations.
These derivations download files from given URL.
To ensure that the downloaded file has not been modified, each derivation must also specify a cryptographic hash of the file.
For example,
```jsonc
{
"outputs: {
"out": {
"method": "nar",
"hashAlgo": "sha256",
"hash: "1md7jsfd8pa45z73bz1kszpp01yw6x5ljkjk2hx7wl800any6465",
},
},
"env": {
"url": "http://ftp.gnu.org/pub/gnu/hello/hello-2.1.1.tar.gz"
// ...
},
// ...
}
```
It sometimes happens that the URL of the file changes,
e.g., because servers are reorganised or no longer available.
In these cases, we then must update the call to `fetchurl`, e.g.,
```diff
"env": {
- "url": "http://ftp.gnu.org/pub/gnu/hello/hello-2.1.1.tar.gz"
+ "url": "ftp://ftp.nluug.nl/pub/gnu/hello/hello-2.1.1.tar.gz"
// ...
},
```
If a `fetchurl` derivation's outputs were [input-addressed][input addressing], the output paths of the derivation and of *all derivations depending on it* would change.
For instance, if we were to change the URL of the Glibc source distribution in Nixpkgs (a package on which almost all other packages depend on Linux) massive rebuilds would be needed.
This is unfortunate for a change which we know cannot have a real effect as it propagates upwards through the dependency graph.
For content-addressed outputs (fixed or floating), on the other hand, the outputs' store path only depends on the derivation's name, data, and the `method` of the outputs' specs.
The rest of the derivation is ignored for the purpose of computing the output path.
> **History Note**
>
> Fixed content-addressing is especially important both today and historically as the *only* form of content-addressing that is stabilized.
> This is why the rationale above contrasts it with [input addressing].
## (Floating) Content-Addressing {#floating}
> **Warning**
> This is part of an [experimental feature](@docroot@/development/experimental-features.md).
>
> To use this type of output addressing, you must enable the
> [`ca-derivations`][xp-feature-ca-derivations] experimental feature.
> For example, in [nix.conf](@docroot@/command-ref/conf-file.md) you could add:
>
> ```
> extra-experimental-features = ca-derivations
> ```
With this experimemental feature enabled, derivation outputs can also be content-addressed *without* fixing in the output spec what the outputs' content address must be.
### Purity
Because the derivation output is not fixed (just like with [input addressing]), the [builder] is not given any impure capabilities [^purity].
> **Configuration note**
>
> Strictly speaking, the extent to which sandboxing and deprivilaging is possible varies with the environment Nix is running in.
> Nix's configuration settings indicate what level of sandboxing is required or enabled.
> Builds of derivations will fail if they request an absense of sandboxing which is not allowed.
> Builds of derivations will also fail if the level of sandboxing specified in the configure exceeds what is possible in teh given environment.
>
> (The "environment", in this case, consists of attributes such as the Operating System Nix runs atop, along with the operating-system-specific privilages that Nix has been granted.
> Because of how conventional operating systems like macos, Linux, etc. work, granting builders *fewer* privilages may ironically require that Nix be run with *more* privilages.)
That said, derivations producing floating content-addressed outputs may declare their builders as impure (like the builders of derivations producing producing fixed outputs).
This is provisionally supported as part of the [`impure-derivations`][xp-feature-impure-derivations] experimental feature.
### Compatibility negotiation
Any derivation producing a floating content-addresssed output implicitly requires the `ca-derivations` [system feature](@docroot@/command-ref/conf-file.md#conf-system-features).
This prevents scheduling the building of the derivation on a machine without the experimental feature enabled.
Even once the experimental feature is stabilized, this is still useful in order to be allow using remote builder running odler versions of Nix, or alternative implementations that do not support floating content addressing.
### Determinism
In the earlier [discussion of how self-references are handled when content-addressing store objects](@docroot@/store/store-object/content-address.html#self-references), it was pointed out that methods of producing store objects ought to be deterministic regardless of the choice of provisional store path.
For store objects produced by manually inserting into the store to create a store object, the "method of production" is an informally concept --- formally, Nix has no idea where the store object came from, and content-addressing is crucial in order to ensure that the derivation is *intrinsically* tamper-proof.
But for store objects produced by derivation, the "method is quite formal" --- the whole point of derivations is to be a formal notion of building, after all.
In this case, we can elevate this informal property to a formal one.
A *determinstic* content-addressing derivation should produce outputs with the same content addresses:
1. Every time the builder is run
This is because either the builder is completely sandboxed, or because all any remaining impurities that leak inside the build sandbox are ignored by the builder and do not influence its behavior.
2. Regardless of the choice of any provisional outputs paths
Provisional store paths must be chosen for any output that has a self-reference.
The choice of provisional store path can be thought of as an impurity, since it is an arbitrary choice.
If provisional outputs paths are deterministically chosen, we are in the first branch of part (1).
The builder the data it produces based on it in arbitrary ways, but this gets us closer to to [input addressing].
Deterministically choosing the provisional path may be considered "complete sandboxing" by removing an impurity, but this is unsatisfactory
<!--
TODO
(Both these points will be expanded-upon below.)
-->
If provisional outputs paths are randomly chosen, we are in the second branch of part (1).
The builder *must* not let the random input affect the final outputs it produces, and multiple builds may be performed and the compared in order to ensure that this is in fact the case.
### Floating versus Fixed
While the distinction between content- and input-addressing is one of *mechanism*, the distinction between fixed and floating content addressing is more one of *policy*.
A fixed output that passes its content address check is just like a floating output.
It is only in the potential for that check to fail that they are different.
> **Design Note**
>
> In a future world where floating content-addressing is also stable, we in principle no longer need separate [fixed](#fixed) content-addressing.
> Instead, we could always use floating content-addressing, and separately assert the precise value content address of a given store object to be used as an input (of another derivation).
> A stand-alone assertion object of this sort is not yet implemented, but its possible creation is tracked in [Issue #11955](https://github.com/NixOS/nix/issues/11955).
>
> In the current version of Nix, fixed outputs which fail their hash check are still registered as valid store objects, just not registered as outputs of the derivation which produced them.
> This is an optimization that means if the wrong output hash is specified in a derivation, and then the derivation is recreated with the right output hash, derivation does not need to be rebuilt --- avoiding downloading potentially large amounts of data twice.
> This optimisation prefigures the design above:
> If the output hash assertion was removed outside the derivation itself, Nix could additionally not only register that outputted store object like today, but could also make note that derivation did in fact successfully download some data.
For example, for the "fetch URL" example above, making such a note is tantamount to recording what data is available at the time of download at the given URL.
> It would only be when Nix subsequently tries to build something with that (refining our example) downloaded source code that Nix would be forced to check the output hash assertion, preventing it from e.g. building compromised malware.
>
> Recapping, Nix would
>
> 1. successfully download data
> 2. insert that data into the store
> 3. associate (presumably with some sort of expiration policy) the downloaded data with the derivation that downloaded it
>
> But only use the downloaded store object in subsequent derivations that depended upon the assertion if the assertion passed.
>
> This possible future extension is included to illustrate this distinction:
[input addressing]: ./input-address.md
[xp-feature-ca-derivations]: @docroot@/development/experimental-features.md#xp-feature-ca-derivations
[xp-feature-git-hashing]: @docroot@/development/experimental-features.md#xp-feature-git-hashing
[xp-feature-impure-derivations]: @docroot@/development/experimental-features.md#xp-feature-impure-derivations

97
doc/manual/source/store/derivation/outputs/index.md Normal file
View file

@ -0,0 +1,97 @@
# Derivation Outputs and Types of Derivations
As stated on the [main pages on derivations](../index.md#store-derivation),
a derivation produces [store objects], which are known as the *outputs* of the derivation.
Indeed, the entire point of derivations is to produce these outputs, and to reliably and reproducably produce these derivations each time the derivation is run.
One of the parts of a derivation is its *outputs specification*, which specifies certain information about the outputs the derivation produces when run.
The outputs specification is a map, from names to specifications for individual outputs.
## Output Names {#outputs}
Output names can be any string which is also a valid [store path] name.
The name mapped to each output specification is not actually the name of the output.
In the general case, the output store object has name `derivationName + "-" + outputSpecName`, not any other metadata about it.
However, an output spec named "out" describes and output store object whose name is just the derivation name.
> **Example**
>
> A derivation is named `hello`, and has two outputs, `out`, and `dev`
>
> - The derivation's path will be: `/nix/store/<hash>-hello.drv`.
>
> - The store path of `out` will be: `/nix/store/<hash>-hello`.
>
> - The store path of `dev` will be: `/nix/store/<hash>-hello-dev`.
The outputs are the derivations are the [store objects][store object] it is obligated to produce.
> **Note**
>
> The formal terminology here is somewhat at adds with everyday communication in the Nix community today.
> "output" in casual usage tends to refer to either to the actual output store object, or the notional output spec, depending on context.
>
> For example "hello's `dev` output" means the store object referred to by the store path `/nix/store/<hash>-hello-dev`.
> It is unusual to call this the "`hello-dev` output", even though `hello-dev` is the actual name of that store object.
## Types of output addressing
The main information contained in an output specification is how the derivation output is addressed.
In particular, the specification decides:
- whether the output is [content-addressed](./content-address.md) or [input-addressed](./input-address.md)
- if the content is content-addressed, how is it content addressed
- if the content is content-addressed, [what is its content address](./content-address.md#fixed-content-addressing) (and thus what is its [store path])
## Types of derivations
The sections on each type of derivation output addressing ended up discussing other attributes of the derivation besides its outputs, such as purity, scheduling, determinism, etc.
This is no concidence; for the type of a derivation is in fact one-for-one with the type of its outputs:
- A derivation that produces *xyz-addressed* outputs is an *xyz-addressing* derivations.
The rules for this are fairly concise:
- All the outputs must be of the same type / use the same addressing
- The derivation must have at least one output
- Additionally, if the outputs are fixed content-addressed, there must be exactly one output, whose specification is mapped from the name `out`.
(The name `out` is special, according to the rules described above.
Having only one output and calling its specification `out` means the single output is effectively anonymous; the store path just has the derivation name.)
(This is an arbitrary restriction that could be lifted.)
- The output is either *fixed* or *floating*, indicating whether the its store path is known prior to building it.
- With fixed content-addressing it is fixed.
> A *fixed content-addressing* derivation is also called a *fixed-output derivation*, since that is the only currently-implemented form of fixed-output addressing
- With floating content-addressing or input-addressing it is floating.
> Thus, historically with Nix, with no experimental features enabled, *all* outputs are fixed.
- The derivation may be *pure* or *impure*, indicating what read access to the outside world the [builder](../index.md#builder) has.
- An input-addressing derivation *must* be pure.
> If it is impure, we would have a large problem, because an input-addressed derivation always produces outputs with the same paths.
- A content-addressing derivation may be pure or impure
- If it is impure, it may be be fixed (typical), or it may be floating if the additional [`impure-derivations`][xp-feature-impure-derivations] experimental feature is enabled.
- If it is pure, it must be floating.
- Pure, fixed content-addressing derivations are not suppported
> There is no use for this forth combination.
> The sole purpose of an output's store path being fixed is to support the derivation being impure.
[xp-feature-ca-derivations]: @docroot@/development/experimental-features.md#xp-feature-ca-derivations
[xp-feature-git-hashing]: @docroot@/development/experimental-features.md#xp-feature-git-hashing
[xp-feature-impure-derivations]: @docroot@/development/experimental-features.md#xp-feature-impure-derivations

31
doc/manual/source/store/derivation/outputs/input-address.md Normal file
View file

@ -0,0 +1,31 @@
# Input-addressing derivation outputs
[input addressing]: #input-addressing
"Input addressing" means the address the store object by the *way it was made* rather than *what it is*.
That is to say, an input-addressed output's store path is a function not of the output itself, but of the derivation that produced it.
Even if two store paths have the same contents, if they are produced in different ways, and one is input-addressed, then they will have different store paths, and thus guaranteed to not be the same store object.
<!---
### Modulo fixed-output derivations
**TODO hash derivation modulo.**
So how do we compute the hash part of the output path of a derivation?
This is done by the function `hashDrv`, shown in Figure 5.10.
It distinguishes between two cases.
If the derivation is a fixed-output derivation, then it computes a hash over just the `outputHash` attributes.
If the derivation is not a fixed-output derivation, we replace each element in the derivation’s inputDrvs with the result of a call to `hashDrv` for that element.
(The derivation at each store path in `inputDrvs` is converted from its on-disk ATerm representation back to a `StoreDrv` by the function `parseDrv`.) In essence, `hashDrv` partitions store derivations into equivalence classes, and for hashing purpose it replaces each store path in a derivation graph with its equivalence class.
The recursion in Figure 5.10 is inefficient:
it will call itself once for each path by which a subderivation can be reached, i.e., `O(V k)` times for a derivation graph with `V` derivations and with out-degree of at most `k`.
In the actual implementation, memoisation is used to reduce this to `O(V + E)` complexity for a graph with E edges.
-->
[xp-feature-ca-derivations]: @docroot@/development/experimental-features.md#xp-feature-ca-derivations
[xp-feature-git-hashing]: @docroot@/development/experimental-features.md#xp-feature-git-hashing
[xp-feature-impure-derivations]: @docroot@/development/experimental-features.md#xp-feature-impure-derivations

33
doc/manual/source/store/store-object/content-address.md
View file

@ -24,13 +24,17 @@ For the full specification of the algorithms involved, see the [specification of
### File System Objects
With all currently supported store object content addressing methods, the file system object is always [content-addressed][fso-ca] first, and then that hash is incorporated into content address computation for the store object.
With all currently-supported store object content-addressing methods, the file system object is always [content-addressed][fso-ca] first, and then that hash is incorporated into content address computation for the store object.
### References
#### References to other store objects
With all currently supported store object content addressing methods,
other objects are referred to by their regular (string-encoded-) [store paths][Store Path].
#### Self-references
Self-references however cannot be referred to by their path, because we are in the midst of describing how to compute that path!
> The alternative would require finding as hash function fixed point, i.e. the solution to an equation in the form
@ -40,7 +44,28 @@ Self-references however cannot be referred to by their path, because we are in t
> which is computationally infeasible.
> As far as we know, this is equivalent to finding a hash collision.
Instead we just have a "has self reference" boolean, which will end up affecting the digest.
Instead we have a "has self-reference" boolean, which ends up affecting the digest:
In all currently-supported store object content-addressing methods, when hashing the file system object data, any occurence of store object's own store path in the digested data is replaced with a [sentinel value](https://en.wikipedia.org/wiki/Sentinel_value).
The hashes of these modified input streams are used instead.
When validating the content address of a store object after the fact, the above process works as written.
However, when first creating the store object we don't know the store object's store path, as explained just above.
We therefore, strictly speaking, do not know what value we will be replacing with the sentinental value in the inputs to hash functions.
What instead happens is that the provisional store object --- the data from which we wish to create a store object --- is paired with a provisional "scratch" store path (that presumably was chosen when the data was created).
That provisional store path is instead what is replaced with the sentinel value, rather than the final store object which we do not yet know.
> **Design note**
>
> It is an informal property of content-addressed store objects that the choice of provisional store path should not matter.
> In other words, if a provisional store object is prepared in the same way except for the choice of provision store path, the provisional data need not be identical.
> But, after the sentinel value is substituted in place of each provisional store object's provision store path, the final so-normalized data *should* be identical.
>
> If, conversely, the data after this normalization process is still different, we'll compute a different content-address.
> The method of preparing the provisional self-referenced data has *failed* to be deterministic in the sense of not *leaking* the choice of provisional store path --- a choice which is supposed to be arbitrary --- into the final store object.
>
> This property is informal because at this stage, we are just described store objects, which have no formal notion of their origin.
> Without such a formal notion, there is nothing to formally accuse of being insufficiently deterministic.
> Where we cover [derivations](@docroot@/store/derivation/index.md), we will have a chance to make this a formal property, not of content-addressed store objects themselves, but of derivations that *produce* content-addressed store objects.
### Name and Store Directory
@ -63,7 +88,7 @@ References are not supported: store objects with flat hashing *and* references c
This also uses the corresponding [Flat](../file-system-object/content-address.md#serial-flat) method of file system object content addressing.
References to other store objects are supported, but self references are not.
References to other store objects are supported, but self-references are not.
This is the only store-object content-addressing method that is not named identically with a corresponding file system object method.
It is somewhat obscure, mainly used for "drv files"
@ -74,7 +99,7 @@ Prefer another method if possible.
This uses the corresponding [Nix Archive](../file-system-object/content-address.md#serial-nix-archive) method of file system object content addressing.
References (to other store objects and self references alike) are supported so long as the hash algorithm is SHA-256, but not (neither kind) otherwise.
References (to other store objects and self-references alike) are supported so long as the hash algorithm is SHA-256, but not (neither kind) otherwise.
### Git { #method-git }