kloenk/lix
0
0
Fork 0
forked from lix-project/lix
Code Pull requests Activity

Replace the trailing markdown spaces by a backslash

Browse source 
They are equivalent according to
<https://spec.commonmark.org/0.29/#hard-line-breaks>,
and the trailing spaces tend to be a pain (because the make git
complain, editors tend to want to remove them − the `.editorconfig`
actually specifies that − etc..).
This commit is contained in:
regnat 2021-04-23 14:30:42 +02:00
parent 293220bed5
commit 31313d1401
20 changed files with 260 additions and 260 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

4
doc/manual/src/advanced-topics/cores-vs-jobs.md
View file

@ -4,13 +4,13 @@ Nix has two relevant settings with regards to how your CPU cores will
be utilized: `cores` and `max-jobs`. This chapter will talk about what be utilized: `cores` and `max-jobs`. This chapter will talk about what
they are, how they interact, and their configuration trade-offs. they are, how they interact, and their configuration trade-offs.
- `max-jobs` - `max-jobs`\
Dictates how many separate derivations will be built at the same Dictates how many separate derivations will be built at the same
time. If you set this to zero, the local machine will do no time. If you set this to zero, the local machine will do no
builds. Nix will still substitute from binary caches, and build builds. Nix will still substitute from binary caches, and build
remotely if remote builders are configured. remotely if remote builders are configured.
- `cores` - `cores`\
Suggests how many cores each derivation should use. Similar to Suggests how many cores each derivation should use. Similar to
`make -j`. `make -j`.

30
doc/manual/src/command-ref/env-common.md
View file

@ -2,11 +2,11 @@
Most Nix commands interpret the following environment variables: Most Nix commands interpret the following environment variables:
- `IN_NIX_SHELL` - `IN_NIX_SHELL`\
Indicator that tells if the current environment was set up by Indicator that tells if the current environment was set up by
`nix-shell`. Since Nix 2.0 the values are `"pure"` and `"impure"` `nix-shell`. Since Nix 2.0 the values are `"pure"` and `"impure"`
- `NIX_PATH` - `NIX_PATH`\
A colon-separated list of directories used to look up Nix A colon-separated list of directories used to look up Nix
expressions enclosed in angle brackets (i.e., `<path>`). For expressions enclosed in angle brackets (i.e., `<path>`). For
instance, the value instance, the value
@ -40,7 +40,7 @@ Most Nix commands interpret the following environment variables:
The search path can be extended using the `-I` option, which takes The search path can be extended using the `-I` option, which takes
precedence over `NIX_PATH`. precedence over `NIX_PATH`.
- `NIX_IGNORE_SYMLINK_STORE` - `NIX_IGNORE_SYMLINK_STORE`\
Normally, the Nix store directory (typically `/nix/store`) is not Normally, the Nix store directory (typically `/nix/store`) is not
allowed to contain any symlink components. This is to prevent allowed to contain any symlink components. This is to prevent
“impure” builds. Builders sometimes “canonicalise” paths by “impure” builds. Builders sometimes “canonicalise” paths by
@ -62,41 +62,41 @@ Most Nix commands interpret the following environment variables:
Consult the mount 8 manual page for details. Consult the mount 8 manual page for details.
- `NIX_STORE_DIR` - `NIX_STORE_DIR`\
Overrides the location of the Nix store (default `prefix/store`). Overrides the location of the Nix store (default `prefix/store`).
- `NIX_DATA_DIR` - `NIX_DATA_DIR`\
Overrides the location of the Nix static data directory (default Overrides the location of the Nix static data directory (default
`prefix/share`). `prefix/share`).
- `NIX_LOG_DIR` - `NIX_LOG_DIR`\
Overrides the location of the Nix log directory (default Overrides the location of the Nix log directory (default
`prefix/var/log/nix`). `prefix/var/log/nix`).
- `NIX_STATE_DIR` - `NIX_STATE_DIR`\
Overrides the location of the Nix state directory (default Overrides the location of the Nix state directory (default
`prefix/var/nix`). `prefix/var/nix`).
- `NIX_CONF_DIR` - `NIX_CONF_DIR`\
Overrides the location of the system Nix configuration directory Overrides the location of the system Nix configuration directory
(default `prefix/etc/nix`). (default `prefix/etc/nix`).
- `NIX_CONFIG` - `NIX_CONFIG`\
Applies settings from Nix configuration from the environment. Applies settings from Nix configuration from the environment.
The content is treated as if it was read from a Nix configuration file. The content is treated as if it was read from a Nix configuration file.
Settings are separated by the newline character. Settings are separated by the newline character.
- `NIX_USER_CONF_FILES` - `NIX_USER_CONF_FILES`\
Overrides the location of the user Nix configuration files to load Overrides the location of the user Nix configuration files to load
from (defaults to the XDG spec locations). The variable is treated from (defaults to the XDG spec locations). The variable is treated
as a list separated by the `:` token. as a list separated by the `:` token.
- `TMPDIR` - `TMPDIR`\
Use the specified directory to store temporary files. In particular, Use the specified directory to store temporary files. In particular,
this includes temporary build directories; these can take up this includes temporary build directories; these can take up
substantial amounts of disk space. The default is `/tmp`. substantial amounts of disk space. The default is `/tmp`.
- `NIX_REMOTE` - `NIX_REMOTE`\
This variable should be set to `daemon` if you want to use the Nix This variable should be set to `daemon` if you want to use the Nix
daemon to execute Nix operations. This is necessary in [multi-user daemon to execute Nix operations. This is necessary in [multi-user
Nix installations](../installation/multi-user.md). If the Nix Nix installations](../installation/multi-user.md). If the Nix
@ -104,16 +104,16 @@ Most Nix commands interpret the following environment variables:
should be set to `unix://path/to/socket`. Otherwise, it should be should be set to `unix://path/to/socket`. Otherwise, it should be
left unset. left unset.
- `NIX_SHOW_STATS` - `NIX_SHOW_STATS`\
If set to `1`, Nix will print some evaluation statistics, such as If set to `1`, Nix will print some evaluation statistics, such as
the number of values allocated. the number of values allocated.
- `NIX_COUNT_CALLS` - `NIX_COUNT_CALLS`\
If set to `1`, Nix will print how often functions were called during If set to `1`, Nix will print how often functions were called during
Nix expression evaluation. This is useful for profiling your Nix Nix expression evaluation. This is useful for profiling your Nix
expressions. expressions.
- `GC_INITIAL_HEAP_SIZE` - `GC_INITIAL_HEAP_SIZE`\
If Nix has been configured to use the Boehm garbage collector, this If Nix has been configured to use the Boehm garbage collector, this
variable sets the initial size of the heap in bytes. It defaults to variable sets the initial size of the heap in bytes. It defaults to
384 MiB. Setting it to a low value reduces memory consumption, but 384 MiB. Setting it to a low value reduces memory consumption, but

6
doc/manual/src/command-ref/nix-build.md
View file

