lix-project/lix
19
42
Fork 18
Code Issues 295 Code Review (Gerrit) Projects 1 Releases Wiki Activity

Clean up the manpages

Browse source
This commit is contained in:
Eelco Dolstra 2020-07-24 12:56:19 +02:00
parent 8d0b311a1c
commit 758c9ee1bb
No known key found for this signature in database
GPG key ID: 8170B4726D7198DE
12 changed files with 248 additions and 701 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

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

@ -1,12 +1,8 @@
nix.conf Title: nix.conf
5 # Name
Nix `nix.conf` - Nix configuration file
nix.conf
Nix configuration file
# Description # Description
@ -20,7 +16,7 @@ By default Nix reads settings from the following places:
- If `NIX_USER_CONF_FILES` is set, then each path separated by `:` - If `NIX_USER_CONF_FILES` is set, then each path separated by `:`
will be loaded in reverse order. will be loaded in reverse order.
Otherwise it will look for `nix/nix.conf` files in `XDG_CONFIG_DIRS` Otherwise it will look for `nix/nix.conf` files in `XDG_CONFIG_DIRS`
and `XDG_CONFIG_HOME`. If these are unset, it will look in and `XDG_CONFIG_HOME`. If these are unset, it will look in
`$HOME/.config/nix.conf`. `$HOME/.config/nix.conf`.

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

