diff options
Diffstat (limited to 'doc/manual/src/command-ref')
| -rw-r--r-- | doc/manual/src/command-ref/conf-file.md | 10 | ||||
| -rw-r--r-- | doc/manual/src/command-ref/nix-build.md | 12 | ||||
| -rw-r--r-- | doc/manual/src/command-ref/nix-channel.md | 21 | ||||
| -rw-r--r-- | doc/manual/src/command-ref/nix-collect-garbage.md | 2 | ||||
| -rw-r--r-- | doc/manual/src/command-ref/nix-env.md | 61 | ||||
| -rw-r--r-- | doc/manual/src/command-ref/nix-hash.md | 14 | ||||
| -rw-r--r-- | doc/manual/src/command-ref/nix-instantiate.md | 8 | ||||
| -rw-r--r-- | doc/manual/src/command-ref/nix-prefetch-url.md | 22 | ||||
| -rw-r--r-- | doc/manual/src/command-ref/nix-shell.md | 30 | ||||
| -rw-r--r-- | doc/manual/src/command-ref/nix-store.md | 80 | ||||
| -rw-r--r-- | doc/manual/src/command-ref/opt-common.md | 26 |
11 files changed, 145 insertions, 141 deletions
diff --git a/doc/manual/src/command-ref/conf-file.md b/doc/manual/src/command-ref/conf-file.md index 3f84373e2..92abeb73e 100644 --- a/doc/manual/src/command-ref/conf-file.md +++ b/doc/manual/src/command-ref/conf-file.md @@ -28,8 +28,8 @@ By default Nix reads settings from the following places: The configuration files consist of `name = value` pairs, one per line. Other files can be included with a line like `include -path`, where path is interpreted relative to the current conf file and a -missing file is an error unless `!include` is used instead. Comments +path`, where *path* is interpreted relative to the current conf file and +a missing file is an error unless `!include` is used instead. Comments start with a `#` character. Here is an example configuration file: keep-outputs = true # Nice for developers @@ -216,7 +216,7 @@ The following settings are currently available: - `hashed-mirrors` A list of web servers used by `builtins.fetchurl` to obtain files by hash. The default is `http://tarballs.nixos.org/`. Given a hash type - ht and a base-16 hash h, Nix will try to download the file from + *ht* and a base-16 hash *h*, Nix will try to download the file from `hashed-mirror/ht/h`. This allows files to be downloaded even if they have disappeared from their original URI. For example, given the default mirror `http://tarballs.nixos.org/`, when building the @@ -504,8 +504,8 @@ The following settings are currently available: A list of paths bind-mounted into Nix sandbox environments. You can use the syntax `target=source` to mount a path in a different location in the sandbox; for instance, `/bin=/nix-bin` will mount - the path `/nix-bin` as `/bin` inside the sandbox. If source is - followed by `?`, then it is not an error if source does not exist; + the path `/nix-bin` as `/bin` inside the sandbox. If *source* is + followed by `?`, then it is not an error if *source* does not exist; for example, `/dev/nvidiactl?` specifies that `/dev/nvidiactl` will only be mounted in the sandbox if it exists in the host filesystem. diff --git a/doc/manual/src/command-ref/nix-build.md b/doc/manual/src/command-ref/nix-build.md index 7d0567760..ddebc4b1b 100644 --- a/doc/manual/src/command-ref/nix-build.md +++ b/doc/manual/src/command-ref/nix-build.md @@ -43,16 +43,16 @@ paths # Description The `nix-build` command builds the derivations described by the Nix -expressions in paths. If the build succeeds, it places a symlink to the -result in the current directory. The symlink is called `result`. If +expressions in *paths*. If the build succeeds, it places a symlink to +the result in the current directory. The symlink is called `result`. If there are multiple Nix expressions, or the Nix expressions evaluate to multiple derivations, multiple sequentially numbered symlinks are created (`result`, `result-2`, and so on). -If no paths are specified, then `nix-build` will use `default.nix` in +If no *paths* are specified, then `nix-build` will use `default.nix` in the current directory, if it exists. -If an element of paths starts with `http://` or `https://`, it is +If an element of *paths* starts with `http://` or `https://`, it is interpreted as the URL of a tarball that will be downloaded and unpacked to a temporary location. The tarball must include a single top-level directory containing at least a file named `default.nix`. @@ -83,9 +83,9 @@ All options not listed here are passed to `nix-store - `--dry-run` 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 - `result` to outlink. + `result` to *outlink*. The following common options are supported: diff --git a/doc/manual/src/command-ref/nix-channel.md b/doc/manual/src/command-ref/nix-channel.md index d427151a0..0c20788f0 100644 --- a/doc/manual/src/command-ref/nix-channel.md +++ b/doc/manual/src/command-ref/nix-channel.md @@ -42,25 +42,26 @@ To see the list of official NixOS channels, visit This command has the following operations: - - `--add` url \[name\] - 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 - url, with the suffixes `-stable` or `-unstable` removed. + - `--add` *url* \[*name*\] + 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 + *url*, with the suffixes `-stable` or `-unstable` removed. - - `--remove` name - Removes the channel named name from the list of subscribed channels. + - `--remove` *name* + Removes the channel named *name* from the list of subscribed + channels. - `--list` Prints the names and URLs of all subscribed channels on standard output. - - `--update` \[names…\] + - `--update` \[*names*…\] Downloads the Nix expressions of all subscribed channels (or only - those included in names if specified) and makes them the default for - `nix-env` operations (by symlinking them from the directory + those included in *names* if specified) and makes them the default + for `nix-env` operations (by symlinking them from the directory `~/.nix-defexpr`). - - `--rollback` \[generation\] + - `--rollback` \[*generation*\] Reverts the previous call to `nix-channel --update`. Optionally, you can specify a specific channel generation number to restore. diff --git a/doc/manual/src/command-ref/nix-collect-garbage.md b/doc/manual/src/command-ref/nix-collect-garbage.md index 7946dc875..77b5d42d3 100644 --- a/doc/manual/src/command-ref/nix-collect-garbage.md +++ b/doc/manual/src/command-ref/nix-collect-garbage.md @@ -33,7 +33,7 @@ additional options: `-d` (`--delete-old`), which deletes all old generations of all profiles in `/nix/var/nix/profiles` by invoking `nix-env --delete-generations old` on all profiles (of course, this makes rollbacks to previous configurations impossible); and -`--delete-older-than` period, where period is a value such as `30d`, +`--delete-older-than` *period*, where period is a value such as `30d`, which deletes all generations older than the specified number of days in all profiles in `/nix/var/nix/profiles` (except for the generations that were active at that point in time). diff --git a/doc/manual/src/command-ref/nix-env.md b/doc/manual/src/command-ref/nix-env.md index 90bf6ea08..90a2bd351 100644 --- a/doc/manual/src/command-ref/nix-env.md +++ b/doc/manual/src/command-ref/nix-env.md @@ -98,7 +98,7 @@ This section lists the options that are common to all operations. These options are allowed for every subcommand, though they may not always have an effect. See also [???](#sec-common-options). - - `--file` / `-f` path + - `--file` / `-f` *path* Specifies the Nix expression (designated below as the *active Nix expression*) used by the `--install`, `--upgrade`, and `--query --available` operations to obtain derivations. The default is @@ -109,7 +109,7 @@ have an effect. See also [???](#sec-common-options). unpacked to a temporary location. The tarball must include a single 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 a profile (designated below as the *active profile*). A profile is a sequence of user environments called *generations*, one of which is @@ -125,10 +125,10 @@ have an effect. See also [???](#sec-common-options). [substituted](#gloss-substitute) (i.e., downloaded) and which paths will be built from source (because no substitute is available). - - `--system-filter` system + - `--system-filter` *system* By default, operations such as `--query --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*. <!-- end list --> @@ -200,17 +200,17 @@ args The install operation creates a new user environment, based on the current generation of the active profile, to which a set of store paths -described by args is added. The arguments args map to store paths in a -number of possible ways: +described by *args* is added. The arguments *args* map to store paths in +a number of possible ways: - - By default, args is a set of derivation names denoting derivations + - By default, *args* is a set of derivation names denoting derivations in the active Nix expression. These are realised, and the resulting output paths are installed. Currently installed derivations with a name equal to the name of a derivation being added are removed unless the option `--preserve-installed` is specified. - 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 + 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 derivation with the highest *priority* is used. A derivation can define a priority by declaring the `meta.priority` attribute. This attribute should be a number, with a higher value denoting a lower @@ -230,22 +230,23 @@ number of possible ways: unambiguous. To find out the attribute paths of available packages, use `nix-env -qaP`. - - If `--from-profile` path is given, args is a set of names denoting - installed store paths in the profile path. This is an easy way to - copy user environment elements from one profile to another. + - If `--from-profile` *path* is given, *args* is a set of names + denoting installed store paths in the profile *path*. This is an + easy way to copy user environment elements from one profile to + another. - - If `--from-expression` is given, args are Nix + - If `--from-expression` is given, *args* are Nix [functions](#ss-functions) that are called with the active Nix expression as their single argument. 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. - - If args are store derivations, then these are + - If *args* are store derivations, then these are [realised](#rsec-nix-store-realise), and the resulting output paths are installed. - - If args are store paths that are not store derivations, then these + - If *args* are store paths that are not store derivations, then these are [realised](#rsec-nix-store-realise) and installed. - By default all outputs are installed for each derivation. That can @@ -359,12 +360,12 @@ args The upgrade operation creates a new user environment, based on the current generation of the active profile, in which all store paths are replaced for which there are newer versions in the set of paths -described by args. Paths for which there are no newer versions are left -untouched; this is not an error. It is also not an error if an element -of args matches no installed derivations. +described by *args*. Paths for which there are no newer versions are +left untouched; this is not an error. It is also not an error if an +element of *args* matches no installed derivations. -For a description of how args is mapped to a set of store paths, see -[`--install`](#rsec-nix-env-install). If args describes multiple store +For a description of how *args* is mapped to a set of store paths, see +[`--install`](#rsec-nix-env-install). If *args* describes multiple store paths with the same symbolic name, only the one with the highest version is installed. @@ -462,7 +463,7 @@ drvnames The uninstall operation creates a new user environment, based on the current generation of the active profile, from which the store paths -designated by the symbolic names names are removed. +designated by the symbolic names *names* are removed. ## Examples @@ -629,7 +630,7 @@ The query operation displays information about either the store paths that are installed in the current generation of the active profile (`--installed`), or the derivations that are available for installation in the active Nix expression (`--available`). It only prints information -about derivations whose symbolic name matches one of names. +about derivations whose symbolic name matches one of *names*. The derivations are sorted by their `name` attributes. @@ -696,14 +697,14 @@ derivation is shown unless `--no-name` is specified. upgrades for installed packages are available in a Nix expression. A column is added with the following meaning: - - `<` version + - `<` *version* A newer version of the package is available or installed. - - `=` version + - `=` *version* At most the same version of the package is available or installed. - - `>` version + - `>` *version* Only older versions of the package are available or installed. - `- ?` @@ -806,8 +807,8 @@ path ## Description -This operation makes path the current profile for the user. That is, the -symlink `~/.nix-profile` is made to point to path. +This operation makes *path* the current profile for the user. That is, +the symlink `~/.nix-profile` is made to point to *path*. ## Examples @@ -882,9 +883,9 @@ generation ## Description -This operation makes generation number generation the current generation -of the active profile. That is, if the `profile` is the path to the -active profile, then the symlink `profile` is made to point to +This operation makes generation number *generation* the current +generation of the active profile. That is, if the `profile` is the path +to the active profile, then the symlink `profile` is made to point to `profile-generation-link`, which is in turn a symlink to the actual user environment in the Nix store. diff --git a/doc/manual/src/command-ref/nix-hash.md b/doc/manual/src/command-ref/nix-hash.md index d433cbc5b..3b8bbf740 100644 --- a/doc/manual/src/command-ref/nix-hash.md +++ b/doc/manual/src/command-ref/nix-hash.md @@ -37,7 +37,7 @@ hash # Description The command `nix-hash` computes the cryptographic hash of the contents -of each path and prints it on standard output. By default, it computes +of each *path* and prints it on standard output. By default, it computes an MD5 hash, but other hash algorithms are available as well. The hash is printed in hexadecimal. To generate the same hash as `nix-prefetch-url` you have to specify multiple arguments, see below for @@ -55,9 +55,9 @@ path | md5sum`. - `--flat` Print the cryptographic hash of the contents of each regular file - path. That is, do not compute the hash over the dump of path. The - result is identical to that produced by the GNU commands `md5sum` - and `sha1sum`. + *path*. That is, do not compute the hash over the dump of *path*. + The result is identical to that produced by the GNU commands + `md5sum` and `sha1sum`. - `--base32` Print the hash in a base-32 representation rather than hexadecimal. @@ -67,17 +67,17 @@ path | md5sum`. - `--truncate` 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 `md5`, `sha1`, and `sha256`. - `--to-base16` Don’t hash anything, but convert the base-32 hash representation - hash to hexadecimal. + *hash* to hexadecimal. - `--to-base32` Don’t hash anything, but convert the hexadecimal hash representation - hash to base-32. + *hash* to base-32. # Examples diff --git a/doc/manual/src/command-ref/nix-instantiate.md b/doc/manual/src/command-ref/nix-instantiate.md index 449f5f70f..179fbf5ba 100644 --- a/doc/manual/src/command-ref/nix-instantiate.md +++ b/doc/manual/src/command-ref/nix-instantiate.md @@ -56,19 +56,19 @@ files The command `nix-instantiate` generates [store derivations](#gloss-derivation) from (high-level) Nix expressions. It -evaluates the Nix expressions in each of files (which defaults to -./default.nix). Each top-level expression should evaluate to a +evaluates the Nix expressions in each of *files* (which defaults to +*./default.nix*). Each top-level expression should evaluate to a derivation, a list of derivations, or a set of derivations. The paths of the resulting store derivations are printed on standard output. -If files is the character `-`, then a Nix expression will be read from +If *files* is the character `-`, then a Nix expression will be read from standard input. See also [???](#sec-common-options) for a list of common options. # Options - - `--add-root` path; `--indirect` + - `--add-root` *path*; `--indirect` See the [corresponding options](#opt-add-root) in `nix-store`. - `--parse` diff --git a/doc/manual/src/command-ref/nix-prefetch-url.md b/doc/manual/src/command-ref/nix-prefetch-url.md index bf8084e45..f7de27402 100644 --- a/doc/manual/src/command-ref/nix-prefetch-url.md +++ b/doc/manual/src/command-ref/nix-prefetch-url.md @@ -31,9 +31,9 @@ hash # Description The command `nix-prefetch-url` downloads the file referenced by the URL -url, prints its cryptographic hash, and copies it into the Nix store. -The file name in the store is `hash-baseName`, where baseName is -everything following the final slash in url. +*url*, prints its cryptographic hash, and copies it into the Nix store. +The file name in the store is `hash-baseName`, where *baseName* is +everything following the final slash in *url*. This command is just a convenience for Nix expression writers. Often a Nix expression fetches some source distribution from the network using @@ -44,10 +44,10 @@ again when you build your Nix expression. Since `fetchurl` uses the same name for the downloaded file as `nix-prefetch-url`, the redundant download can be avoided. -If hash is specified, then a download is not performed if the Nix store -already contains a file with the same hash and base name. Otherwise, the -file is downloaded, and an error is signaled if the actual hash of the -file does not match the specified hash. +If *hash* is specified, then a download is not performed if the Nix +store already contains a file with the same hash and base name. +Otherwise, the file is downloaded, and an error is signaled if the +actual hash of the file does not match the specified hash. This command prints the hash on standard output. Additionally, if the option `--print-path` is used, the path of the downloaded file in the @@ -55,7 +55,7 @@ Nix store is also printed. # Options - - `--type` hashAlgo + - `--type` *hashAlgo* Use the specified cryptographic hash algorithm, which can be one of `md5`, `sha1`, and `sha256`. @@ -67,10 +67,10 @@ Nix store is also printed. result to the Nix store. The resulting hash can be used with functions such as Nixpkgs’s `fetchzip` or `fetchFromGitHub`. - - `--name` name + - `--name` *name* Override the name of the file in the Nix store. By default, this is - `hash-basename`, where basename is the last component of url. - Overriding the name is necessary when basename contains characters + `hash-basename`, where *basename* is the last component of *url*. + Overriding the name is necessary when *basename* contains characters that are not allowed in Nix store paths. # Examples diff --git a/doc/manual/src/command-ref/nix-shell.md b/doc/manual/src/command-ref/nix-shell.md index c6910e3f5..9e2b781ab 100644 --- a/doc/manual/src/command-ref/nix-shell.md +++ b/doc/manual/src/command-ref/nix-shell.md @@ -61,14 +61,14 @@ path The command `nix-shell` will build the dependencies of the specified derivation, but not the derivation itself. It will then start an interactive shell in which all environment variables defined by the -derivation path have been set to their corresponding values, and the +derivation *path* have been set to their corresponding values, and the script `$stdenv/setup` has been sourced. This is useful for reproducing the environment of a derivation for development. -If path is not given, `nix-shell` defaults to `shell.nix` if it exists, -and `default.nix` otherwise. +If *path* is not given, `nix-shell` defaults to `shell.nix` if it +exists, and `default.nix` otherwise. -If path starts with `http://` or `https://`, it is interpreted as the +If *path* starts with `http://` or `https://`, it is interpreted as the URL of a tarball that will be downloaded and unpacked to a temporary location. The tarball must include a single top-level directory containing at least a file named `default.nix`. @@ -91,8 +91,8 @@ All options not listed here are passed to `nix-store --realise`, except for `--arg` and `--attr` / `-A` which are passed to `nix-instantiate`. See also [???](#sec-common-options). - - `--command` cmd - In the environment of the derivation, run the shell command cmd. + - `--command` *cmd* + In the environment of the derivation, run the shell command *cmd*. This command is executed in an interactive shell. (Use `--run` to use a non-interactive shell instead.) However, a call to `exit` is implicitly added to the command, so the shell will exit after @@ -102,14 +102,14 @@ All options not listed here are passed to `nix-store interactive shell. This can be useful for doing any additional initialisation. - - `--run` cmd + - `--run` *cmd* Like `--command`, but executes the command in a non-interactive shell. This means (among other things) that if you hit Ctrl-C while the command is running, the shell exits. - - `--exclude` regexp + - `--exclude` *regexp* 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` If this flag is specified, the environment is almost entirely @@ -120,19 +120,19 @@ All options not listed here are passed to `nix-store installation) `/etc/bashrc` are still sourced, so any variables set there will affect the interactive shell. - - `--packages` / `-p` packages… + - `--packages` / `-p` *packages*… Set up an environment in which the specified packages are present. The command line arguments are interpreted as attribute names inside the Nix Packages collection. Thus, `nix-shell -p libjpeg openjdk` will start a shell in which the packages denoted by the attribute names `libjpeg` and `openjdk` are present. - - `-i` interpreter + - `-i` *interpreter* The chained script interpreter to be invoked by `nix-shell`. Only applicable in `#!`-scripts (described [below](#ssec-nix-shell-shebang)). - - `--keep` name + - `--keep` *name* When a `--pure` shell is started, keep the listed environment variables. @@ -199,10 +199,10 @@ done by starting the script with the following lines: #! /usr/bin/env nix-shell #! nix-shell -i real-interpreter -p packages -where real-interpreter is the “real” script interpreter that will be +where *real-interpreter* is the “real” script interpreter that will be invoked by `nix-shell` after it has obtained the dependencies and -initialised the environment, and packages are the attribute names of the -dependencies in Nixpkgs. +initialised the environment, and *packages* are the attribute names of +the dependencies in Nixpkgs. The lines starting with `#! nix-shell` specify `nix-shell` options (see above). Note that you cannot write `#! /usr/bin/env nix-shell -i ...` diff --git a/doc/manual/src/command-ref/nix-store.md b/doc/manual/src/command-ref/nix-store.md index 703e71076..a666de49b 100644 --- a/doc/manual/src/command-ref/nix-store.md +++ b/doc/manual/src/command-ref/nix-store.md @@ -37,10 +37,10 @@ options are allowed for every subcommand, though they may not always have an effect. See also [???](#sec-common-options) for a list of common options. - - `--add-root` path + - `--add-root` *path* Causes the result of a realisation (`--realise` and `--force-realise`) to be registered as a root of the garbage - collector(see [???](#ssec-gc-roots)). The root is stored in path, + collector(see [???](#ssec-gc-roots)). The root is stored in *path*, which must be inside a directory that is scanned for roots by the garbage collector (i.e., typically in a subdirectory of `/nix/var/nix/gcroots/`) *unless* the `--indirect` flag is used. @@ -56,8 +56,8 @@ options. result in the current directory; such a build result should not be garbage-collected unless the symlink is removed. - The `--indirect` flag causes a uniquely named symlink to path to be - stored in `/nix/var/nix/gcroots/auto/`. For instance, + The `--indirect` flag causes a uniquely named symlink to *path* to + be stored in `/nix/var/nix/gcroots/auto/`. For instance, $ nix-store --add-root /home/eelco/bla/result --indirect -r ... @@ -262,10 +262,11 @@ The following suboperations may be specified: By default, all unreachable paths are deleted. The following options control what gets deleted and in what order: - - `--max-freed` bytes - Keep deleting paths until at least bytes bytes have been deleted, - then stop. The argument bytes can be followed by the multiplicative - suffix `K`, `M`, `G` or `T`, denoting KiB, MiB, GiB or TiB units. + - `--max-freed` *bytes* + Keep deleting paths until at least *bytes* bytes have been deleted, + then stop. The argument *bytes* can be followed by the + multiplicative suffix `K`, `M`, `G` or `T`, denoting KiB, MiB, GiB + or TiB units. The behaviour of the collector is also influenced by the [`keep-outputs`](#conf-keep-outputs) and @@ -303,7 +304,7 @@ paths ## Description -The operation `--delete` deletes the store paths paths from the Nix +The operation `--delete` deletes the store paths *paths* from the Nix store, but only if it is safe to do so; that is, when the path is not reachable from a root of the garbage collector. This means that you can only delete paths that would also be deleted by `nix-store --gc`. Thus, @@ -379,7 +380,7 @@ The operation `--query` displays various bits of information about the store paths . The queries are described below. At most one query can be specified. The default query is `--outputs`. -The paths paths may also be symlinks from outside of the Nix store, to +The paths *paths* may also be symlinks from outside of the Nix store, to the Nix store. In that case, the query is applied to the target of the symlink. @@ -397,11 +398,11 @@ symlink. - `--outputs` Prints out the [output paths](#gloss-output-path) 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. - `--requisites`; `-R` - Prints out the [closure](#gloss-closure) of the store path paths. + Prints out the [closure](#gloss-closure) of the store path *paths*. This query has one option: @@ -419,29 +420,30 @@ symlink. - `--references` Prints the set of [references](#gloss-reference) of the store paths - paths, that is, their immediate dependencies. (For *all* + *paths*, that is, their immediate dependencies. (For *all* dependencies, use `--requisites`.) - `--referrers` - Prints the set of *referrers* of the store paths paths, that is, the - store paths currently existing in the Nix store that refer to 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 removed. + Prints the set of *referrers* of the store paths *paths*, that is, + the store paths currently existing in the Nix store that refer to + 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 + removed. - `--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 - indirectly refer to one of paths. These are all the path currently - in the Nix store that are dependent on paths. + indirectly refer to one of *paths*. These are all the path currently + in the Nix store that are dependent on *paths*. - `--deriver`; `-d` - Prints the [deriver](#gloss-deriver) of the store paths paths. If + Prints the [deriver](#gloss-deriver) of the store paths *paths*. If 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 deployment), the string `unknown-deriver` is printed. - `--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 package](http://www.graphviz.org/). This can be used to visualise dependency graphs. To obtain a build-time dependency graph, apply @@ -449,40 +451,40 @@ symlink. apply it to an output path. - `--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 tends to flatten the tree, making it more readable. The query only recurses into a store path when it is first encountered; this prevents a blowup of the tree representation of the graph. - `--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 used to visualise dependency graphs. To obtain a build-time dependency graph, apply this to a store derivation. To obtain a runtime dependency graph, apply it to an output path. - - `--binding` name; `-b` name - Prints the value of the attribute name (i.e., environment variable) - of the store derivations paths. It is an error for a derivation to - not have the specified attribute. + - `--binding` *name*; `-b` *name* + Prints the value of the attribute *name* (i.e., environment + variable) of the store derivations *paths*. It is an error for a + derivation to not have the specified attribute. - `--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 paths). Since the hash is stored in the Nix database, this is a fast operation. - `--size` - 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 the - given paths. Note that the actual disk space required by the store - paths may be higher, especially on filesystems with large cluster - sizes. + 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 + the given paths. Note that the actual disk space required by the + store paths may be higher, especially on filesystems with large + cluster sizes. - `--roots` Prints the garbage collector roots that point, directly or - indirectly, at the store paths paths. + indirectly, at the store paths *paths*. ## Examples @@ -708,8 +710,8 @@ path ## Description The operation `--dump` produces a NAR (Nix ARchive) file containing the -contents of the file system tree rooted at path. The archive is written -to standard output. +contents of the file system tree rooted at *path*. The archive is +written to standard output. A NAR archive is like a TAR or Zip archive, but it contains only the information that Nix considers important. For instance, timestamps are @@ -745,8 +747,8 @@ path ## Description -The operation `--restore` unpacks a NAR archive to path, which must not -already exist. The archive is read from standard input. +The operation `--restore` unpacks a NAR archive to *path*, which must +not already exist. The archive is read from standard input. # Operation `--export` diff --git a/doc/manual/src/command-ref/opt-common.md b/doc/manual/src/command-ref/opt-common.md index ac9d996c3..dce95773a 100644 --- a/doc/manual/src/command-ref/opt-common.md +++ b/doc/manual/src/command-ref/opt-common.md @@ -44,9 +44,9 @@ Most Nix commands accept the following command-line options: This option may be specified repeatedly. See the previous verbosity levels list. - - `--log-format` format + - `--log-format` *format* This option can be used to change the output of the log format, with - format being one of: + *format* being one of: - raw This is the raw format, as outputted by nix-build. @@ -68,7 +68,7 @@ Most Nix commands accept the following command-line options: output and error are always written to a log file in `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 parallel to the specified number. Specify `auto` to use the number of CPUs in the system. The default is specified by the @@ -144,7 +144,7 @@ Most Nix commands accept the following command-line options: database. Most Nix operations do need database access, so those operations will fail. - - `--arg` name value + - `--arg` *name* *value* This option is accepted by `nix-env`, `nix-instantiate`, `nix-shell` and `nix-build`. When evaluating Nix expressions, the expression evaluator will automatically try to call functions that it @@ -153,8 +153,8 @@ Most Nix commands accept the following command-line options: defaultValue }: ...`). With `--arg`, you can also call functions that have arguments without a default value (or override a default value). That is, if - the evaluator encounters a function with an argument named name, it - will call it with value value. + the evaluator encounters a function with an argument named *name*, + it will call it with value *value*. For instance, the top-level `default.nix` in Nixpkgs is actually a function: @@ -172,18 +172,18 @@ Most Nix commands accept the following command-line options: \"i686-freebsd\"`. (Note that since the argument is a Nix string literal, you have to escape the quotes.) - - `--argstr` name value + - `--argstr` *name* *value* This option is like `--arg`, only the value is not a Nix expression but a string. So instead of `--arg system \"i686-linux\"` (the outer quotes are to keep the shell happy) you can say `--argstr system i686-linux`. - - `--attr` / `-A` attrPath + - `--attr` / `-A` *attrPath* Select an attribute from the top-level Nix expression being evaluated. (`nix-env`, `nix-instantiate`, `nix-build` and - `nix-shell` only.) The *attribute path* attrPath is a sequence of + `nix-shell` only.) The *attribute path* *attrPath* is a sequence of attribute names separated by dots. For instance, given a top-level - Nix expression e, the attribute path `xorg.xorgserver` would cause + Nix expression *e*, the attribute path `xorg.xorgserver` would cause the expression `e.xorg.xorgserver` to be used. See [`nix-env --install`](#refsec-nix-env-install-examples) for some concrete examples. @@ -204,14 +204,14 @@ Most Nix commands accept the following command-line options: use, give your expression to the `nix-shell -p` convenience flag instead. - - `-I` path + - `-I` *path* Add a path to the Nix expression search path. This option may be given multiple times. See the NIX\_PATH\</literal\> environment variable for information on the semantics of the Nix search path. Paths added through `-I` take precedence over `NIX_PATH`. - - `--option` name value - Set the Nix configuration option name to value. This overrides + - `--option` *name* *value* + Set the Nix configuration option *name* to *value*. This overrides settings in the Nix configuration file (see nix.conf5). - `--repair` |