Rename doc/manual{src -> source}

This is needed to avoid this
https://github.com/mesonbuild/meson/issues/13774 when we go back to
making our subproject directory `src`.

doc/manual/source/package-management/binary-cache-substituter.md

@@ -0,0 +1,50 @@
+# Serving a Nix store via HTTP
+
+You can easily share the Nix store of a machine via HTTP. This allows
+other machines to fetch store paths from that machine to speed up
+installations. It uses the same *binary cache* mechanism that Nix
+usually uses to fetch pre-built binaries from <https://cache.nixos.org>.
+
+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:
+
+```console
+$ nix-env --install --attr nixpkgs.nix-serve
+```
+
+You can then start the server, listening for HTTP connections on
+whatever port you like:
+
+```console
+$ nix-serve -p 8080
+```
+
+To check whether it works, try the following on the client:
+
+```console
+$ curl http://avalon:8080/nix-cache-info
+```
+
+which should print something like:
+
+    StoreDir: /nix/store
+    WantMassQuery: 1
+    Priority: 30
+
+On the client side, you can tell Nix to use your binary cache using
+`--substituters`, e.g.:
+
+```console
+$ nix-env --install --attr nixpkgs.firefox --substituters http://avalon:8080/
+```
+
+The option `substituters` tells Nix to use this binary cache in
+addition to your default caches, such as <https://cache.nixos.org>.
+Thus, for any path in the closure of Firefox, Nix will first check if
+the path is available on the server `avalon` or another binary caches.
+If not, it will fall back to building from source.
+
+You can also tell Nix to always use your binary cache by adding a line
+to the `nix.conf` configuration file like this:
+
+    substituters = http://avalon:8080/ https://cache.nixos.org/

doc/manual/source/package-management/garbage-collection.md

@@ -0,0 +1,73 @@
+# Garbage Collection
+
+`nix-env` operations such as upgrades (`-u`) and uninstall (`-e`) never
+actually delete packages from the system. All they do (as shown above)
+is to create a new user environment that no longer contains symlinks to
+the “deleted” packages.
+
+Of course, since disk space is not infinite, unused packages should be
+removed at some point. You can do this by running the Nix garbage
+collector. It will remove from the Nix store any package not used
+(directly or indirectly) by any generation of any profile.
+
+Note however that as long as old generations reference a package, it
+will not be deleted. After all, we wouldn’t be able to do a rollback
+otherwise. So in order for garbage collection to be effective, you
+should also delete (some) old generations. Of course, this should only
+be done if you are certain that you will not need to roll back.
+
+To delete all old (non-current) generations of your current profile:
+
+```console
+$ nix-env --delete-generations old
+```
+
+Instead of `old` you can also specify a list of generations, e.g.,
+
+```console
+$ nix-env --delete-generations 10 11 14
+```
+
+To delete all generations older than a specified number of days (except
+the current generation), use the `d` suffix. For example,
+
+```console
+$ nix-env --delete-generations 14d
+```
+
+deletes all generations older than two weeks.
+
+After removing appropriate old generations you can run the garbage
+collector as follows:
+
+```console
+$ nix-store --gc
+```
+
+The behaviour of the garbage collector is affected by the
+`keep-derivations` (default: true) and `keep-outputs` (default: false)
+options in the Nix configuration file. The defaults will ensure that all
+derivations that are build-time dependencies of garbage collector roots
+will be kept and that all output paths that are runtime dependencies
+will be kept as well. All other derivations or paths will be collected.
+(This is usually what you want, but while you are developing it may make
+sense to keep outputs to ensure that rebuild times are quick.) If you
+are feeling uncertain, you can also first view what files would be
+deleted:
+
+```console
+$ nix-store --gc --print-dead
+```
+
+Likewise, the option `--print-live` will show the paths that *won’t* be
+deleted.
+
+There is also a convenient little utility `nix-collect-garbage`, which
+when invoked with the `-d` (`--delete-old`) switch deletes all old
+generations of all profiles in `/nix/var/nix/profiles`. So
+
+```console
+$ nix-collect-garbage -d
+```
+
+is a quick and easy way to clean up your system.

doc/manual/source/package-management/garbage-collector-roots.md

