Skip to content

Commit

Permalink
reword nix-env documentation (NixOS#10718)
Browse files Browse the repository at this point in the history
* reword `nix-env` documentation

- added links
- added an overview of package sources
- clarified parsing and matching of package names

Co-authored-by: Valentin Gagarin <[email protected]>
  • Loading branch information
wamirez and fricklerhandwerk authored May 15, 2024
1 parent bbe780b commit 50bbe22
Show file tree
Hide file tree
Showing 2 changed files with 76 additions and 33 deletions.
106 changes: 75 additions & 31 deletions doc/manual/src/command-ref/nix-env.md
Original file line number Diff line number Diff line change
Expand Up @@ -47,39 +47,83 @@ These pages can be viewed offline:

Example: `nix-env --help --install`

# Package sources

`nix-env` can obtain packages from multiple sources:

- An attribute set of derivations from:
- The [default Nix expression](@docroot@/command-ref/files/default-nix-expression.md) (by default)
- A Nix file, specified via `--file`
- A [profile](@docroot@/command-ref/files/profiles.md), specified via `--from-profile`
- A Nix expression that is a function which takes default expression as argument, specified via `--from-expression`
- A [store path](@docroot@/store/store-path.md)

# Selectors

Several commands, such as `nix-env --query ` and `nix-env --install `, take a list of
arguments that specify the packages on which to operate. These are
extended regular expressions that must match the entire name of the
package. (For details on regular expressions, see **regex**(7).) The match is
case-sensitive. The regular expression can optionally be followed by a
dash and a version number; if omitted, any version of the package will
match. Here are some examples:

- `firefox`\
Matches the package name `firefox` and any version.

- `firefox-32.0`\
Matches the package name `firefox` and version `32.0`.

- `gtk\\+`\
Matches the package name `gtk+`. The `+` character must be escaped
using a backslash to prevent it from being interpreted as a
quantifier, and the backslash must be escaped in turn with another
backslash to ensure that the shell passes it on.

- `.\*`\
Matches any package name. This is the default for most commands.

- `'.*zip.*'`\
Matches any package name containing the string `zip`. Note the dots:
`'*zip*'` does not work, because in a regular expression, the
character `*` is interpreted as a quantifier.

- `'.*(firefox|chromium).*'`\
Matches any package name containing the strings `firefox` or
`chromium`.
Several operations, such as [`nix-env --query`](./nix-env/query.md) and [`nix-env --install`](./nix-env/install.md), take a list of *arguments* that specify the packages on which to operate.

Packages are identified based on a `name` part and a `version` part of a [symbolic derivation name](@docroot@/language/derivations.md#attr-names):

- `name`: Everything up to but not including the first dash (`-`) that is *not* followed by a letter.
- `version`: The rest, excluding the separating dash.

> **Example**
>
> `nix-env` parses the symbolic derivation name `apache-httpd-2.0.48` as:
>
> ```json
> {
> "name": "apache-httpd",
> "version": "2.0.48"
> }
> ```
> **Example**
>
> `nix-env` parses the symbolic derivation name `firefox.*` as:
>
> ```json
> {
> "name": "firefox.*",
> "version": ""
> }
> ```
The `name` parts of the *arguments* to `nix-env` are treated as extended regular expressions and matched against the `name` parts of derivation names in the package source.
The match is case-sensitive.
The regular expression can optionally be followed by a dash (`-`) and a version number; if omitted, any version of the package will match.
For details on regular expressions, see [**regex**(7)](https://linux.die.net/man/7/regex).
> **Example**
>
> Common patterns for finding package names with `nix-env`:
>
> - `firefox`
>
> Matches the package name `firefox` and any version.
>
> - `firefox-32.0`
>
> Matches the package name `firefox` and version `32.0`.
>
> - `gtk\\+`
>
> Matches the package name `gtk+`.
> The `+` character must be escaped using a backslash (`\`) to prevent it from being interpreted as a quantifier, and the backslash must be escaped in turn with another backslash to ensure that the shell passes it on.
>
> - `.\*`
>
> Matches any package name.
> This is the default for most commands.
>
> - `'.*zip.*'`
>
> Matches any package name containing the string `zip`.
> Note the dots: `'*zip*'` does not work, because in a regular expression, the character `*` is interpreted as a quantifier.
>
> - `'.*(firefox|chromium).*'`
>
> Matches any package name containing the strings `firefox` or `chromium`.
# Files
Expand Down
3 changes: 1 addition & 2 deletions doc/manual/src/command-ref/nix-env/install.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,14 +14,13 @@

# Description

The install operation creates a new user environment.
The `--install` operation creates a new user environment.
It is based on the current generation of the active [profile](@docroot@/command-ref/files/profiles.md), to which a set of [store paths] described by *args* is added.

[store paths]: @docroot@/glossary.md#gloss-store-path

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].
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.
Expand Down

0 comments on commit 50bbe22

Please sign in to comment.