cafkafk/lix
cafkafk/lix
1
0
Fork 0
Code Issues Pull requests 1 Projects Releases Packages Wiki Activity Actions

doc: De-emphasize nix-env without -A

Browse source 
The manual uses `nix-env -i` without `-A` prominently, teaching a bad practice to newcomers.
This commit is contained in:
Jan Tojnar 2021-11-17 16:30:39 +01:00
parent 480c883f36
commit ca4d8ce9e2
9 changed files with 80 additions and 61 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

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

@ -238,7 +238,16 @@ a number of possible ways:
## Examples ## Examples
To install a specific version of `gcc` from the active Nix expression: To install a package using a specific attribute path from the active Nix expression:
```console
$ nix-env -iA gcc40mips
installing `gcc-4.0.2'
$ nix-env -iA xorg.xorgserver
installing `xorg-server-1.2.0'
```
To install a specific version of `gcc` using the derivation name:
```console ```console
$ nix-env --install gcc-3.3.2 $ nix-env --install gcc-3.3.2
@ -246,6 +255,9 @@ installing `gcc-3.3.2'
uninstalling `gcc-3.1' uninstalling `gcc-3.1'
``` ```
Using attribute path for selecting a package is preferred,
as it is much faster and there will not be multiple matches.
Note the previously installed version is removed, since Note the previously installed version is removed, since
`--preserve-installed` was not specified. `--preserve-installed` was not specified.
@ -256,13 +268,6 @@ $ nix-env --install gcc
installing `gcc-3.3.2' installing `gcc-3.3.2'
``` ```
To install using a specific attribute:
```console
$ nix-env -i -A gcc40mips
$ nix-env -i -A xorg.xorgserver
```
To install all derivations in the Nix expression `foo.nix`: To install all derivations in the Nix expression `foo.nix`:
```console ```console
@ -374,22 +379,29 @@ For the other flags, see `--install`.
## Examples ## Examples
```console ```console
$ nix-env --upgrade gcc $ nix-env --upgrade -A nixpkgs.gcc
upgrading `gcc-3.3.1' to `gcc-3.4' upgrading `gcc-3.3.1' to `gcc-3.4'
``` ```
When there are no updates available, nothing will happen:
```console ```console
$ nix-env -u gcc-3.3.2 --always (switch to a specific version) $ nix-env --upgrade -A nixpkgs.pan
```
Using `-A` is preferred when possible, as it is faster and unambiguous but
it is also possible to upgrade to a specific version by matching the derivation name:
```console
$ nix-env -u gcc-3.3.2 --always
upgrading `gcc-3.4' to `gcc-3.3.2' upgrading `gcc-3.4' to `gcc-3.3.2'
``` ```
```console To try to upgrade everything
$ nix-env --upgrade pan (matching packages based on the part of the derivation name without version):
(no upgrades available, so nothing happens)
```
```console ```console
$ nix-env -u (try to upgrade everything) $ nix-env -u
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'
``` ```

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

@ -162,11 +162,11 @@ Most Nix commands accept the following command-line options:
}: ... }: ...
``` ```
So if you call this Nix expression (e.g., when you do `nix-env -i So if you call this Nix expression (e.g., when you do `nix-env -iA
pkgname`), the function will be called automatically using the pkgname`), the function will be called automatically using the
value [`builtins.currentSystem`](../expressions/builtins.md) for value [`builtins.currentSystem`](../expressions/builtins.md) for
the `system` argument. You can override this using `--arg`, e.g., the `system` argument. You can override this using `--arg`, e.g.,
`nix-env -i pkgname --arg system \"i686-freebsd\"`. (Note that `nix-env -iA pkgname --arg system \"i686-freebsd\"`. (Note that
since the argument is a Nix string literal, you have to escape the since the argument is a Nix string literal, you have to escape the
quotes.) quotes.)

2
doc/manual/src/expressions/simple-building-testing.md
View file

@ -1,6 +1,6 @@
# Building and Testing # Building and Testing
You can now try to build Hello. Of course, you could do `nix-env -i You can now try to build Hello. Of course, you could do `nix-env -f . -iA
hello`, but you may not want to install a possibly broken package just hello`, but you may not want to install a possibly broken package just
yet. The best way to test the package is by using the command yet. The best way to test the package is by using the command
`nix-build`, which builds a Nix expression and creates a symlink named `nix-build`, which builds a Nix expression and creates a symlink named

4
doc/manual/src/introduction.md
View file

@ -76,7 +76,7 @@ there after an upgrade. This means that you can _roll back_ to the
old version: old version:
```console ```console
$ nix-env --upgrade some-packages $ nix-env --upgrade -A nixpkgs.some-package
$ nix-env --rollback $ nix-env --rollback
``` ```
@ -122,7 +122,7 @@ Nix expressions generally describe how to build a package from
source, so an installation action like source, so an installation action like
```console ```console
$ nix-env --install firefox $ nix-env --install -A nixpkgs.firefox
``` ```
_could_ cause quite a bit of build activity, as not only Firefox but _could_ cause quite a bit of build activity, as not only Firefox but