@ -47,16 +47,16 @@ All options not listed here are passed to `nix-store
--realise`, except for `--arg` and `--attr` / `-A` which are passed to --realise`, except for `--arg` and `--attr` / `-A` which are passed to
`nix-instantiate`. `nix-instantiate`.
- `--no-out-link` - `--no-out-link`\
Do not create a symlink to the output path. Note that as a result Do not create a symlink to the output path. Note that as a result
the output does not become a root of the garbage collector, and so the output does not become a root of the garbage collector, and so
might be deleted by `nix-store might be deleted by `nix-store
--gc`. --gc`.
- `--dry-run` - `--dry-run`\
Show what store paths would be built or downloaded. Show what store paths would be built or downloaded.
- `--out-link` / `-o` *outlink* - `--out-link` / `-o` *outlink*\
Change the name of the symlink to the output path created from Change the name of the symlink to the output path created from
`result` to *outlink*. `result` to *outlink*.

16
doc/manual/src/command-ref/nix-channel.md
View file

@ -17,26 +17,26 @@ To see the list of official NixOS channels, visit
This command has the following operations: This command has the following operations:
- `--add` *url* \[*name*\] - `--add` *url* \[*name*\]\
Adds a channel named *name* with URL *url* to the list of subscribed Adds a channel named *name* with URL *url* to the list of subscribed
channels. If *name* is omitted, it defaults to the last component of channels. If *name* is omitted, it defaults to the last component of
*url*, with the suffixes `-stable` or `-unstable` removed. *url*, with the suffixes `-stable` or `-unstable` removed.
- `--remove` *name* - `--remove` *name*\
Removes the channel named *name* from the list of subscribed Removes the channel named *name* from the list of subscribed
channels. channels.
- `--list` - `--list`\
Prints the names and URLs of all subscribed channels on standard Prints the names and URLs of all subscribed channels on standard
output. output.
- `--update` \[*names*…\] - `--update` \[*names*…\]\
Downloads the Nix expressions of all subscribed channels (or only Downloads the Nix expressions of all subscribed channels (or only
those included in *names* if specified) and makes them the default those included in *names* if specified) and makes them the default
for `nix-env` operations (by symlinking them from the directory for `nix-env` operations (by symlinking them from the directory
`~/.nix-defexpr`). `~/.nix-defexpr`).
- `--rollback` \[*generation*\] - `--rollback` \[*generation*\]\
Reverts the previous call to `nix-channel Reverts the previous call to `nix-channel
--update`. Optionally, you can specify a specific channel generation --update`. Optionally, you can specify a specific channel generation
number to restore. number to restore.
@ -70,14 +70,14 @@ $ nix-instantiate --eval -E '(import <nixpkgs> {}).lib.version'
# Files # Files
- `/nix/var/nix/profiles/per-user/username/channels` - `/nix/var/nix/profiles/per-user/username/channels`\
`nix-channel` uses a `nix-env` profile to keep track of previous `nix-channel` uses a `nix-env` profile to keep track of previous
versions of the subscribed channels. Every time you run `nix-channel versions of the subscribed channels. Every time you run `nix-channel
--update`, a new channel generation (that is, a symlink to the --update`, a new channel generation (that is, a symlink to the
channel Nix expressions in the Nix store) is created. This enables channel Nix expressions in the Nix store) is created. This enables
`nix-channel --rollback` to revert to previous versions. `nix-channel --rollback` to revert to previous versions.
- `~/.nix-defexpr/channels` - `~/.nix-defexpr/channels`\
This is a symlink to This is a symlink to
`/nix/var/nix/profiles/per-user/username/channels`. It ensures that `/nix/var/nix/profiles/per-user/username/channels`. It ensures that
`nix-env` can find your channels. In a multi-user installation, you `nix-env` can find your channels. In a multi-user installation, you
@ -89,7 +89,7 @@ $ nix-instantiate --eval -E '(import <nixpkgs> {}).lib.version'
A channel URL should point to a directory containing the following A channel URL should point to a directory containing the following
files: files:
- `nixexprs.tar.xz` - `nixexprs.tar.xz`\
A tarball containing Nix expressions and files referenced by them A tarball containing Nix expressions and files referenced by them
(such as build scripts and patches). At the top level, the tarball (such as build scripts and patches). At the top level, the tarball
should contain a single directory. That directory must contain a should contain a single directory. That directory must contain a

14
doc/manual/src/command-ref/nix-copy-closure.md
View file

@ -35,21 +35,21 @@ and second to send the dump of those paths. If this bothers you, use
# Options # Options
- `--to` - `--to`\
Copy the closure of _paths_ from the local Nix store to the Nix Copy the closure of _paths_ from the local Nix store to the Nix
store on _machine_. This is the default. store on _machine_. This is the default.
- `--from` - `--from`\
Copy the closure of _paths_ from the Nix store on _machine_ to the Copy the closure of _paths_ from the Nix store on _machine_ to the
local Nix store. local Nix store.
- `--gzip` - `--gzip`\
Enable compression of the SSH connection. Enable compression of the SSH connection.
- `--include-outputs` - `--include-outputs`\
Also copy the outputs of store derivations included in the closure. Also copy the outputs of store derivations included in the closure.
- `--use-substitutes` / `-s` - `--use-substitutes` / `-s`\
Attempt to download missing paths on the target machine using Nix’s Attempt to download missing paths on the target machine using Nix’s
substitute mechanism. Any paths that cannot be substituted on the substitute mechanism. Any paths that cannot be substituted on the
target are still copied normally from the source. This is useful, target are still copied normally from the source. This is useful,
@ -58,12 +58,12 @@ and second to send the dump of those paths. If this bothers you, use
`nixos.org` (the default binary cache server) is `nixos.org` (the default binary cache server) is
fast. fast.
- `-v` - `-v`\
Show verbose output. Show verbose output.
# Environment variables # Environment variables
- `NIX_SSHOPTS` - `NIX_SSHOPTS`\
Additional options to be passed to `ssh` on the command Additional options to be passed to `ssh` on the command
line. line.

76
doc/manual/src/command-ref/nix-env.md
View file

@ -36,27 +36,27 @@ case-sensitive. The regular expression can optionally be followed by a
dash and a version number; if omitted, any version of the package will dash and a version number; if omitted, any version of the package will
match. Here are some examples: match. Here are some examples:
- `firefox` - `firefox`\
Matches the package name `firefox` and any version. Matches the package name `firefox` and any version.
- `firefox-32.0` - `firefox-32.0`\
Matches the package name `firefox` and version `32.0`. Matches the package name `firefox` and version `32.0`.
- `gtk\\+` - `gtk\\+`\
Matches the package name `gtk+`. The `+` character must be escaped Matches the package name `gtk+`. The `+` character must be escaped
using a backslash to prevent it from being interpreted as a using a backslash to prevent it from being interpreted as a
quantifier, and the backslash must be escaped in turn with another quantifier, and the backslash must be escaped in turn with another
backslash to ensure that the shell passes it on. backslash to ensure that the shell passes it on.
- `.\*` - `.\*`\
Matches any package name. This is the default for most commands. Matches any package name. This is the default for most commands.
- `'.*zip.*'` - `'.*zip.*'`\
Matches any package name containing the string `zip`. Note the dots: Matches any package name containing the string `zip`. Note the dots:
`'*zip*'` does not work, because in a regular expression, the `'*zip*'` does not work, because in a regular expression, the
character `*` is interpreted as a quantifier. character `*` is interpreted as a quantifier.
- `'.*(firefox|chromium).*'` - `'.*(firefox|chromium).*'`\
Matches any package name containing the strings `firefox` or Matches any package name containing the strings `firefox` or
`chromium`. `chromium`.
@ -66,7 +66,7 @@ This section lists the options that are common to all operations. These
options are allowed for every subcommand, though they may not always options are allowed for every subcommand, though they may not always
have an effect. have an effect.
- `--file` / `-f` *path* - `--file` / `-f` *path*\
Specifies the Nix expression (designated below as the *active Nix Specifies the Nix expression (designated below as the *active Nix
expression*) used by the `--install`, `--upgrade`, and `--query expression*) used by the `--install`, `--upgrade`, and `--query
--available` operations to obtain derivations. The default is --available` operations to obtain derivations. The default is
@ -77,13 +77,13 @@ have an effect.
unpacked to a temporary location. The tarball must include a single unpacked to a temporary location. The tarball must include a single
top-level directory containing at least a file named `default.nix`. top-level directory containing at least a file named `default.nix`.
- `--profile` / `-p` *path* - `--profile` / `-p` *path*\
Specifies the profile to be used by those operations that operate on Specifies the profile to be used by those operations that operate on
a profile (designated below as the *active profile*). A profile is a a profile (designated below as the *active profile*). A profile is a
sequence of user environments called *generations*, one of which is sequence of user environments called *generations*, one of which is
the *current generation*. the *current generation*.
- `--dry-run` - `--dry-run`\
For the `--install`, `--upgrade`, `--uninstall`, For the `--install`, `--upgrade`, `--uninstall`,
`--switch-generation`, `--delete-generations` and `--rollback` `--switch-generation`, `--delete-generations` and `--rollback`
operations, this flag will cause `nix-env` to print what *would* be operations, this flag will cause `nix-env` to print what *would* be
@ -93,7 +93,7 @@ have an effect.
[substituted](../glossary.md) (i.e., downloaded) and which paths [substituted](../glossary.md) (i.e., downloaded) and which paths
will be built from source (because no substitute is available). will be built from source (because no substitute is available).
- `--system-filter` *system* - `--system-filter` *system*\
By default, operations such as `--query By default, operations such as `--query
--available` show derivations matching any platform. This option --available` show derivations matching any platform. This option
allows you to use derivations for the specified platform *system*. allows you to use derivations for the specified platform *system*.
@ -102,7 +102,7 @@ have an effect.
# Files # Files
- `~/.nix-defexpr` - `~/.nix-defexpr`\
The source for the default Nix expressions used by the The source for the default Nix expressions used by the
`--install`, `--upgrade`, and `--query --available` operations to `--install`, `--upgrade`, and `--query --available` operations to
obtain derivations. The `--file` option may be used to override obtain derivations. The `--file` option may be used to override
@ -140,7 +140,7 @@ have an effect.
The command `nix-channel` places symlinks to the downloaded Nix The command `nix-channel` places symlinks to the downloaded Nix
expressions from each subscribed channel in this directory. expressions from each subscribed channel in this directory.
- `~/.nix-profile` - `~/.nix-profile`\
A symbolic link to the user's current profile. By default, this A symbolic link to the user's current profile. By default, this
symlink points to `prefix/var/nix/profiles/default`. The `PATH` symlink points to `prefix/var/nix/profiles/default`. The `PATH`
environment variable should include `~/.nix-profile/bin` for the environment variable should include `~/.nix-profile/bin` for the
@ -217,13 +217,13 @@ a number of possible ways:
## Flags ## Flags
- `--prebuilt-only` / `-b` - `--prebuilt-only` / `-b`\
Use only derivations for which a substitute is registered, i.e., Use only derivations for which a substitute is registered, i.e.,
there is a pre-built binary available that can be downloaded in lieu there is a pre-built binary available that can be downloaded in lieu
of building the derivation. Thus, no packages will be built from of building the derivation. Thus, no packages will be built from
source. source.
- `--preserve-installed`; `-P` - `--preserve-installed`; `-P`\
Do not remove derivations with a name matching one of the Do not remove derivations with a name matching one of the
derivations being installed. Usually, trying to have two versions of derivations being installed. Usually, trying to have two versions of
the same package installed in the same generation of a profile will the same package installed in the same generation of a profile will
@ -231,7 +231,7 @@ a number of possible ways:
clashes between the two versions. However, this is not the case for clashes between the two versions. However, this is not the case for
all packages. all packages.
- `--remove-all`; `-r` - `--remove-all`; `-r`\
Remove all previously installed packages first. This is equivalent Remove all previously installed packages first. This is equivalent
to running `nix-env -e '.*'` first, except that everything happens to running `nix-env -e '.*'` first, except that everything happens
in a single transaction. in a single transaction.
@ -346,24 +346,24 @@ version is installed.
## Flags ## Flags
- `--lt` - `--lt`\
Only upgrade a derivation to newer versions. This is the default. Only upgrade a derivation to newer versions. This is the default.
- `--leq` - `--leq`\
In addition to upgrading to newer versions, also “upgrade” to In addition to upgrading to newer versions, also “upgrade” to
derivations that have the same version. Version are not a unique derivations that have the same version. Version are not a unique
identification of a derivation, so there may be many derivations identification of a derivation, so there may be many derivations
that have the same version. This flag may be useful to force that have the same version. This flag may be useful to force
“synchronisation” between the installed and available derivations. “synchronisation” between the installed and available derivations.
- `--eq` - `--eq`\
*Only* “upgrade” to derivations that have the same version. This may *Only* “upgrade” to derivations that have the same version. This may
not seem very useful, but it actually is, e.g., when there is a new not seem very useful, but it actually is, e.g., when there is a new
release of Nixpkgs and you want to replace installed applications release of Nixpkgs and you want to replace installed applications
with the same versions built against newer dependencies (to reduce with the same versions built against newer dependencies (to reduce
the number of dependencies floating around on your system). the number of dependencies floating around on your system).
- `--always` - `--always`\
In addition to upgrading to newer versions, also “upgrade” to In addition to upgrading to newer versions, also “upgrade” to
derivations that have the same or a lower version. I.e., derivations derivations that have the same or a lower version. I.e., derivations
may actually be downgraded depending on what is available in the may actually be downgraded depending on what is available in the
@ -578,11 +578,11 @@ The derivations are sorted by their `name` attributes.
The following flags specify the set of things on which the query The following flags specify the set of things on which the query
operates. operates.
- `--installed` - `--installed`\
The query operates on the store paths that are installed in the The query operates on the store paths that are installed in the
current generation of the active profile. This is the default. current generation of the active profile. This is the default.
- `--available`; `-a` - `--available`; `-a`\
The query operates on the derivations that are available in the The query operates on the derivations that are available in the
active Nix expression. active Nix expression.
@ -593,24 +593,24 @@ selected derivations. Multiple flags may be specified, in which case the
information is shown in the order given here. Note that the name of the information is shown in the order given here. Note that the name of the
derivation is shown unless `--no-name` is specified. derivation is shown unless `--no-name` is specified.
- `--xml` - `--xml`\
Print the result in an XML representation suitable for automatic Print the result in an XML representation suitable for automatic
processing by other tools. The root element is called `items`, which processing by other tools. The root element is called `items`, which
contains a `item` element for each available or installed contains a `item` element for each available or installed
derivation. The fields discussed below are all stored in attributes derivation. The fields discussed below are all stored in attributes
of the `item` elements. of the `item` elements.
- `--json` - `--json`\
Print the result in a JSON representation suitable for automatic Print the result in a JSON representation suitable for automatic
processing by other tools. processing by other tools.
- `--prebuilt-only` / `-b` - `--prebuilt-only` / `-b`\
Show only derivations for which a substitute is registered, i.e., Show only derivations for which a substitute is registered, i.e.,
there is a pre-built binary available that can be downloaded in lieu there is a pre-built binary available that can be downloaded in lieu
of building the derivation. Thus, this shows all packages that of building the derivation. Thus, this shows all packages that
probably can be installed quickly. probably can be installed quickly.
- `--status`; `-s` - `--status`; `-s`\
Print the *status* of the derivation. The status consists of three Print the *status* of the derivation. The status consists of three
characters. The first is `I` or `-`, indicating whether the characters. The first is `I` or `-`, indicating whether the
derivation is currently installed in the current generation of the derivation is currently installed in the current generation of the
@ -621,49 +621,49 @@ derivation is shown unless `--no-name` is specified.
derivation to be built. The third is `S` or `-`, indicating whether derivation to be built. The third is `S` or `-`, indicating whether
a substitute is available for the derivation. a substitute is available for the derivation.
- `--attr-path`; `-P` - `--attr-path`; `-P`\
Print the *attribute path* of the derivation, which can be used to Print the *attribute path* of the derivation, which can be used to
unambiguously select it using the `--attr` option available in unambiguously select it using the `--attr` option available in
commands that install derivations like `nix-env --install`. This commands that install derivations like `nix-env --install`. This
option only works together with `--available` option only works together with `--available`
- `--no-name` - `--no-name`\
Suppress printing of the `name` attribute of each derivation. Suppress printing of the `name` attribute of each derivation.
- `--compare-versions` / `-c` - `--compare-versions` / `-c`\
Compare installed versions to available versions, or vice versa (if Compare installed versions to available versions, or vice versa (if
`--available` is given). This is useful for quickly seeing whether `--available` is given). This is useful for quickly seeing whether
upgrades for installed packages are available in a Nix expression. A upgrades for installed packages are available in a Nix expression. A
column is added with the following meaning: column is added with the following meaning:
- `<` *version* - `<` *version*\
A newer version of the package is available or installed. A newer version of the package is available or installed.
- `=` *version* - `=` *version*\
At most the same version of the package is available or At most the same version of the package is available or
installed. installed.
- `>` *version* - `>` *version*\
Only older versions of the package are available or installed. Only older versions of the package are available or installed.
- `- ?` - `- ?`\
No version of the package is available or installed. No version of the package is available or installed.
- `--system` - `--system`\
Print the `system` attribute of the derivation. Print the `system` attribute of the derivation.
- `--drv-path` - `--drv-path`\
Print the path of the store derivation. Print the path of the store derivation.
- `--out-path` - `--out-path`\
Print the output path of the derivation. Print the output path of the derivation.
- `--description` - `--description`\
Print a short (one-line) description of the derivation, if Print a short (one-line) description of the derivation, if
available. The description is taken from the `meta.description` available. The description is taken from the `meta.description`
attribute of the derivation. attribute of the derivation.
- `--meta` - `--meta`\
Print all of the meta-attributes of the derivation. This option is Print all of the meta-attributes of the derivation. This option is
only available with `--xml` or `--json`. only available with `--xml` or `--json`.
@ -874,7 +874,7 @@ error: no generation older than the current (91) exists
# Environment variables # Environment variables
- `NIX_PROFILE` - `NIX_PROFILE`\
Location of the Nix profile. Defaults to the target of the symlink Location of the Nix profile. Defaults to the target of the symlink
`~/.nix-profile`, if it exists, or `/nix/var/nix/profiles/default` `~/.nix-profile`, if it exists, or `/nix/var/nix/profiles/default`
otherwise. otherwise.

12
doc/manual/src/command-ref/nix-hash.md
View file

@ -29,29 +29,29 @@ md5sum`.
# Options # Options
- `--flat` - `--flat`\
Print the cryptographic hash of the contents of each regular file Print the cryptographic hash of the contents of each regular file
*path*. That is, do not compute the hash over the dump of *path*. *path*. That is, do not compute the hash over the dump of *path*.
The result is identical to that produced by the GNU commands The result is identical to that produced by the GNU commands
`md5sum` and `sha1sum`. `md5sum` and `sha1sum`.
- `--base32` - `--base32`\
Print the hash in a base-32 representation rather than hexadecimal. Print the hash in a base-32 representation rather than hexadecimal.
This base-32 representation is more compact and can be used in Nix This base-32 representation is more compact and can be used in Nix
expressions (such as in calls to `fetchurl`). expressions (such as in calls to `fetchurl`).
- `--truncate` - `--truncate`\
Truncate hashes longer than 160 bits (such as SHA-256) to 160 bits. Truncate hashes longer than 160 bits (such as SHA-256) to 160 bits.
- `--type` *hashAlgo* - `--type` *hashAlgo*\
Use the specified cryptographic hash algorithm, which can be one of Use the specified cryptographic hash algorithm, which can be one of
`md5`, `sha1`, `sha256`, and `sha512`. `md5`, `sha1`, `sha256`, and `sha512`.
- `--to-base16` - `--to-base16`\
Don’t hash anything, but convert the base-32 hash representation Don’t hash anything, but convert the base-32 hash representation
*hash* to hexadecimal. *hash* to hexadecimal.
- `--to-base32` - `--to-base32`\
Don’t hash anything, but convert the hexadecimal hash representation Don’t hash anything, but convert the hexadecimal hash representation
*hash* to base-32. *hash* to base-32.