@ -1,44 +1,18 @@
nix-build Title: nix-build
1 # Name
Nix `nix-build` - build a Nix expression
nix-build # Synopsis
build a Nix expression `nix-build` [*paths…*]
[`--arg` *name* *value*]
nix-build [`--argstr` *name* *value*]
[{`--attr` | `-A`} *attrPath*]
\--arg [`--no-out-link`]
[`--dry-run`]
name [{`--out-link` | `-o`} *outlink*]
value
\--argstr
name
value
\--attr
\-A
attrPath
\--no-out-link
\--dry-run
\--out-link
\-o
outlink
paths
# Description # Description
@ -63,7 +37,7 @@ expression to a low-level store derivation) and [`nix-store
--realise`](#rsec-nix-store-realise) (to build the store derivation). --realise`](#rsec-nix-store-realise) (to build the store derivation).
> **Warning** > **Warning**
> >
> The result of the build is automatically registered as a root of the > The result of the build is automatically registered as a root of the
> Nix garbage collector. This root disappears automatically when the > Nix garbage collector. This root disappears automatically when the
> `result` symlink is deleted or renamed. So don’t rename the symlink. > `result` symlink is deleted or renamed. So don’t rename the symlink.
@ -94,10 +68,10 @@ The following common options are supported:
$ nix-build '<nixpkgs>' -A firefox $ nix-build '<nixpkgs>' -A firefox
store derivation is /nix/store/qybprl8sz2lc...-firefox-1.5.0.7.drv store derivation is /nix/store/qybprl8sz2lc...-firefox-1.5.0.7.drv
/nix/store/d18hyl92g30l...-firefox-1.5.0.7 /nix/store/d18hyl92g30l...-firefox-1.5.0.7
$ ls -l result $ ls -l result
lrwxrwxrwx ... result -> /nix/store/d18hyl92g30l...-firefox-1.5.0.7 lrwxrwxrwx ... result -> /nix/store/d18hyl92g30l...-firefox-1.5.0.7
$ ls ./result/bin/ $ ls ./result/bin/
firefox firefox-config firefox firefox-config

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

@ -1,34 +1,12 @@
nix-channel Title: nix-channel
1 # Name
Nix `nix-channel` - manage Nix channels
nix-channel # Synopsis
manage Nix channels `nix-channel` {`--add` url [*name*] | `--remove` *name* | `--list` | `--update` [*names…*] | `--rollback` [*generation*] }
nix-channel
\--add
url
name
\--remove
name
\--list
\--update
names
\--rollback
generation
# Description # Description
@ -82,10 +60,10 @@ You can revert channel updates using `--rollback`:
$ nix-instantiate --eval -E '(import <nixpkgs> {}).lib.version' $ nix-instantiate --eval -E '(import <nixpkgs> {}).lib.version'
"14.04.527.0e935f1" "14.04.527.0e935f1"
$ nix-channel --rollback $ nix-channel --rollback
switching from generation 483 to 482 switching from generation 483 to 482
$ nix-instantiate --eval -E '(import <nixpkgs> {}).lib.version' $ nix-instantiate --eval -E '(import <nixpkgs> {}).lib.version'
"14.04.526.dbadfad" "14.04.526.dbadfad"

26
doc/manual/src/command-ref/nix-collect-garbage.md
View file

@ -1,28 +1,12 @@
nix-collect-garbage Title: nix-collect-garbage
1 # Name
Nix `nix-collect-garbage` - delete unreachable store paths
nix-collect-garbage # Synopsis
delete unreachable store paths `nix-collect-garbage` [`--delete-old`] [`-d`] [`--delete-older-than` *period*] [`--max-freed` *bytes*] [`--dry-run`]
nix-collect-garbage
\--delete-old
\-d
\--delete-older-than
period
\--max-freed
bytes
\--dry-run
# Description # Description

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

@ -6,7 +6,13 @@ Title: nix-copy-closure
# Synopsis # Synopsis
`nix-copy-closure` [`--to` | `--from`] [`--gzip`] [`--include-outputs`] [`--use-substitutes` | `-s`] [`-v`] _user@machine_ _paths_ `nix-copy-closure`
[`--to` | `--from`]
[`--gzip`]
[`--include-outputs`]
[`--use-substitutes` | `-s`]
[`-v`]
_user@machine_ _paths_
# Description # Description
@ -75,4 +81,3 @@ environment:
$ nix-copy-closure --from alice@itchy.labs \ $ nix-copy-closure --from alice@itchy.labs \
/nix/store/0dj0503hjxy5mbwlafv1rsbdiyx1gkdy-subversion-1.4.4 /nix/store/0dj0503hjxy5mbwlafv1rsbdiyx1gkdy-subversion-1.4.4
$ nix-env -i /nix/store/0dj0503hjxy5mbwlafv1rsbdiyx1gkdy-subversion-1.4.4 $ nix-env -i /nix/store/0dj0503hjxy5mbwlafv1rsbdiyx1gkdy-subversion-1.4.4

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

@ -1,14 +1,12 @@
nix-daemon Title: nix-daemon
8 # Name
Nix `nix-daemon` - Nix multi-user support daemon
nix-daemon # Synopsis
Nix multi-user support daemon `nix-daemon`
nix-daemon
# Description # Description

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

@ -1,50 +1,20 @@
nix-env Title: nix-env
1 # Name
Nix `nix-env` - manipulate or query Nix user environments
nix-env # Synopsis
manipulate or query Nix user environments `nix-env`
[`--option` *name* *value*]
nix-env [`--arg` *name* *value*]
[`--argstr` *name* *value*]
\--arg [{`--file` | `-f`} *path*]
[{`--profile` | `-p`} *path(]
name [`--system-filter` *system*]
[`--dry-run`]
value *operation* [*options…*] [*arguments…*]
\--argstr
name
value
\--file
\-f
path
\--profile
\-p
path
\--system-filter
system
\--dry-run
operation
options
arguments
# Description # Description
@ -103,7 +73,7 @@ have an effect. See also [???](#sec-common-options).
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
@ -120,7 +90,7 @@ have an effect. See also [???](#sec-common-options).
`--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](#gloss-substitute) (i.e., downloaded) and which paths [substituted](#gloss-substitute) (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).
@ -135,38 +105,38 @@ have an effect. See also [???](#sec-common-options).
# Files # Files
- `~/.nix-defexpr` - `~/.nix-defexpr`
The source for the default Nix expressions used by the `--install`, The source for the default Nix expressions used by the
`--upgrade`, and `--query `--install`, `--upgrade`, and `--query --available` operations to
--available` operations to obtain derivations. The `--file` option obtain derivations. The `--file` option may be used to override
may be used to override this default. this default.
If `~/.nix-defexpr` is a file, it is loaded as a Nix expression. If If `~/.nix-defexpr` is a file, it is loaded as a Nix expression. If
the expression is a set, it is used as the default Nix expression. the expression is a set, it is used as the default Nix expression.
If the expression is a function, an empty set is passed as argument If the expression is a function, an empty set is passed as argument
and the return value is used as the default Nix expression. and the return value is used as the default Nix expression.
If `~/.nix-defexpr` is a directory containing a `default.nix` file, If `~/.nix-defexpr` is a directory containing a `default.nix` file,
that file is loaded as in the above paragraph. that file is loaded as in the above paragraph.
If `~/.nix-defexpr` is a directory without a `default.nix` file, If `~/.nix-defexpr` is a directory without a `default.nix` file,
then its contents (both files and subdirectories) are loaded as Nix then its contents (both files and subdirectories) are loaded as Nix
expressions. The expressions are combined into a single set, each expressions. The expressions are combined into a single set, each
expression under an attribute with the same name as the original expression under an attribute with the same name as the original
file or subdirectory. file or subdirectory.
For example, if `~/.nix-defexpr` contains two files, `foo.nix` and For example, if `~/.nix-defexpr` contains two files, `foo.nix` and
`bar.nix`, then the default Nix expression will essentially be `bar.nix`, then the default Nix expression will essentially be
{ {
foo = import ~/.nix-defexpr/foo.nix; foo = import ~/.nix-defexpr/foo.nix;
bar = import ~/.nix-defexpr/bar.nix; bar = import ~/.nix-defexpr/bar.nix;
} }
The file `manifest.nix` is always ignored. Subdirectories without a The file `manifest.nix` is always ignored. Subdirectories without a
`default.nix` file are traversed recursively in search of more Nix `default.nix` file are traversed recursively in search of more Nix
expressions, but the names of these intermediate directories are not expressions, but the names of these intermediate directories are not
added to the attribute paths of the default Nix expression. added to the attribute paths of the default Nix expression.
The command `nix-channel` places symlinks to the downloaded Nix The command `nix-channel` places symlinks to the downloaded Nix
expressions from each subscribed channel in this directory. expressions from each subscribed channel in this directory.
@ -180,21 +150,13 @@ have an effect. See also [???](#sec-common-options).
## Synopsis ## Synopsis
nix-env `nix-env` {`--install` | `-i`} *args…*
[{`--prebuilt-only` | `-b`}]
\--install [{`--attr` | `-A`}]
[`--from-expression`] [`-E`]
\-i [`--from-profile` *path*]
[`--preserve-installed` | `-P`]
\--preserve-installed [`--remove-all` | `-r`]
\-P
\--remove-all
\-r
args
## Description ## Description
@ -208,17 +170,17 @@ a number of possible ways:
output paths are installed. Currently installed derivations with a output paths are installed. Currently installed derivations with a
name equal to the name of a derivation being added are removed name equal to the name of a derivation being added are removed
unless the option `--preserve-installed` is specified. unless the option `--preserve-installed` is specified.
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 `0`. priority. The default priority is `0`.
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 -i name by being specific about the versions. For instance, `nix-env -i
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
@ -339,21 +301,13 @@ channel:
## Synopsis ## Synopsis
nix-env `nix-env` {`--upgrade` | `-u`} *args*
[`--lt` | `--leq` | `--eq` | `--always`]
\--upgrade [{`--prebuilt-only` | `-b`}]
[{`--attr` | `-A`}]
\-u [`--from-expression`] [`-E`]
[`--from-profile` *path*]
\--lt [`--preserve-installed` | `-P`]
\--leq
\--eq
\--always
args
## Description ## Description
@ -400,13 +354,13 @@ For the other flags, see `--install`.
$ nix-env --upgrade gcc $ nix-env --upgrade gcc
upgrading `gcc-3.3.1' to `gcc-3.4' upgrading `gcc-3.3.1' to `gcc-3.4'
$ nix-env -u gcc-3.3.2 --always (switch to a specific version) $ nix-env -u gcc-3.3.2 --always (switch to a specific version)
upgrading `gcc-3.4' to `gcc-3.3.2' upgrading `gcc-3.4' to `gcc-3.3.2'
$ nix-env --upgrade pan $ nix-env --upgrade pan
(no upgrades available, so nothing happens) (no upgrades available, so nothing happens)
$ nix-env -u (try to upgrade everything) $ nix-env -u (try to upgrade everything)
upgrading `hello-2.1.2' to `hello-2.1.3' upgrading `hello-2.1.2' to `hello-2.1.3'
upgrading `mozilla-1.2' to `mozilla-1.4' upgrading `mozilla-1.2' to `mozilla-1.4'
@ -451,19 +405,13 @@ This is illustrated by the following examples:
## Synopsis ## Synopsis
nix-env `nix-env` {`--uninstall` | `-e`} *drvnames…*
\--uninstall
\-e
drvnames
## Description ## Description
The uninstall operation creates a new user environment, based on the The uninstall operation creates a new user environment, based on the
current generation of the active profile, from which the store paths current generation of the active profile, from which the store paths
designated by the symbolic names *names* are removed. designated by the symbolic names *drvnames* are removed.
## Examples ## Examples
@ -474,11 +422,7 @@ designated by the symbolic names *names* are removed.
## Synopsis ## Synopsis
nix-env `nix-env` `--set` *drvname*
\--set
drvname
## Description ## Description
@ -496,15 +440,7 @@ contain just Firefox:
## Synopsis ## Synopsis
nix-env `nix-env` `--set-flag` *name* *value* *drvnames*
\--set-flag
name
value
drvnames
## Description ## Description
@ -545,20 +481,20 @@ while the old remains part of the profile:
$ nix-env -q $ nix-env -q
firefox-2.0.0.9 (the current one) firefox-2.0.0.9 (the current one)
$ nix-env --preserve-installed -i firefox-2.0.0.11 $ nix-env --preserve-installed -i firefox-2.0.0.11
installing `firefox-2.0.0.11' installing `firefox-2.0.0.11'
building path(s) `/nix/store/myy0y59q3ig70dgq37jqwg1j0rsapzsl-user-environment' building path(s) `/nix/store/myy0y59q3ig70dgq37jqwg1j0rsapzsl-user-environment'
collision between `/nix/store/...-firefox-2.0.0.11/bin/firefox' collision between `/nix/store/...-firefox-2.0.0.11/bin/firefox'
and `/nix/store/...-firefox-2.0.0.9/bin/firefox'. and `/nix/store/...-firefox-2.0.0.9/bin/firefox'.
(i.e., can’t have two active at the same time) (i.e., can’t have two active at the same time)
$ nix-env --set-flag active false firefox $ nix-env --set-flag active false firefox
setting flag on `firefox-2.0.0.9' setting flag on `firefox-2.0.0.9'
$ nix-env --preserve-installed -i firefox-2.0.0.11 $ nix-env --preserve-installed -i firefox-2.0.0.11
installing `firefox-2.0.0.11' installing `firefox-2.0.0.11'
$ nix-env -q $ nix-env -q
firefox-2.0.0.11 (the enabled one) firefox-2.0.0.11 (the enabled one)
firefox-2.0.0.9 (the disabled one) firefox-2.0.0.9 (the disabled one)
@ -572,57 +508,21 @@ To make files from `binutils` take precedence over files from `gcc`:
## Synopsis ## Synopsis
nix-env `nix-env` {`--query` | `-q`} *names…*
[`--installed` | `--available` | `-a`]
\--query [{`--status` | `-s`}]
[{`--attr-path` | `-P`}]
\-q [`--no-name`]
[{`--compare-versions` | `-c`}]
\--installed [`--system`]
[`--drv-path`]
\--available [`--out-path`]
[`--description`]
\-a [`--meta`]
[`--xml`]
\--status [`--json`]
[{`--prebuilt-only` | `-b`}]
\-s [{`--attr` | `-A`} *attribute-path*]
\--attr-path
\-P
\--no-name
\--compare-versions
\-c
\--system
\--drv-path
\--out-path
\--description
\--meta
\--xml
\--json
\--prebuilt-only
\-b
\--attr
\-A
attribute-path
names
## Description ## Description
@ -696,17 +596,17 @@ derivation is shown unless `--no-name` is specified.
`--available` is given). This is useful for quickly seeing whether `--available` is given). This is useful for quickly seeing whether
upgrades for installed packages are available in a Nix expression. A upgrades for installed packages are available in a Nix expression. A
column is added with the following meaning: column is added with the following meaning:
- `<` *version* - `<` *version*
A newer version of the package is available or installed. A newer version of the package is available or installed.
- `=` *version* - `=` *version*
At most the same version of the package is available or At most the same version of the package is available or
installed. installed.
- `>` *version* - `>` *version*
Only older versions of the package are available or installed. Only older versions of the package are available or installed.
- `- ?` - `- ?`
No version of the package is available or installed. No version of the package is available or installed.
@ -797,13 +697,7 @@ To show all packages in the latest revision of the Nixpkgs repository:
## Synopsis ## Synopsis
nix-env `nix-env` {`--switch-profile` | `-S`} *path*
\--switch-profile
\-S
path
## Description ## Description
@ -818,9 +712,7 @@ the symlink `~/.nix-profile` is made to point to *path*.
## Synopsis ## Synopsis
nix-env `nix-env` `--list-generations`
\--list-generations
## Description ## Description
@ -841,11 +733,7 @@ generation, and indicates the current generation.
## Synopsis ## Synopsis
nix-env `nix-env` `--delete-generations` *generations*
\--delete-generations
generations
## Description ## Description
@ -862,24 +750,18 @@ generations is important to make garbage collection effective.
## Examples ## Examples
$ nix-env --delete-generations 3 4 8 $ nix-env --delete-generations 3 4 8
$ nix-env --delete-generations +5 $ nix-env --delete-generations +5
$ nix-env --delete-generations 30d $ nix-env --delete-generations 30d
$ nix-env -p other_profile --delete-generations old $ nix-env -p other_profile --delete-generations old
# Operation `--switch-generation` # Operation `--switch-generation`
## Synopsis ## Synopsis
nix-env `nix-env` {`--switch-generation` | `-G`} *generation*
\--switch-generation
\-G
generation
## Description ## Description
@ -900,9 +782,7 @@ Switching will fail if the specified generation does not exist.
## Synopsis ## Synopsis
nix-env `nix-env` `--rollback`
\--rollback
## Description ## Description
@ -915,7 +795,7 @@ generation, if it exists. It is just a convenience wrapper around
$ nix-env --rollback $ nix-env --rollback
switching from generation 92 to 91 switching from generation 92 to 91
$ nix-env --rollback $ nix-env --rollback
error: no generation older than the current (91) exists error: no generation older than the current (91) exists

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

@ -1,38 +1,16 @@
nix-hash Title: nix-hash
1 # Name
Nix `nix-hash` - compute the cryptographic hash of a path
nix-hash # Synopsis
compute the cryptographic hash of a path `nix-hash` [`--flat`] [`--base32`] [`--truncate`] [`--type` *hashAlgo*] *path…*
nix-hash `nix-hash` `--to-base16` *hash…*
\--flat `nix-hash` `--to-base32` *hash…*
\--base32
\--truncate
\--type
hashAlgo
path
nix-hash
\--to-base16
hash
nix-hash
\--to-base32
hash
# Description # Description
@ -92,22 +70,22 @@ Computing hashes:
$ mkdir test $ mkdir test
$ echo "hello" > test/world $ echo "hello" > test/world
$ nix-hash test/ (MD5 hash; default) $ nix-hash test/ (MD5 hash; default)
8179d3caeff1869b5ba1744e5a245c04 8179d3caeff1869b5ba1744e5a245c04
$ nix-store --dump test/ | md5sum (for comparison) $ nix-store --dump test/ | md5sum (for comparison)
8179d3caeff1869b5ba1744e5a245c04 - 8179d3caeff1869b5ba1744e5a245c04 -
$ nix-hash --type sha1 test/ $ nix-hash --type sha1 test/
e4fd8ba5f7bbeaea5ace89fe10255536cd60dab6 e4fd8ba5f7bbeaea5ace89fe10255536cd60dab6
$ nix-hash --type sha1 --base32 test/ $ nix-hash --type sha1 --base32 test/
nvd61k9nalji1zl9rrdfmsmvyyjqpzg4 nvd61k9nalji1zl9rrdfmsmvyyjqpzg4
$ nix-hash --type sha256 --flat test/ $ nix-hash --type sha256 --flat test/
error: reading file `test/': Is a directory error: reading file `test/': Is a directory
$ nix-hash --type sha256 --flat test/world $ nix-hash --type sha256 --flat test/world
5891b5b522d5df086d0ff0b110fbd9d21bb4fc7163af34d08286a2e846f6be03 5891b5b522d5df086d0ff0b110fbd9d21bb4fc7163af34d08286a2e846f6be03
@ -115,6 +93,6 @@ Converting between hexadecimal and base-32:
$ nix-hash --type sha1 --to-base32 e4fd8ba5f7bbeaea5ace89fe10255536cd60dab6 $ nix-hash --type sha1 --to-base32 e4fd8ba5f7bbeaea5ace89fe10255536cd60dab6
nvd61k9nalji1zl9rrdfmsmvyyjqpzg4 nvd61k9nalji1zl9rrdfmsmvyyjqpzg4
$ nix-hash --type sha1 --to-base16 nvd61k9nalji1zl9rrdfmsmvyyjqpzg4 $ nix-hash --type sha1 --to-base16 nvd61k9nalji1zl9rrdfmsmvyyjqpzg4
e4fd8ba5f7bbeaea5ace89fe10255536cd60dab6 e4fd8ba5f7bbeaea5ace89fe10255536cd60dab6

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

@ -1,56 +1,22 @@
nix-instantiate Title: nix-instantiate
1 # Name
Nix `nix-instantiate` - instantiate store derivations from Nix expressions
nix-instantiate # Synopsis
instantiate store derivations from Nix expressions `nix-instantiate`
[`--parse` | `--eval` [`--strict`] [`--json`] [`--xml`] ]
[`--read-write-mode`]
[`--arg` *name* *value*]
[{`--attr`| `-A`} *attrPath*]
[`--add-root` *path*]
[`--indirect`]
[`--expr` | `-E`]
*files…*
nix-instantiate `nix-instantiate` `--find-file` *files…*
\--parse
\--eval
\--strict
\--json
\--xml
\--read-write-mode
\--arg
name
value
\--attr
\-A
attrPath
\--add-root
path
\--indirect
\--expr
\-E
files
nix-instantiate
\--find-file
files
# Description # Description
@ -91,9 +57,9 @@ See also [???](#sec-common-options) for a list of common options.
When used with `--eval`, recursively evaluate list elements and When used with `--eval`, recursively evaluate list elements and
attributes. Normally, such sub-expressions are left unevaluated attributes. Normally, such sub-expressions are left unevaluated
(since the Nix expression language is lazy). (since the Nix expression language is lazy).
> **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.
@ -123,11 +89,11 @@ using `nix-store`:
$ nix-instantiate test.nix (instantiate) $ nix-instantiate test.nix (instantiate)
/nix/store/cigxbmvy6dzix98dxxh9b6shg7ar5bvs-perl-BerkeleyDB-0.26.drv /nix/store/cigxbmvy6dzix98dxxh9b6shg7ar5bvs-perl-BerkeleyDB-0.26.drv
$ nix-store -r $(nix-instantiate test.nix) (build) $ nix-store -r $(nix-instantiate test.nix) (build)
... ...
/nix/store/qhqk4n8ci095g3sdp93x7rgwyh9rdvgk-perl-BerkeleyDB-0.26 (output path) /nix/store/qhqk4n8ci095g3sdp93x7rgwyh9rdvgk-perl-BerkeleyDB-0.26 (output path)
$ ls -l /nix/store/qhqk4n8ci095g3sdp93x7rgwyh9rdvgk-perl-BerkeleyDB-0.26 $ ls -l /nix/store/qhqk4n8ci095g3sdp93x7rgwyh9rdvgk-perl-BerkeleyDB-0.26
dr-xr-xr-x 2 eelco users 4096 1970-01-01 01:00 lib dr-xr-xr-x 2 eelco users 4096 1970-01-01 01:00 lib
... ...
@ -145,10 +111,10 @@ Parsing and evaluating Nix expressions:
$ nix-instantiate --parse -E '1 + 2' $ nix-instantiate --parse -E '1 + 2'
1 + 2 1 + 2
$ nix-instantiate --eval -E '1 + 2' $ nix-instantiate --eval -E '1 + 2'
3 3
$ nix-instantiate --eval --xml -E '1 + 2' $ nix-instantiate --eval --xml -E '1 + 2'
<?xml version='1.0' encoding='utf-8'?> <?xml version='1.0' encoding='utf-8'?>
<expr> <expr>
@ -179,5 +145,3 @@ attempt to show non-normal forms).
<string value="foo" /> <string value="foo" />
</attr> </attr>
... ...
# Environment variables

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

@ -1,32 +1,16 @@
nix-prefetch-url Title: nix-prefetch-url
1 # Name
Nix `nix-prefetch-url` - copy a file from a URL into the store and print its hash
nix-prefetch-url # Synopsis
copy a file from a URL into the store and print its hash `nix-prefetch-url` *url* [*hash*]
[`--type` *hashAlgo*]
nix-prefetch-url [`--print-path`]
[`--unpack`]
\--version [`--name` *name*]
\--type
hashAlgo
\--print-path
\--unpack
\--name
name
url
hash
# Description # Description
@ -77,11 +61,11 @@ Nix store is also printed.
$ nix-prefetch-url ftp://ftp.gnu.org/pub/gnu/hello/hello-2.10.tar.gz $ nix-prefetch-url ftp://ftp.gnu.org/pub/gnu/hello/hello-2.10.tar.gz
0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i 0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i
$ nix-prefetch-url --print-path mirror://gnu/hello/hello-2.10.tar.gz $ nix-prefetch-url --print-path mirror://gnu/hello/hello-2.10.tar.gz
0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i 0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i
/nix/store/3x7dwzq014bblazs7kq20p9hyzz0qh8g-hello-2.10.tar.gz /nix/store/3x7dwzq014bblazs7kq20p9hyzz0qh8g-hello-2.10.tar.gz
$ nix-prefetch-url --unpack --print-path https://github.com/NixOS/patchelf/archive/0.8.tar.gz $ nix-prefetch-url --unpack --print-path https://github.com/NixOS/patchelf/archive/0.8.tar.gz
079agjlv0hrv7fxnx9ngipx14gyncbkllxrp9cccnh3a50fxcmy7 079agjlv0hrv7fxnx9ngipx14gyncbkllxrp9cccnh3a50fxcmy7
/nix/store/19zrmhm3m40xxaw81c8cqm6aljgrnwj2-0.8.tar.gz /nix/store/19zrmhm3m40xxaw81c8cqm6aljgrnwj2-0.8.tar.gz

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

@ -1,60 +1,21 @@
nix-shell Title: nix-shell
1 # Name
Nix `nix-shell` - start an interactive shell based on a Nix expression
nix-shell # Synopsis
start an interactive shell based on a Nix expression `nix-shell`
[`--arg` *name* *value*]
nix-shell [`--argstr` *name* *value*]
[{`--attr` | `-A`} *attrPath*]
\--arg [`--command` *cmd*]
[`--run` *cmd*]
name [`--exclude` *regexp*]
[--pure]
value [--keep *name*]
{{`--packages` | `-p`} {*packages* | *expressions*} … | [*path*]}
\--argstr
name
value
\--attr
\-A
attrPath
\--command
cmd
\--run
cmd
\--exclude
regexp
\--pure
\--keep
name
\--packages
\-p
packages
expressions
path
# Description # Description
@ -96,11 +57,10 @@ All options not listed here are passed to `nix-store
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; e.g. running the command. To prevent this, add `return` at the end;
`--command e.g. `--command "echo Hello; return"` will print `Hello` and then
"echo Hello; return"` will print `Hello` and then drop you into the drop you into the interactive shell. This can be useful for doing
interactive shell. This can be useful for doing any additional any additional initialisation.
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
@ -129,8 +89,7 @@ All options not listed here are passed to `nix-store
- `-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 applicable in `#!`-scripts (described below).
[below](#ssec-nix-shell-shebang)).
- `--keep` *name* - `--keep` *name*
When a `--pure` shell is started, keep the listed environment When a `--pure` shell is started, keep the listed environment
@ -186,7 +145,7 @@ gives you a shell containing the Pan package from a specific revision of
Nixpkgs: Nixpkgs:
$ nix-shell -p pan -I nixpkgs=https://github.com/NixOS/nixpkgs/archive/8a3eea054838b55aca962c3fbde9c83c102b8bf2.tar.gz $ nix-shell -p pan -I nixpkgs=https://github.com/NixOS/nixpkgs/archive/8a3eea054838b55aca962c3fbde9c83c102b8bf2.tar.gz
[nix-shell:~]$ pan --version [nix-shell:~]$ pan --version
Pan 0.139 Pan 0.139
@ -213,9 +172,9 @@ For example, here is a Python script that depends on Python and the
#! /usr/bin/env nix-shell #! /usr/bin/env nix-shell
#! nix-shell -i python -p python pythonPackages.prettytable #! nix-shell -i python -p python pythonPackages.prettytable
import prettytable import prettytable
# Print a simple table. # Print a simple table.
t = prettytable.PrettyTable(["N", "N^2"]) t = prettytable.PrettyTable(["N", "N^2"])
for n in range(1, 10): t.add_row([n, n * n]) for n in range(1, 10): t.add_row([n, n * n])
@ -226,12 +185,12 @@ requires Perl and the `HTML::TokeParser::Simple` and `LWP` packages:
#! /usr/bin/env nix-shell #! /usr/bin/env nix-shell
#! nix-shell -i perl -p perl perlPackages.HTMLTokeParserSimple perlPackages.LWP #! nix-shell -i perl -p perl perlPackages.HTMLTokeParserSimple perlPackages.LWP
use HTML::TokeParser::Simple; use HTML::TokeParser::Simple;
# Fetch nixos.org and print all hrefs. # Fetch nixos.org and print all hrefs.
my $p = HTML::TokeParser::Simple->new(url => 'http://nixos.org/'); my $p = HTML::TokeParser::Simple->new(url => 'http://nixos.org/');
while (my $token = $p->get_tag("a")) { while (my $token = $p->get_tag("a")) {
my $href = $token->get_attr("href"); my $href = $token->get_attr("href");
print "$href\n" if $href; print "$href\n" if $href;
@ -242,11 +201,11 @@ package like Terraform:
#! /usr/bin/env nix-shell #! /usr/bin/env nix-shell
#! nix-shell -i bash -p "terraform.withPlugins (plugins: [ plugins.openstack ])" #! nix-shell -i bash -p "terraform.withPlugins (plugins: [ plugins.openstack ])"
terraform apply terraform apply
> **Note** > **Note**
> >
> You must use double quotes (`"`) when passing a simple Nix expression > You must use double quotes (`"`) when passing a simple Nix expression
> in a nix-shell shebang. > in a nix-shell shebang.
@ -257,10 +216,10 @@ branch):
#! /usr/bin/env nix-shell #! /usr/bin/env nix-shell
#! nix-shell -i runghc -p "haskellPackages.ghcWithPackages (ps: [ps.HTTP ps.tagsoup])" #! nix-shell -i runghc -p "haskellPackages.ghcWithPackages (ps: [ps.HTTP ps.tagsoup])"
#! nix-shell -I nixpkgs=https://github.com/NixOS/nixpkgs/archive/nixos-18.03.tar.gz #! nix-shell -I nixpkgs=https://github.com/NixOS/nixpkgs/archive/nixos-18.03.tar.gz
import Network.HTTP import Network.HTTP
import Text.HTML.TagSoup import Text.HTML.TagSoup
-- Fetch nixos.org and print all hrefs. -- Fetch nixos.org and print all hrefs.
main = do main = do
resp <- Network.HTTP.simpleHTTP (getRequest "http://nixos.org/") resp <- Network.HTTP.simpleHTTP (getRequest "http://nixos.org/")
@ -285,7 +244,5 @@ where the file `deps.nix` in the same directory as the `#!`-script
contains: contains:
with import <nixpkgs> {}; with import <nixpkgs> {};
runCommand "dummy" { buildInputs = [ python pythonPackages.prettytable ]; } ""
# Environment variables runCommand "dummy" { buildInputs = [ python pythonPackages.prettytable ]; } ""

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

@ -1,26 +1,15 @@
nix-store Title: nix-store
1 # Name
Nix `nix-store` - manipulate or query the Nix store
nix-store # Synopsis
manipulate or query the Nix store `nix-store` *operation* [*options…*] [*arguments…*]
[`--option` *name* *value*]
nix-store [`--add-root` *path*]
[`--indirect`]
\--add-root
path
\--indirect
operation
options
arguments
# Description # Description
@ -44,7 +33,7 @@ options.
which must be inside a directory that is scanned for roots by the which must be inside a directory that is scanned for roots by the
garbage collector (i.e., typically in a subdirectory of garbage collector (i.e., typically in a subdirectory of
`/nix/var/nix/gcroots/`) *unless* the `--indirect` flag is used. `/nix/var/nix/gcroots/`) *unless* the `--indirect` flag is used.
If there are multiple results, then multiple symlinks will be If there are multiple results, then multiple symlinks will be
created by sequentially numbering symlinks beyond the first one created by sequentially numbering symlinks beyond the first one
(e.g., `foo`, `foo-2`, `foo-3`, and so on). (e.g., `foo`, `foo-2`, `foo-3`, and so on).
@ -55,24 +44,24 @@ options.
commands such as `nix-build` that place a symlink to the build commands such as `nix-build` that place a symlink to the build
result in the current directory; such a build result should not be result in the current directory; such a build result should not be
garbage-collected unless the symlink is removed. garbage-collected unless the symlink is removed.
The `--indirect` flag causes a uniquely named symlink to *path* to The `--indirect` flag causes a uniquely named symlink to *path* to
be stored in `/nix/var/nix/gcroots/auto/`. For instance, be stored in `/nix/var/nix/gcroots/auto/`. For instance,
$ nix-store --add-root /home/eelco/bla/result --indirect -r ... $ nix-store --add-root /home/eelco/bla/result --indirect -r ...
$ ls -l /nix/var/nix/gcroots/auto $ ls -l /nix/var/nix/gcroots/auto
lrwxrwxrwx 1 ... 2005-03-13 21:10 dn54lcypm8f8... -> /home/eelco/bla/result lrwxrwxrwx 1 ... 2005-03-13 21:10 dn54lcypm8f8... -> /home/eelco/bla/result
$ ls -l /home/eelco/bla/result $ ls -l /home/eelco/bla/result
lrwxrwxrwx 1 ... 2005-03-13 21:10 /home/eelco/bla/result -> /nix/store/1r11343n6qd4...-f-spot-0.0.10 lrwxrwxrwx 1 ... 2005-03-13 21:10 /home/eelco/bla/result -> /nix/store/1r11343n6qd4...-f-spot-0.0.10
Thus, when `/home/eelco/bla/result` is removed, the GC root in the Thus, when `/home/eelco/bla/result` is removed, the GC root in the
`auto` directory becomes a dangling symlink and will be ignored by `auto` directory becomes a dangling symlink and will be ignored by
the collector. the collector.
> **Warning** > **Warning**
> >
> Note that it is not possible to move or rename indirect GC roots, > Note that it is not possible to move or rename indirect GC roots,
> since the symlink in the `auto` directory will still point to the > since the symlink in the `auto` directory will still point to the
> old location. > old location.
@ -83,15 +72,7 @@ options.
## Synopsis ## Synopsis
nix-store `nix-store` {`--realise` | `-r`} *paths…* [`--dry-run`]
\--realise
\-r
paths
\--dry-run
## Description ## Description
@ -136,7 +117,7 @@ The following flags are available:
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.`
See also the `build-repeat` configuration option, which repeats a See also the `build-repeat` configuration option, which repeats a
derivation a number of times and prevents its outputs from being derivation a number of times and prevents its outputs from being
registered as “valid” in the Nix store unless they are identical. registered as “valid” in the Nix store unless they are identical.
@ -188,11 +169,7 @@ To test whether a previously-built derivation is deterministic:
## Synopsis ## Synopsis
nix-store `nix-store` `--serve` [`--write`]
\--serve
\--write
## Description ## Description
@ -220,19 +197,7 @@ used to provide build access to a given SSH public key:
## Synopsis ## Synopsis
nix-store `nix-store` `--gc` [`--print-roots` | `--print-live` | `--print-dead`] [`--max-freed` *bytes*]
\--gc
\--print-roots
\--print-live
\--print-dead
\--max-freed
bytes
## Description ## Description
@ -294,13 +259,7 @@ To delete at least 100 MiBs of unreachable paths:
## Synopsis ## Synopsis
nix-store `nix-store` `--delete` [`--ignore-liveness`] *paths…*
\--delete
\--ignore-liveness
paths
## Description ## Description
@ -324,55 +283,13 @@ paths in the store that refer to it (i.e., depend on it).
## Synopsis ## Synopsis
nix-store `nix-store` {`--query` | `-q`}
{`--outputs` | `--requisites` | `-R` | `--references` |
\--query `--referrers` | `--referrers-closure` | `--deriver` | `-d` |
`--graph` | `--tree` | `--binding` *name* | `-b` *name* | `--hash` |
\-q `--size` | `--roots`}
[`--use-output`] [`-u`] [`--force-realise`] [`-f`]
\--outputs *paths…*
\--requisites
\-R
\--references
\--referrers
\--referrers-closure
\--deriver
\-d
\--graph
\--tree
\--binding
name
\-b
name
\--hash
\--size
\--roots
\--use-output
\-u
\--force-realise
\-f
paths
## Description ## Description
@ -403,13 +320,13 @@ symlink.
- `--requisites`; `-R` - `--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: This query has one option:
- `--include-outputs` - `--include-outputs`
Also include the output path of store derivations, and their Also include the output path of store derivations, and their
closures. 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
@ -555,11 +472,7 @@ depends on `svn`:
## Synopsis ## Synopsis
nix-store `nix-store` `--add` *paths…*
\--add
paths
## Description ## Description
@ -575,15 +488,7 @@ prints the resulting paths in the Nix store on standard output.
## Synopsis ## Synopsis
nix-store `nix-store` `--add-fixed` [`--recursive`] *algorithm* *paths…*
\--recursive
\--add-fixed
algorithm
paths
## Description ## Description
@ -608,13 +513,7 @@ This operation has the following options:
## Synopsis ## Synopsis
nix-store `nix-store` `--verify` [`--check-contents`] [`--repair`]
\--verify
\--check-contents
\--repair
## Description ## Description
@ -643,11 +542,7 @@ This operation has the following options:
## Synopsis ## Synopsis
nix-store `nix-store` `--verify-path` *paths…*
\--verify-path
paths
## Description ## Description
@ -666,11 +561,7 @@ To verify the integrity of the `svn` command and all its dependencies:
## Synopsis ## Synopsis
nix-store `nix-store` `--repair-path` *paths…*
\--repair-path
paths
## Description ## Description
@ -679,7 +570,7 @@ by redownloading them using the available substituters. If no
substitutes are available, then repair is not possible. substitutes are available, then repair is not possible.
> **Warning** > **Warning**
> >
> During repair, there is a very small time window during which the old > During repair, there is a very small time window during which the old
> path (if it exists) is moved out of the way and replaced with the new > path (if it exists) is moved out of the way and replaced with the new
> path. If repair is interrupted in between, then the system may be left > path. If repair is interrupted in between, then the system may be left
@ -692,7 +583,7 @@ substitutes are available, then repair is not possible.
path `/nix/store/dj7a81wsm1ijwwpkks3725661h3263p5-glibc-2.13' was modified! path `/nix/store/dj7a81wsm1ijwwpkks3725661h3263p5-glibc-2.13' was modified!
expected hash `2db57715ae90b7e31ff1f2ecb8c12ec1cc43da920efcbe3b22763f36a1861588', expected hash `2db57715ae90b7e31ff1f2ecb8c12ec1cc43da920efcbe3b22763f36a1861588',
got `481c5aa5483ebc97c20457bb8bca24deea56550d3985cda0027f67fe54b808e4' got `481c5aa5483ebc97c20457bb8bca24deea56550d3985cda0027f67fe54b808e4'
$ nix-store --repair-path /nix/store/dj7a81wsm1ijwwpkks3725661h3263p5-glibc-2.13 $ nix-store --repair-path /nix/store/dj7a81wsm1ijwwpkks3725661h3263p5-glibc-2.13
fetching path `/nix/store/d7a81wsm1ijwwpkks3725661h3263p5-glibc-2.13'... fetching path `/nix/store/d7a81wsm1ijwwpkks3725661h3263p5-glibc-2.13'...
… …
@ -701,11 +592,7 @@ substitutes are available, then repair is not possible.
## Synopsis ## Synopsis
nix-store `nix-store` `--dump` *path*
\--dump
path
## Description ## Description
@ -739,11 +626,7 @@ A Nix archive can be unpacked using `nix-store
## Synopsis ## Synopsis
nix-store `nix-store` `--restore` *path*
\--restore
path
## Description ## Description
@ -754,11 +637,7 @@ not already exist. The archive is read from standard input.
## Synopsis ## Synopsis
nix-store `nix-store` `--export` *paths…*
\--export
paths
## Description ## Description
@ -784,9 +663,7 @@ To import the whole closure again, run:
## Synopsis ## Synopsis
nix-store `nix-store` `--import`
\--import
## Description ## Description
@ -800,9 +677,7 @@ Nix store, the import fails.
## Synopsis ## Synopsis
nix-store `nix-store` `--optimise`
\--optimise
## Description ## Description
@ -832,13 +707,7 @@ Use `-vv` or `-vvv` to get some progress indication.
## Synopsis ## Synopsis
nix-store `nix-store` {`--read-log` | `-l`} *paths…*
\--read-log
\-l
paths
## Description ## Description
@ -866,11 +735,7 @@ substitute, then the log is unavailable.
## Synopsis ## Synopsis
nix-store `nix-store` `--dump-db` [*paths…*]
\--dump-db
paths
## Description ## Description
@ -889,9 +754,7 @@ example.
## Synopsis ## Synopsis
nix-store `nix-store` `--load-db`
\--load-db
## Description ## Description
@ -902,11 +765,7 @@ The operation `--load-db` reads a dump of the Nix database created by
## Synopsis ## Synopsis
nix-store `nix-store` `--print-env` *drvpath*
\--print-env
drvpath
## Description ## Description
@ -927,15 +786,7 @@ of the builder are placed in the variable `_args`.
## Synopsis ## Synopsis
nix-store `nix-store` `--generate-binary-cache-key` *key-name* *secret-key-file* *public-key-file*
\--generate-binary-cache-key
key-name
secret-key-file
public-key-file
## Description ## Description
@ -952,5 +803,3 @@ mandatory parameters:
2. The file name where the secret key is to be stored. 2. The file name where the secret key is to be stored.
3. The file name where the public key is to be stored. 3. The file name where the public key is to be stored.
# Environment variables