Merge branch 'master' into debug-merge

7 files changed, 112 insertions, 205 deletions

diff --git a/doc/manual/src/installation/building-source.md b/doc/manual/src/installation/building-source.md
index d21a51a82..ed1efffd8 100644
--- a/doc/manual/src/installation/building-source.md
+++ b/doc/manual/src/installation/building-source.md
@@ -1,9 +1,9 @@
 # Building Nix from Source
 
-After unpacking or checking out the Nix sources, issue the following
-commands:
+After cloning Nix's Git repository, issue the following commands:
 
 ```console
+$ ./bootstrap.sh
 $ ./configure options...
 $ make
 $ make install
@@ -11,13 +11,6 @@ $ make install
 
 Nix requires GNU Make so you may need to invoke `gmake` instead.
 
-When building from the Git repository, these should be preceded by the
-command:
-
-```console
-$ ./bootstrap.sh
-```
-
 The installation path can be specified by passing the `--prefix=prefix`
 to `configure`. The default installation directory is `/usr/local`. You
 can change this to any location you like. You must have write permission
diff --git a/doc/manual/src/installation/env-variables.md b/doc/manual/src/installation/env-variables.md
index 4a49897e4..bb35c0e9f 100644
--- a/doc/manual/src/installation/env-variables.md
+++ b/doc/manual/src/installation/env-variables.md
@@ -40,7 +40,7 @@ export NIX_SSL_CERT_FILE=/etc/ssl/my-certificate-bundle.crt
 > **Note**
 > 
 > You must not add the export and then do the install, as the Nix
-> installer will detect the presense of Nix configuration, and abort.
+> installer will detect the presence of Nix configuration, and abort.
 
 ## `NIX_SSL_CERT_FILE` with macOS and the Nix daemon
 
diff --git a/doc/manual/src/installation/installing-binary.md b/doc/manual/src/installation/installing-binary.md
index ae7fd458b..96fa34635 100644
--- a/doc/manual/src/installation/installing-binary.md
+++ b/doc/manual/src/installation/installing-binary.md
@@ -1,18 +1,26 @@
 # Installing a Binary Distribution
 
-If you are using Linux or macOS versions up to 10.14 (Mojave), the
-easiest way to install Nix is to run the following command:
+The easiest way to install Nix is to run the following command:
 
 ```console
 $ sh <(curl -L https://nixos.org/nix/install)
 ```
 
-If you're using macOS 10.15 (Catalina) or newer, consult [the macOS
-installation instructions](#macos-installation) before installing.
+This will run the installer interactively (causing it to explain what
+it is doing more explicitly), and perform the default "type" of install
+for your platform:
+- single-user on Linux
+- multi-user on macOS
 
-As of Nix 2.1.0, the Nix installer will always default to creating a
-single-user installation, however opting in to the multi-user
-installation is highly recommended.
+  > **Notes on read-only filesystem root in macOS 10.15 Catalina +**
+  > 
+  > - It took some time to support this cleanly. You may see posts,
+  >   examples, and tutorials using obsolete workarounds.
+  > - Supporting it cleanly made macOS installs too complex to qualify
+  >   as single-user, so this type is no longer supported on macOS.
+
+We recommend the multi-user install if it supports your platform and
+you can authenticate with `sudo`.
 
 # Single User Installation
 
@@ -50,9 +58,9 @@ $ rm -rf /nix
 The multi-user Nix installation creates system users, and a system
 service for the Nix daemon.
 
-  - Linux running systemd, with SELinux disabled
-
-  - macOS
+**Supported Systems**
+- Linux running systemd, with SELinux disabled
+- macOS
 
 You can instruct the installer to perform a multi-user installation on
 your system:
@@ -96,165 +104,28 @@ sudo rm /Library/LaunchDaemons/org.nixos.nix-daemon.plist
 There may also be references to Nix in `/etc/profile`, `/etc/bashrc`,
 and `/etc/zshrc` which you may remove.
 
-# macOS Installation
-
-Starting with macOS 10.15 (Catalina), the root filesystem is read-only.
-This means `/nix` can no longer live on your system volume, and that
-you'll need a workaround to install Nix.
-
-The recommended approach, which creates an unencrypted APFS volume for
-your Nix store and a "synthetic" empty directory to mount it over at
-`/nix`, is least likely to impair Nix or your system.
-
-> **Note**
-> 
-> With all separate-volume approaches, it's possible something on your
-> system (particularly daemons/services and restored apps) may need
-> access to your Nix store before the volume is mounted. Adding
-> additional encryption makes this more likely.
-
-If you're using a recent Mac with a [T2
-chip](https://www.apple.com/euro/mac/shared/docs/Apple_T2_Security_Chip_Overview.pdf),
-your drive will still be encrypted at rest (in which case "unencrypted"
-is a bit of a misnomer). To use this approach, just install Nix with:
-
-```console
-$ sh <(curl -L https://nixos.org/nix/install) --darwin-use-unencrypted-nix-store-volume
-```
-
-If you don't like the sound of this, you'll want to weigh the other
-approaches and tradeoffs detailed in this section.
-
-> **Note**
-> 
-> All of the known workarounds have drawbacks, but we hope better
-> solutions will be available in the future. Some that we have our eye
-> on are:
-> 
-> 1.  A true firmlink would enable the Nix store to live on the primary
->     data volume without the build problems caused by the symlink
->     approach. End users cannot currently create true firmlinks.
-> 
-> 2.  If the Nix store volume shared FileVault encryption with the
->     primary data volume (probably by using the same volume group and
->     role), FileVault encryption could be easily supported by the
->     installer without requiring manual setup by each user.
-
-## Change the Nix store path prefix
-
-Changing the default prefix for the Nix store is a simple approach which
-enables you to leave it on your root volume, where it can take full
-advantage of FileVault encryption if enabled. Unfortunately, this
-approach also opts your device out of some benefits that are enabled by
-using the same prefix across systems:
-
-  - Your system won't be able to take advantage of the binary cache
-    (unless someone is able to stand up and support duplicate caching
-    infrastructure), which means you'll spend more time waiting for
-    builds.
-
-  - It's harder to build and deploy packages to Linux systems.
-
-It would also possible (and often requested) to just apply this change
-ecosystem-wide, but it's an intrusive process that has side effects we
-want to avoid for now.
-
-## Use a separate encrypted volume
-
-If you like, you can also add encryption to the recommended approach
-taken by the installer. You can do this by pre-creating an encrypted
-volume before you run the installer--or you can run the installer and
-encrypt the volume it creates later.
-
-In either case, adding encryption to a second volume isn't quite as
-simple as enabling FileVault for your boot volume. Before you dive in,
-there are a few things to weigh:
-
-1.  The additional volume won't be encrypted with your existing
-    FileVault key, so you'll need another mechanism to decrypt the
-    volume.
-
-2.  You can store the password in Keychain to automatically decrypt the
-    volume on boot--but it'll have to wait on Keychain and may not mount
-    before your GUI apps restore. If any of your launchd agents or apps
-    depend on Nix-installed software (for example, if you use a
-    Nix-installed login shell), the restore may fail or break.
-    
-    On a case-by-case basis, you may be able to work around this problem
-    by using `wait4path` to block execution until your executable is
-    available.
-    
-    It's also possible to decrypt and mount the volume earlier with a
-    login hook--but this mechanism appears to be deprecated and its
-    future is unclear.
-
-3.  You can hard-code the password in the clear, so that your store
-    volume can be decrypted before Keychain is available.
-
-If you are comfortable navigating these tradeoffs, you can encrypt the
-volume with something along the lines of:
-
-```console
-$ diskutil apfs enableFileVault /nix -user disk
-```
-
-## Symlink the Nix store to a custom location
-
-Another simple approach is using `/etc/synthetic.conf` to symlink the
-Nix store to the data volume. This option also enables your store to
-share any configured FileVault encryption. Unfortunately, builds that
-resolve the symlink may leak the canonical path or even fail.
-
-Because of these downsides, we can't recommend this approach.
-
-## Notes on the recommended approach
-
-This section goes into a little more detail on the recommended approach.
-You don't need to understand it to run the installer, but it can serve
-as a helpful reference if you run into trouble.
-
-1.  In order to compose user-writable locations into the new read-only
-    system root, Apple introduced a new concept called `firmlinks`,
-    which it describes as a "bi-directional wormhole" between two
-    filesystems. You can see the current firmlinks in
-    `/usr/share/firmlinks`. Unfortunately, firmlinks aren't (currently?)
-    user-configurable.
-    
-    For special cases like NFS mount points or package manager roots,
-    [synthetic.conf(5)](https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man5/synthetic.conf.5.html)
-    supports limited user-controlled file-creation (of symlinks, and
-    synthetic empty directories) at `/`. To create a synthetic empty
-    directory for mounting at `/nix`, add the following line to
-    `/etc/synthetic.conf` (create it if necessary):
-    
-        nix
-
-2.  This configuration is applied at boot time, but you can use
-    `apfs.util` to trigger creation (not deletion) of new entries
-    without a reboot:
-    
-    ```console
-    $ /System/Library/Filesystems/apfs.fs/Contents/Resources/apfs.util -B
-    ```
-
-3.  Create the new APFS volume with diskutil:
-    
-    ```console
-    $ sudo diskutil apfs addVolume diskX APFS 'Nix Store' -mountpoint /nix
-    ```
-
-4.  Using `vifs`, add the new mount to `/etc/fstab`. If it doesn't
-    already have other entries, it should look something like:
-    
-        #
-        # Warning - this file should only be modified with vifs(8)
-        #
-        # Failure to do so is unsupported and may be destructive.
-        #
-        LABEL=Nix\040Store /nix apfs rw,nobrowse
-    
-    The nobrowse setting will keep Spotlight from indexing this volume,
-    and keep it from showing up on your desktop.
+# macOS Installation <a name="sect-macos-installation-change-store-prefix"></a><a name="sect-macos-installation-encrypted-volume"></a><a name="sect-macos-installation-symlink"></a><a name="sect-macos-installation-recommended-notes"></a>
+<!-- Note: anchors above to catch permalinks to old explanations -->
+
+We believe we have ironed out how to cleanly support the read-only root
+on modern macOS. New installs will do this automatically, and you can
+also re-run a new installer to convert your existing setup.
+
+This section previously detailed the situation, options, and trade-offs,
+but it now only outlines what the installer does. You don't need to know
+this to run the installer, but it may help if you run into trouble:
+
+- create a new APFS volume for your Nix store
+- update `/etc/synthetic.conf` to direct macOS to create a "synthetic"
+  empty root directory to mount your volume
+- specify mount options for the volume in `/etc/fstab`
+- if you have FileVault enabled
+    - generate an encryption password
+    - put it in your system Keychain
+    - use it to encrypt the volume
+- create a system LaunchDaemon to mount this volume early enough in the
+  boot process to avoid problems loading or restoring any programs that
+  need access to your Nix store
 
 # Installing a pinned Nix version from a URL
 
diff --git a/doc/manual/src/installation/installing-docker.md b/doc/manual/src/installation/installing-docker.md
new file mode 100644
index 000000000..3d2255b7a
--- /dev/null
+++ b/doc/manual/src/installation/installing-docker.md
@@ -0,0 +1,59 @@
+# Using Nix within Docker
+
+To run the latest stable release of Nix with Docker run the following command:
+
+```console
+$ docker -ti run nixos/nix
+Unable to find image 'nixos/nix:latest' locally
+latest: Pulling from nixos/nix
+5843afab3874: Pull complete
+b52bf13f109c: Pull complete
+1e2415612aa3: Pull complete
+Digest: sha256:27f6e7f60227e959ee7ece361f75d4844a40e1cc6878b6868fe30140420031ff
+Status: Downloaded newer image for nixos/nix:latest
+35ca4ada6e96:/# nix --version
+nix (Nix) 2.3.12
+35ca4ada6e96:/# exit
+```
+
+# What is included in Nix' Docker image?
+
+The official Docker image is created using `pkgs.dockerTools.buildLayeredImage`
+(and not with `Dockerfile` as it is usual with Docker images). You can still
+base your custom Docker image on it as you would do with any other Docker
+image.
+
+The Docker image is also not based on any other image and includes minimal set
+of runtime dependencies that are required to use Nix:
+
+ - pkgs.nix
+ - pkgs.bashInteractive
+ - pkgs.coreutils-full
+ - pkgs.gnutar
+ - pkgs.gzip
+ - pkgs.gnugrep
+ - pkgs.which
+ - pkgs.curl
+ - pkgs.less
+ - pkgs.wget
+ - pkgs.man
+ - pkgs.cacert.out
+ - pkgs.findutils
+
+# Docker image with the latest development version of Nix
+
+To get the latest image that was built by [Hydra](https://hydra.nixos.org) run
+the following command:
+
+```console
+$ curl -L https://hydra.nixos.org/job/nix/master/dockerImage.x86_64-linux/latest/download/1 | docker load
+$ docker run -ti nix:2.5pre20211105
+```
+
+You can also build a Docker image from source yourself:
+
+```console
+$ nix build ./\#hydraJobs.dockerImage.x86_64-linux
+$ docker load -i ./result
+$ docker run -ti nix:2.5pre20211105
+```
diff --git a/doc/manual/src/installation/installing-source.md b/doc/manual/src/installation/installing-source.md
index e52d38a03..09b4e4887 100644
--- a/doc/manual/src/installation/installing-source.md
+++ b/doc/manual/src/installation/installing-source.md
@@ -1,4 +1,4 @@
 # Installing Nix from Source
 
-If no binary package is available, you can download and compile a source
-distribution.
+If no binary package is available or if you want to hack on Nix, you
+can build Nix from its Git repository.
diff --git a/doc/manual/src/installation/obtaining-source.md b/doc/manual/src/installation/obtaining-source.md
index 0a906e390..da05d243d 100644
--- a/doc/manual/src/installation/obtaining-source.md
+++ b/doc/manual/src/installation/obtaining-source.md
@@ -1,14 +1,9 @@
-# Obtaining a Source Distribution
+# Obtaining the Source
 
-The source tarball of the most recent stable release can be downloaded
-from the [Nix homepage](http://nixos.org/nix/download.html). You can
-also grab the [most recent development
-release](http://hydra.nixos.org/job/nix/master/release/latest-finished#tabs-constituents).
-
-Alternatively, the most recent sources of Nix can be obtained from its
-[Git repository](https://github.com/NixOS/nix). For example, the
-following command will check out the latest revision into a directory
-called `nix`:
+The most recent sources of Nix can be obtained from its [Git
+repository](https://github.com/NixOS/nix). For example, the following
+command will check out the latest revision into a directory called
+`nix`:
 
 ```console
 $ git clone https://github.com/NixOS/nix
diff --git a/doc/manual/src/installation/prerequisites-source.md b/doc/manual/src/installation/prerequisites-source.md
index 6825af707..0323a4f55 100644
--- a/doc/manual/src/installation/prerequisites-source.md
+++ b/doc/manual/src/installation/prerequisites-source.md
@@ -2,9 +2,8 @@
 
   - GNU Autoconf (<https://www.gnu.org/software/autoconf/>) and the
     autoconf-archive macro collection
-    (<https://www.gnu.org/software/autoconf-archive/>). These are only
-    needed to run the bootstrap script, and are not necessary if your
-    source distribution came with a pre-built `./configure` script.
+    (<https://www.gnu.org/software/autoconf-archive/>). These are
+    needed to run the bootstrap script.
 
   - GNU Make.
 
@@ -26,15 +25,6 @@
     available for download from the official repository
     <https://github.com/google/brotli>.
 
-  - The bzip2 compressor program and the `libbz2` library. Thus you must
-    have bzip2 installed, including development headers and libraries.
-    If your distribution does not provide these, you can obtain bzip2
-    from
-    <https://sourceware.org/bzip2/>.
-
-  - `liblzma`, which is provided by XZ Utils. If your distribution does
-    not provide this, you can get it from <https://tukaani.org/xz/>.
-
   - cURL and its library. If your distribution does not provide it, you
     can get it from <https://curl.haxx.se/>.
 
@@ -61,8 +51,7 @@
     you need version 2.5.35, which is available on
     [SourceForge](http://lex.sourceforge.net/). Slightly older versions
     may also work, but ancient versions like the ubiquitous 2.5.4a
-    won't. Note that these are only required if you modify the parser or
-    when you are building from the Git repository.
+    won't.
 
   - The `libseccomp` is used to provide syscall filtering on Linux. This
     is an optional dependency and can be disabled passing a