16
doc/manual/src/command-ref/nix-instantiate.md
View file

@ -29,26 +29,26 @@ standard input.
# Options # Options
- `--add-root` *path* - `--add-root` *path*\
See the [corresponding option](nix-store.md) in `nix-store`. See the [corresponding option](nix-store.md) in `nix-store`.
- `--parse` - `--parse`\
Just parse the input files, and print their abstract syntax trees on Just parse the input files, and print their abstract syntax trees on
standard output in ATerm format. standard output in ATerm format.
- `--eval` - `--eval`\
Just parse and evaluate the input files, and print the resulting Just parse and evaluate the input files, and print the resulting
values on standard output. No instantiation of store derivations values on standard output. No instantiation of store derivations
takes place. takes place.
- `--find-file` - `--find-file`\
Look up the given files in Nix’s search path (as specified by the Look up the given files in Nix’s search path (as specified by the
`NIX_PATH` environment variable). If found, print the corresponding `NIX_PATH` environment variable). If found, print the corresponding
absolute paths on standard output. For instance, if `NIX_PATH` is absolute paths on standard output. For instance, if `NIX_PATH` is
`nixpkgs=/home/alice/nixpkgs`, then `nix-instantiate --find-file `nixpkgs=/home/alice/nixpkgs`, then `nix-instantiate --find-file
nixpkgs/default.nix` will print `/home/alice/nixpkgs/default.nix`. nixpkgs/default.nix` will print `/home/alice/nixpkgs/default.nix`.
- `--strict` - `--strict`\
When used with `--eval`, recursively evaluate list elements and When used with `--eval`, recursively evaluate list elements and
attributes. Normally, such sub-expressions are left unevaluated attributes. Normally, such sub-expressions are left unevaluated
(since the Nix expression language is lazy). (since the Nix expression language is lazy).
@ -58,17 +58,17 @@ standard input.
> This option can cause non-termination, because lazy data > This option can cause non-termination, because lazy data
> structures can be infinitely large. > structures can be infinitely large.
- `--json` - `--json`\
When used with `--eval`, print the resulting value as an JSON When used with `--eval`, print the resulting value as an JSON
representation of the abstract syntax tree rather than as an ATerm. representation of the abstract syntax tree rather than as an ATerm.
- `--xml` - `--xml`\
When used with `--eval`, print the resulting value as an XML When used with `--eval`, print the resulting value as an XML
representation of the abstract syntax tree rather than as an ATerm. representation of the abstract syntax tree rather than as an ATerm.
The schema is the same as that used by the [`toXML` The schema is the same as that used by the [`toXML`
built-in](../expressions/builtins.md). built-in](../expressions/builtins.md).
- `--read-write-mode` - `--read-write-mode`\
When used with `--eval`, perform evaluation in read/write mode so When used with `--eval`, perform evaluation in read/write mode so
nix language features that require it will still work (at the cost nix language features that require it will still work (at the cost
of needing to do instantiation of every evaluated derivation). If of needing to do instantiation of every evaluated derivation). If

10
doc/manual/src/command-ref/nix-prefetch-url.md
View file

@ -37,22 +37,22 @@ Nix store is also printed.
# Options # Options
- `--type` *hashAlgo* - `--type` *hashAlgo*\
Use the specified cryptographic hash algorithm, which can be one of Use the specified cryptographic hash algorithm, which can be one of
`md5`, `sha1`, `sha256`, and `sha512`. `md5`, `sha1`, `sha256`, and `sha512`.
- `--print-path` - `--print-path`\
Print the store path of the downloaded file on standard output. Print the store path of the downloaded file on standard output.
- `--unpack` - `--unpack`\
Unpack the archive (which must be a tarball or zip file) and add the Unpack the archive (which must be a tarball or zip file) and add the
result to the Nix store. The resulting hash can be used with result to the Nix store. The resulting hash can be used with
functions such as Nixpkgs’s `fetchzip` or `fetchFromGitHub`. functions such as Nixpkgs’s `fetchzip` or `fetchFromGitHub`.
- `--executable` - `--executable`\
Set the executable bit on the downloaded file. Set the executable bit on the downloaded file.
- `--name` *name* - `--name` *name*\
Override the name of the file in the Nix store. By default, this is Override the name of the file in the Nix store. By default, this is
`hash-basename`, where *basename* is the last component of *url*. `hash-basename`, where *basename* is the last component of *url*.
Overriding the name is necessary when *basename* contains characters Overriding the name is necessary when *basename* contains characters

16
doc/manual/src/command-ref/nix-shell.md
View file

