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

dedent lists

Browse source 
this indentation is unnecessary and probably an artefact from the
migration off XML.
This commit is contained in:
Valentin Gagarin 2024-06-18 11:26:08 +02:00
parent 4f340213bb
commit b975151c09
17 changed files with 523 additions and 524 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

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

@ -55,20 +55,20 @@ All options not listed here are passed to
[`nix-store --realise`](nix-store/realise.md), [`nix-store --realise`](nix-store/realise.md),
except for `--arg` and `--attr` / `-A` which are passed to [`nix-instantiate`](nix-instantiate.md). except for `--arg` and `--attr` / `-A` which are passed to [`nix-instantiate`](nix-instantiate.md).
- <span id="opt-no-out-link">[`--no-out-link`](#opt-no-out-link)<span> - <span id="opt-no-out-link">[`--no-out-link`](#opt-no-out-link)<span>
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 --gc`. might be deleted by `nix-store --gc`.
- <span id="opt-dry-run">[`--dry-run`](#opt-dry-run)</span> - <span id="opt-dry-run">[`--dry-run`](#opt-dry-run)</span>
Show what store paths would be built or downloaded. Show what store paths would be built or downloaded.
- <span id="opt-out-link">[`--out-link`](#opt-out-link)</span> / `-o` *outlink* - <span id="opt-out-link">[`--out-link`](#opt-out-link)</span> / `-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*.
{{#include ./status-build-failure.md}} {{#include ./status-build-failure.md}}

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

@ -27,46 +27,46 @@ The moving parts of channels are:
This command has the following operations: This command has the following operations:
- `--add` *url* \[*name*\] - `--add` *url* \[*name*\]
Add a channel *name* located at *url* to the list of subscribed channels. Add a channel *name* located at *url* to the list of subscribed channels.
If *name* is omitted, default to the last component of *url*, with the suffixes `-stable` or `-unstable` removed. If *name* is omitted, default to the last component of *url*, with the suffixes `-stable` or `-unstable` removed.
> **Note** > **Note**
> >
> `--add` does not automatically perform an update. > `--add` does not automatically perform an update.
> Use `--update` explicitly. > Use `--update` explicitly.
A channel URL must point to a directory containing a file `nixexprs.tar.gz`. A channel URL must point to a directory containing a file `nixexprs.tar.gz`.
At the top level, that tarball must contain a single directory with a `default.nix` file that serves as the channel’s entry point. At the top level, that tarball must contain a single directory with a `default.nix` file that serves as the channel’s entry point.
- `--remove` *name* - `--remove` *name*
Remove the channel *name* from the list of subscribed channels. Remove the channel *name* from the list of subscribed channels.
- `--list` - `--list`
Print the names and URLs of all subscribed channels on standard output. Print the names and URLs of all subscribed channels on standard output.
- `--update` \[*names*…\] - `--update` \[*names*…\]
Download the Nix expressions of subscribed channels and create a new generation. Download the Nix expressions of subscribed channels and create a new generation.
Update all channels if none is specified, and only those included in *names* otherwise. Update all channels if none is specified, and only those included in *names* otherwise.
- `--list-generations` - `--list-generations`
Prints a list of all the current existing generations for the Prints a list of all the current existing generations for the
channel profile. channel profile.
Works the same way as Works the same way as
``` ```
nix-env --profile /nix/var/nix/profiles/per-user/$USER/channels --list-generations nix-env --profile /nix/var/nix/profiles/per-user/$USER/channels --list-generations
``` ```
- `--rollback` \[*generation*\] - `--rollback` \[*generation*\]
Revert channels to the state before the last call to `nix-channel --update`. Revert channels to the state before the last call to `nix-channel --update`.
Optionally, you can specify a specific channel *generation* number to restore. Optionally, you can specify a specific channel *generation* number to restore.
{{#include ./opt-common.md}} {{#include ./opt-common.md}}

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

@ -27,38 +27,38 @@ When using public key authentication, you can avoid typing the passphrase with `
# Options # Options
- `--to` - `--to`
Copy the closure of _paths_ from a Nix store accessible from the local machine to the Nix store on the remote _machine_. Copy the closure of _paths_ from a Nix store accessible from the local machine to the Nix store on the remote _machine_.
This is the default behavior. This is the default behavior.
- `--from` - `--from`
Copy the closure of _paths_ from the Nix store on the remote _machine_ to the local machine's specified Nix store. Copy the closure of _paths_ from the Nix store on the remote _machine_ to the local machine's specified 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 derivation]s included in the closure. Also copy the outputs of [store derivation]s included in the closure.
[store derivation]: @docroot@/glossary.md#gloss-store-derivation [store derivation]: @docroot@/glossary.md#gloss-store-derivation
- `--use-substitutes` / `-s` - `--use-substitutes` / `-s`
Attempt to download missing store objects on the target from [substituters](@docroot@/command-ref/conf-file.md#conf-substituters). Attempt to download missing store objects on the target from [substituters](@docroot@/command-ref/conf-file.md#conf-substituters).
Any store objects that cannot be substituted on the target are still copied normally from the source. Any store objects that cannot be substituted on the target are still copied normally from the source.
This is useful, for instance, if the connection between the source and target machine is slow, but the connection between the target machine and `cache.nixos.org` (the default binary cache server) is fast. This is useful, for instance, if the connection between the source and target machine is slow, but the connection between the target machine and `cache.nixos.org` (the default binary cache server) is fast.
{{#include ./opt-common.md}} {{#include ./opt-common.md}}
# Environment variables # Environment variables
- `NIX_SSHOPTS` - `NIX_SSHOPTS`
Additional options to be passed to `ssh` on the command line. Additional options to be passed to `ssh` on the command line.
{{#include ./env-common.md}} {{#include ./env-common.md}}

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

@ -21,125 +21,125 @@ It is based on the current generation of the active [profile](@docroot@/command-
The arguments *args* map to store paths in a number of possible ways: The arguments *args* map to store paths in a number of possible ways:
- By default, *args* is a set of [derivation] names denoting derivations in the [default Nix expression]. - By default, *args* is a set of [derivation] names denoting derivations in the [default Nix expression].
These are [realised], and the resulting output paths are installed. These are [realised], and the resulting output paths are installed.
Currently installed derivations with a name equal to the name of a derivation being added are removed unless the option `--preserve-installed` is specified. Currently installed derivations with a name equal to the name of a derivation being added are removed unless the option `--preserve-installed` is specified.
[derivation]: @docroot@/glossary.md#gloss-derivation [derivation]: @docroot@/glossary.md#gloss-derivation
[default Nix expression]: @docroot@/command-ref/files/default-nix-expression.md [default Nix expression]: @docroot@/command-ref/files/default-nix-expression.md
[realised]: @docroot@/glossary.md#gloss-realise [realised]: @docroot@/glossary.md#gloss-realise
If there are multiple derivations matching a name in *args* that If there are multiple derivations matching a name in *args* that
have the same name (e.g., `gcc-3.3.6` and `gcc-4.1.1`), then the have the same name (e.g., `gcc-3.3.6` and `gcc-4.1.1`), then the
derivation with the highest *priority* is used. A derivation can derivation with the highest *priority* is used. A derivation can
define a priority by declaring the `meta.priority` attribute. This define a priority by declaring the `meta.priority` attribute. This
attribute should be a number, with a higher value denoting a lower attribute should be a number, with a higher value denoting a lower
priority. The default priority is `5`. priority. The default priority is `5`.
If there are multiple matching derivations with the same priority, If there are multiple matching derivations with the same priority,
then the derivation with the highest version will be installed. then the derivation with the highest version will be installed.
You can force the installation of multiple derivations with the same You can force the installation of multiple derivations with the same
name by being specific about the versions. For instance, `nix-env --install name by being specific about the versions. For instance, `nix-env --install
gcc-3.3.6 gcc-4.1.1` will install both version of GCC (and will gcc-3.3.6 gcc-4.1.1` will install both version of GCC (and will
probably cause a user environment conflict\!). probably cause a user environment conflict\!).
- If [`--attr`](#opt-attr) / `-A` is specified, the arguments are *attribute paths* that select attributes from the [default Nix expression]. - If [`--attr`](#opt-attr) / `-A` is specified, the arguments are *attribute paths* that select attributes from the [default Nix expression].
This is faster than using derivation names and unambiguous. This is faster than using derivation names and unambiguous.
Show the attribute paths of available packages with [`nix-env --query`](./query.md): Show the attribute paths of available packages with [`nix-env --query`](./query.md):
```console ```console
nix-env --query --available --attr-path nix-env --query --available --attr-path
``` ```
- If `--from-profile` *path* is given, *args* is a set of names - If `--from-profile` *path* is given, *args* is a set of names
denoting installed [store paths] in the profile *path*. This is an denoting installed [store paths] in the profile *path*. This is an
easy way to copy user environment elements from one profile to easy way to copy user environment elements from one profile to
another. another.
- If `--from-expression` is given, *args* are [Nix language functions](@docroot@/language/constructs.md#functions) that are called with the [default Nix expression] as their single argument. - If `--from-expression` is given, *args* are [Nix language functions](@docroot@/language/constructs.md#functions) that are called with the [default Nix expression] as their single argument.
The derivations returned by those function calls are installed. The derivations returned by those function calls are installed.
This allows derivations to be specified in an unambiguous way, which is necessary if there are multiple derivations with the same name. This allows derivations to be specified in an unambiguous way, which is necessary if there are multiple derivations with the same name.
- If *args* are [store derivations](@docroot@/glossary.md#gloss-store-derivation), then these are [realised], and the resulting output paths are installed. - If *args* are [store derivations](@docroot@/glossary.md#gloss-store-derivation), then these are [realised], and the resulting output paths are installed.
- If *args* are [store paths] that are not store derivations, then these are [realised] and installed. - If *args* are [store paths] that are not store derivations, then these are [realised] and installed.
- By default all [outputs](@docroot@/language/derivations.md#attr-outputs) are installed for each [derivation]. - By default all [outputs](@docroot@/language/derivations.md#attr-outputs) are installed for each [derivation].
This can be overridden by adding a `meta.outputsToInstall` attribute on the derivation listing a subset of the output names. This can be overridden by adding a `meta.outputsToInstall` attribute on the derivation listing a subset of the output names.
Example: Example:
The file `example.nix` defines a derivation with two outputs `foo` and `bar`, each containing a file. The file `example.nix` defines a derivation with two outputs `foo` and `bar`, each containing a file.
```nix ```nix
# example.nix # example.nix
let let
pkgs = import <nixpkgs> {}; pkgs = import <nixpkgs> {};
command = '' command = ''
${pkgs.coreutils}/bin/mkdir -p $foo $bar ${pkgs.coreutils}/bin/mkdir -p $foo $bar
echo foo > $foo/foo-file echo foo > $foo/foo-file
echo bar > $bar/bar-file echo bar > $bar/bar-file
''; '';
in in
derivation { derivation {
name = "example"; name = "example";
builder = "${pkgs.bash}/bin/bash"; builder = "${pkgs.bash}/bin/bash";
args = [ "-c" command ]; args = [ "-c" command ];
outputs = [ "foo" "bar" ]; outputs = [ "foo" "bar" ];
system = builtins.currentSystem; system = builtins.currentSystem;
} }
``` ```
Installing from this Nix expression will make files from both outputs appear in the current profile. Installing from this Nix expression will make files from both outputs appear in the current profile.
```console ```console
$ nix-env --install --file example.nix $ nix-env --install --file example.nix
installing 'example' installing 'example'
$ ls ~/.nix-profile $ ls ~/.nix-profile
foo-file foo-file
bar-file bar-file
manifest.nix manifest.nix
``` ```
Adding `meta.outputsToInstall` to that derivation will make `nix-env` only install files from the specified outputs. Adding `meta.outputsToInstall` to that derivation will make `nix-env` only install files from the specified outputs.
```nix ```nix
# example-outputs.nix # example-outputs.nix
import ./example.nix // { meta.outputsToInstall = [ "bar" ]; } import ./example.nix // { meta.outputsToInstall = [ "bar" ]; }
``` ```
```console ```console
$ nix-env --install --file example-outputs.nix $ nix-env --install --file example-outputs.nix
installing 'example' installing 'example'
$ ls ~/.nix-profile $ ls ~/.nix-profile
bar-file bar-file
manifest.nix manifest.nix
``` ```
# Options # Options
- `--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
lead to an error in building the generation, due to file name lead to an error in building the generation, due to file name
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 --uninstall '.*'` first, except that everything happens to running `nix-env --uninstall '.*'` first, except that everything happens
in a single transaction. in a single transaction.
{{#include ./opt-common.md}} {{#include ./opt-common.md}}

51
doc/manual/src/command-ref/nix-env/opt-common.md
View file

@ -2,38 +2,37 @@
The following options are allowed for all `nix-env` operations, but may not always have an effect. The following options are allowed for all `nix-env` operations, but may not always 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
`~/.nix-defexpr`. `~/.nix-defexpr`.
If the argument starts with `http://` or `https://`, it is If the argument starts with `http://` or `https://`, it is
interpreted as the URL of a tarball that will be downloaded and interpreted as the URL of a tarball that will be downloaded and
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
done if this flag had not been specified, without actually doing it. done if this flag had not been specified, without actually doing it.
`--dry-run` also prints out which paths will be `--dry-run` also prints out which paths will be
[substituted](@docroot@/glossary.md) (i.e., downloaded) and which paths [substituted](@docroot@/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*.

32
doc/manual/src/command-ref/nix-env/set-flag.md
View file

@ -13,24 +13,24 @@ to be modified. There are several attributes that can be usefully
modified, because they affect the behaviour of `nix-env` or the user modified, because they affect the behaviour of `nix-env` or the user
environment build script: environment build script:
- `priority` can be changed to resolve filename clashes. The user - `priority` can be changed to resolve filename clashes. The user
environment build script uses the `meta.priority` attribute of environment build script uses the `meta.priority` attribute of
derivations to resolve filename collisions between packages. Lower derivations to resolve filename collisions between packages. Lower
priority values denote a higher priority. For instance, the GCC priority values denote a higher priority. For instance, the GCC
wrapper package and the Binutils package in Nixpkgs both have a file wrapper package and the Binutils package in Nixpkgs both have a file
`bin/ld`, so previously if you tried to install both you would get a `bin/ld`, so previously if you tried to install both you would get a
collision. Now, on the other hand, the GCC wrapper declares a higher collision. Now, on the other hand, the GCC wrapper declares a higher
priority than Binutils, so the former’s `bin/ld` is symlinked in the priority than Binutils, so the former’s `bin/ld` is symlinked in the
user environment. user environment.
- `keep` can be set to `true` to prevent the package from being - `keep` can be set to `true` to prevent the package from being
upgraded or replaced. This is useful if you want to hang on to an upgraded or replaced. This is useful if you want to hang on to an
older version of a package. older version of a package.
- `active` can be set to `false` to “disable” the package. That is, no - `active` can be set to `false` to “disable” the package. That is, no
symlinks will be generated to the files of the package, but it symlinks will be generated to the files of the package, but it
remains part of the profile (so it won’t be garbage-collected). It remains part of the profile (so it won’t be garbage-collected). It
can be set back to `true` to re-enable the package. can be set back to `true` to re-enable the package.
{{#include ./opt-common.md}} {{#include ./opt-common.md}}

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

@ -28,48 +28,48 @@ 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
active Nix expression. active Nix expression.
- `--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
lead to an error in building the generation, due to file name lead to an error in building the generation, due to file name
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.
{{#include ./opt-common.md}} {{#include ./opt-common.md}}

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

@ -29,65 +29,65 @@ md5sum`.
# Options # Options
- `--flat` - `--flat`
Print the cryptographic hash of the contents of each regular file *path*. Print the cryptographic hash of the contents of each regular file *path*.
That is, instead of computing That is, instead of computing
the hash of the [Nix Archive (NAR)](@docroot@/store/file-system-object/content-address.md#serial-nix-archive) of *path*, the hash of the [Nix Archive (NAR)](@docroot@/store/file-system-object/content-address.md#serial-nix-archive) of *path*,
just [directly hash]((@docroot@/store/file-system-object/content-address.md#serial-flat) *path* as is. just [directly hash]((@docroot@/store/file-system-object/content-address.md#serial-flat) *path* as is.
This requires *path* to resolve to a regular file rather than directory. This requires *path* to resolve to a regular file rather than directory.
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`.
- `--base16` - `--base16`
Print the hash in a hexadecimal representation (default). Print the hash in a hexadecimal representation (default).
- `--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`).
- `--base64` - `--base64`
Similar to --base32, but print the hash in a base-64 representation, Similar to --base32, but print the hash in a base-64 representation,
which is more compact than the base-32 one. which is more compact than the base-32 one.
- `--sri` - `--sri`
Print the hash in SRI format with base-64 encoding. Print the hash in SRI format with base-64 encoding.
The type of hash algorithm will be prepended to the hash string, The type of hash algorithm will be prepended to the hash string,
followed by a hyphen (-) and the base-64 hash body. followed by a hyphen (-) and the base-64 hash body.
- `--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.
- `--to-base64` - `--to-base64`
Don’t hash anything, but convert the hexadecimal hash representation Don’t hash anything, but convert the hexadecimal hash representation
*hash* to base-64. *hash* to base-64.
- `--to-sri` - `--to-sri`
Don’t hash anything, but convert the hexadecimal hash representation Don’t hash anything, but convert the hexadecimal hash representation
*hash* to SRI. *hash* to SRI.
# Examples # Examples

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

@ -30,97 +30,97 @@ 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 as a Nix expression. standard output as a Nix expression.
- `--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.
> **Warning** > **Warning**
> >
> This option produces output which can be parsed as a Nix expression which > This option produces output which can be parsed as a Nix expression which
> will produce a different result than the input expression when evaluated. > will produce a different result than the input expression when evaluated.
> For example, these two Nix expressions print the same result despite > For example, these two Nix expressions print the same result despite
> having different meaning: > having different meaning:
> >
> ```console > ```console
> $ nix-instantiate --eval --expr '{ a = {}; }' > $ nix-instantiate --eval --expr '{ a = {}; }'
> { a = <CODE>; } > { a = <CODE>; }
> $ nix-instantiate --eval --expr '{ a = <CODE>; }' > $ nix-instantiate --eval --expr '{ a = <CODE>; }'
> { a = <CODE>; } > { a = <CODE>; }
> ``` > ```
> >
> For human-readable output, `nix eval` (experimental) is more informative: > For human-readable output, `nix eval` (experimental) is more informative:
> >
> ```console > ```console
> $ nix-instantiate --eval --expr 'a: a' > $ nix-instantiate --eval --expr 'a: a'
> <LAMBDA> > <LAMBDA>
> $ nix eval --expr 'a: a' > $ nix eval --expr 'a: a'
> «lambda @ «string»:1:1» > «lambda @ «string»:1:1»
> ``` > ```
> >
> For machine-readable output, the `--xml` option produces unambiguous > For machine-readable output, the `--xml` option produces unambiguous
> output: > output:
> >
> ```console > ```console
> $ nix-instantiate --eval --xml --expr '{ foo = <CODE>; }' > $ nix-instantiate --eval --xml --expr '{ foo = <CODE>; }'
> <?xml version='1.0' encoding='utf-8'?> > <?xml version='1.0' encoding='utf-8'?>
> <expr> > <expr>
> <attrs> > <attrs>
> <attr column="3" line="1" name="foo"> > <attr column="3" line="1" name="foo">
> <unevaluated /> > <unevaluated />
> </attr> > </attr>
> </attrs> > </attrs>
> </expr> > </expr>
> ``` > ```
- `--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 language is lazy). (since the Nix language is lazy).
> **Warning** > **Warning**
> >
> 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 a Nix expression. representation of the abstract syntax tree rather than as a Nix expression.
- `--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 a Nix expression. representation of the abstract syntax tree rather than as a Nix expression.
The schema is the same as that used by the [`toXML` The schema is the same as that used by the [`toXML`
built-in](../language/builtins.md). built-in](../language/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
this option is not enabled, there may be uninstantiated store paths this option is not enabled, there may be uninstantiated store paths
in the final output. in the final output.
{{#include ./opt-common.md}} {{#include ./opt-common.md}}

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

@ -39,32 +39,32 @@ the path of the downloaded file in the Nix store is also printed.
# Options # Options
- `--type` *hashAlgo* - `--type` *hashAlgo*
Use the specified cryptographic hash algorithm, Use the specified cryptographic hash algorithm,
which can be one of `md5`, `sha1`, `sha256`, and `sha512`. which can be one of `md5`, `sha1`, `sha256`, and `sha512`.
The default is `sha256`. The default is `sha256`.
- `--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
that are not allowed in Nix store paths. that are not allowed in Nix store paths.
# Examples # Examples

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

@ -60,63 +60,63 @@ 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
implicitly added to the command, so the shell will exit after implicitly added to the command, so the shell will exit after
running the command. To prevent this, add `return` at the end; running the command. To prevent this, add `return` at the end;
e.g. `--command "echo Hello; return"` will print `Hello` and then e.g. `--command "echo Hello; return"` will print `Hello` and then
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
few variables, in particular `HOME`, `USER` and `DISPLAY`, are few variables, in particular `HOME`, `USER` and `DISPLAY`, are
retained. retained.
- `--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 --packages libjpeg openjdk` the Nix Packages collection. Thus, `nix-shell --packages 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.
{{#include ./opt-common.md}} {{#include ./opt-common.md}}
# 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 `<nixpkgs>`, falling back to the `bash` found in `bash` found in `<nixpkgs>`, falling back to the `bash` found in
`PATH` if not found. `PATH` if not found.
{{#include ./env-common.md}} {{#include ./env-common.md}}

6
doc/manual/src/command-ref/nix-store/add-fixed.md
View file

@ -16,10 +16,10 @@ 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.
{{#include ./opt-common.md}} {{#include ./opt-common.md}}

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

@ -14,34 +14,34 @@ 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.
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
or TiB units. or TiB units.
The behaviour of the collector is also influenced by the The behaviour of the collector is also influenced by the
`keep-outputs` and `keep-derivations` settings in the Nix `keep-outputs` and `keep-derivations` settings in the Nix

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

@ -24,138 +24,138 @@ 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`](./realise.md)). Realise each argument to the query first (see [`nix-store --realise`](./realise.md)).
[store derivation]: @docroot@/glossary.md#gloss-store-derivation [store derivation]: @docroot@/glossary.md#gloss-store-derivation
# Queries # Queries
- `--outputs` - `--outputs`
Prints out the [output paths] of the store Prints out the [output paths] 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.
[output paths]: @docroot@/glossary.md#gloss-output-path [output paths]: @docroot@/glossary.md#gloss-output-path
- `--requisites` / `-R` - `--requisites` / `-R`
Prints out the [closure] of the store path *paths*. Prints out the [closure] of the store path *paths*.
[closure]: @docroot@/glossary.md#gloss-closure [closure]: @docroot@/glossary.md#gloss-closure
This query has one option: This query has one option:
- `--include-outputs` - `--include-outputs`
Also include the existing output paths of [store derivation]s, Also include the existing output paths of [store derivation]s,
and their closures. and their closures.
This query can be used to implement various kinds of deployment. A This query can be used to implement various kinds of deployment. A
*source deployment* is obtained by distributing the closure of a *source deployment* is obtained by distributing the closure of a
store derivation. A *binary deployment* is obtained by distributing store derivation. A *binary deployment* is obtained by distributing
the closure of an output path. A *cache deployment* (combined the closure of an output path. A *cache deployment* (combined
source/binary deployment, including binaries of build-time-only source/binary deployment, including binaries of build-time-only
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] of the store paths Prints the set of [references] 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`.)
[references]: @docroot@/glossary.md#gloss-reference [references]: @docroot@/glossary.md#gloss-reference
- `--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] that was used to build the store paths *paths*. If Prints the [deriver] that was used to build 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.
The returned deriver is not guaranteed to exist in the local store, for The returned deriver is not guaranteed to exist in the local store, for
example when *paths* were substituted from a binary cache. example when *paths* were substituted from a binary cache.
Use `--valid-derivers` instead to obtain valid paths only. Use `--valid-derivers` instead to obtain valid paths only.
[deriver]: @docroot@/glossary.md#gloss-deriver [deriver]: @docroot@/glossary.md#gloss-deriver
- `--valid-derivers` - `--valid-derivers`
Prints a set of derivation files (`.drv`) which are supposed produce Prints a set of derivation files (`.drv`) which are supposed produce
said paths when realized. Might print nothing, for example for source paths said paths when realized. Might print nothing, for example for source paths
or paths subsituted from a binary cache. or paths subsituted from a binary cache.
- `--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
dependency graphs. To obtain a build-time dependency graph, apply dependency graphs. To obtain a build-time dependency graph, apply
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 derivation]s *paths*. It is an error for a variable) of the [store derivation]s *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*.
{{#include ./opt-common.md}} {{#include ./opt-common.md}}

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

@ -42,26 +42,26 @@ For non-derivation arguments, the argument itself is printed.
# Options # Options
- `--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,
printing an error if that’s not the case. The outputs of the printing an error if that’s not the case. The outputs of the
specified derivation must already exist. When used with `-K`, if an specified derivation must already exist. When used with `-K`, if an
output path is not identical to the corresponding output from the output path is not identical to the corresponding output from the
previous build, the new output path is left in previous build, the new output path is left in
`/nix/store/name.check.` `/nix/store/name.check.`
{{#include ./opt-common.md}} {{#include ./opt-common.md}}

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

@ -14,11 +14,11 @@ 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.
{{#include ./opt-common.md}} {{#include ./opt-common.md}}

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

@ -16,20 +16,20 @@ 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
`nix-store --repair-path` for details. `nix-store --repair-path` for details.
{{#include ./opt-common.md}} {{#include ./opt-common.md}}