@@ -0,0 +1,18 @@
+# Garbage Collector Roots
+
+The roots of the garbage collector are all store paths to which there
+are symlinks in the directory `prefix/nix/var/nix/gcroots`. For
+instance, the following command makes the path
+`/nix/store/d718ef...-foo` a root of the collector:
+
+```console
+$ ln -s /nix/store/d718ef...-foo /nix/var/nix/gcroots/bar
+```
+
+That is, after this command, the garbage collector will not remove
+`/nix/store/d718ef...-foo` or any of its dependencies.
+
+Subdirectories of `prefix/nix/var/nix/gcroots` are also searched for
+symlinks. Symlinks to non-store paths are followed and searched for
+roots, but symlinks to non-store paths *inside* the paths reached in
+that way are not followed to prevent infinite recursion.

doc/manual/source/package-management/index.md

@@ -0,0 +1,4 @@
+This chapter discusses how to do package management with Nix, i.e.,
+how to obtain, install, upgrade, and erase packages. This is the
+“user’s” perspective of the Nix system — people who want to *create*
+packages should consult the chapter on the [Nix language](../language/index.md).

doc/manual/source/package-management/profiles.md

@@ -0,0 +1,133 @@
+# Profiles
+
+Profiles and user environments are Nix’s mechanism for implementing the
+ability to allow different users to have different configurations, and
+to do atomic upgrades and rollbacks. To understand how they work, it’s
+useful to know a bit about how Nix works. In Nix, packages are stored in
+unique locations in the *Nix store* (typically, `/nix/store`). For
+instance, a particular version of the Subversion package might be stored
+in a directory
+`/nix/store/dpmvp969yhdqs7lm2r1a3gng7pyq6vy4-subversion-1.1.3/`, while
+another version might be stored in
+`/nix/store/5mq2jcn36ldlmh93yj1n8s9c95pj7c5s-subversion-1.1.2`. The long
+strings prefixed to the directory names are cryptographic hashes (to be
+precise, 160-bit truncations of SHA-256 hashes encoded in a base-32
+notation) of *all* inputs involved in building the package — sources,
+dependencies, compiler flags, and so on. So if two packages differ in
+any way, they end up in different locations in the file system, so they
+don’t interfere with each other. Here is what a part of a typical Nix
+store looks like:
+
+![](../figures/user-environments.png)
+
+Of course, you wouldn’t want to type
+
+```console
+$ /nix/store/dpmvp969yhdq...-subversion-1.1.3/bin/svn
+```
+
+every time you want to run Subversion. Of course we could set up the
+`PATH` environment variable to include the `bin` directory of every
+package we want to use, but this is not very convenient since changing
+`PATH` doesn’t take effect for already existing processes. The solution
+Nix uses is to create directory trees of symlinks to *activated*
+packages. These are called *user environments* and they are packages
+themselves (though automatically generated by `nix-env`), so they too
+reside in the Nix store. For instance, in the figure above, the user
+environment `/nix/store/0c1p5z4kda11...-user-env` contains a symlink to
+just Subversion 1.1.2 (arrows in the figure indicate symlinks). This
+would be what we would obtain if we had done
+
+```console
+$ nix-env --install --attr nixpkgs.subversion
+```
+
+on a set of Nix expressions that contained Subversion 1.1.2.
+
+This doesn’t in itself solve the problem, of course; you wouldn’t want
+to type `/nix/store/0c1p5z4kda11...-user-env/bin/svn` either. That’s why
+there are symlinks outside of the store that point to the user
+environments in the store; for instance, the symlinks `default-42-link`
+and `default-43-link` in the example. These are called *generations*
+since every time you perform a `nix-env` operation, a new user
+environment is generated based on the current one. For instance,
+generation 43 was created from generation 42 when we did
+
+```console
+$ nix-env --install --attr nixpkgs.subversion nixpkgs.firefox
+```
+
+on a set of Nix expressions that contained Firefox and a new version of
+Subversion.
+
+Generations are grouped together into *profiles* so that different users
+don’t interfere with each other if they don’t want to. For example:
+
+```console
+$ ls -l /nix/var/nix/profiles/
+...
+lrwxrwxrwx  1 eelco ... default-42-link -> /nix/store/0c1p5z4kda11...-user-env
+lrwxrwxrwx  1 eelco ... default-43-link -> /nix/store/3aw2pdyx2jfc...-user-env
+lrwxrwxrwx  1 eelco ... default -> default-43-link
+```
+
+This shows a profile called `default`. The file `default` itself is
+actually a symlink that points to the current generation. When we do a
+`nix-env` operation, a new user environment and generation link are
+created based on the current one, and finally the `default` symlink is
+made to point at the new generation. This last step is atomic on Unix,
+which explains how we can do atomic upgrades. (Note that the
+building/installing of new packages doesn’t interfere in any way with
+old packages, since they are stored in different locations in the Nix
+store.)
+
+If you find that you want to undo a `nix-env` operation, you can just do
+
+```console
+$ nix-env --rollback
+```
+
+which will just make the current generation link point at the previous
+link. E.g., `default` would be made to point at `default-42-link`. You
+can also switch to a specific generation:
+
+```console
+$ nix-env --switch-generation 43
+```
+
+which in this example would roll forward to generation 43 again. You can
+also see all available generations:
+
+```console
+$ nix-env --list-generations
+```
+
+You generally wouldn’t have `/nix/var/nix/profiles/some-profile/bin` in
+your `PATH`. Rather, there is a symlink `~/.nix-profile` that points to
+your current profile. This means that you should put
+`~/.nix-profile/bin` in your `PATH` (and indeed, that’s what the
+initialisation script `/nix/etc/profile.d/nix.sh` does). This makes it
+easier to switch to a different profile. You can do that using the
+command `nix-env --switch-profile`:
+
+```console
+$ nix-env --switch-profile /nix/var/nix/profiles/my-profile
+
+$ nix-env --switch-profile /nix/var/nix/profiles/default
+```
+
+These commands switch to the `my-profile` and default profile,
+respectively. If the profile doesn’t exist, it will be created
+automatically. You should be careful about storing a profile in another
+location than the `profiles` directory, since otherwise it might not be
+used as a root of the [garbage collector](garbage-collection.md).
+
+All `nix-env` operations work on the profile pointed to by
+`~/.nix-profile`, but you can override this using the `--profile` option
+(abbreviation `-p`):
+
+```console
+$ nix-env --profile /nix/var/nix/profiles/other-profile --install --attr nixpkgs.subversion
+```
+
+This will *not* change the `~/.nix-profile` symlink.