@ -54,7 +54,7 @@ All options not listed here are passed to `nix-store
--realise`, except for `--arg` and `--attr` / `-A` which are passed to --realise`, except for `--arg` and `--attr` / `-A` which are passed to
`nix-instantiate`. `nix-instantiate`.
- `--command` *cmd* - `--command` *cmd*\
In the environment of the derivation, run the shell command *cmd*. In the environment of the derivation, run the shell command *cmd*.
This command is executed in an interactive shell. (Use `--run` to This command is executed in an interactive shell. (Use `--run` to
use a non-interactive shell instead.) However, a call to `exit` is use a non-interactive shell instead.) However, a call to `exit` is
@ -64,16 +64,16 @@ All options not listed here are passed to `nix-store
drop you into the interactive shell. This can be useful for doing drop you into the interactive shell. This can be useful for doing
any additional initialisation. any additional initialisation.
- `--run` *cmd* - `--run` *cmd*\
Like `--command`, but executes the command in a non-interactive Like `--command`, but executes the command in a non-interactive
shell. This means (among other things) that if you hit Ctrl-C while shell. This means (among other things) that if you hit Ctrl-C while
the command is running, the shell exits. the command is running, the shell exits.
- `--exclude` *regexp* - `--exclude` *regexp*\
Do not build any dependencies whose store path matches the regular Do not build any dependencies whose store path matches the regular
expression *regexp*. This option may be specified multiple times. expression *regexp*. This option may be specified multiple times.
- `--pure` - `--pure`\
If this flag is specified, the environment is almost entirely If this flag is specified, the environment is almost entirely
cleared before the interactive shell is started, so you get an cleared before the interactive shell is started, so you get an
environment that more closely corresponds to the “real” Nix build. A environment that more closely corresponds to the “real” Nix build. A
@ -82,18 +82,18 @@ All options not listed here are passed to `nix-store
installation) `/etc/bashrc` is still sourced, so any variables set installation) `/etc/bashrc` is still sourced, so any variables set
there will affect the interactive shell. there will affect the interactive shell.
- `--packages` / `-p` *packages*… - `--packages` / `-p` *packages*…\
Set up an environment in which the specified packages are present. Set up an environment in which the specified packages are present.
The command line arguments are interpreted as attribute names inside The command line arguments are interpreted as attribute names inside
the Nix Packages collection. Thus, `nix-shell -p libjpeg openjdk` the Nix Packages collection. Thus, `nix-shell -p libjpeg openjdk`
will start a shell in which the packages denoted by the attribute will start a shell in which the packages denoted by the attribute
names `libjpeg` and `openjdk` are present. names `libjpeg` and `openjdk` are present.
- `-i` *interpreter* - `-i` *interpreter*\
The chained script interpreter to be invoked by `nix-shell`. Only The chained script interpreter to be invoked by `nix-shell`. Only
applicable in `#!`-scripts (described below). applicable in `#!`-scripts (described below).
- `--keep` *name* - `--keep` *name*\
When a `--pure` shell is started, keep the listed environment When a `--pure` shell is started, keep the listed environment
variables. variables.
@ -101,7 +101,7 @@ The following common options are supported:
# Environment variables # Environment variables
- `NIX_BUILD_SHELL` - `NIX_BUILD_SHELL`\
Shell used to start the interactive environment. Defaults to the Shell used to start the interactive environment. Defaults to the
`bash` found in `PATH`. `bash` found in `PATH`.

62
doc/manual/src/command-ref/nix-store.md
View file