63
doc/manual/src/package-management/basic-package-mgmt.md
View file

@ -24,7 +24,7 @@ collection; you could write your own Nix expressions based on Nixpkgs,
or completely new ones.) or completely new ones.)
You can manually download the latest version of Nixpkgs from You can manually download the latest version of Nixpkgs from
<http://nixos.org/nixpkgs/download.html>. However, it’s much more <https://github.com/NixOS/nixpkgs>. However, it’s much more
convenient to use the Nixpkgs [*channel*](channels.md), since it makes convenient to use the Nixpkgs [*channel*](channels.md), since it makes
it easy to stay up to date with new versions of Nixpkgs. Nixpkgs is it easy to stay up to date with new versions of Nixpkgs. Nixpkgs is
automatically added to your list of “subscribed” channels when you automatically added to your list of “subscribed” channels when you
@ -47,41 +47,45 @@ $ nix-channel --update
You can view the set of available packages in Nixpkgs: You can view the set of available packages in Nixpkgs:
```console ```console
$ nix-env -qa $ nix-env -qaP
aterm-2.2 nixpkgs.aterm aterm-2.2
bash-3.0 nixpkgs.bash bash-3.0
binutils-2.15 nixpkgs.binutils binutils-2.15
bison-1.875d nixpkgs.bison bison-1.875d
blackdown-1.4.2 nixpkgs.blackdown blackdown-1.4.2
bzip2-1.0.2 nixpkgs.bzip2 bzip2-1.0.2
… …
``` ```
The flag `-q` specifies a query operation, and `-a` means that you want The flag `-q` specifies a query operation, `-a` means that you want
to show the “available” (i.e., installable) packages, as opposed to the to show the “available” (i.e., installable) packages, as opposed to the
installed packages. If you downloaded Nixpkgs yourself, or if you installed packages, and `-P` prints the attribute paths that can be used
checked it out from GitHub, then you need to pass the path to your to unambiguously select a package for installation (listed in the first column).
Nixpkgs tree using the `-f` flag: If you downloaded Nixpkgs yourself, or if you checked it out from GitHub,
then you need to pass the path to your Nixpkgs tree using the `-f` flag:
```console ```console
$ nix-env -qaf /path/to/nixpkgs $ nix-env -qaPf /path/to/nixpkgs
aterm aterm-2.2
bash bash-3.0
…
``` ```
where */path/to/nixpkgs* is where you’ve unpacked or checked out where */path/to/nixpkgs* is where you’ve unpacked or checked out
Nixpkgs. Nixpkgs.
You can select specific packages by name: You can filter the packages by name:
```console ```console
$ nix-env -qa firefox $ nix-env -qaP firefox
firefox-34.0.5 nixpkgs.firefox-esr firefox-91.3.0esr
firefox-with-plugins-34.0.5 nixpkgs.firefox firefox-94.0.1
``` ```
and using regular expressions: and using regular expressions:
```console ```console
$ nix-env -qa 'firefox.*' $ nix-env -qaP 'firefox.*'
``` ```
It is also possible to see the *status* of available packages, i.e., It is also possible to see the *status* of available packages, i.e.,
@ -89,11 +93,11 @@ whether they are installed into the user environment and/or present in
the system: the system:
```console ```console
$ nix-env -qas $ nix-env -qaPs
… …
-PS bash-3.0 -PS nixpkgs.bash bash-3.0
--S binutils-2.15 --S nixpkgs.binutils binutils-2.15
IPS bison-1.875d IPS nixpkgs.bison bison-1.875d
… …
``` ```
@ -106,13 +110,13 @@ which is Nix’s mechanism for doing binary deployment. It just means that
Nix knows that it can fetch a pre-built package from somewhere Nix knows that it can fetch a pre-built package from somewhere
(typically a network server) instead of building it locally. (typically a network server) instead of building it locally.
You can install a package using `nix-env -i`. For instance, You can install a package using `nix-env -iA`. For instance,
```console ```console
$ nix-env -i subversion $ nix-env -iA nixpkgs.subversion
``` ```
will install the package called `subversion` (which is, of course, the will install the package called `subversion` from `nixpkgs` channel (which is, of course, the
[Subversion version management system](http://subversion.tigris.org/)). [Subversion version management system](http://subversion.tigris.org/)).
> **Note** > **Note**
@ -122,7 +126,7 @@ will install the package called `subversion` (which is, of course, the
> binary cache <https://cache.nixos.org>; it contains binaries for most > binary cache <https://cache.nixos.org>; it contains binaries for most
> packages in Nixpkgs. Only if no binary is available in the binary > packages in Nixpkgs. Only if no binary is available in the binary
> cache, Nix will build the package from source. So if `nix-env > cache, Nix will build the package from source. So if `nix-env
> -i subversion` results in Nix building stuff from source, then either > -iA nixpkgs.subversion` results in Nix building stuff from source, then either
> the package is not built for your platform by the Nixpkgs build > the package is not built for your platform by the Nixpkgs build
> servers, or your version of Nixpkgs is too old or too new. For > servers, or your version of Nixpkgs is too old or too new. For
> instance, if you have a very recent checkout of Nixpkgs, then the > instance, if you have a very recent checkout of Nixpkgs, then the
@ -133,7 +137,10 @@ will install the package called `subversion` (which is, of course, the
> using a Git checkout of the Nixpkgs tree), you will get binaries for > using a Git checkout of the Nixpkgs tree), you will get binaries for
> most packages. > most packages.
Naturally, packages can also be uninstalled: Naturally, packages can also be uninstalled. Unlike when installing, you will
need to use the derivation name (though the version part can be omitted),
instead of the attribute path, as `nix-env` does not record which attribute
was used for installing:
```console ```console
$ nix-env -e subversion $ nix-env -e subversion
@ -143,7 +150,7 @@ Upgrading to a new version is just as easy. If you have a new release of
Nix Packages, you can do: Nix Packages, you can do:
```console ```console
$ nix-env -u subversion $ nix-env -uA nixpkgs.subversion
``` ```
This will *only* upgrade Subversion if there is a “newer” version in the This will *only* upgrade Subversion if there is a “newer” version in the

4
doc/manual/src/package-management/binary-cache-substituter.md
View file

@ -9,7 +9,7 @@ The daemon that handles binary cache requests via HTTP, `nix-serve`, is
not part of the Nix distribution, but you can install it from Nixpkgs: not part of the Nix distribution, but you can install it from Nixpkgs:
```console ```console
$ nix-env -i nix-serve $ nix-env -iA nixpkgs.nix-serve
``` ```
You can then start the server, listening for HTTP connections on You can then start the server, listening for HTTP connections on
@ -35,7 +35,7 @@ On the client side, you can tell Nix to use your binary cache using
`--option extra-binary-caches`, e.g.: `--option extra-binary-caches`, e.g.:
```console ```console
$ nix-env -i firefox --option extra-binary-caches http://avalon:8080/ $ nix-env -iA nixpkgs.firefox --option extra-binary-caches http://avalon:8080/
``` ```
The option `extra-binary-caches` tells Nix to use this binary cache in The option `extra-binary-caches` tells Nix to use this binary cache in

6
doc/manual/src/package-management/profiles.md
View file

@ -39,7 +39,7 @@ just Subversion 1.1.2 (arrows in the figure indicate symlinks). This
would be what we would obtain if we had done would be what we would obtain if we had done
```console ```console
$ nix-env -i subversion $ nix-env -iA nixpkgs.subversion
``` ```
on a set of Nix expressions that contained Subversion 1.1.2. on a set of Nix expressions that contained Subversion 1.1.2.
@ -54,7 +54,7 @@ environment is generated based on the current one. For instance,
generation 43 was created from generation 42 when we did generation 43 was created from generation 42 when we did
```console ```console
$ nix-env -i subversion firefox $ nix-env -iA nixpkgs.subversion nixpkgs.firefox
``` ```
on a set of Nix expressions that contained Firefox and a new version of on a set of Nix expressions that contained Firefox and a new version of
@ -127,7 +127,7 @@ All `nix-env` operations work on the profile pointed to by
(abbreviation `-p`): (abbreviation `-p`):
```console ```console
$ nix-env -p /nix/var/nix/profiles/other-profile -i subversion $ nix-env -p /nix/var/nix/profiles/other-profile -iA nixpkgs.subversion
``` ```
This will *not* change the `~/.nix-profile` symlink. This will *not* change the `~/.nix-profile` symlink.

2
doc/manual/src/package-management/ssh-substituter.md
View file

@ -6,7 +6,7 @@ automatically fetching any store paths in Firefox’s closure if they are
available on the server `avalon`: available on the server `avalon`:
```console ```console
$ nix-env -i firefox --substituters ssh://alice@avalon $ nix-env -iA nixpkgs.firefox --substituters ssh://alice@avalon
``` ```
This works similar to the binary cache substituter that Nix usually This works similar to the binary cache substituter that Nix usually

14
doc/manual/src/quick-start.md
View file

@ -19,19 +19,19 @@ to subsequent chapters.
channel: channel:
```console ```console
$ nix-env -qa $ nix-env -qaP
docbook-xml-4.3 nixpkgs.docbook_xml_dtd_43 docbook-xml-4.3
docbook-xml-4.5 nixpkgs.docbook_xml_dtd_45 docbook-xml-4.5
firefox-33.0.2 nixpkgs.firefox firefox-33.0.2
hello-2.9 nixpkgs.hello hello-2.9
libxslt-1.1.28 nixpkgs.libxslt libxslt-1.1.28
… …
``` ```
1. Install some packages from the channel: 1. Install some packages from the channel:
```console ```console
$ nix-env -i hello $ nix-env -iA nixpkgs.hello
``` ```
This should download pre-built packages; it should not build them This should download pre-built packages; it should not build them