doc/manual/source/package-management/sharing-packages.md

@@ -0,0 +1,6 @@
+# Sharing Packages Between Machines
+
+Sometimes you want to copy a package from one machine to another. Or,
+you want to install some packages and you know that another machine
+already has some or all of those packages or their dependencies. In that
+case there are mechanisms to quickly copy packages between machines.

doc/manual/source/package-management/ssh-substituter.md

@@ -0,0 +1,62 @@
+# Serving a Nix store via SSH
+
+You can tell Nix to automatically fetch needed binaries from a remote
+Nix store via SSH. For example, the following installs Firefox,
+automatically fetching any store paths in Firefox’s closure if they are
+available on the server `avalon`:
+
+```console
+$ nix-env --install --attr nixpkgs.firefox --substituters ssh://alice@avalon
+```
+
+This works similar to the binary cache substituter that Nix usually
+uses, only using SSH instead of HTTP: if a store path `P` is needed, Nix
+will first check if it’s available in the Nix store on `avalon`. If not,
+it will fall back to using the binary cache substituter, and then to
+building from source.
+
+> **Note**
+> 
+> The SSH substituter currently does not allow you to enter an SSH
+> passphrase interactively. Therefore, you should use `ssh-add` to load
+> the decrypted private key into `ssh-agent`.
+
+You can also copy the closure of some store path, without installing it
+into your profile, e.g.
+
+```console
+$ nix-store --realise /nix/store/m85bxg…-firefox-34.0.5 --substituters
+ssh://alice@avalon
+```
+
+This is essentially equivalent to doing
+
+```console
+$ nix-copy-closure --from alice@avalon
+/nix/store/m85bxg…-firefox-34.0.5
+```
+
+You can use SSH’s *forced command* feature to set up a restricted user
+account for SSH substituter access, allowing read-only access to the
+local Nix store, but nothing more. For example, add the following lines
+to `sshd_config` to restrict the user `nix-ssh`:
+
+    Match User nix-ssh
+      AllowAgentForwarding no
+      AllowTcpForwarding no
+      PermitTTY no
+      PermitTunnel no
+      X11Forwarding no
+      ForceCommand nix-store --serve
+    Match All
+
+On NixOS, you can accomplish the same by adding the following to your
+`configuration.nix`:
+
+```nix
+nix.sshServe.enable = true;
+nix.sshServe.keys = [ "ssh-dss AAAAB3NzaC1k... bob@example.org" ];
+```
+
+where the latter line lists the public keys of users that are allowed to
+connect.