@ -22,7 +22,7 @@ This section lists the options that are common to all operations. These
options are allowed for every subcommand, though they may not always options are allowed for every subcommand, though they may not always
have an effect. have an effect.
- `--add-root` *path* - `--add-root` *path*\
Causes the result of a realisation (`--realise` and Causes the result of a realisation (`--realise` and
`--force-realise`) to be registered as a root of the garbage `--force-realise`) to be registered as a root of the garbage
collector. *path* will be created as a symlink to the resulting collector. *path* will be created as a symlink to the resulting
@ -86,15 +86,15 @@ non-derivations argument, the argument itself is printed.)
The following flags are available: The following flags are available:
- `--dry-run` - `--dry-run`\
Print on standard error a description of what packages would be Print on standard error a description of what packages would be
built or downloaded, without actually performing the operation. built or downloaded, without actually performing the operation.
- `--ignore-unknown` - `--ignore-unknown`\
If a non-derivation path does not have a substitute, then silently If a non-derivation path does not have a substitute, then silently
ignore it. ignore it.
- `--check` - `--check`\
This option allows you to check whether a derivation is This option allows you to check whether a derivation is
deterministic. It rebuilds the specified derivation and checks deterministic. It rebuilds the specified derivation and checks
whether the result is bitwise-identical with the existing outputs, whether the result is bitwise-identical with the existing outputs,
@ -110,20 +110,20 @@ The following flags are available:
Special exit codes: Special exit codes:
- `100` - `100`\
Generic build failure, the builder process returned with a non-zero Generic build failure, the builder process returned with a non-zero
exit code. exit code.
- `101` - `101`\
Build timeout, the build was aborted because it did not complete Build timeout, the build was aborted because it did not complete
within the specified `timeout`. within the specified `timeout`.
- `102` - `102`\
Hash mismatch, the build output was rejected because it does not Hash mismatch, the build output was rejected because it does not
match the [`outputHash` attribute of the match the [`outputHash` attribute of the
derivation](../expressions/advanced-attributes.md). derivation](../expressions/advanced-attributes.md).
- `104` - `104`\
Not deterministic, the build succeeded in check mode but the Not deterministic, the build succeeded in check mode but the
resulting output is not binary reproducable. resulting output is not binary reproducable.
@ -170,7 +170,7 @@ access to a restricted ssh user.
The following flags are available: The following flags are available:
- `--write` - `--write`\
Allow the connected client to request the realization of Allow the connected client to request the realization of
derivations. In effect, this can be used to make the host act as a derivations. In effect, this can be used to make the host act as a
remote builder. remote builder.
@ -200,18 +200,18 @@ reachable via file system references from a set of “roots”, are deleted.
The following suboperations may be specified: The following suboperations may be specified:
- `--print-roots` - `--print-roots`\
This operation prints on standard output the set of roots used by This operation prints on standard output the set of roots used by
the garbage collector. the garbage collector.
- `--print-live` - `--print-live`\
This operation prints on standard output the set of “live” store This operation prints on standard output the set of “live” store
paths, which are all the store paths reachable from the roots. Live paths, which are all the store paths reachable from the roots. Live
paths should never be deleted, since that would break consistency — paths should never be deleted, since that would break consistency —
it would become possible that applications are installed that it would become possible that applications are installed that
reference things that are no longer present in the store. reference things that are no longer present in the store.
- `--print-dead` - `--print-dead`\
This operation prints out on standard output the set of “dead” store This operation prints out on standard output the set of “dead” store
paths, which is just the opposite of the set of live paths: any path paths, which is just the opposite of the set of live paths: any path
in the store that is not live (with respect to the roots) is dead. in the store that is not live (with respect to the roots) is dead.
@ -219,7 +219,7 @@ The following suboperations may be specified:
By default, all unreachable paths are deleted. The following options By default, all unreachable paths are deleted. The following options
control what gets deleted and in what order: control what gets deleted and in what order:
- `--max-freed` *bytes* - `--max-freed` *bytes*\
Keep deleting paths until at least *bytes* bytes have been deleted, Keep deleting paths until at least *bytes* bytes have been deleted,
then stop. The argument *bytes* can be followed by the then stop. The argument *bytes* can be followed by the
multiplicative suffix `K`, `M`, `G` or `T`, denoting KiB, MiB, GiB multiplicative suffix `K`, `M`, `G` or `T`, denoting KiB, MiB, GiB
@ -300,22 +300,22 @@ symlink.
## Common query options ## Common query options
- `--use-output`; `-u` - `--use-output`; `-u`\
For each argument to the query that is a store derivation, apply the For each argument to the query that is a store derivation, apply the
query to the output path of the derivation instead. query to the output path of the derivation instead.
- `--force-realise`; `-f` - `--force-realise`; `-f`\
Realise each argument to the query first (see [`nix-store Realise each argument to the query first (see [`nix-store
--realise`](#operation---realise)). --realise`](#operation---realise)).
## Queries ## Queries
- `--outputs` - `--outputs`\
Prints out the [output paths](../glossary.md) of the store Prints out the [output paths](../glossary.md) of the store
derivations *paths*. These are the paths that will be produced when derivations *paths*. These are the paths that will be produced when
the derivation is built. the derivation is built.
- `--requisites`; `-R` - `--requisites`; `-R`\
Prints out the [closure](../glossary.md) of the store path *paths*. Prints out the [closure](../glossary.md) of the store path *paths*.
This query has one option: This query has one option:
@ -332,31 +332,31 @@ symlink.
dependencies) is obtained by distributing the closure of a store dependencies) is obtained by distributing the closure of a store
derivation and specifying the option `--include-outputs`. derivation and specifying the option `--include-outputs`.
- `--references` - `--references`\
Prints the set of [references](../glossary.md) of the store paths Prints the set of [references](../glossary.md) of the store paths
*paths*, that is, their immediate dependencies. (For *all* *paths*, that is, their immediate dependencies. (For *all*
dependencies, use `--requisites`.) dependencies, use `--requisites`.)
- `--referrers` - `--referrers`\
Prints the set of *referrers* of the store paths *paths*, that is, Prints the set of *referrers* of the store paths *paths*, that is,
the store paths currently existing in the Nix store that refer to the store paths currently existing in the Nix store that refer to
one of *paths*. Note that contrary to the references, the set of one of *paths*. Note that contrary to the references, the set of
referrers is not constant; it can change as store paths are added or referrers is not constant; it can change as store paths are added or
removed. removed.
- `--referrers-closure` - `--referrers-closure`\
Prints the closure of the set of store paths *paths* under the Prints the closure of the set of store paths *paths* under the
referrers relation; that is, all store paths that directly or referrers relation; that is, all store paths that directly or
indirectly refer to one of *paths*. These are all the path currently indirectly refer to one of *paths*. These are all the path currently
in the Nix store that are dependent on *paths*. in the Nix store that are dependent on *paths*.
- `--deriver`; `-d` - `--deriver`; `-d`\
Prints the [deriver](../glossary.md) of the store paths *paths*. If Prints the [deriver](../glossary.md) of the store paths *paths*. If
the path has no deriver (e.g., if it is a source file), or if the the path has no deriver (e.g., if it is a source file), or if the
deriver is not known (e.g., in the case of a binary-only deriver is not known (e.g., in the case of a binary-only
deployment), the string `unknown-deriver` is printed. deployment), the string `unknown-deriver` is printed.
- `--graph` - `--graph`\
Prints the references graph of the store paths *paths* in the format Prints the references graph of the store paths *paths* in the format
of the `dot` tool of AT\&T's [Graphviz of the `dot` tool of AT\&T's [Graphviz
package](http://www.graphviz.org/). This can be used to visualise package](http://www.graphviz.org/). This can be used to visualise
@ -364,39 +364,39 @@ symlink.
this to a store derivation. To obtain a runtime dependency graph, this to a store derivation. To obtain a runtime dependency graph,
apply it to an output path. apply it to an output path.
- `--tree` - `--tree`\
Prints the references graph of the store paths *paths* as a nested Prints the references graph of the store paths *paths* as a nested
ASCII tree. References are ordered by descending closure size; this ASCII tree. References are ordered by descending closure size; this
tends to flatten the tree, making it more readable. The query only tends to flatten the tree, making it more readable. The query only
recurses into a store path when it is first encountered; this recurses into a store path when it is first encountered; this
prevents a blowup of the tree representation of the graph. prevents a blowup of the tree representation of the graph.
- `--graphml` - `--graphml`\
Prints the references graph of the store paths *paths* in the Prints the references graph of the store paths *paths* in the
[GraphML](http://graphml.graphdrawing.org/) file format. This can be [GraphML](http://graphml.graphdrawing.org/) file format. This can be
used to visualise dependency graphs. To obtain a build-time used to visualise dependency graphs. To obtain a build-time
dependency graph, apply this to a store derivation. To obtain a dependency graph, apply this to a store derivation. To obtain a
runtime dependency graph, apply it to an output path. runtime dependency graph, apply it to an output path.
- `--binding` *name*; `-b` *name* - `--binding` *name*; `-b` *name*\
Prints the value of the attribute *name* (i.e., environment Prints the value of the attribute *name* (i.e., environment
variable) of the store derivations *paths*. It is an error for a variable) of the store derivations *paths*. It is an error for a
derivation to not have the specified attribute. derivation to not have the specified attribute.
- `--hash` - `--hash`\
Prints the SHA-256 hash of the contents of the store paths *paths* Prints the SHA-256 hash of the contents of the store paths *paths*
(that is, the hash of the output of `nix-store --dump` on the given (that is, the hash of the output of `nix-store --dump` on the given
paths). Since the hash is stored in the Nix database, this is a fast paths). Since the hash is stored in the Nix database, this is a fast
operation. operation.
- `--size` - `--size`\
Prints the size in bytes of the contents of the store paths *paths* Prints the size in bytes of the contents of the store paths *paths*
— to be precise, the size of the output of `nix-store --dump` on — to be precise, the size of the output of `nix-store --dump` on
the given paths. Note that the actual disk space required by the the given paths. Note that the actual disk space required by the
store paths may be higher, especially on filesystems with large store paths may be higher, especially on filesystems with large
cluster sizes. cluster sizes.
- `--roots` - `--roots`\
Prints the garbage collector roots that point, directly or Prints the garbage collector roots that point, directly or
indirectly, at the store paths *paths*. indirectly, at the store paths *paths*.
@ -513,7 +513,7 @@ public url or broke since the download expression was written.
This operation has the following options: This operation has the following options:
- `--recursive` - `--recursive`\
Use recursive instead of flat hashing mode, used when adding Use recursive instead of flat hashing mode, used when adding
directories to the store. directories to the store.
@ -540,14 +540,14 @@ being modified by non-Nix tools, or of bugs in Nix itself.
This operation has the following options: This operation has the following options:
- `--check-contents` - `--check-contents`\
Checks that the contents of every valid store path has not been Checks that the contents of every valid store path has not been
altered by computing a SHA-256 hash of the contents and comparing it altered by computing a SHA-256 hash of the contents and comparing it
with the hash stored in the Nix database at build time. Paths that with the hash stored in the Nix database at build time. Paths that
have been modified are printed out. For large stores, have been modified are printed out. For large stores,
`--check-contents` is obviously quite slow. `--check-contents` is obviously quite slow.
- `--repair` - `--repair`\
If any valid path is missing from the store, or (if If any valid path is missing from the store, or (if
`--check-contents` is given) the contents of a valid path has been `--check-contents` is given) the contents of a valid path has been
modified, then try to repair the path by redownloading it. See modified, then try to repair the path by redownloading it. See

96
doc/manual/src/command-ref/opt-common.md
View file

@ -2,56 +2,56 @@
Most Nix commands accept the following command-line options: Most Nix commands accept the following command-line options:
- `--help` - `--help`\
Prints out a summary of the command syntax and exits. Prints out a summary of the command syntax and exits.
- `--version` - `--version`\
Prints out the Nix version number on standard output and exits. Prints out the Nix version number on standard output and exits.
- `--verbose` / `-v` - `--verbose` / `-v`\
Increases the level of verbosity of diagnostic messages printed on Increases the level of verbosity of diagnostic messages printed on
standard error. For each Nix operation, the information printed on standard error. For each Nix operation, the information printed on
standard output is well-defined; any diagnostic information is standard output is well-defined; any diagnostic information is
printed on standard error, never on standard output. printed on standard error, never on standard output.
This option may be specified repeatedly. Currently, the following This option may be specified repeatedly. Currently, the following
verbosity levels exist: verbosity levels exist:
- 0 - 0\
“Errors only”: only print messages explaining why the Nix “Errors only”: only print messages explaining why the Nix
invocation failed. invocation failed.
- 1 - 1\
“Informational”: print *useful* messages about what Nix is “Informational”: print *useful* messages about what Nix is
doing. This is the default. doing. This is the default.
- 2 - 2\
“Talkative”: print more informational messages. “Talkative”: print more informational messages.
- 3 - 3\
“Chatty”: print even more informational messages. “Chatty”: print even more informational messages.
- 4 - 4\
“Debug”: print debug information. “Debug”: print debug information.
- 5 - 5\
“Vomit”: print vast amounts of debug information. “Vomit”: print vast amounts of debug information.
- `--quiet` - `--quiet`\
Decreases the level of verbosity of diagnostic messages printed on Decreases the level of verbosity of diagnostic messages printed on
standard error. This is the inverse option to `-v` / `--verbose`. standard error. This is the inverse option to `-v` / `--verbose`.
This option may be specified repeatedly. See the previous verbosity This option may be specified repeatedly. See the previous verbosity
levels list. levels list.
- `--log-format` *format* - `--log-format` *format*\
This option can be used to change the output of the log format, with This option can be used to change the output of the log format, with
*format* being one of: *format* being one of:
- raw - raw\
This is the raw format, as outputted by nix-build. This is the raw format, as outputted by nix-build.
- internal-json - internal-json\
Outputs the logs in a structured manner. Outputs the logs in a structured manner.
> **Warning** > **Warning**
@ -60,30 +60,30 @@ Most Nix commands accept the following command-line options:
> the error-messages (namely of the `msg`-field) can change > the error-messages (namely of the `msg`-field) can change
> between releases. > between releases.
- bar - bar\
Only display a progress bar during the builds. Only display a progress bar during the builds.
- bar-with-logs - bar-with-logs\
Display the raw logs, with the progress bar at the bottom. Display the raw logs, with the progress bar at the bottom.
- `--no-build-output` / `-Q` - `--no-build-output` / `-Q`\
By default, output written by builders to standard output and By default, output written by builders to standard output and
standard error is echoed to the Nix command's standard error. This standard error is echoed to the Nix command's standard error. This
option suppresses this behaviour. Note that the builder's standard option suppresses this behaviour. Note that the builder's standard
output and error are always written to a log file in output and error are always written to a log file in
`prefix/nix/var/log/nix`. `prefix/nix/var/log/nix`.
- `--max-jobs` / `-j` *number* - `--max-jobs` / `-j` *number*\
Sets the maximum number of build jobs that Nix will perform in Sets the maximum number of build jobs that Nix will perform in
parallel to the specified number. Specify `auto` to use the number parallel to the specified number. Specify `auto` to use the number
of CPUs in the system. The default is specified by the `max-jobs` of CPUs in the system. The default is specified by the `max-jobs`
configuration setting, which itself defaults to `1`. A higher configuration setting, which itself defaults to `1`. A higher
value is useful on SMP systems or to exploit I/O latency. value is useful on SMP systems or to exploit I/O latency.
Setting it to `0` disallows building on the local machine, which is Setting it to `0` disallows building on the local machine, which is
useful when you want builds to happen only on remote builders. useful when you want builds to happen only on remote builders.
- `--cores` - `--cores`\
Sets the value of the `NIX_BUILD_CORES` environment variable in Sets the value of the `NIX_BUILD_CORES` environment variable in
the invocation of builders. Builders can use this variable at the invocation of builders. Builders can use this variable at
their discretion to control the maximum amount of parallelism. For their discretion to control the maximum amount of parallelism. For
@ -94,18 +94,18 @@ Most Nix commands accept the following command-line options:
means that the builder should use all available CPU cores in the means that the builder should use all available CPU cores in the
system. system.
- `--max-silent-time` - `--max-silent-time`\
Sets the maximum number of seconds that a builder can go without Sets the maximum number of seconds that a builder can go without
producing any data on standard output or standard error. The producing any data on standard output or standard error. The
default is specified by the `max-silent-time` configuration default is specified by the `max-silent-time` configuration
setting. `0` means no time-out. setting. `0` means no time-out.
- `--timeout` - `--timeout`\
Sets the maximum number of seconds that a builder can run. The Sets the maximum number of seconds that a builder can run. The
default is specified by the `timeout` configuration setting. `0` default is specified by the `timeout` configuration setting. `0`
means no timeout. means no timeout.
- `--keep-going` / `-k` - `--keep-going` / `-k`\
Keep going in case of failed builds, to the greatest extent Keep going in case of failed builds, to the greatest extent
possible. That is, if building an input of some derivation fails, possible. That is, if building an input of some derivation fails,
Nix will still build the other inputs, but not the derivation Nix will still build the other inputs, but not the derivation
@ -113,17 +113,17 @@ Most Nix commands accept the following command-line options:
for builds of substitutes), possibly killing builds in progress (in for builds of substitutes), possibly killing builds in progress (in
case of parallel or distributed builds). case of parallel or distributed builds).
- `--keep-failed` / `-K` - `--keep-failed` / `-K`\
Specifies that in case of a build failure, the temporary directory Specifies that in case of a build failure, the temporary directory
(usually in `/tmp`) in which the build takes place should not be (usually in `/tmp`) in which the build takes place should not be
deleted. The path of the build directory is printed as an deleted. The path of the build directory is printed as an
informational message. informational message.
- `--fallback` - `--fallback`\
Whenever Nix attempts to build a derivation for which substitutes Whenever Nix attempts to build a derivation for which substitutes
are known for each output path, but realising the output paths are known for each output path, but realising the output paths
through the substitutes fails, fall back on building the derivation. through the substitutes fails, fall back on building the derivation.
The most common scenario in which this is useful is when we have The most common scenario in which this is useful is when we have
registered substitutes in order to perform binary distribution from, registered substitutes in order to perform binary distribution from,
say, a network repository. If the repository is down, the say, a network repository. If the repository is down, the
@ -134,12 +134,12 @@ Most Nix commands accept the following command-line options:
failure in obtaining the substitutes to lead to a full build from failure in obtaining the substitutes to lead to a full build from
source (with the related consumption of resources). source (with the related consumption of resources).
- `--readonly-mode` - `--readonly-mode`\
When this option is used, no attempt is made to open the Nix When this option is used, no attempt is made to open the Nix
database. Most Nix operations do need database access, so those database. Most Nix operations do need database access, so those
operations will fail. operations will fail.
- `--arg` *name* *value* - `--arg` *name* *value*\
This option is accepted by `nix-env`, `nix-instantiate`, This option is accepted by `nix-env`, `nix-instantiate`,
`nix-shell` and `nix-build`. When evaluating Nix expressions, the `nix-shell` and `nix-build`. When evaluating Nix expressions, the
expression evaluator will automatically try to call functions that expression evaluator will automatically try to call functions that
@ -151,7 +151,7 @@ Most Nix commands accept the following command-line options:
override a default value). That is, if the evaluator encounters a override a default value). That is, if the evaluator encounters a
function with an argument named *name*, it will call it with value function with an argument named *name*, it will call it with value
*value*. *value*.
For instance, the top-level `default.nix` in Nixpkgs is actually a For instance, the top-level `default.nix` in Nixpkgs is actually a
function: function:
@ -161,7 +161,7 @@ Most Nix commands accept the following command-line options:
... ...
}: ... }: ...
``` ```
So if you call this Nix expression (e.g., when you do `nix-env -i So if you call this Nix expression (e.g., when you do `nix-env -i
pkgname`), the function will be called automatically using the pkgname`), the function will be called automatically using the
value [`builtins.currentSystem`](../expressions/builtins.md) for value [`builtins.currentSystem`](../expressions/builtins.md) for
@ -170,13 +170,13 @@ Most Nix commands accept the following command-line options:
since the argument is a Nix string literal, you have to escape the since the argument is a Nix string literal, you have to escape the
quotes.) quotes.)
- `--argstr` *name* *value* - `--argstr` *name* *value*\
This option is like `--arg`, only the value is not a Nix This option is like `--arg`, only the value is not a Nix
expression but a string. So instead of `--arg system expression but a string. So instead of `--arg system
\"i686-linux\"` (the outer quotes are to keep the shell happy) you \"i686-linux\"` (the outer quotes are to keep the shell happy) you
can say `--argstr system i686-linux`. can say `--argstr system i686-linux`.
- `--attr` / `-A` *attrPath* - `--attr` / `-A` *attrPath*\
Select an attribute from the top-level Nix expression being Select an attribute from the top-level Nix expression being
evaluated. (`nix-env`, `nix-instantiate`, `nix-build` and evaluated. (`nix-env`, `nix-instantiate`, `nix-build` and
`nix-shell` only.) The *attribute path* *attrPath* is a sequence `nix-shell` only.) The *attribute path* *attrPath* is a sequence
@ -185,34 +185,34 @@ Most Nix commands accept the following command-line options:
would cause the expression `e.xorg.xorgserver` to be used. See would cause the expression `e.xorg.xorgserver` to be used. See
[`nix-env --install`](nix-env.md#operation---install) for some [`nix-env --install`](nix-env.md#operation---install) for some
concrete examples. concrete examples.
In addition to attribute names, you can also specify array indices. In addition to attribute names, you can also specify array indices.
For instance, the attribute path `foo.3.bar` selects the `bar` For instance, the attribute path `foo.3.bar` selects the `bar`
attribute of the fourth element of the array in the `foo` attribute attribute of the fourth element of the array in the `foo` attribute
of the top-level expression. of the top-level expression.
- `--expr` / `-E` - `--expr` / `-E`\
Interpret the command line arguments as a list of Nix expressions to Interpret the command line arguments as a list of Nix expressions to
be parsed and evaluated, rather than as a list of file names of Nix be parsed and evaluated, rather than as a list of file names of Nix
expressions. (`nix-instantiate`, `nix-build` and `nix-shell` only.) expressions. (`nix-instantiate`, `nix-build` and `nix-shell` only.)
For `nix-shell`, this option is commonly used to give you a shell in For `nix-shell`, this option is commonly used to give you a shell in
which you can build the packages returned by the expression. If you which you can build the packages returned by the expression. If you
want to get a shell which contain the *built* packages ready for want to get a shell which contain the *built* packages ready for
use, give your expression to the `nix-shell -p` convenience flag use, give your expression to the `nix-shell -p` convenience flag
instead. instead.
- `-I` *path* - `-I` *path*\
Add a path to the Nix expression search path. This option may be Add a path to the Nix expression search path. This option may be
given multiple times. See the `NIX_PATH` environment variable for given multiple times. See the `NIX_PATH` environment variable for
information on the semantics of the Nix search path. Paths added information on the semantics of the Nix search path. Paths added
through `-I` take precedence over `NIX_PATH`. through `-I` take precedence over `NIX_PATH`.
- `--option` *name* *value* - `--option` *name* *value*\
Set the Nix configuration option *name* to *value*. This overrides Set the Nix configuration option *name* to *value*. This overrides
settings in the Nix configuration file (see nix.conf5). settings in the Nix configuration file (see nix.conf5).
- `--repair` - `--repair`\
Fix corrupted or missing store paths by redownloading or rebuilding Fix corrupted or missing store paths by redownloading or rebuilding
them. Note that this is slow because it requires computing a them. Note that this is slow because it requires computing a
cryptographic hash of the contents of every path in the closure of cryptographic hash of the contents of every path in the closure of

92
doc/manual/src/expressions/advanced-attributes.md
View file

@ -2,14 +2,14 @@
Derivations can declare some infrequently used optional attributes. Derivations can declare some infrequently used optional attributes.
- `allowedReferences` - `allowedReferences`\
The optional attribute `allowedReferences` specifies a list of legal The optional attribute `allowedReferences` specifies a list of legal
references (dependencies) of the output of the builder. For example, references (dependencies) of the output of the builder. For example,
```nix ```nix
allowedReferences = []; allowedReferences = [];
``` ```
enforces that the output of a derivation cannot have any runtime enforces that the output of a derivation cannot have any runtime
dependencies on its inputs. To allow an output to have a runtime dependencies on its inputs. To allow an output to have a runtime
dependency on itself, use `"out"` as a list item. This is used in dependency on itself, use `"out"` as a list item. This is used in
@ -17,45 +17,45 @@ Derivations can declare some infrequently used optional attributes.
booting Linux don’t have accidental dependencies on other paths in booting Linux don’t have accidental dependencies on other paths in
the Nix store. the Nix store.
- `allowedRequisites` - `allowedRequisites`\
This attribute is similar to `allowedReferences`, but it specifies This attribute is similar to `allowedReferences`, but it specifies
the legal requisites of the whole closure, so all the dependencies the legal requisites of the whole closure, so all the dependencies
recursively. For example, recursively. For example,
```nix ```nix
allowedRequisites = [ foobar ]; allowedRequisites = [ foobar ];
``` ```
enforces that the output of a derivation cannot have any other enforces that the output of a derivation cannot have any other
runtime dependency than `foobar`, and in addition it enforces that runtime dependency than `foobar`, and in addition it enforces that
`foobar` itself doesn't introduce any other dependency itself. `foobar` itself doesn't introduce any other dependency itself.
- `disallowedReferences` - `disallowedReferences`\
The optional attribute `disallowedReferences` specifies a list of The optional attribute `disallowedReferences` specifies a list of
illegal references (dependencies) of the output of the builder. For illegal references (dependencies) of the output of the builder. For
example, example,
```nix ```nix
disallowedReferences = [ foo ]; disallowedReferences = [ foo ];
``` ```
enforces that the output of a derivation cannot have a direct enforces that the output of a derivation cannot have a direct
runtime dependencies on the derivation `foo`. runtime dependencies on the derivation `foo`.
- `disallowedRequisites` - `disallowedRequisites`\
This attribute is similar to `disallowedReferences`, but it This attribute is similar to `disallowedReferences`, but it
specifies illegal requisites for the whole closure, so all the specifies illegal requisites for the whole closure, so all the
dependencies recursively. For example, dependencies recursively. For example,
```nix ```nix
disallowedRequisites = [ foobar ]; disallowedRequisites = [ foobar ];
``` ```
enforces that the output of a derivation cannot have any runtime enforces that the output of a derivation cannot have any runtime
dependency on `foobar` or any other derivation depending recursively dependency on `foobar` or any other derivation depending recursively
on `foobar`. on `foobar`.
- `exportReferencesGraph` - `exportReferencesGraph`\
This attribute allows builders access to the references graph of This attribute allows builders access to the references graph of
their inputs. The attribute is a list of inputs in the Nix store their inputs. The attribute is a list of inputs in the Nix store
whose references graph the builder needs to know. The value of whose references graph the builder needs to know. The value of
@ -65,17 +65,17 @@ Derivations can declare some infrequently used optional attributes.
files have the format used by `nix-store --register-validity` files have the format used by `nix-store --register-validity`
(with the deriver fields left empty). For example, when the (with the deriver fields left empty). For example, when the
following derivation is built: following derivation is built:
```nix ```nix
derivation { derivation {
... ...
exportReferencesGraph = [ "libfoo-graph" libfoo ]; exportReferencesGraph = [ "libfoo-graph" libfoo ];
}; };
``` ```
the references graph of `libfoo` is placed in the file the references graph of `libfoo` is placed in the file
`libfoo-graph` in the temporary build directory. `libfoo-graph` in the temporary build directory.
`exportReferencesGraph` is useful for builders that want to do `exportReferencesGraph` is useful for builders that want to do
something with the closure of a store path. Examples include the something with the closure of a store path. Examples include the
builders in NixOS that generate the initial ramdisk for booting builders in NixOS that generate the initial ramdisk for booting
@ -84,66 +84,66 @@ Derivations can declare some infrequently used optional attributes.
with a Nix store containing the closure of a bootable NixOS with a Nix store containing the closure of a bootable NixOS
configuration). configuration).
- `impureEnvVars` - `impureEnvVars`\
This attribute allows you to specify a list of environment variables This attribute allows you to specify a list of environment variables
that should be passed from the environment of the calling user to that should be passed from the environment of the calling user to
the builder. Usually, the environment is cleared completely when the the builder. Usually, the environment is cleared completely when the
builder is executed, but with this attribute you can allow specific builder is executed, but with this attribute you can allow specific
environment variables to be passed unmodified. For example, environment variables to be passed unmodified. For example,
`fetchurl` in Nixpkgs has the line `fetchurl` in Nixpkgs has the line
```nix ```nix
impureEnvVars = [ "http_proxy" "https_proxy" ... ]; impureEnvVars = [ "http_proxy" "https_proxy" ... ];
``` ```
to make it use the proxy server configuration specified by the user to make it use the proxy server configuration specified by the user
in the environment variables `http_proxy` and friends. in the environment variables `http_proxy` and friends.
This attribute is only allowed in *fixed-output derivations* (see This attribute is only allowed in *fixed-output derivations* (see
below), where impurities such as these are okay since (the hash below), where impurities such as these are okay since (the hash
of) the output is known in advance. It is ignored for all other of) the output is known in advance. It is ignored for all other
derivations. derivations.
> **Warning** > **Warning**
> >
> `impureEnvVars` implementation takes environment variables from > `impureEnvVars` implementation takes environment variables from
> the current builder process. When a daemon is building its > the current builder process. When a daemon is building its
> environmental variables are used. Without the daemon, the > environmental variables are used. Without the daemon, the
> environmental variables come from the environment of the > environmental variables come from the environment of the
> `nix-build`. > `nix-build`.
- `outputHash`; `outputHashAlgo`; `outputHashMode` - `outputHash`; `outputHashAlgo`; `outputHashMode`\
These attributes declare that the derivation is a so-called These attributes declare that the derivation is a so-called
*fixed-output derivation*, which means that a cryptographic hash of *fixed-output derivation*, which means that a cryptographic hash of
the output is already known in advance. When the build of a the output is already known in advance. When the build of a
fixed-output derivation finishes, Nix computes the cryptographic fixed-output derivation finishes, Nix computes the cryptographic
hash of the output and compares it to the hash declared with these hash of the output and compares it to the hash declared with these
attributes. If there is a mismatch, the build fails. attributes. If there is a mismatch, the build fails.
The rationale for fixed-output derivations is derivations such as The rationale for fixed-output derivations is derivations such as
those produced by the `fetchurl` function. This function downloads a those produced by the `fetchurl` function. This function downloads a
file from a given URL. To ensure that the downloaded file has not file from a given URL. To ensure that the downloaded file has not
been modified, the caller must also specify a cryptographic hash of been modified, the caller must also specify a cryptographic hash of
the file. For example, the file. For example,
```nix ```nix
fetchurl { fetchurl {
url = "http://ftp.gnu.org/pub/gnu/hello/hello-2.1.1.tar.gz"; url = "http://ftp.gnu.org/pub/gnu/hello/hello-2.1.1.tar.gz";
sha256 = "1md7jsfd8pa45z73bz1kszpp01yw6x5ljkjk2hx7wl800any6465"; sha256 = "1md7jsfd8pa45z73bz1kszpp01yw6x5ljkjk2hx7wl800any6465";
} }
``` ```
It sometimes happens that the URL of the file changes, e.g., because It sometimes happens that the URL of the file changes, e.g., because
servers are reorganised or no longer available. We then must update servers are reorganised or no longer available. We then must update
the call to `fetchurl`, e.g., the call to `fetchurl`, e.g.,
```nix ```nix
fetchurl { fetchurl {
url = "ftp://ftp.nluug.nl/pub/gnu/hello/hello-2.1.1.tar.gz"; url = "ftp://ftp.nluug.nl/pub/gnu/hello/hello-2.1.1.tar.gz";
sha256 = "1md7jsfd8pa45z73bz1kszpp01yw6x5ljkjk2hx7wl800any6465"; sha256 = "1md7jsfd8pa45z73bz1kszpp01yw6x5ljkjk2hx7wl800any6465";
} }
``` ```
If a `fetchurl` derivation was treated like a normal derivation, the If a `fetchurl` derivation was treated like a normal derivation, the
output paths of the derivation and *all derivations depending on it* output paths of the derivation and *all derivations depending on it*
would change. For instance, if we were to change the URL of the would change. For instance, if we were to change the URL of the
@ -151,16 +151,16 @@ Derivations can declare some infrequently used optional attributes.
other packages depend) massive rebuilds would be needed. This is other packages depend) massive rebuilds would be needed. This is
unfortunate for a change which we know cannot have a real effect as unfortunate for a change which we know cannot have a real effect as
it propagates upwards through the dependency graph. it propagates upwards through the dependency graph.
For fixed-output derivations, on the other hand, the name of the For fixed-output derivations, on the other hand, the name of the
output path only depends on the `outputHash*` and `name` attributes, output path only depends on the `outputHash*` and `name` attributes,
while all other attributes are ignored for the purpose of computing while all other attributes are ignored for the purpose of computing
the output path. (The `name` attribute is included because it is the output path. (The `name` attribute is included because it is
part of the path.) part of the path.)
As an example, here is the (simplified) Nix expression for As an example, here is the (simplified) Nix expression for
`fetchurl`: `fetchurl`:
```nix ```nix
{ stdenv, curl }: # The curl program is used for downloading. { stdenv, curl }: # The curl program is used for downloading.
@ -180,43 +180,43 @@ Derivations can declare some infrequently used optional attributes.
inherit url; inherit url;
} }
``` ```
The `outputHashAlgo` attribute specifies the hash algorithm used to The `outputHashAlgo` attribute specifies the hash algorithm used to
compute the hash. It can currently be `"sha1"`, `"sha256"` or compute the hash. It can currently be `"sha1"`, `"sha256"` or
`"sha512"`. `"sha512"`.
The `outputHashMode` attribute determines how the hash is computed. The `outputHashMode` attribute determines how the hash is computed.
It must be one of the following two values: It must be one of the following two values:
- `"flat"` - `"flat"`\
The output must be a non-executable regular file. If it isn’t, The output must be a non-executable regular file. If it isn’t,
the build fails. The hash is simply computed over the contents the build fails. The hash is simply computed over the contents
of that file (so it’s equal to what Unix commands like of that file (so it’s equal to what Unix commands like
`sha256sum` or `sha1sum` produce). `sha256sum` or `sha1sum` produce).
This is the default. This is the default.
- `"recursive"` - `"recursive"`\
The hash is computed over the NAR archive dump of the output The hash is computed over the NAR archive dump of the output
(i.e., the result of [`nix-store (i.e., the result of [`nix-store
--dump`](../command-ref/nix-store.md#operation---dump)). In --dump`](../command-ref/nix-store.md#operation---dump)). In
this case, the output can be anything, including a directory this case, the output can be anything, including a directory
tree. tree.
The `outputHash` attribute, finally, must be a string containing The `outputHash` attribute, finally, must be a string containing
the hash in either hexadecimal or base-32 notation. (See the the hash in either hexadecimal or base-32 notation. (See the
[`nix-hash` command](../command-ref/nix-hash.md) for information [`nix-hash` command](../command-ref/nix-hash.md) for information
about converting to and from base-32 notation.) about converting to and from base-32 notation.)
- `passAsFile` - `passAsFile`\
A list of names of attributes that should be passed via files rather A list of names of attributes that should be passed via files rather
than environment variables. For example, if you have than environment variables. For example, if you have
```nix ```nix
passAsFile = ["big"]; passAsFile = ["big"];
big = "a very long string"; big = "a very long string";
``` ```
then when the builder runs, the environment variable `bigPath` then when the builder runs, the environment variable `bigPath`
will contain the absolute path to a temporary file containing `a will contain the absolute path to a temporary file containing `a
very long string`. That is, for any attribute *x* listed in very long string`. That is, for any attribute *x* listed in
@ -226,7 +226,7 @@ Derivations can declare some infrequently used optional attributes.
builder, since most operating systems impose a limit on the size builder, since most operating systems impose a limit on the size
of the environment (typically, a few hundred kilobyte). of the environment (typically, a few hundred kilobyte).
- `preferLocalBuild` - `preferLocalBuild`\
If this attribute is set to `true` and [distributed building is If this attribute is set to `true` and [distributed building is
enabled](../advanced-topics/distributed-builds.md), then, if enabled](../advanced-topics/distributed-builds.md), then, if
possible, the derivaton will be built locally instead of forwarded possible, the derivaton will be built locally instead of forwarded
@ -234,14 +234,14 @@ Derivations can declare some infrequently used optional attributes.
where the cost of doing a download or remote build would exceed where the cost of doing a download or remote build would exceed
the cost of building locally. the cost of building locally.
- `allowSubstitutes` - `allowSubstitutes`\
If this attribute is set to `false`, then Nix will always build this If this attribute is set to `false`, then Nix will always build this
derivation; it will not try to substitute its outputs. This is derivation; it will not try to substitute its outputs. This is
useful for very trivial derivations (such as `writeText` in Nixpkgs) useful for very trivial derivations (such as `writeText` in Nixpkgs)
that are cheaper to build than to substitute from a binary cache. that are cheaper to build than to substitute from a binary cache.
> **Note** > **Note**
> >
> You need to have a builder configured which satisfies the > You need to have a builder configured which satisfies the
> derivation’s `system` attribute, since the derivation cannot be > derivation’s `system` attribute, since the derivation cannot be
> substituted. Thus it is usually a good idea to align `system` with > substituted. Thus it is usually a good idea to align `system` with

4
doc/manual/src/expressions/builtin-constants.md
View file

@ -2,7 +2,7 @@
Here are the constants built into the Nix expression evaluator: Here are the constants built into the Nix expression evaluator:
- `builtins` - `builtins`\
The set `builtins` contains all the built-in functions and values. The set `builtins` contains all the built-in functions and values.
You can use `builtins` to test for the availability of features in You can use `builtins` to test for the availability of features in
the Nix installation, e.g., the Nix installation, e.g.,
@ -14,7 +14,7 @@ Here are the constants built into the Nix expression evaluator:
This allows a Nix expression to fall back gracefully on older Nix This allows a Nix expression to fall back gracefully on older Nix
installations that don’t have the desired built-in function. installations that don’t have the desired built-in function.
- `builtins.currentSystem` - `builtins.currentSystem`\
The built-in value `currentSystem` evaluates to the Nix platform The built-in value `currentSystem` evaluates to the Nix platform
identifier for the Nix installation on which the expression is being identifier for the Nix installation on which the expression is being
evaluated, such as `"i686-linux"` or `"x86_64-darwin"`. evaluated, such as `"i686-linux"` or `"x86_64-darwin"`.

2
doc/manual/src/expressions/builtins-prefix.md
View file

@ -9,7 +9,7 @@ scope. Instead, you can access them through the `builtins` built-in
value, which is a set that contains all built-in functions and values. value, which is a set that contains all built-in functions and values.
For instance, `derivation` is also available as `builtins.derivation`. For instance, `derivation` is also available as `builtins.derivation`.
- `derivation` *attrs*; `builtins.derivation` *attrs* - `derivation` *attrs*; `builtins.derivation` *attrs*\
`derivation` is described in [its own section](derivations.md). `derivation` is described in [its own section](derivations.md).

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

@ -1,48 +1,48 @@
# Glossary # Glossary
- derivation - derivation\
A description of a build action. The result of a derivation is a A description of a build action. The result of a derivation is a
store object. Derivations are typically specified in Nix expressions store object. Derivations are typically specified in Nix expressions
using the [`derivation` primitive](expressions/derivations.md). These are using the [`derivation` primitive](expressions/derivations.md). These are
translated into low-level *store derivations* (implicitly by translated into low-level *store derivations* (implicitly by
`nix-env` and `nix-build`, or explicitly by `nix-instantiate`). `nix-env` and `nix-build`, or explicitly by `nix-instantiate`).
- store - store\
The location in the file system where store objects live. Typically The location in the file system where store objects live. Typically
`/nix/store`. `/nix/store`.
- store path - store path\
The location in the file system of a store object, i.e., an The location in the file system of a store object, i.e., an
immediate child of the Nix store directory. immediate child of the Nix store directory.
- store object - store object\
A file that is an immediate child of the Nix store directory. These A file that is an immediate child of the Nix store directory. These
can be regular files, but also entire directory trees. Store objects can be regular files, but also entire directory trees. Store objects
can be sources (objects copied from outside of the store), can be sources (objects copied from outside of the store),
derivation outputs (objects produced by running a build action), or derivation outputs (objects produced by running a build action), or
derivations (files describing a build action). derivations (files describing a build action).
- substitute - substitute\
A substitute is a command invocation stored in the Nix database that A substitute is a command invocation stored in the Nix database that
describes how to build a store object, bypassing the normal build describes how to build a store object, bypassing the normal build
mechanism (i.e., derivations). Typically, the substitute builds the mechanism (i.e., derivations). Typically, the substitute builds the
store object by downloading a pre-built version of the store object store object by downloading a pre-built version of the store object
from some server. from some server.
- purity - purity\
The assumption that equal Nix derivations when run always produce The assumption that equal Nix derivations when run always produce
the same output. This cannot be guaranteed in general (e.g., a the same output. This cannot be guaranteed in general (e.g., a
builder can rely on external inputs such as the network or the builder can rely on external inputs such as the network or the
system time) but the Nix model assumes it. system time) but the Nix model assumes it.
- Nix expression - Nix expression\
A high-level description of software packages and compositions A high-level description of software packages and compositions
thereof. Deploying software using Nix entails writing Nix thereof. Deploying software using Nix entails writing Nix
expressions for your packages. Nix expressions are translated to expressions for your packages. Nix expressions are translated to
derivations that are stored in the Nix store. These derivations can derivations that are stored in the Nix store. These derivations can
then be built. then be built.
- reference - reference\
A store path `P` is said to have a reference to a store path `Q` if A store path `P` is said to have a reference to a store path `Q` if
the store object at `P` contains the path `Q` somewhere. The the store object at `P` contains the path `Q` somewhere. The
*references* of a store path are the set of store paths to which it *references* of a store path are the set of store paths to which it
@ -52,11 +52,11 @@
output paths), whereas an output path only references other output output paths), whereas an output path only references other output
paths. paths.
- reachable - reachable\
A store path `Q` is reachable from another store path `P` if `Q` A store path `Q` is reachable from another store path `P` if `Q`
is in the *closure* of the *references* relation. is in the *closure* of the *references* relation.
- closure - closure\
The closure of a store path is the set of store paths that are The closure of a store path is the set of store paths that are
directly or indirectly “reachable” from that store path; that is, directly or indirectly “reachable” from that store path; that is,
it’s the closure of the path under the *references* relation. For it’s the closure of the path under the *references* relation. For
@ -71,29 +71,29 @@
to path `Q`, then `Q` is in the closure of `P`. Further, if `Q` to path `Q`, then `Q` is in the closure of `P`. Further, if `Q`
references `R` then `R` is also in the closure of `P`. references `R` then `R` is also in the closure of `P`.
- output path - output path\
A store path produced by a derivation. A store path produced by a derivation.
- deriver - deriver\
The deriver of an *output path* is the store The deriver of an *output path* is the store
derivation that built it. derivation that built it.
- validity - validity\
A store path is considered *valid* if it exists in the file system, A store path is considered *valid* if it exists in the file system,
is listed in the Nix database as being valid, and if all paths in is listed in the Nix database as being valid, and if all paths in
its closure are also valid. its closure are also valid.
- user environment - user environment\
An automatically generated store object that consists of a set of An automatically generated store object that consists of a set of
symlinks to “active” applications, i.e., other store paths. These symlinks to “active” applications, i.e., other store paths. These
are generated automatically by are generated automatically by
[`nix-env`](command-ref/nix-env.md). See *profiles*. [`nix-env`](command-ref/nix-env.md). See *profiles*.
- profile - profile\
A symlink to the current *user environment* of a user, e.g., A symlink to the current *user environment* of a user, e.g.,
`/nix/var/nix/profiles/default`. `/nix/var/nix/profiles/default`.
- NAR - NAR\
A *N*ix *AR*chive. This is a serialisation of a path in the Nix A *N*ix *AR*chive. This is a serialisation of a path in the Nix
store. It can contain regular files, directories and symbolic store. It can contain regular files, directories and symbolic
links. NARs are generated and unpacked using `nix-store --dump` links. NARs are generated and unpacked using `nix-store --dump`

8
doc/manual/src/package-management/s3-substituter.md
View file

@ -7,17 +7,17 @@ cache mechanism that Nix usually uses to fetch prebuilt binaries from
The following options can be specified as URL parameters to the S3 URL: The following options can be specified as URL parameters to the S3 URL:
- `profile` - `profile`\
The name of the AWS configuration profile to use. By default Nix The name of the AWS configuration profile to use. By default Nix
will use the `default` profile. will use the `default` profile.
- `region` - `region`\
The region of the S3 bucket. `us–east-1` by default. The region of the S3 bucket. `us–east-1` by default.
If your bucket is not in `us–east-1`, you should always explicitly If your bucket is not in `us–east-1`, you should always explicitly
specify the region parameter. specify the region parameter.
- `endpoint` - `endpoint`\
The URL to your S3-compatible service, for when not using Amazon S3. The URL to your S3-compatible service, for when not using Amazon S3.
Do not specify this value if you're using Amazon S3. Do not specify this value if you're using Amazon S3.
@ -26,7 +26,7 @@ The following options can be specified as URL parameters to the S3 URL:
> This endpoint must support HTTPS and will use path-based > This endpoint must support HTTPS and will use path-based
> addressing instead of virtual host based addressing. > addressing instead of virtual host based addressing.
- `scheme` - `scheme`\
The scheme used for S3 requests, `https` (default) or `http`. This The scheme used for S3 requests, `https` (default) or `http`. This
option allows you to disable HTTPS for binary caches which don't option allows you to disable HTTPS for binary caches which don't
support it. support it.

10
src/libexpr/primops.cc
View file

@ -1962,26 +1962,26 @@ static RegisterPrimOp primop_path({
An enrichment of the built-in path type, based on the attributes An enrichment of the built-in path type, based on the attributes
present in *args*. All are optional except `path`: present in *args*. All are optional except `path`:
- path - path\
The underlying path. The underlying path.
- name - name\
The name of the path when added to the store. This can used to The name of the path when added to the store. This can used to
reference paths that have nix-illegal characters in their names, reference paths that have nix-illegal characters in their names,
like `@`. like `@`.
- filter - filter\
A function of the type expected by `builtins.filterSource`, A function of the type expected by `builtins.filterSource`,
with the same semantics. with the same semantics.
- recursive - recursive\
When `false`, when `path` is added to the store it is with a When `false`, when `path` is added to the store it is with a
flat hash, rather than a hash of the NAR serialization of the flat hash, rather than a hash of the NAR serialization of the
file. Thus, `path` must refer to a regular file, not a file. Thus, `path` must refer to a regular file, not a
directory. This allows similar behavior to `fetchurl`. Defaults directory. This allows similar behavior to `fetchurl`. Defaults
to `true`. to `true`.
- sha256 - sha256\
When provided, this is the expected hash of the file at the When provided, this is the expected hash of the file at the
path. Evaluation will fail if the hash is incorrect, and path. Evaluation will fail if the hash is incorrect, and
providing a hash allows `builtins.path` to be used even when the providing a hash allows `builtins.path` to be used even when the

12
src/libexpr/primops/fetchTree.cc
View file

@ -303,17 +303,17 @@ static RegisterPrimOp primop_fetchGit({
of the repo at that URL is fetched. Otherwise, it can be an of the repo at that URL is fetched. Otherwise, it can be an
attribute with the following attributes (all except `url` optional): attribute with the following attributes (all except `url` optional):
- url - url\
The URL of the repo. The URL of the repo.
- name - name\
The name of the directory the repo should be exported to in the The name of the directory the repo should be exported to in the
store. Defaults to the basename of the URL. store. Defaults to the basename of the URL.
- rev - rev\
The git revision to fetch. Defaults to the tip of `ref`. The git revision to fetch. Defaults to the tip of `ref`.
- ref - ref\
The git ref to look for the requested revision under. This is The git ref to look for the requested revision under. This is
often a branch or tag name. Defaults to `HEAD`. often a branch or tag name. Defaults to `HEAD`.
@ -321,11 +321,11 @@ static RegisterPrimOp primop_fetchGit({
of Nix 2.3.0 Nix will not prefix `refs/heads/` if `ref` starts of Nix 2.3.0 Nix will not prefix `refs/heads/` if `ref` starts
with `refs/`. with `refs/`.
- submodules - submodules\
A Boolean parameter that specifies whether submodules should be A Boolean parameter that specifies whether submodules should be
checked out. Defaults to `false`. checked out. Defaults to `false`.
- allRefs - allRefs\
Whether to fetch all refs of the repository. With this argument being Whether to fetch all refs of the repository. With this argument being
true, it's possible to load a `rev` from *any* `ref` (by default only true, it's possible to load a `rev` from *any* `ref` (by default only
`rev`s from the specified `ref` are supported). `rev`s from the specified `ref` are supported).

2
src/libstore/globals.hh
View file

@ -701,7 +701,7 @@ public:
send a series of commands to modify various settings to stdout. The send a series of commands to modify various settings to stdout. The
currently recognized commands are: currently recognized commands are:
- `extra-sandbox-paths` - `extra-sandbox-paths`\
Pass a list of files and directories to be included in the Pass a list of files and directories to be included in the
sandbox for this build. One entry per line, terminated by an sandbox for this build. One entry per line, terminated by an
empty line. Entries have the same format as `sandbox-paths`. empty line. Entries have the same format as `sandbox-paths`.