Merge commit '84d74ae9c9cbed73274b8e4e00be14688ffc93fe'

author: Alyssa Ross <hi@alyssa.is> 2021-01-10 07:13:44 +0000
committer: Alyssa Ross <hi@alyssa.is> 2021-01-12 14:07:16 +0000
commit: e2698550456abba83c6dcd5d5e5a9990a0b96f8a (patch)
tree: 79a56f0df3fa55e470d84b4dff6059fbf487ec18 /nixpkgs/doc
parent: 1cdc42df888dc98c347e03bd942ed9825a55bcb3 (diff)
parent: 84d74ae9c9cbed73274b8e4e00be14688ffc93fe (diff)
download: nixlib-e2698550456abba83c6dcd5d5e5a9990a0b96f8a.tar
nixlib-e2698550456abba83c6dcd5d5e5a9990a0b96f8a.tar.gz
nixlib-e2698550456abba83c6dcd5d5e5a9990a0b96f8a.tar.bz2
nixlib-e2698550456abba83c6dcd5d5e5a9990a0b96f8a.tar.lz
nixlib-e2698550456abba83c6dcd5d5e5a9990a0b96f8a.tar.xz
nixlib-e2698550456abba83c6dcd5d5e5a9990a0b96f8a.tar.zst
nixlib-e2698550456abba83c6dcd5d5e5a9990a0b96f8a.zip
28 files changed, 728 insertions, 336 deletions
diff --git a/nixpkgs/doc/Makefile b/nixpkgs/doc/Makefile
index cdef493502bf..49f361ebb60b 100644
--- a/nixpkgs/doc/Makefile
+++ b/nixpkgs/doc/Makefile
@@ -1,4 +1,4 @@
-MD_TARGETS=$(addsuffix .xml, $(basename $(wildcard ./*.md ./**/*.md)))
+MD_TARGETS=$(addsuffix .xml, $(basename $(shell find . -type f -regex '.*\.md$$')))
 
 .PHONY: all
 all: validate format out/html/index.html out/epub/manual.epub
diff --git a/nixpkgs/doc/builders/images/dockertools.xml b/nixpkgs/doc/builders/images/dockertools.xml
index e7f37fdaaf00..d881e712a041 100644
--- a/nixpkgs/doc/builders/images/dockertools.xml
+++ b/nixpkgs/doc/builders/images/dockertools.xml
@@ -132,11 +132,11 @@ buildImage {
    <para>
     By default <function>buildImage</function> will use a static date of one second past the UNIX Epoch. This allows <function>buildImage</function> to produce binary reproducible images. When listing images with <command>docker images</command>, the newly created images will be listed like this:
    </para>
-<screen><![CDATA[
-$ docker images
+<screen>
+<prompt>$ </prompt>docker images
 REPOSITORY   TAG      IMAGE ID       CREATED        SIZE
 hello        latest   08c791c7846e   48 years ago   25.2MB
-]]></screen>
+</screen>
    <para>
     You can break binary reproducibility but have a sorted, meaningful <literal>CREATED</literal> column by setting <literal>created</literal> to <literal>now</literal>.
    </para>
@@ -152,11 +152,11 @@ pkgs.dockerTools.buildImage {
 ]]></programlisting>
    <para>
     and now the Docker CLI will display a reasonable date and sort the images as expected:
-<screen><![CDATA[
-$ docker images
+<screen>
+<prompt>$ </prompt>docker images
 REPOSITORY   TAG      IMAGE ID       CREATED              SIZE
 hello        latest   de2bf4786de6   About a minute ago   25.2MB
-]]></screen>
+</screen>
     however, the produced images will not be binary reproducible.
    </para>
   </example>
@@ -166,7 +166,7 @@ hello        latest   de2bf4786de6   About a minute ago   25.2MB
   <title>buildLayeredImage</title>
 
   <para>
-   Create a Docker image with many of the store paths being on their own layer to improve sharing between images.
+   Create a Docker image with many of the store paths being on their own layer to improve sharing between images. The image is realized into the Nix store as a gzipped tarball. Depending on the intended usage, many users might prefer to use <function>streamLayeredImage</function> instead, which this function uses internally.
   </para>
 
   <variablelist>
@@ -327,6 +327,27 @@ pkgs.dockerTools.buildLayeredImage {
   </section>
  </section>
 
+ <section xml:id="ssec-pkgs-dockerTools-streamLayeredImage">
+  <title>streamLayeredImage</title>
+
+  <para>
+   Builds a script which, when run, will stream an uncompressed tarball of a Docker image to stdout. The arguments to this function are as for <function>buildLayeredImage</function>. This method of constructing an image does not realize the image into the Nix store, so it saves on IO and disk/cache space, particularly with large images.
+  </para>
+
+  <para>
+    The image produced by running the output script can be piped directly into <command>docker load</command>, to load it into the local docker daemon:
+    <screen><![CDATA[
+$(nix-build) | docker load
+    ]]></screen>
+  </para>
+  <para>
+    Alternatively, the image be piped via <command>gzip</command> into <command>skopeo</command>, e.g. to copy it into a registry:
+    <screen><![CDATA[
+$(nix-build) | gzip --fast | skopeo copy docker-archive:/dev/stdin docker://some_docker_registry/myimage:tag
+    ]]></screen>
+  </para>
+ </section>
+
  <section xml:id="ssec-pkgs-dockerTools-fetchFromRegistry">
   <title>pullImage</title>
 
diff --git a/nixpkgs/doc/builders/images/ocitools.xml b/nixpkgs/doc/builders/images/ocitools.xml
index e8cd3472f54d..f26ed8644276 100644
--- a/nixpkgs/doc/builders/images/ocitools.xml
+++ b/nixpkgs/doc/builders/images/ocitools.xml
@@ -38,8 +38,7 @@ buildContainer {
 
   readonly = false; <co xml:id='ex-ociTools-buildContainer-3' />
 }
-
-    </programlisting>
+</programlisting>
    <calloutlist>
     <callout arearefs='ex-ociTools-buildContainer-1'>
      <para>
diff --git a/nixpkgs/doc/builders/packages/cataclysm-dda.section.md b/nixpkgs/doc/builders/packages/cataclysm-dda.section.md
new file mode 100644
index 000000000000..ae2ee56a010e
--- /dev/null
+++ b/nixpkgs/doc/builders/packages/cataclysm-dda.section.md
@@ -0,0 +1,94 @@
+# Cataclysm: Dark Days Ahead
+
+## How to install Cataclysm DDA
+
+To install the latest stable release of Cataclysm DDA to your profile, execute
+`nix-env -f "<nixpkgs>" -iA cataclysm-dda`. For the curses build (build
+without tiles), install `cataclysmDDA.stable.curses`. Note: `cataclysm-dda` is
+an alias to `cataclysmDDA.stable.tiles`.
+
+If you like access to a development build of your favorite git revision,
+override `cataclysm-dda-git` (or `cataclysmDDA.git.curses` if you like curses
+build):
+
+```nix
+cataclysm-dda-git.override {
+  version = "YYYY-MM-DD";
+  rev = "YOUR_FAVORITE_REVISION";
+  sha256 = "CHECKSUM_OF_THE_REVISION";
+}
+```
+
+The sha256 checksum can be obtained by
+
+```sh
+nix-prefetch-url --unpack "https://github.com/CleverRaven/Cataclysm-DDA/archive/${YOUR_FAVORITE_REVISION}.tar.gz"
+```
+
+The default configuration directory is `~/.cataclysm-dda`. If you prefer
+`$XDG_CONFIG_HOME/cataclysm-dda`, override the derivation:
+
+```nix
+cataclysm-dda.override {
+  useXdgDir = true;
+}
+```
+
+## Customizing with mods
+
+To install Cataclysm DDA with mods of your choice, you can use `withMods`
+attribute:
+
+```nix
+cataclysm-dda.withMods (mods: with mods; [
+  tileset.UndeadPeople
+])
+```
+
+All mods, soundpacks, and tilesets available in nixpkgs are found in
+`cataclysmDDA.pkgs`.
+
+Here is an example to modify existing mods and/or add more mods not available
+in nixpkgs:
+
+```nix
+let
+  customMods = self: super: lib.recursiveUpdate super {
+    # Modify existing mod
+    tileset.UndeadPeople = super.tileset.UndeadPeople.overrideAttrs (old: {
+      # If you like to apply a patch to the tileset for example
+      patches = [ ./path/to/your.patch ];
+    });
+
+    # Add another mod
+    mod.Awesome = cataclysmDDA.buildMod {
+      modName = "Awesome";
+      version = "0.x";
+      src = fetchFromGitHub {
+        owner = "Someone";
+        repo = "AwesomeMod";
+        rev = "...";
+        sha256 = "...";
+      };
+      # Path to be installed in the unpacked source (default: ".")
+      modRoot = "contents/under/this/path/will/be/installed";
+    };
+
+    # Add another soundpack
+    soundpack.Fantastic = cataclysmDDA.buildSoundPack {
+      # ditto
+    };
+
+    # Add another tileset
+    tileset.SuperDuper = cataclysmDDA.buildTileSet {
+      # ditto
+    };
+  };
+in
+cataclysm-dda.withMods (mods: with mods.extend customMods; [
+  tileset.UndeadPeople
+  mod.Awesome
+  soundpack.Fantastic
+  tileset.SuperDuper
+])
+```
diff --git a/nixpkgs/doc/builders/packages/citrix.xml b/nixpkgs/doc/builders/packages/citrix.xml
index c629dc9ee503..803eb2e4fc40 100644
--- a/nixpkgs/doc/builders/packages/citrix.xml
+++ b/nixpkgs/doc/builders/packages/citrix.xml
@@ -4,34 +4,36 @@
  <title>Citrix Workspace</title>
 
  <para>
-  <note>
-   <para>
-    Please note that the <literal>citrix_receiver</literal> package has been deprecated since its development was <link xlink:href="https://docs.citrix.com/en-us/citrix-workspace-app.html">discontinued by upstream</link> and has been replaced by <link xlink:href="https://www.citrix.com/products/workspace-app/">the citrix workspace app</link>.
-   </para>
-  </note>
-  <link xlink:href="https://www.citrix.com/products/receiver/">Citrix Receiver</link> and <link xlink:href="https://www.citrix.com/products/workspace-app/">Citrix Workspace App</link> are a remote desktop viewers which provide access to <link xlink:href="https://www.citrix.com/products/xenapp-xendesktop/">XenDesktop</link> installations.
+  The <link xlink:href="https://www.citrix.com/products/workspace-app/">Citrix Workspace App</link> is a remote desktop viewer which provides access to <link xlink:href="https://www.citrix.com/products/xenapp-xendesktop/">XenDesktop</link> installations.
  </para>
 
  <section xml:id="sec-citrix-base">
   <title>Basic usage</title>
 
   <para>
-   The tarball archive needs to be downloaded manually as the license agreements of the vendor for <link xlink:href="https://www.citrix.com/downloads/citrix-receiver/">Citrix Receiver</link> or <link xlink:href="https://www.citrix.de/downloads/workspace-app/linux/workspace-app-for-linux-latest.html">Citrix Workspace</link> need to be accepted first. Then run <command>nix-prefetch-url file://$PWD/linuxx64-$version.tar.gz</command>. With the archive available in the store the package can be built and installed with Nix.
+   The tarball archive needs to be downloaded manually as the license agreements of the vendor for <link xlink:href="https://www.citrix.de/downloads/workspace-app/linux/workspace-app-for-linux-latest.html">Citrix Workspace</link> needs to be accepted first. Then run <command>nix-prefetch-url file://$PWD/linuxx64-$version.tar.gz</command>. With the archive available in the store the package can be built and installed with Nix.
   </para>
+ </section>
 
-  <warning>
-   <title>Caution with <command>nix-shell</command> installs</title>
-   <para>
-    It's recommended to install <literal>Citrix Receiver</literal> and/or <literal>Citrix Workspace</literal> using <literal>nix-env -i</literal> or globally to ensure that the <literal>.desktop</literal> files are installed properly into <literal>$XDG_CONFIG_DIRS</literal>. Otherwise it won't be possible to open <literal>.ica</literal> files automatically from the browser to start a Citrix connection.
-   </para>
-  </warning>
+ <section xml:id="sec-citrix-selfservice">
+  <title>Citrix Selfservice</title>
+  <para>
+   The <link xlink:href="https://support.citrix.com/article/CTX200337">selfservice</link> is an application managing Citrix desktops and applications. Please note that this feature only works with at least <package>citrix_workspace_20_06_0</package> and later versions.
+  </para>
+  <para>
+   In order to set this up, you first have to <link xlink:href="https://its.uiowa.edu/support/article/102186">download the <literal>.cr</literal> file from the Netscaler Gateway</link>. After that you can configure the <command>selfservice</command> like this:
+<screen>
+<prompt>$ </prompt>storebrowse -C ~/Downloads/receiverconfig.cr
+<prompt>$ </prompt>selfservice
+</screen>
+  </para>
  </section>
 
  <section xml:id="sec-citrix-custom-certs">
   <title>Custom certificates</title>
 
   <para>
-   The <literal>Citrix Workspace App</literal> in <literal>nixpkgs</literal> trust several certificates <link xlink:href="https://curl.haxx.se/docs/caextract.html">from the Mozilla database</link> by default. However several companies using Citrix might require their own corporate certificate. On distros with imperative packaging these certs can be stored easily in <link xlink:href="https://developer-docs.citrix.com/projects/receiver-for-linux-command-reference/en/13.7/"><literal>$ICAROOT</literal></link>, however this directory is a store path in <literal>nixpkgs</literal>. In order to work around this issue the package provides a simple mechanism to add custom certificates without rebuilding the entire package using <literal>symlinkJoin</literal>:
+   The <literal>Citrix Workspace App</literal> in <literal>nixpkgs</literal> trusts several certificates <link xlink:href="https://curl.haxx.se/docs/caextract.html">from the Mozilla database</link> by default. However several companies using Citrix might require their own corporate certificate. On distros with imperative packaging these certs can be stored easily in <link xlink:href="https://developer-docs.citrix.com/projects/receiver-for-linux-command-reference/en/13.7/"><literal>$ICAROOT</literal></link>, however this directory is a store path in <literal>nixpkgs</literal>. In order to work around this issue the package provides a simple mechanism to add custom certificates without rebuilding the entire package using <literal>symlinkJoin</literal>:
 <programlisting>
 <![CDATA[with import <nixpkgs> { config.allowUnfree = true; };
 let extraCerts = [ ./custom-cert-1.pem ./custom-cert-2.pem /* ... */ ]; in
diff --git a/nixpkgs/doc/builders/packages/index.xml b/nixpkgs/doc/builders/packages/index.xml
index 4e109bd1c599..e20b0c689a80 100644
--- a/nixpkgs/doc/builders/packages/index.xml
+++ b/nixpkgs/doc/builders/packages/index.xml
@@ -18,6 +18,7 @@
  <xi:include href="opengl.xml" />
  <xi:include href="shell-helpers.xml" />
  <xi:include href="steam.xml" />
+ <xi:include href="cataclysm-dda.section.xml" />
  <xi:include href="urxvt.xml" />
  <xi:include href="weechat.xml" />
  <xi:include href="xorg.xml" />
diff --git a/nixpkgs/doc/builders/packages/steam.xml b/nixpkgs/doc/builders/packages/steam.xml
index 8dfede59ac1b..59673328bace 100644
--- a/nixpkgs/doc/builders/packages/steam.xml
+++ b/nixpkgs/doc/builders/packages/steam.xml
@@ -45,13 +45,7 @@
   <title>How to play</title>
 
   <para>
-   For 64-bit systems it's important to have
-<programlisting>hardware.opengl.driSupport32Bit = true;</programlisting>
-   in your <filename>/etc/nixos/configuration.nix</filename>. You'll also need
-<programlisting>hardware.pulseaudio.support32Bit = true;</programlisting>
-   if you are using PulseAudio - this will enable 32bit ALSA apps integration. To use the Steam controller or other Steam supported controllers such as the DualShock 4 or Nintendo Switch Pro, you need to add
-<programlisting>hardware.steam-hardware.enable = true;</programlisting>
-   to your configuration.
+   Use <programlisting>programs.steam.enable = true;</programlisting> if you want to add steam to systemPackages and also enable a few workarrounds aswell as Steam controller support or other Steam supported controllers such as the DualShock 4 or Nintendo Switch Pr.
   </para>
  </section>
 
diff --git a/nixpkgs/doc/builders/packages/urxvt.xml b/nixpkgs/doc/builders/packages/urxvt.xml
index f85680cecc40..330e056b6560 100644
--- a/nixpkgs/doc/builders/packages/urxvt.xml
+++ b/nixpkgs/doc/builders/packages/urxvt.xml
@@ -18,10 +18,13 @@
    includes all available plugins. To make use of this functionality, use an
    overlay or directly install an expression that overrides its configuration,
    such as
-   <programlisting>rxvt-unicode.override { configure = { availablePlugins, ... }: {
+<programlisting>
+rxvt-unicode.override {
+  configure = { availablePlugins, ... }: {
     plugins = with availablePlugins; [ perls resize-font vtwheel ];
-  }
-}</programlisting>
+  };
+}
+</programlisting>
    If the <literal>configure</literal> function returns an attrset without the
    <literal>plugins</literal> attribute, <literal>availablePlugins</literal>
    will be used automatically.
@@ -30,18 +33,22 @@
   <para>
    In order to add plugins but also keep all default plugins installed, it is
    possible to use the following method:
-   <programlisting>rxvt-unicode.override { configure = { availablePlugins, ... }: {
-     plugins = (builtins.attrValues availablePlugins) ++ [ custom-plugin ];
-   };
-}</programlisting>
+<programlisting>
+rxvt-unicode.override {
+  configure = { availablePlugins, ... }: {
+    plugins = (builtins.attrValues availablePlugins) ++ [ custom-plugin ];
+  };
+}
+</programlisting>
   </para>
 
   <para>
    To get a list of all the plugins available, open the Nix REPL and run
-   <programlisting>$ nix repl
+<screen>
+<prompt>$ </prompt>nix repl
 :l &lt;nixpkgs&gt;
 map (p: p.name) pkgs.rxvt-unicode.plugins
-   </programlisting>
+</screen>
    Alternatively, if your shell is bash or zsh and have completion enabled,
    simply type <literal>nixpkgs.rxvt-unicode.plugins.&lt;tab&gt;</literal>.
   </para>
@@ -50,21 +57,27 @@ map (p: p.name) pkgs.rxvt-unicode.plugins
     In addition to <literal>plugins</literal> the options
     <literal>extraDeps</literal> and <literal>perlDeps</literal> can be used
     to install extra packages.
-    <literal>extraDeps</literal> can be used, for example, to provide 
+    <literal>extraDeps</literal> can be used, for example, to provide
     <literal>xsel</literal> (a clipboard manager) to the clipboard plugin,
     without installing it globally:
-    <programlisting>rxvt-unicode.override { configure = { availablePlugins, ... }: {
-     pluginsDeps = [ xsel ];
-   }
-}</programlisting>
+<programlisting>
+rxvt-unicode.override {
+  configure = { availablePlugins, ... }: {
+    pluginsDeps = [ xsel ];
+  };
+}
+</programlisting>
 
     <literal>perlDeps</literal> is a handy way to provide Perl packages to
     your custom plugins (in <literal>$HOME/.urxvt/ext</literal>). For example,
     if you need <literal>AnyEvent</literal> you can do:
-    <programlisting>rxvt-unicode.override { configure = { availablePlugins, ... }: {
-     perlDeps = with perlPackages; [ AnyEvent ];
-   }
-}</programlisting>
+<programlisting>
+rxvt-unicode.override {
+  configure = { availablePlugins, ... }: {
+    perlDeps = with perlPackages; [ AnyEvent ];
+  };
+}
+</programlisting>
   </para>
 
  </section>
@@ -90,7 +103,8 @@ map (p: p.name) pkgs.rxvt-unicode.plugins
   <para>
    If the plugin is itself a perl package that needs to be imported from
    other plugins or scripts, add the following passthrough:
-   <programlisting>passthru.perlPackages = [ "self" ];
+<programlisting>
+passthru.perlPackages = [ "self" ];
 </programlisting>
    This will make the urxvt wrapper pick up the dependency and set up the perl
    path accordingly.
diff --git a/nixpkgs/doc/contributing/submitting-changes.xml b/nixpkgs/doc/contributing/submitting-changes.xml
index a88965f5cc60..22389c24ea26 100644
--- a/nixpkgs/doc/contributing/submitting-changes.xml
+++ b/nixpkgs/doc/contributing/submitting-changes.xml
@@ -209,12 +209,12 @@ Additional information.
   </para>
 
 <programlisting>
-   (fetchpatch {
-     name = "CVE-2019-11068.patch";
-     url = "https://gitlab.gnome.org/GNOME/libxslt/commit/e03553605b45c88f0b4b2980adfbbb8f6fca2fd6.patch";
-     sha256 = "0pkpb4837km15zgg6h57bncp66d5lwrlvkr73h0lanywq7zrwhj8";
-   })
-  </programlisting>
+(fetchpatch {
+  name = "CVE-2019-11068.patch";
+  url = "https://gitlab.gnome.org/GNOME/libxslt/commit/e03553605b45c88f0b4b2980adfbbb8f6fca2fd6.patch";
+  sha256 = "0pkpb4837km15zgg6h57bncp66d5lwrlvkr73h0lanywq7zrwhj8";
+})
+</programlisting>
 
   <para>
    If a security fix applies to both master and a stable release then, similar to regular changes, they are preferably delivered via master first and cherry-picked to the release branch.
diff --git a/nixpkgs/doc/languages-frameworks/android.section.md b/nixpkgs/doc/languages-frameworks/android.section.md
index 1a8924082bfb..f4f6c086a805 100644
--- a/nixpkgs/doc/languages-frameworks/android.section.md
+++ b/nixpkgs/doc/languages-frameworks/android.section.md
@@ -191,6 +191,8 @@ androidenv.emulateApp {
 }
 ```
 
+Additional flags may be applied to the Android SDK's emulator through the runtime environment variable `$NIX_ANDROID_EMULATOR_FLAGS`.
+
 It is also possible to specify an APK to deploy inside the emulator
 and the package and activity names to launch it:
 
diff --git a/nixpkgs/doc/languages-frameworks/beam.xml b/nixpkgs/doc/languages-frameworks/beam.xml
index 278535237c2c..addab24f7f6d 100644
--- a/nixpkgs/doc/languages-frameworks/beam.xml
+++ b/nixpkgs/doc/languages-frameworks/beam.xml
@@ -68,13 +68,13 @@
   <title>How to Install BEAM Packages</title>
 
   <para>
-   BEAM builders are not registered at the top level, simply because they are not relevant to the vast majority of Nix users. 
+   BEAM builders are not registered at the top level, simply because they are not relevant to the vast majority of Nix users.
    To install any of those builders into your profile, refer to them by their attribute path <literal>beamPackages.rebar3</literal>:
   </para>
 
-  <screen>
-  <prompt>$ </prompt>nix-env -f &quot;&lt;nixpkgs&gt;&quot; -iA beamPackages.rebar3
-  </screen>
+<screen>
+<prompt>$ </prompt>nix-env -f &quot;&lt;nixpkgs&gt;&quot; -iA beamPackages.rebar3
+</screen>
 </section>
 
  <section xml:id="packaging-beam-applications">
diff --git a/nixpkgs/doc/languages-frameworks/emscripten.section.md b/nixpkgs/doc/languages-frameworks/emscripten.section.md
index 80e1094809ad..3663f962d5f2 100644
--- a/nixpkgs/doc/languages-frameworks/emscripten.section.md
+++ b/nixpkgs/doc/languages-frameworks/emscripten.section.md
@@ -21,11 +21,11 @@ Modes of use of `emscripten`:
 * **Declarative usage**:
 
     This mode is far more power full since this makes use of `nix` for dependency management of emscripten libraries and targets by using the `mkDerivation` which is implemented by `pkgs.emscriptenStdenv` and `pkgs.buildEmscriptenPackage`. The source for the packages is in `pkgs/top-level/emscripten-packages.nix` and the abstraction behind it in `pkgs/development/em-modules/generic/default.nix`.
-    * build and install all packages: 
-        * `nix-env -iA emscriptenPackages` 
-          
-    * dev-shell for zlib implementation hacking: 
-        * `nix-shell -A emscriptenPackages.zlib` 
+    * build and install all packages:
+        * `nix-env -iA emscriptenPackages`
+
+    * dev-shell for zlib implementation hacking:
+        * `nix-shell -A emscriptenPackages.zlib`
 
 
 ## Imperative usage
@@ -90,7 +90,7 @@ See the `zlib` example:
         libz.so.${old.version} -I . -o example.js
 
         echo "Using node to execute the test"
-        ${pkgs.nodejs}/bin/node ./example.js 
+        ${pkgs.nodejs}/bin/node ./example.js
 
         set +x
         if [ $? -ne 0 ]; then
@@ -112,7 +112,7 @@ See the `zlib` example:
 
 ### Usage 2: pkgs.buildEmscriptenPackage
 
-This `xmlmirror` example features a emscriptenPackage which is defined completely from this context and no `pkgs.zlib.override` is used. 
+This `xmlmirror` example features a emscriptenPackage which is defined completely from this context and no `pkgs.zlib.override` is used.
 
     xmlmirror = pkgs.buildEmscriptenPackage rec {
       name = "xmlmirror";
@@ -163,7 +163,7 @@ This `xmlmirror` example features a emscriptenPackage which is defined completel
       checkPhase = ''
 
       '';
-    }; 
+    };
 
 ### Declarative debugging
 
@@ -182,4 +182,3 @@ Use `nix-shell -I nixpkgs=/some/dir/nixpkgs -A emscriptenPackages.libz` and from
 Using this toolchain makes it easy to leverage `nix` from NixOS, MacOSX or even Windows (WSL+ubuntu+nix). This toolchain is reproducible, behaves like the rest of the packages from nixpkgs and contains a set of well working examples to learn and adapt from.
 
 If in trouble, ask the maintainers.
-
diff --git a/nixpkgs/doc/languages-frameworks/go.xml b/nixpkgs/doc/languages-frameworks/go.xml
index ff39276f640e..ebdcf616054c 100644
--- a/nixpkgs/doc/languages-frameworks/go.xml
+++ b/nixpkgs/doc/languages-frameworks/go.xml
@@ -38,7 +38,7 @@ pet = buildGoModule rec {
 
   vendorSha256 = "1879j77k96684wi554rkjxydrj8g3hpp0kvxz03sd8dmwr3lh83j"; <co xml:id='ex-buildGoModule-1' />
 
-  subPackages = [ "." ]; <co xml:id='ex-buildGoModule-2' />
+  runVend = true; <co xml:id='ex-buildGoModule-2' />
 
   meta = with lib; {
     description = "Simple command-line snippet manager, written in Go";
@@ -61,19 +61,14 @@ pet = buildGoModule rec {
     </callout>
     <callout arearefs='ex-buildGoModule-2'>
      <para>
-      <varname>subPackages</varname> limits the builder from building child packages that have not been listed. If <varname>subPackages</varname> is not specified, all child packages will be built.
+      <varname>runVend</varname> runs the vend command to generate the vendor directory. This is useful if your code depends on c code and go mod tidy does not include the needed sources to build.
      </para>
     </callout>
    </calloutlist>
   </para>
 
   <para>
-    <varname>vendorSha256</varname> can also take <varname>null</varname> as an input.
-
-    When `null` is used as a value, rather than fetching the dependencies
-    and vendoring them, we use the vendoring included within the source repo.
-    If you'd like to not have to update this field on dependency changes, 
-    run `go mod vendor` in your source repo and set 'vendorSha256 = null;'
+   <varname>vendorSha256</varname> can also take <varname>null</varname> as an input. When `null` is used as a value, rather than fetching the dependencies and vendoring them, we use the vendoring included within the source repo. If you'd like to not have to update this field on dependency changes, run `go mod vendor` in your source repo and set 'vendorSha256 = null;'
   </para>
  </section>
 
@@ -92,7 +87,6 @@ deis = buildGoPackage rec {
   version = "1.13.0";
 
   goPackagePath = "github.com/deis/deis"; <co xml:id='ex-buildGoPackage-1' />
-  subPackages = [ "client" ]; <co xml:id='ex-buildGoPackage-2' />
 
   src = fetchFromGitHub {
     owner = "deis";
@@ -101,9 +95,7 @@ deis = buildGoPackage rec {
     sha256 = "1qv9lxqx7m18029lj8cw3k7jngvxs4iciwrypdy0gd2nnghc68sw";
   };
 
-  goDeps = ./deps.nix; <co xml:id='ex-buildGoPackage-3' />
-
-  buildFlags = [ "--tags" "release" ]; <co xml:id='ex-buildGoPackage-4' />
+  goDeps = ./deps.nix; <co xml:id='ex-buildGoPackage-2' />
 }
 </programlisting>
   </example>
@@ -118,22 +110,9 @@ deis = buildGoPackage rec {
     </callout>
     <callout arearefs='ex-buildGoPackage-2'>
      <para>
-      <varname>subPackages</varname> limits the builder from building child packages that have not been listed. If <varname>subPackages</varname> is not specified, all child packages will be built.
-     </para>
-     <para>
-      In this example only <literal>github.com/deis/deis/client</literal> will be built.
-     </para>
-    </callout>
-    <callout arearefs='ex-buildGoPackage-3'>
-     <para>
       <varname>goDeps</varname> is where the Go dependencies of a Go program are listed as a list of package source identified by Go import path. It could be imported as a separate <varname>deps.nix</varname> file for readability. The dependency data structure is described below.
      </para>
     </callout>
-    <callout arearefs='ex-buildGoPackage-4'>
-     <para>
-      <varname>buildFlags</varname> is a list of flags passed to the go build command.
-     </para>
-    </callout>
    </calloutlist>
   </para>
 
@@ -200,4 +179,70 @@ done
 </screen>
   </para>
  </section>
+
+ <section xml:id="ssec-go-common-attributes">
+  <title>Attributes used by the builders</title>
+
+  <para>
+   Both <link xlink:href="#ssec-go-modules"><varname>buildGoModule</varname></link> and <link xlink:href="#ssec-go-modules"><varname>buildGoPackage</varname></link> can be tweaked to behave slightly differently, if the following attributes are used:
+  </para>
+
+  <variablelist>
+   <varlistentry xml:id="var-go-buildFlagsArray">
+    <term>
+     <varname>buildFlagsArray</varname> and <varname>buildFlags</varname>
+    </term>
+    <listitem>
+     <para>
+      These attributes set build flags supported by <varname>go build</varname>. We recommend using <varname>buildFlagsArray</varname>. The most common use case of these attributes is to make the resulting executable aware of its own version. For example:
+     </para>
+     <example xml:id='ex-goBuildFlags-nospaces'>
+      <title>buildFlagsArray</title>
+<programlisting>
+  buildFlagsArray = [
+    "-ldflags=-X main.Version=${version} -X main.Commit=${version}" <co xml:id='ex-goBuildFlags-1' />
+  ];
+</programlisting>
+     </example>
+     <calloutlist>
+      <callout arearefs='ex-goBuildFlags-1'>
+       <para>
+        Note: single quotes are not needed.
+       </para>
+      </callout>
+     </calloutlist>
+     <example xml:id='ex-goBuildFlags-noarray'>
+      <title>buildFlagsArray</title>
+<programlisting>
+  buildFlagsArray = ''
+    -ldflags=
+    -X main.Version=${version}
+    -X main.Commit=${version}
+  '';
+</programlisting>
+     </example>
+    </listitem>
+   </varlistentry>
+   <varlistentry xml:id="var-go-deleteVendor">
+    <term>
+     <varname>deleteVendor</varname>
+    </term>
+    <listitem>
+     <para>
+      Removes the pre-existing vendor directory. This should only be used if the dependencies included in the vendor folder are broken or incomplete.
+     </para>
+    </listitem>
+   </varlistentry>
+   <varlistentry xml:id="var-go-subPackages">
+    <term>
+     <varname>subPackages</varname>
+    </term>
+    <listitem>
+     <para>
+      Limits the builder from building child packages that have not been listed. If <varname>subPackages</varname> is not specified, all child packages will be built.
+     </para>
+    </listitem>
+   </varlistentry>
+  </variablelist>
+ </section>
 </section>
diff --git a/nixpkgs/doc/languages-frameworks/node.section.md b/nixpkgs/doc/languages-frameworks/node.section.md
index c1f4294711a1..2120adfc0b49 100644
--- a/nixpkgs/doc/languages-frameworks/node.section.md
+++ b/nixpkgs/doc/languages-frameworks/node.section.md
@@ -25,12 +25,13 @@ build system it uses. Here are some examples:
 
 After you have identified the correct system, you need to override your package
 expression while adding in build system as a build input. For example, `dat`
-requires `node-gyp-build`, so we override its expression in `default.nix`:
+requires `node-gyp-build`, so [we override](https://github.com/NixOS/nixpkgs/blob/32f5e5da4a1b3f0595527f5195ac3a91451e9b56/pkgs/development/node-packages/default.nix#L37-L40) its expression in [`default.nix`](https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/node-packages/default.nix):
 
 ```nix
-dat = nodePackages.dat.override (oldAttrs: {
-  buildInputs = oldAttrs.buildInputs ++ [ nodePackages.node-gyp-build ];
-});
+    dat = super.dat.override {
+      buildInputs = [ self.node-gyp-build pkgs.libtool pkgs.autoconf pkgs.automake ];
+      meta.broken = since "12";
+    };
 ```
 
 To add a package from NPM to nixpkgs:
diff --git a/nixpkgs/doc/languages-frameworks/perl.xml b/nixpkgs/doc/languages-frameworks/perl.xml
index d9b6b2721c67..b017c028f64c 100644
--- a/nixpkgs/doc/languages-frameworks/perl.xml
+++ b/nixpkgs/doc/languages-frameworks/perl.xml
@@ -3,14 +3,47 @@
          xml:id="sec-language-perl">
  <title>Perl</title>
 
- <para>
-  Nixpkgs provides a function <varname>buildPerlPackage</varname>, a generic package builder function for any Perl package that has a standard <varname>Makefile.PL</varname>. It’s implemented in <link
-xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/perl-modules/generic"><filename>pkgs/development/perl-modules/generic</filename></link>.
- </para>
-
- <para>
-  Perl packages from CPAN are defined in <link
-xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/top-level/perl-packages.nix"><filename>pkgs/top-level/perl-packages.nix</filename></link>, rather than <filename>pkgs/all-packages.nix</filename>. Most Perl packages are so straight-forward to build that they are defined here directly, rather than having a separate function for each package called from <filename>perl-packages.nix</filename>. However, more complicated packages should be put in a separate file, typically in <filename>pkgs/development/perl-modules</filename>. Here is an example of the former:
+ <section xml:id="ssec-perl-running">
+  <title>Running perl programs on the shell</title>
+
+  <para>
+   When executing a Perl script, it is possible you get an error such as <literal>./myscript.pl: bad interpreter: /usr/bin/perl: no such file or directory</literal>. This happens when the script expects Perl to be installed at <filename>/usr/bin/perl</filename>, which is not the case when using Perl from nixpkgs. You can fix the script by changing the first line to:
+<programlisting>
+#!/usr/bin/env perl
+</programlisting>
+  to take the Perl installation from the <literal>PATH</literal> environment variable, or invoke Perl directly with:
+<screen>
+<prompt>$ </prompt>perl ./myscript.pl
+</screen>
+  </para>
+
+  <para>
+   When the script is using a Perl library that is not installed globally, you might get an error such as <literal>Can't locate DB_File.pm in @INC (you may need to install the DB_File module)</literal>. In that case, you can use <command>nix-shell</command> to start an ad-hoc shell with that library installed, for instance:
+<screen>
+<prompt>$ </prompt>nix-shell -p perl perlPackages.DBFile --run ./myscript.pl
+</screen>
+  </para>
+
+  <para>
+  If you are always using the script in places where <command>nix-shell</command> is available, you can embed the <command>nix-shell</command> invocation in the shebang like this:
+<programlisting>
+#!/usr/bin/env nix-shell
+#! nix-shell -i perl -p perl perlPackages.DBFile
+</programlisting>
+  </para>
+ </section>
+
+ <section xml:id="ssec-perl-packaging">
+  <title>Packaging Perl programs</title>
+
+  <para>
+   Nixpkgs provides a function <varname>buildPerlPackage</varname>, a generic package builder function for any Perl package that has a standard <varname>Makefile.PL</varname>. It’s implemented in <link
+ xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/perl-modules/generic"><filename>pkgs/development/perl-modules/generic</filename></link>.
+  </para>
+
+  <para>
+   Perl packages from CPAN are defined in <link
+ xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/top-level/perl-packages.nix"><filename>pkgs/top-level/perl-packages.nix</filename></link>, rather than <filename>pkgs/all-packages.nix</filename>. Most Perl packages are so straight-forward to build that they are defined here directly, rather than having a separate function for each package called from <filename>perl-packages.nix</filename>. However, more complicated packages should be put in a separate file, typically in <filename>pkgs/development/perl-modules</filename>. Here is an example of the former:
 <programlisting>
 ClassC3 = buildPerlPackage rec {
   name = "Class-C3-0.21";
@@ -20,47 +53,47 @@ ClassC3 = buildPerlPackage rec {
   };
 };
 </programlisting>
-  Note the use of <literal>mirror://cpan/</literal>, and the <literal>${name}</literal> in the URL definition to ensure that the name attribute is consistent with the source that we’re actually downloading. Perl packages are made available in <filename>all-packages.nix</filename> through the variable <varname>perlPackages</varname>. For instance, if you have a package that needs <varname>ClassC3</varname>, you would typically write
+   Note the use of <literal>mirror://cpan/</literal>, and the <literal>${name}</literal> in the URL definition to ensure that the name attribute is consistent with the source that we’re actually downloading. Perl packages are made available in <filename>all-packages.nix</filename> through the variable <varname>perlPackages</varname>. For instance, if you have a package that needs <varname>ClassC3</varname>, you would typically write
 <programlisting>
 foo = import ../path/to/foo.nix {
   inherit stdenv fetchurl ...;
   inherit (perlPackages) ClassC3;
 };
 </programlisting>
-  in <filename>all-packages.nix</filename>. You can test building a Perl package as follows:
+   in <filename>all-packages.nix</filename>. You can test building a Perl package as follows:
 <screen>
 <prompt>$ </prompt>nix-build -A perlPackages.ClassC3
 </screen>
-  <varname>buildPerlPackage</varname> adds <literal>perl-</literal> to the start of the name attribute, so the package above is actually called <literal>perl-Class-C3-0.21</literal>. So to install it, you can say:
+   <varname>buildPerlPackage</varname> adds <literal>perl-</literal> to the start of the name attribute, so the package above is actually called <literal>perl-Class-C3-0.21</literal>. So to install it, you can say:
 <screen>
 <prompt>$ </prompt>nix-env -i perl-Class-C3
 </screen>
-  (Of course you can also install using the attribute name: <literal>nix-env -i -A perlPackages.ClassC3</literal>.)
- </para>
-
- <para>
-  So what does <varname>buildPerlPackage</varname> do? It does the following:
-  <orderedlist>
-   <listitem>
-    <para>
-     In the configure phase, it calls <literal>perl Makefile.PL</literal> to generate a Makefile. You can set the variable <varname>makeMakerFlags</varname> to pass flags to <filename>Makefile.PL</filename>
-    </para>
-   </listitem>
-   <listitem>
-    <para>
-     It adds the contents of the <envar>PERL5LIB</envar> environment variable to <literal>#! .../bin/perl</literal> line of Perl scripts as <literal>-I<replaceable>dir</replaceable></literal> flags. This ensures that a script can find its dependencies. (This can cause this shebang line to become too long for Darwin to handle; see the note below.)
-    </para>
-   </listitem>
-   <listitem>
-    <para>
-     In the fixup phase, it writes the propagated build inputs (<varname>propagatedBuildInputs</varname>) to the file <filename>$out/nix-support/propagated-user-env-packages</filename>. <command>nix-env</command> recursively installs all packages listed in this file when you install a package that has it. This ensures that a Perl package can find its dependencies.
-    </para>
-   </listitem>
-  </orderedlist>
- </para>
-
- <para>
-  <varname>buildPerlPackage</varname> is built on top of <varname>stdenv</varname>, so everything can be customised in the usual way. For instance, the <literal>BerkeleyDB</literal> module has a <varname>preConfigure</varname> hook to generate a configuration file used by <filename>Makefile.PL</filename>:
+   (Of course you can also install using the attribute name: <literal>nix-env -i -A perlPackages.ClassC3</literal>.)
+  </para>
+
+  <para>
+   So what does <varname>buildPerlPackage</varname> do? It does the following:
+   <orderedlist>
+    <listitem>
+     <para>
+      In the configure phase, it calls <literal>perl Makefile.PL</literal> to generate a Makefile. You can set the variable <varname>makeMakerFlags</varname> to pass flags to <filename>Makefile.PL</filename>
+     </para>
+    </listitem>
+    <listitem>
+     <para>
+      It adds the contents of the <envar>PERL5LIB</envar> environment variable to <literal>#! .../bin/perl</literal> line of Perl scripts as <literal>-I<replaceable>dir</replaceable></literal> flags. This ensures that a script can find its dependencies. (This can cause this shebang line to become too long for Darwin to handle; see the note below.)
+     </para>
+    </listitem>
+    <listitem>
+     <para>
+      In the fixup phase, it writes the propagated build inputs (<varname>propagatedBuildInputs</varname>) to the file <filename>$out/nix-support/propagated-user-env-packages</filename>. <command>nix-env</command> recursively installs all packages listed in this file when you install a package that has it. This ensures that a Perl package can find its dependencies.
+     </para>
+    </listitem>
+   </orderedlist>
+  </para>
+
+  <para>
+   <varname>buildPerlPackage</varname> is built on top of <varname>stdenv</varname>, so everything can be customised in the usual way. For instance, the <literal>BerkeleyDB</literal> module has a <varname>preConfigure</varname> hook to generate a configuration file used by <filename>Makefile.PL</filename>:
 <programlisting>
 { buildPerlPackage, fetchurl, db }:
 
@@ -78,10 +111,10 @@ buildPerlPackage rec {
   '';
 }
 </programlisting>
- </para>
+  </para>
 
- <para>
-  Dependencies on other Perl packages can be specified in the <varname>buildInputs</varname> and <varname>propagatedBuildInputs</varname> attributes. If something is exclusively a build-time dependency, use <varname>buildInputs</varname>; if it’s (also) a runtime dependency, use <varname>propagatedBuildInputs</varname>. For instance, this builds a Perl module that has runtime dependencies on a bunch of other modules:
+  <para>
+   Dependencies on other Perl packages can be specified in the <varname>buildInputs</varname> and <varname>propagatedBuildInputs</varname> attributes. If something is exclusively a build-time dependency, use <varname>buildInputs</varname>; if it’s (also) a runtime dependency, use <varname>propagatedBuildInputs</varname>. For instance, this builds a Perl module that has runtime dependencies on a bunch of other modules:
 <programlisting>
 ClassC3Componentised = buildPerlPackage rec {
   name = "Class-C3-Componentised-1.0004";
@@ -94,10 +127,10 @@ ClassC3Componentised = buildPerlPackage rec {
   ];
 };
 </programlisting>
- </para>
+  </para>
 
- <para>
-  On Darwin, if a script has too many <literal>-I<replaceable>dir</replaceable></literal> flags in its first line (its “shebang line”), it will not run. This can be worked around by calling the <literal>shortenPerlShebang</literal> function from the <literal>postInstall</literal> phase:
+  <para>
+   On Darwin, if a script has too many <literal>-I<replaceable>dir</replaceable></literal> flags in its first line (its “shebang line”), it will not run. This can be worked around by calling the <literal>shortenPerlShebang</literal> function from the <literal>postInstall</literal> phase:
 <programlisting>
 { stdenv, buildPerlPackage, fetchurl, shortenPerlShebang }:
 
@@ -116,22 +149,22 @@ ImageExifTool = buildPerlPackage {
   '';
 };
 </programlisting>
-  This will remove the <literal>-I</literal> flags from the shebang line, rewrite them in the <literal>use lib</literal> form, and put them on the next line instead. This function can be given any number of Perl scripts as arguments; it will modify them in-place.
- </para>
+   This will remove the <literal>-I</literal> flags from the shebang line, rewrite them in the <literal>use lib</literal> form, and put them on the next line instead. This function can be given any number of Perl scripts as arguments; it will modify them in-place.
+  </para>
 
- <section xml:id="ssec-generation-from-CPAN">
-  <title>Generation from CPAN</title>
+  <section xml:id="ssec-generation-from-CPAN">
+   <title>Generation from CPAN</title>
 
-  <para>
-   Nix expressions for Perl packages can be generated (almost) automatically from CPAN. This is done by the program <command>nix-generate-from-cpan</command>, which can be installed as follows:
-  </para>
+   <para>
+    Nix expressions for Perl packages can be generated (almost) automatically from CPAN. This is done by the program <command>nix-generate-from-cpan</command>, which can be installed as follows:
+   </para>
 
 <screen>
 <prompt>$ </prompt>nix-env -i nix-generate-from-cpan
 </screen>
 
-  <para>
-   This program takes a Perl module name, looks it up on CPAN, fetches and unpacks the corresponding package, and prints a Nix expression on standard output. For example:
+   <para>
+    This program takes a Perl module name, looks it up on CPAN, fetches and unpacks the corresponding package, and prints a Nix expression on standard output. For example:
 <screen>
 <prompt>$ </prompt>nix-generate-from-cpan XML::Simple
   XMLSimple = buildPerlPackage rec {
@@ -147,15 +180,16 @@ ImageExifTool = buildPerlPackage {
     };
   };
 </screen>
-   The output can be pasted into <filename>pkgs/top-level/perl-packages.nix</filename> or wherever else you need it.
-  </para>
- </section>
+    The output can be pasted into <filename>pkgs/top-level/perl-packages.nix</filename> or wherever else you need it.
+   </para>
+  </section>
 
- <section xml:id="ssec-perl-cross-compilation">
-  <title>Cross-compiling modules</title>
+  <section xml:id="ssec-perl-cross-compilation">
+   <title>Cross-compiling modules</title>
 
-  <para>
-   Nixpkgs has experimental support for cross-compiling Perl modules. In many cases, it will just work out of the box, even for modules with native extensions. Sometimes, however, the Makefile.PL for a module may (indirectly) import a native module. In that case, you will need to make a stub for that module that will satisfy the Makefile.PL and install it into <filename>lib/perl5/site_perl/cross_perl/${perl.version}</filename>. See the <varname>postInstall</varname> for <varname>DBI</varname> for an example.
-  </para>
+   <para>
+    Nixpkgs has experimental support for cross-compiling Perl modules. In many cases, it will just work out of the box, even for modules with native extensions. Sometimes, however, the Makefile.PL for a module may (indirectly) import a native module. In that case, you will need to make a stub for that module that will satisfy the Makefile.PL and install it into <filename>lib/perl5/site_perl/cross_perl/${perl.version}</filename>. See the <varname>postInstall</varname> for <varname>DBI</varname> for an example.
+   </para>
+  </section>
  </section>
 </section>
diff --git a/nixpkgs/doc/languages-frameworks/python.section.md b/nixpkgs/doc/languages-frameworks/python.section.md
index dc10483ce694..e2d9172919ef 100644
--- a/nixpkgs/doc/languages-frameworks/python.section.md
+++ b/nixpkgs/doc/languages-frameworks/python.section.md
@@ -538,8 +538,123 @@ buildPythonPackage rec {
 ```
 Note also the line `doCheck = false;`, we explicitly disabled running the test-suite.
 
+#### Testing Python Packages
+
+It is highly encouraged to have testing as part of the package build. This
+helps to avoid situations where the package was able to build and install,
+but is not usable at runtime. Currently, all packages will use the `test`
+command provided by the setup.py (i.e. `python setup.py test`). However,
+this is currently deprecated https://github.com/pypa/setuptools/pull/1878
+and your package should provide its own checkPhase.
+
+*NOTE:* The `checkPhase` for python maps to the `installCheckPhase` on a
+normal derivation. This is due to many python packages not behaving well
+to the pre-installed version of the package. Version info, and natively
+compiled extensions generally only exist in the install directory, and
+thus can cause issues when a test suite asserts on that behavior.
+
+*NOTE:* Tests should only be disabled if they don't agree with nix
+(e.g. external dependencies, network access, flakey tests), however,
+as many tests should be enabled as possible. Failing tests can still be
+a good indication that the package is not in a valid state.
+
+#### Using pytest
+
+Pytest is the most common test runner for python repositories. A trivial
+test run would be:
+```
+  checkInputs = [ pytest ];
+  checkPhase = "pytest";
+```
+
+However, many repositories' test suites do not translate well to nix's build
+sandbox, and will generally need many tests to be disabled.
+
+To filter tests using pytest, one can do the following:
+```
+  checkInputs = [ pytest ];
+  # avoid tests which need additional data or touch network
+  checkPhase = ''
+    pytest tests/ --ignore=tests/integration -k 'not download and not update'
+  '';
+```
+
+`--ignore` will tell pytest to ignore that file or directory from being
+collected as part of a test run. This is useful is a file uses a package
+which is not available in nixpkgs, thus skipping that test file is much
+easier than having to create a new package.
+
+`-k` is used to define a predicate for test names. In this example, we are
+filtering out tests which contain `download` or `update` in their test case name.
+Only one `-k` argument is allows, and thus a long predicate should be concatenated
+with "\" and wrapped to the next line.
+
+*NOTE:* In pytest==6.0.1, the use of "\" to continue a line (e.g. `-k 'not download \'`) has
+been removed, in this case, it's recommended to use `pytestCheckHook`.
+
+#### Using pytestCheckHook
+
+`pytestCheckHook` is a convenient hook which will substitute the setuptools
+`test` command for a checkPhase which runs `pytest`. This is also beneficial
+when a package may need many items disabled to run the test suite.
+
+Using the example above, the analagous pytestCheckHook usage would be:
+```
+  checkInputs = [ pytestCheckHook ];
+
+  # requires additional data
+  pytestFlagsArray = [ "tests/" "--ignore=tests/integration" ];
+
+  disabledTests = [
+    # touches network
+    "download"
+    "update"
+  ];
+```
+
+This is expecially useful when tests need to be conditionallydisabled,
+for example:
+
+```
+  disabledTests = [
+    # touches network
+    "download"
+    "update"
+  ] ++ lib.optionals (pythonAtLeast "3.8") [
+    # broken due to python3.8 async changes
+    "async"
+  ] ++ lib.optionals stdenv.isDarwin [
+    # can fail when building with other packages
+    "socket"
+  ];
+```
+Trying to concatenate the related strings to disable tests in a regular checkPhase
+would be much harder to read. This also enables us to comment on why specific tests
+are disabled.
+
+#### Using pythonImportsCheck
+
+Although unit tests are highly prefered to valid correctness of a package. Not
+all packages have test suites that can be ran easily, and some have none at all.
+To help ensure the package still works, `pythonImportsCheck` can attempt to import
+the listed modules.
+
+```
+  pythonImportsCheck = [ "requests" "urllib" ];
+```
+roughly translates to:
+```
+  postCheck = ''
+    PYTHONPATH=$out/${python.sitePackages}:$PYTHONPATH
+    python -c "import requests; import urllib"
+  '';
+```
+However, this is done in it's own phase, and not dependent on whether `doCheck = true;`
+
+This can also be useful in verifying that the package doesn't assume commonly
+present packages (e.g. `setuptools`)
 
-#### Develop local package
+### Develop local package
 
 As a Python developer you're likely aware of [development mode](http://setuptools.readthedocs.io/en/latest/setuptools.html#development-mode)
 (`python setup.py develop`); instead of installing the package this command
@@ -640,8 +755,8 @@ and in this case the `python38` interpreter is automatically used.
 
 ### Interpreters
 
-Versions 2.7, 3.5, 3.6, 3.7 and 3.8 of the CPython interpreter are available as
-respectively `python27`, `python35`, `python36`, `python37` and `python38`. The
+Versions 2.7, 3.6, 3.7 and 3.8 of the CPython interpreter are available as
+respectively `python27`, `python36`, `python37` and `python38`. The
 aliases `python2` and `python3` correspond to respectively `python27` and
 `python38`. The default interpreter, `python`, maps to `python2`. The PyPy
 interpreters compatible with Python 2.7 and 3 are available as `pypy27` and
@@ -689,15 +804,16 @@ attribute set is created for each available Python interpreter. The available
 sets are
 
 * `pkgs.python27Packages`
-* `pkgs.python35Packages`
 * `pkgs.python36Packages`
 * `pkgs.python37Packages`
+* `pkgs.python38Packages`
+* `pkgs.python39Packages`
 * `pkgs.pypyPackages`
 
 and the aliases
 
 * `pkgs.python2Packages` pointing to `pkgs.python27Packages`
-* `pkgs.python3Packages` pointing to `pkgs.python37Packages`
+* `pkgs.python3Packages` pointing to `pkgs.python38Packages`
 * `pkgs.pythonPackages` pointing to `pkgs.python2Packages`
 
 #### `buildPythonPackage` function
@@ -1016,7 +1132,7 @@ are used in `buildPythonPackage`.
 - `pipBuildHook` to build a wheel using `pip` and PEP 517. Note a build system
   (e.g. `setuptools` or `flit`) should still be added as `nativeBuildInput`.
 - `pipInstallHook` to install wheels.
-- `pytestCheckHook` to run tests with `pytest`.
+- `pytestCheckHook` to run tests with `pytest`. See [example usage](#using-pytestcheckhook).
 - `pythonCatchConflictsHook` to check whether a Python package is not already existing.
 - `pythonImportsCheckHook` to check whether importing the listed modules works.
 - `pythonRemoveBinBytecode` to remove bytecode from the `/bin` folder.
diff --git a/nixpkgs/doc/languages-frameworks/qt.xml b/nixpkgs/doc/languages-frameworks/qt.xml
index 8d97de504ad3..ec95621d8ff2 100644
--- a/nixpkgs/doc/languages-frameworks/qt.xml
+++ b/nixpkgs/doc/languages-frameworks/qt.xml
@@ -18,7 +18,7 @@ mkDerivation { <co xml:id='qt-default-nix-co-2' />
 
   buildInputs = [ qtbase ]; <co xml:id='qt-default-nix-co-3' />
 }
-   </programlisting>
+</programlisting>
  </example>
 
  <calloutlist>
diff --git a/nixpkgs/doc/languages-frameworks/ruby.xml b/nixpkgs/doc/languages-frameworks/ruby.xml
index 9b36801fb966..9b579d6804f4 100644
--- a/nixpkgs/doc/languages-frameworks/ruby.xml
+++ b/nixpkgs/doc/languages-frameworks/ruby.xml
@@ -12,14 +12,14 @@
  </para>
 
 <screen>
-<![CDATA[$ cd pkgs/servers/monitoring
-$ mkdir sensu
-$ cd sensu
-$ cat > Gemfile
+<prompt>$ </prompt>cd pkgs/servers/monitoring
+<prompt>$ </prompt>mkdir sensu
+<prompt>$ </prompt>cd sensu
+<prompt>$ </prompt>cat > Gemfile
 source 'https://rubygems.org'
 gem 'sensu'
-$ $(nix-build '<nixpkgs>' -A bundix --no-out-link)/bin/bundix --magic
-$ cat > default.nix
+<prompt>$ </prompt>$(nix-build '&lt;nixpkgs>' -A bundix --no-out-link)/bin/bundix --magic
+<prompt>$ </prompt>cat > default.nix
 { lib, bundlerEnv, ruby }:
 
 bundlerEnv rec {
@@ -37,7 +37,7 @@ bundlerEnv rec {
     maintainers = with maintainers; [ theuni ];
     platforms   = platforms.unix;
   };
-}]]>
+}
 </screen>
 
  <para>
@@ -49,17 +49,16 @@ bundlerEnv rec {
  </para>
 
 <screen>
-<![CDATA[$ cd pkgs/servers/monitoring/sensu
-$ nix-shell -p bundler --run 'bundle lock --update'
-$ nix-shell -p bundix --run 'bundix'
-]]>
+<prompt>$ </prompt>cd pkgs/servers/monitoring/sensu
+<prompt>$ </prompt>nix-shell -p bundler --run 'bundle lock --update'
+<prompt>$ </prompt>nix-shell -p bundix --run 'bundix'
 </screen>
 
  <para>
   For tools written in Ruby - i.e. where the desire is to install a package and then execute e.g. <command>rake</command> at the command line, there is an alternative builder called <literal>bundlerApp</literal>. Set up the <filename>gemset.nix</filename> the same way, and then, for example:
  </para>
 
-<screen>
+<programlisting>
 <![CDATA[{ lib, bundlerApp }:
 
 bundlerApp {
@@ -75,7 +74,7 @@ bundlerApp {
     platforms   = platforms.unix;
   };
 }]]>
-</screen>
+</programlisting>
 
  <para>
   The chief advantage of <literal>bundlerApp</literal> over <literal>bundlerEnv</literal> is the executables introduced in the environment are precisely those selected in the <literal>exes</literal> list, as opposed to <literal>bundlerEnv</literal> which adds all the executables made available by gems in the gemset, which can mean e.g. <command>rspec</command> or <command>rake</command> in unpredictable versions available from various packages.
diff --git a/nixpkgs/doc/languages-frameworks/rust.section.md b/nixpkgs/doc/languages-frameworks/rust.section.md
index ec418c563359..0e1d59e1a952 100644
--- a/nixpkgs/doc/languages-frameworks/rust.section.md
+++ b/nixpkgs/doc/languages-frameworks/rust.section.md
@@ -43,7 +43,6 @@ rustPlatform.buildRustPackage rec {
     homepage = "https://github.com/BurntSushi/ripgrep";
     license = licenses.unlicense;
     maintainers = [ maintainers.tailhook ];
-    platforms = platforms.all;
   };
 }
 ```
@@ -51,7 +50,7 @@ rustPlatform.buildRustPackage rec {
 `buildRustPackage` requires a `cargoSha256` attribute which is computed over
 all crate sources of this package. Currently it is obtained by inserting a
 fake checksum into the expression and building the package once. The correct
-checksum can be then take from the failed build.
+checksum can then be taken from the failed build.
 
 Per the instructions in the [Cargo Book](https://doc.rust-lang.org/cargo/guide/cargo-toml-vs-cargo-lock.html)
 best practices guide, Rust applications should always commit the `Cargo.lock`
@@ -79,7 +78,7 @@ pkgs.rustPlatform.buildRustPackage {
 
 When using `buildRustPackage`, the `checkPhase` is enabled by default and runs
 `cargo test` on the package to build. To make sure that we don't compile the
-sources twice and to actually test the artifacts that will be used at runtime, 
+sources twice and to actually test the artifacts that will be used at runtime,
 the tests will be ran in the `release` mode by default.
 
 However, in some cases the test-suite of a package doesn't work properly in the
@@ -120,6 +119,18 @@ The above are just guidelines, and exceptions may be granted on a case-by-case b
 However, please check if it's possible to disable a problematic subset of the
 test suite and leave a comment explaining your reasoning.
 
+#### Setting `test-threads`
+
+`buildRustPackage` will use parallel test threads by default,
+sometimes it may be necessary to disable this so the tests run consecutively.
+
+```nix
+rustPlatform.buildRustPackage {
+  /* ... */
+  cargoParallelTestThreads = false;
+}
+```
+
 ### Building a package in `debug` mode
 
 By default, `buildRustPackage` will use `release` mode for builds. If a package
diff --git a/nixpkgs/doc/languages-frameworks/texlive.xml b/nixpkgs/doc/languages-frameworks/texlive.xml
index a581ec5911cb..141c46e5a623 100644
--- a/nixpkgs/doc/languages-frameworks/texlive.xml
+++ b/nixpkgs/doc/languages-frameworks/texlive.xml
@@ -44,11 +44,11 @@ texlive.combine {
    <listitem>
     <para>
      You can list packages e.g. by <command>nix repl</command>.
-<programlisting><![CDATA[
-$ nix repl
-nix-repl> :l <nixpkgs>
-nix-repl> texlive.collection-<TAB>
-]]></programlisting>
+<programlisting>
+<prompt>$ </prompt>nix repl
+<prompt>nix-repl> </prompt>:l &lt;nixpkgs>
+<prompt>nix-repl> </prompt>texlive.collection-<keycap function="tab" />
+</programlisting>
     </para>
    </listitem>
    <listitem>
diff --git a/nixpkgs/doc/languages-frameworks/vim.section.md b/nixpkgs/doc/languages-frameworks/vim.section.md
index 4911509212e6..8e4826232e1a 100644
--- a/nixpkgs/doc/languages-frameworks/vim.section.md
+++ b/nixpkgs/doc/languages-frameworks/vim.section.md
@@ -263,6 +263,8 @@ Sometimes plugins require an override that must be changed when the plugin is up
 
 To add a new plugin, run `./update.py --add "[owner]/[name]"`. **NOTE**: This script automatically commits to your git repository. Be sure to check out a fresh branch before running.
 
+Finally, there are some plugins that are also packaged in nodePackages because they have Javascript-related build steps, such as running webpack. Those plugins are not listed in `vim-plugin-names` or managed by `update.py` at all, and are included separately in `overrides.nix`. Currently, all these plugins are related to the `coc.nvim` ecosystem of Language Server Protocol integration with vim/neovim.
+
 ## Important repositories
 
 - [vim-pi](https://bitbucket.org/vimcommunity/vim-pi) is a plugin repository
diff --git a/nixpkgs/doc/manual.xml b/nixpkgs/doc/manual.xml
index 1f69872d2a72..4ca497e234ea 100644
--- a/nixpkgs/doc/manual.xml
+++ b/nixpkgs/doc/manual.xml
@@ -1,7 +1,7 @@
 <book xmlns="http://docbook.org/ns/docbook"
       xmlns:xi="http://www.w3.org/2001/XInclude">
  <info>
-  <title>Nixpkgs Users and Contributors Guide</title>
+  <title>Nixpkgs Manual</title>
   <subtitle>Version <xi:include href=".version" parse="text" />
   </subtitle>
  </info>
diff --git a/nixpkgs/doc/old/cross.txt b/nixpkgs/doc/old/cross.txt
index 9dd5b4c9993b..064ca8d37b01 100644
--- a/nixpkgs/doc/old/cross.txt
+++ b/nixpkgs/doc/old/cross.txt
@@ -220,7 +220,7 @@ fi
 
 preConfigure=preConfigure
 preConfigure() {
-    
+
     # Determine the frontends to build.
     langs="c"
     if test -n "$langCC"; then
@@ -262,7 +262,7 @@ postInstall() {
 
 #if test -z "$profiledCompiler"; then
     #makeFlags="bootstrap"
-#else    
+#else
     #makeFlags="profiledbootstrap"
 #fi
 
diff --git a/nixpkgs/doc/stdenv/meta.xml b/nixpkgs/doc/stdenv/meta.xml
index 45f7834eb2cc..9cef9360002c 100644
--- a/nixpkgs/doc/stdenv/meta.xml
+++ b/nixpkgs/doc/stdenv/meta.xml
@@ -155,17 +155,17 @@ hello-2.3  A program that produces a familiar, friendly greeting
       <itemizedlist>
        <listitem>
         <para>
-         Single license referenced by attribute (preferred) <literal>stdenv.lib.licenses.gpl3</literal>.
+         Single license referenced by attribute (preferred) <literal>stdenv.lib.licenses.gpl3Only</literal>.
         </para>
        </listitem>
        <listitem>
         <para>
-         Single license referenced by its attribute shortName (frowned upon) <literal>"gpl3"</literal>.
+         Single license referenced by its attribute shortName (frowned upon) <literal>"gpl3Only"</literal>.
         </para>
        </listitem>
        <listitem>
         <para>
-         Single license referenced by its attribute spdxId (frowned upon) <literal>"GPL-3.0"</literal>.
+         Single license referenced by its attribute spdxId (frowned upon) <literal>"GPL-3.0-only"</literal>.
         </para>
        </listitem>
        <listitem>
diff --git a/nixpkgs/doc/stdenv/multiple-output.xml b/nixpkgs/doc/stdenv/multiple-output.xml
index 51e1cc2e024a..20658918db72 100644
--- a/nixpkgs/doc/stdenv/multiple-output.xml
+++ b/nixpkgs/doc/stdenv/multiple-output.xml
@@ -22,39 +22,69 @@
     The reduction effects could be instead achieved by building the parts in completely separate derivations. That would often additionally reduce build-time closures, but it tends to be much harder to write such derivations, as build systems typically assume all parts are being built at once. This compromise approach of single source package producing multiple binary packages is also utilized often by rpm and deb.
    </para>
   </note>
+
+  <para>
+   A number of attributes can be used to work with a derivation with multiple outputs. The attribute <varname>outputs</varname> is a list of strings, which are the names of the outputs. For each of these names, an identically named attribute is created, corresponding to that output. The attribute <varname>meta.outputsToInstall</varname> is used to determine the default set of outputs to install when using the derivation name unqualified.
+  </para>
+
  </section>
  <section xml:id="sec-multiple-outputs-installing">
   <title>Installing a split package</title>
 
   <para>
-   When installing a package via <varname>systemPackages</varname> or <command>nix-env</command> you have several options:
+   When installing a package with multiple outputs, the package's <varname>meta.outputsToInstall</varname> attribute determines which outputs are actually installed. <varname>meta.outputsToInstall</varname> is a list whose <link xlink:href="https://github.com/NixOS/nixpkgs/blob/f1680774340d5443a1409c3421ced84ac1163ba9/pkgs/stdenv/generic/make-derivation.nix#L310-L320">default installs binaries and the associated man pages</link>. The following sections describe ways to install different outputs.
   </para>
 
-  <itemizedlist>
-   <listitem>
-    <para>
-     You can install particular outputs explicitly, as each is available in the Nix language as an attribute of the package. The <varname>outputs</varname> attribute contains a list of output names.
-    </para>
-   </listitem>
-   <listitem>
-    <para>
-     You can let it use the default outputs. These are handled by <varname>meta.outputsToInstall</varname> attribute that contains a list of output names.
-    </para>
+  <section xml:id="sec-multiple-outputs-installing-nixos">
+   <title>Selecting outputs to install via NixOS</title>
+
+   <para>
+    NixOS provides two ways to select the outputs to install for packages listed in <varname>environment.systemPackages</varname>:
+   </para>
+
+   <itemizedlist>
+    <listitem>
+     <para>
+      The configuration option <varname>environment.extraOutputsToInstall</varname> is appended to each package's <varname>meta.outputsToInstall</varname> attribute to determine the outputs to install. It can for example be used to install <literal>info</literal> documentation or debug symbols for all packages.
+     </para>
+    </listitem>
+    <listitem>
+     <para>
+      The outputs can be listed as packages in <varname>environment.systemPackages</varname>. For example, the <literal>"out"</literal> and <literal>"info"</literal> outputs for the <varname>coreutils</varname> package can be installed by including <varname>coreutils</varname> and <varname>coreutils.info</varname> in <varname>environment.systemPackages</varname>.
+     </para>
+    </listitem>
+   </itemizedlist>
+  </section>
+
+  <section xml:id="sec-multiple-outputs-installing-nix-env">
+   <title>Selecting outputs to install via <command>nix-env</command></title>
+
+   <para>
+    <command>nix-env</command> lacks an easy way to select the outputs to install. When installing a package, <command>nix-env</command> always installs the outputs listed in <varname>meta.outputsToInstall</varname>, even when the user explicitly selects an output.
+   </para>
+
+   <warning>
     <para>
-     TODO: more about tweaking the attribute, etc.
+     <command>nix-env</command> silenty disregards the outputs selected by the user, and instead installs the outputs from <varname>meta.outputsToInstall</varname>. For example,
     </para>
-   </listitem>
-   <listitem>
+<screen><prompt>$ </prompt>nix-env -iA nixpkgs.coreutils.info</screen>
     <para>
-     NixOS provides configuration option <varname>environment.extraOutputsToInstall</varname> that allows adding extra outputs of <varname>environment.systemPackages</varname> atop the default ones. It's mainly meant for documentation and debug symbols, and it's also modified by specific options.
+     installs the <literal>"out"</literal> output (<varname>coreutils.meta.outputsToInstall</varname> is <literal>[ "out" ]</literal>) instead of the requested <literal>"info"</literal>.
     </para>
-    <note>
-     <para>
-      At this moment there is no similar configurability for packages installed by <command>nix-env</command>. You can still use approach from <xref linkend="sec-modify-via-packageOverrides" /> to override <varname>meta.outputsToInstall</varname> attributes, but that's a rather inconvenient way.
-     </para>
-    </note>
-   </listitem>
-  </itemizedlist>
+   </warning>
+
+   <para>
+    The only recourse to select an output with <command>nix-env</command> is to override the package's <varname>meta.outputsToInstall</varname>, using the functions described in <xref linkend="chap-overrides" />. For example, the following overlay adds the <literal>"info"</literal> output for the <varname>coreutils</varname> package:
+   </para>
+
+<programlisting>self: super:
+{
+  coreutils = super.coreutils.overrideAttrs (oldAttrs: {
+    meta = oldAttrs.meta // { outputsToInstall = oldAttrs.meta.outputsToInstall or [ "out" ] ++ [ "info" ]; };
+  });
+}
+</programlisting>
+  </section>
  </section>
  <section xml:id="sec-multiple-outputs-using-split-packages">
   <title>Using a split package</title>
diff --git a/nixpkgs/doc/stdenv/stdenv.xml b/nixpkgs/doc/stdenv/stdenv.xml
index ee93f39318b8..42fae73e8816 100644
--- a/nixpkgs/doc/stdenv/stdenv.xml
+++ b/nixpkgs/doc/stdenv/stdenv.xml
@@ -254,7 +254,7 @@ let f(h, h + 1, i) = i + h
 
   <variablelist>
    <title>Variables specifying dependencies</title>
-   <varlistentry>
+   <varlistentry xml:id="var-stdenv-depsBuildBuild">
     <term>
      <varname>depsBuildBuild</varname>
     </term>
@@ -267,7 +267,7 @@ let f(h, h + 1, i) = i + h
      </para>
     </listitem>
    </varlistentry>
-   <varlistentry>
+   <varlistentry xml:id="var-stdenv-nativeBuildInputs">
     <term>
      <varname>nativeBuildInputs</varname>
     </term>
@@ -280,7 +280,7 @@ let f(h, h + 1, i) = i + h
      </para>
     </listitem>
    </varlistentry>
-   <varlistentry>
+   <varlistentry xml:id="var-stdenv-depsBuildTarget">
     <term>
      <varname>depsBuildTarget</varname>
     </term>
@@ -296,7 +296,7 @@ let f(h, h + 1, i) = i + h
      </para>
     </listitem>
    </varlistentry>
-   <varlistentry>
+   <varlistentry xml:id="var-stdenv-depsHostHost">
     <term>
      <varname>depsHostHost</varname>
     </term>
@@ -306,7 +306,7 @@ let f(h, h + 1, i) = i + h
      </para>
     </listitem>
    </varlistentry>
-   <varlistentry>
+   <varlistentry xml:id="var-stdenv-buildInputs">
     <term>
      <varname>buildInputs</varname>
     </term>
@@ -319,7 +319,7 @@ let f(h, h + 1, i) = i + h
      </para>
     </listitem>
    </varlistentry>
-   <varlistentry>
+   <varlistentry xml:id="var-stdenv-depsTargetTarget">
     <term>
      <varname>depsTargetTarget</varname>
     </term>
@@ -329,7 +329,7 @@ let f(h, h + 1, i) = i + h
      </para>
     </listitem>
    </varlistentry>
-   <varlistentry>
+   <varlistentry xml:id="var-stdenv-depsBuildBuildPropagated">
     <term>
      <varname>depsBuildBuildPropagated</varname>
     </term>
@@ -339,7 +339,7 @@ let f(h, h + 1, i) = i + h
      </para>
     </listitem>
    </varlistentry>
-   <varlistentry>
+   <varlistentry xml:id="var-stdenv-propagatedNativeBuildInputs">
     <term>
      <varname>propagatedNativeBuildInputs</varname>
     </term>
@@ -349,7 +349,7 @@ let f(h, h + 1, i) = i + h
      </para>
     </listitem>
    </varlistentry>
-   <varlistentry>
+   <varlistentry xml:id="var-stdenv-depsBuildTargetPropagated">
     <term>
      <varname>depsBuildTargetPropagated</varname>
     </term>
@@ -359,7 +359,7 @@ let f(h, h + 1, i) = i + h
      </para>
     </listitem>
    </varlistentry>
-   <varlistentry>
+   <varlistentry xml:id="var-stdenv-depsHostHostPropagated">
     <term>
      <varname>depsHostHostPropagated</varname>
     </term>
@@ -369,7 +369,7 @@ let f(h, h + 1, i) = i + h
      </para>
     </listitem>
    </varlistentry>
-   <varlistentry>
+   <varlistentry xml:id="var-stdenv-propagatedBuildInputs">
     <term>
      <varname>propagatedBuildInputs</varname>
     </term>
@@ -379,7 +379,7 @@ let f(h, h + 1, i) = i + h
      </para>
     </listitem>
    </varlistentry>
-   <varlistentry>
+   <varlistentry xml:id="var-stdenv-depsTargetTargetPropagated">
     <term>
      <varname>depsTargetTargetPropagated</varname>
     </term>
@@ -396,7 +396,7 @@ let f(h, h + 1, i) = i + h
 
   <variablelist>
    <title>Variables affecting <literal>stdenv</literal> initialisation</title>
-   <varlistentry>
+   <varlistentry xml:id="var-stdenv-NIX_DEBUG">
     <term>
      <varname>NIX_DEBUG</varname>
     </term>
@@ -410,7 +410,7 @@ let f(h, h + 1, i) = i + h
 
   <variablelist>
    <title>Attributes affecting build properties</title>
-   <varlistentry>
+   <varlistentry xml:id="var-stdenv-enableParallelBuilding">
     <term>
      <varname>enableParallelBuilding</varname>
     </term>
@@ -427,7 +427,7 @@ let f(h, h + 1, i) = i + h
 
   <variablelist>
    <title>Special variables</title>
-   <varlistentry>
+   <varlistentry xml:id="var-stdenv-passthru">
     <term>
      <varname>passthru</varname>
     </term>
@@ -504,7 +504,7 @@ passthru.updateScript = [ ../../update.sh pname "--requested-release=unstable" ]
     There are a number of variables that control what phases are executed and in what order:
     <variablelist>
      <title>Variables affecting phase control</title>
-     <varlistentry>
+     <varlistentry xml:id="var-stdenv-phases">
       <term>
        <varname>phases</varname>
       </term>
@@ -517,7 +517,7 @@ passthru.updateScript = [ ../../update.sh pname "--requested-release=unstable" ]
        </para>
       </listitem>
      </varlistentry>
-     <varlistentry>
+     <varlistentry xml:id="var-stdenv-prePhases">
       <term>
        <varname>prePhases</varname>
       </term>
@@ -527,7 +527,7 @@ passthru.updateScript = [ ../../update.sh pname "--requested-release=unstable" ]
        </para>
       </listitem>
      </varlistentry>
-     <varlistentry>
+     <varlistentry xml:id="var-stdenv-preConfigurePhases">
       <term>
        <varname>preConfigurePhases</varname>
       </term>
@@ -537,7 +537,7 @@ passthru.updateScript = [ ../../update.sh pname "--requested-release=unstable" ]
        </para>
       </listitem>
      </varlistentry>
-     <varlistentry>
+     <varlistentry xml:id="var-stdenv-preBuildPhases">
       <term>
        <varname>preBuildPhases</varname>
       </term>
@@ -547,7 +547,7 @@ passthru.updateScript = [ ../../update.sh pname "--requested-release=unstable" ]
        </para>
       </listitem>
      </varlistentry>
-     <varlistentry>
+     <varlistentry xml:id="var-stdenv-preInstallPhases">
       <term>
        <varname>preInstallPhases</varname>
       </term>
@@ -557,7 +557,7 @@ passthru.updateScript = [ ../../update.sh pname "--requested-release=unstable" ]
        </para>
       </listitem>
      </varlistentry>
-     <varlistentry>
+     <varlistentry xml:id="var-stdenv-preFixupPhases">
       <term>
        <varname>preFixupPhases</varname>
       </term>
@@ -567,7 +567,7 @@ passthru.updateScript = [ ../../update.sh pname "--requested-release=unstable" ]
        </para>
       </listitem>
      </varlistentry>
-     <varlistentry>
+     <varlistentry xml:id="var-stdenv-preDistPhases">
       <term>
        <varname>preDistPhases</varname>
       </term>
@@ -577,7 +577,7 @@ passthru.updateScript = [ ../../update.sh pname "--requested-release=unstable" ]
        </para>
       </listitem>
      </varlistentry>
-     <varlistentry>
+     <varlistentry xml:id="var-stdenv-postPhases">
       <term>
        <varname>postPhases</varname>
       </term>
@@ -635,7 +635,7 @@ passthru.updateScript = [ ../../update.sh pname "--requested-release=unstable" ]
 
    <variablelist>
     <title>Variables controlling the unpack phase</title>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-src">
      <term>
       <varname>srcs</varname> / <varname>src</varname>
      </term>
@@ -645,7 +645,7 @@ passthru.updateScript = [ ../../update.sh pname "--requested-release=unstable" ]
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-sourceRoot">
      <term>
       <varname>sourceRoot</varname>
      </term>
@@ -655,7 +655,7 @@ passthru.updateScript = [ ../../update.sh pname "--requested-release=unstable" ]
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-setSourceRoot">
      <term>
       <varname>setSourceRoot</varname>
      </term>
@@ -665,7 +665,7 @@ passthru.updateScript = [ ../../update.sh pname "--requested-release=unstable" ]
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-preUnpack">
      <term>
       <varname>preUnpack</varname>
      </term>
@@ -675,7 +675,7 @@ passthru.updateScript = [ ../../update.sh pname "--requested-release=unstable" ]
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-postUnpack">
      <term>
       <varname>postUnpack</varname>
      </term>
@@ -685,7 +685,7 @@ passthru.updateScript = [ ../../update.sh pname "--requested-release=unstable" ]
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-dontUnpack">
      <term>
       <varname>dontUnpack</varname>
      </term>
@@ -695,7 +695,7 @@ passthru.updateScript = [ ../../update.sh pname "--requested-release=unstable" ]
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-dontMakeSourcesWritable">
      <term>
       <varname>dontMakeSourcesWritable</varname>
      </term>
@@ -705,7 +705,7 @@ passthru.updateScript = [ ../../update.sh pname "--requested-release=unstable" ]
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-unpackCmd">
      <term>
       <varname>unpackCmd</varname>
      </term>
@@ -727,7 +727,7 @@ passthru.updateScript = [ ../../update.sh pname "--requested-release=unstable" ]
 
    <variablelist>
     <title>Variables controlling the patch phase</title>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-dontPatch">
      <term>
       <varname>dontPatch</varname>
      </term>
@@ -737,7 +737,7 @@ passthru.updateScript = [ ../../update.sh pname "--requested-release=unstable" ]
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-patches">
      <term>
       <varname>patches</varname>
      </term>
@@ -747,7 +747,7 @@ passthru.updateScript = [ ../../update.sh pname "--requested-release=unstable" ]
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-patchFlags">
      <term>
       <varname>patchFlags</varname>
      </term>
@@ -757,7 +757,7 @@ passthru.updateScript = [ ../../update.sh pname "--requested-release=unstable" ]
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-prePatch">
      <term>
       <varname>prePatch</varname>
      </term>
@@ -767,7 +767,7 @@ passthru.updateScript = [ ../../update.sh pname "--requested-release=unstable" ]
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-postPatch">
      <term>
       <varname>postPatch</varname>
      </term>
@@ -789,7 +789,7 @@ passthru.updateScript = [ ../../update.sh pname "--requested-release=unstable" ]
 
    <variablelist>
     <title>Variables controlling the configure phase</title>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-configureScript">
      <term>
       <varname>configureScript</varname>
      </term>
@@ -799,7 +799,7 @@ passthru.updateScript = [ ../../update.sh pname "--requested-release=unstable" ]
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-configureFlags">
      <term>
       <varname>configureFlags</varname>
      </term>
@@ -809,7 +809,7 @@ passthru.updateScript = [ ../../update.sh pname "--requested-release=unstable" ]
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-dontConfigure">
      <term>
       <varname>dontConfigure</varname>
      </term>
@@ -819,7 +819,7 @@ passthru.updateScript = [ ../../update.sh pname "--requested-release=unstable" ]
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-configureFlagsArray">
      <term>
       <varname>configureFlagsArray</varname>
      </term>
@@ -829,7 +829,7 @@ passthru.updateScript = [ ../../update.sh pname "--requested-release=unstable" ]
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-dontAddPrefix">
      <term>
       <varname>dontAddPrefix</varname>
      </term>
@@ -839,7 +839,7 @@ passthru.updateScript = [ ../../update.sh pname "--requested-release=unstable" ]
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-prefix">
      <term>
       <varname>prefix</varname>
      </term>
@@ -849,7 +849,7 @@ passthru.updateScript = [ ../../update.sh pname "--requested-release=unstable" ]
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-prefixKey">
      <term>
       <varname>prefixKey</varname>
      </term>
@@ -859,7 +859,7 @@ passthru.updateScript = [ ../../update.sh pname "--requested-release=unstable" ]
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-dontAddDisableDepTrack">
      <term>
       <varname>dontAddDisableDepTrack</varname>
      </term>
@@ -869,7 +869,7 @@ passthru.updateScript = [ ../../update.sh pname "--requested-release=unstable" ]
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-dontFixLibtool">
      <term>
       <varname>dontFixLibtool</varname>
      </term>
@@ -885,7 +885,7 @@ passthru.updateScript = [ ../../update.sh pname "--requested-release=unstable" ]
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-dontDisableStatic">
      <term>
       <varname>dontDisableStatic</varname>
      </term>
@@ -898,7 +898,7 @@ passthru.updateScript = [ ../../update.sh pname "--requested-release=unstable" ]
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-configurePlatforms">
      <term>
       <varname>configurePlatforms</varname>
      </term>
@@ -913,7 +913,7 @@ passthru.updateScript = [ ../../update.sh pname "--requested-release=unstable" ]
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-preConfigure">
      <term>
       <varname>preConfigure</varname>
      </term>
@@ -923,7 +923,7 @@ passthru.updateScript = [ ../../update.sh pname "--requested-release=unstable" ]
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-postConfigure">
      <term>
       <varname>postConfigure</varname>
      </term>
@@ -945,7 +945,7 @@ passthru.updateScript = [ ../../update.sh pname "--requested-release=unstable" ]
 
    <variablelist>
     <title>Variables controlling the build phase</title>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-dontBuild">
      <term>
       <varname>dontBuild</varname>
      </term>
@@ -955,7 +955,7 @@ passthru.updateScript = [ ../../update.sh pname "--requested-release=unstable" ]
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-makefile">
      <term>
       <varname>makefile</varname>
      </term>
@@ -965,7 +965,7 @@ passthru.updateScript = [ ../../update.sh pname "--requested-release=unstable" ]
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-makeFlags">
      <term>
       <varname>makeFlags</varname>
      </term>
@@ -983,7 +983,7 @@ makeFlags = [ "PREFIX=$(out)" ];
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-makeFlagsArray">
      <term>
       <varname>makeFlagsArray</varname>
      </term>
@@ -999,7 +999,7 @@ preBuild = ''
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-buildFlags">
      <term>
       <varname>buildFlags</varname> / <varname>buildFlagsArray</varname>
      </term>
@@ -1009,7 +1009,7 @@ preBuild = ''
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-preBuild">
      <term>
       <varname>preBuild</varname>
      </term>
@@ -1019,7 +1019,7 @@ preBuild = ''
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-postBuild">
      <term>
       <varname>postBuild</varname>
      </term>
@@ -1049,7 +1049,7 @@ preBuild = ''
 
    <variablelist>
     <title>Variables controlling the check phase</title>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-doCheck">
      <term>
       <varname>doCheck</varname>
      </term>
@@ -1067,11 +1067,11 @@ preBuild = ''
      </term>
      <listitem>
       <para>
-       See the build phase for details.
+       See the <link xlink:href="#var-stdenv-makeFlags">build phase</link> for details.
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-checkTarget">
      <term>
       <varname>checkTarget</varname>
      </term>
@@ -1081,7 +1081,7 @@ preBuild = ''
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-checkFlags">
      <term>
       <varname>checkFlags</varname> / <varname>checkFlagsArray</varname>
      </term>
@@ -1091,7 +1091,7 @@ preBuild = ''
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-checkInputs">
      <term>
       <varname>checkInputs</varname>
      </term>
@@ -1101,7 +1101,7 @@ preBuild = ''
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-preCheck">
      <term>
       <varname>preCheck</varname>
      </term>
@@ -1111,7 +1111,7 @@ preBuild = ''
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-postCheck">
      <term>
       <varname>postCheck</varname>
      </term>
@@ -1133,7 +1133,7 @@ preBuild = ''
 
    <variablelist>
     <title>Variables controlling the install phase</title>
-     <varlistentry>
+     <varlistentry xml:id="var-stdenv-dontInstall">
      <term>
        <varname>dontInstall</varname>
      </term>
@@ -1149,11 +1149,11 @@ preBuild = ''
      </term>
      <listitem>
       <para>
-       See the build phase for details.
+       See the <link xlink:href="#var-stdenv-makeFlags">build phase</link> for details.
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-installTargets">
      <term>
       <varname>installTargets</varname>
      </term>
@@ -1165,7 +1165,7 @@ installTargets = "install-bin install-doc";</programlisting>
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-installFlags">
      <term>
       <varname>installFlags</varname> / <varname>installFlagsArray</varname>
      </term>
@@ -1175,7 +1175,7 @@ installTargets = "install-bin install-doc";</programlisting>
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-preInstall">
      <term>
       <varname>preInstall</varname>
      </term>
@@ -1185,7 +1185,7 @@ installTargets = "install-bin install-doc";</programlisting>
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-postInstall">
      <term>
       <varname>postInstall</varname>
      </term>
@@ -1229,7 +1229,7 @@ installTargets = "install-bin install-doc";</programlisting>
 
    <variablelist>
     <title>Variables controlling the fixup phase</title>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-dontFixup">
      <term>
       <varname>dontFixup</varname>
      </term>
@@ -1239,7 +1239,7 @@ installTargets = "install-bin install-doc";</programlisting>
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-dontStrip">
      <term>
       <varname>dontStrip</varname>
      </term>
@@ -1249,7 +1249,7 @@ installTargets = "install-bin install-doc";</programlisting>
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-dontStripHost">
      <term>
       <varname>dontStripHost</varname>
      </term>
@@ -1259,7 +1259,7 @@ installTargets = "install-bin install-doc";</programlisting>
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-dontStripTarget">
      <term>
       <varname>dontStripTarget</varname>
      </term>
@@ -1269,7 +1269,7 @@ installTargets = "install-bin install-doc";</programlisting>
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-dontMoveSbin">
      <term>
       <varname>dontMoveSbin</varname>
      </term>
@@ -1279,7 +1279,7 @@ installTargets = "install-bin install-doc";</programlisting>
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-stripAllList">
      <term>
       <varname>stripAllList</varname>
      </term>
@@ -1289,7 +1289,7 @@ installTargets = "install-bin install-doc";</programlisting>
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-stripAllFlags">
      <term>
       <varname>stripAllFlags</varname>
      </term>
@@ -1299,7 +1299,7 @@ installTargets = "install-bin install-doc";</programlisting>
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-stripDebugList">
      <term>
       <varname>stripDebugList</varname>
      </term>
@@ -1309,7 +1309,7 @@ installTargets = "install-bin install-doc";</programlisting>
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-stripDebugFlags">
      <term>
       <varname>stripDebugFlags</varname>
      </term>
@@ -1319,7 +1319,7 @@ installTargets = "install-bin install-doc";</programlisting>
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-dontPatchELF">
      <term>
       <varname>dontPatchELF</varname>
      </term>
@@ -1329,7 +1329,7 @@ installTargets = "install-bin install-doc";</programlisting>
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-dontPatchShebangs">
      <term>
       <varname>dontPatchShebangs</varname>
      </term>
@@ -1339,7 +1339,7 @@ installTargets = "install-bin install-doc";</programlisting>
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-dontPruneLibtoolFiles">
      <term>
       <varname>dontPruneLibtoolFiles</varname>
      </term>
@@ -1349,7 +1349,7 @@ installTargets = "install-bin install-doc";</programlisting>
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-forceShare">
      <term>
       <varname>forceShare</varname>
      </term>
@@ -1359,7 +1359,7 @@ installTargets = "install-bin install-doc";</programlisting>
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-setupHook">
      <term>
       <varname>setupHook</varname>
      </term>
@@ -1370,7 +1370,7 @@ installTargets = "install-bin install-doc";</programlisting>
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-preFixup">
      <term>
       <varname>preFixup</varname>
      </term>
@@ -1380,7 +1380,7 @@ installTargets = "install-bin install-doc";</programlisting>
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-postFixup">
      <term>
       <varname>postFixup</varname>
      </term>
@@ -1419,7 +1419,7 @@ set debug-file-directory ~/.nix-profile/lib/debug
 
    <variablelist>
     <title>Variables controlling the installCheck phase</title>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-doInstallCheck">
      <term>
       <varname>doInstallCheck</varname>
      </term>
@@ -1431,7 +1431,7 @@ set debug-file-directory ~/.nix-profile/lib/debug
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-installCheckTarget">
      <term>
       <varname>installCheckTarget</varname>
      </term>
@@ -1441,7 +1441,7 @@ set debug-file-directory ~/.nix-profile/lib/debug
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-installCheckFlags">
      <term>
       <varname>installCheckFlags</varname> / <varname>installCheckFlagsArray</varname>
      </term>
@@ -1451,7 +1451,7 @@ set debug-file-directory ~/.nix-profile/lib/debug
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-installCheckInputs">
      <term>
       <varname>installCheckInputs</varname>
      </term>
@@ -1461,7 +1461,7 @@ set debug-file-directory ~/.nix-profile/lib/debug
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-preInstallCheck">
      <term>
       <varname>preInstallCheck</varname>
      </term>
@@ -1471,7 +1471,7 @@ set debug-file-directory ~/.nix-profile/lib/debug
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-postInstallCheck">
      <term>
       <varname>postInstallCheck</varname>
      </term>
@@ -1493,7 +1493,7 @@ set debug-file-directory ~/.nix-profile/lib/debug
 
    <variablelist>
     <title>Variables controlling the distribution phase</title>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-distTarget">
      <term>
       <varname>distTarget</varname>
      </term>
@@ -1503,7 +1503,7 @@ set debug-file-directory ~/.nix-profile/lib/debug
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-distFlags">
      <term>
       <varname>distFlags</varname> / <varname>distFlagsArray</varname>
      </term>
@@ -1513,7 +1513,7 @@ set debug-file-directory ~/.nix-profile/lib/debug
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-tarballs">
      <term>
       <varname>tarballs</varname>
      </term>
@@ -1523,7 +1523,7 @@ set debug-file-directory ~/.nix-profile/lib/debug
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-dontCopyDist">
      <term>
       <varname>dontCopyDist</varname>
      </term>
@@ -1533,7 +1533,7 @@ set debug-file-directory ~/.nix-profile/lib/debug
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-preDist">
      <term>
       <varname>preDist</varname>
      </term>
@@ -1543,7 +1543,7 @@ set debug-file-directory ~/.nix-profile/lib/debug
       </para>
      </listitem>
     </varlistentry>
-    <varlistentry>
+    <varlistentry xml:id="var-stdenv-postDist">
      <term>
       <varname>postDist</varname>
      </term>
@@ -1636,10 +1636,6 @@ substitute ./foo.in ./foo.out \
     --subst-var someVar
 </programlisting>
      </para>
-     <para>
-      <function>substitute</function> is implemented using the <command
-      xlink:href="http://replace.richardlloyd.org.uk/">replace</command> command. Unlike with the <command>sed</command> command, you don’t have to worry about escaping special characters. It supports performing substitutions on binary files (such as executables), though there you’ll probably want to make sure that the replacement string is as long as the replaced string.
-     </para>
     </listitem>
    </varlistentry>
    <varlistentry xml:id='fun-substituteInPlace'>
@@ -2019,6 +2015,9 @@ addEnvHooks "$hostOffset" myBashFunction
        In certain situations you may want to run the main command (<command>autoPatchelf</command>) of the setup hook on a file or a set of directories instead of unconditionally patching all outputs. This can be done by setting the <varname>dontAutoPatchelf</varname> environment variable to a non-empty value.
       </para>
       <para>
+       By default <command>autoPatchelf</command> will fail as soon as any ELF file requires a dependency which cannot be resolved via the given build inputs. In some situations you might prefer to just leave missing dependencies unpatched and continue to patch the rest. This can be achieved by setting the <envar>autoPatchelfIgnoreMissingDeps</envar> environment variable to a non-empty value.
+      </para>
+      <para>
        The <command>autoPatchelf</command> command also recognizes a <parameter class="command">--no-recurse</parameter> command line flag, which prevents it from recursing into subdirectories.
       </para>
      </listitem>
diff --git a/nixpkgs/doc/using/configuration.xml b/nixpkgs/doc/using/configuration.xml
index f19eddb58686..3e21b0e22843 100644
--- a/nixpkgs/doc/using/configuration.xml
+++ b/nixpkgs/doc/using/configuration.xml
@@ -66,7 +66,7 @@
    <listitem>
     <para>
      For allowing the build of a broken package once, you can use an environment variable for a single invocation of the nix tools:
-<programlisting>$ export NIXPKGS_ALLOW_BROKEN=1</programlisting>
+<screen><prompt>$ </prompt>export NIXPKGS_ALLOW_BROKEN=1</screen>
     </para>
    </listitem>
    <listitem>
@@ -85,19 +85,19 @@
   <title>Installing packages on unsupported systems</title>
 
   <para>
-   There are also two ways to try compiling a package which has been marked as unsuported for the given system.
+   There are also two ways to try compiling a package which has been marked as unsupported for the given system.
   </para>
 
   <itemizedlist>
    <listitem>
     <para>
-     For allowing the build of a broken package once, you can use an environment variable for a single invocation of the nix tools:
-<programlisting>$ export NIXPKGS_ALLOW_UNSUPPORTED_SYSTEM=1</programlisting>
+     For allowing the build of an unsupported package once, you can use an environment variable for a single invocation of the nix tools:
+<screen><prompt>$ </prompt>export NIXPKGS_ALLOW_UNSUPPORTED_SYSTEM=1</screen>
     </para>
    </listitem>
    <listitem>
     <para>
-     For permanently allowing broken packages to be built, you may add <literal>allowUnsupportedSystem = true;</literal> to your user's configuration file, like this:
+     For permanently allowing unsupported packages to be built, you may add <literal>allowUnsupportedSystem = true;</literal> to your user's configuration file, like this:
 <programlisting>
 {
   allowUnsupportedSystem = true;
@@ -122,7 +122,7 @@
    <listitem>
     <para>
      To temporarily allow all unfree packages, you can use an environment variable for a single invocation of the nix tools:
-<programlisting>$ export NIXPKGS_ALLOW_UNFREE=1</programlisting>
+<screen><prompt>$ </prompt>export NIXPKGS_ALLOW_UNFREE=1</screen>
     </para>
    </listitem>
    <listitem>
@@ -162,10 +162,10 @@
 </programlisting>
     </para>
     <para>
-     The following example configuration blacklists the <literal>gpl3</literal> and <literal>agpl3</literal> licenses:
+     The following example configuration blacklists the <literal>gpl3Only</literal> and <literal>agpl3Only</literal> licenses:
 <programlisting>
 {
-  blacklistedLicenses = with stdenv.lib.licenses; [ agpl3 gpl3 ];
+  blacklistedLicenses = with stdenv.lib.licenses; [ agpl3Only gpl3Only ];
 }
 </programlisting>
     </para>
@@ -187,7 +187,7 @@
    <listitem>
     <para>
      To temporarily allow all insecure packages, you can use an environment variable for a single invocation of the nix tools:
-<programlisting>$ export NIXPKGS_ALLOW_INSECURE=1</programlisting>
+<screen><prompt>$ </prompt>export NIXPKGS_ALLOW_INSECURE=1</screen>
     </para>
    </listitem>
    <listitem>
diff --git a/nixpkgs/doc/using/overlays.xml b/nixpkgs/doc/using/overlays.xml
index 3fa68e32a3c5..4937e9508857 100644
--- a/nixpkgs/doc/using/overlays.xml
+++ b/nixpkgs/doc/using/overlays.xml
@@ -178,26 +178,54 @@ self: super:
          <para>
            <link
            xlink:href="https://software.intel.com/en-us/mkl">Intel
-           MKL</link> (only works on x86 architecture, unfree)
+           MKL</link> (only works on the x86_64 architecture, unfree)
          </para>
          <para>
            The Nixpkgs attribute is <literal>mkl</literal>.
          </para>
        </listitem>
+       <listitem>
+         <para>
+           <link
+           xlink:href="https://github.com/flame/blis">BLIS</link>
+         </para>
+         <para>
+          BLIS, available through the attribute
+          <literal>blis</literal>, is a framework for linear algebra kernels. In
+          addition, it implements the BLAS interface.
+         </para>
+       </listitem>
+       <listitem>
+         <para>
+          <link
+           xlink:href="https://developer.amd.com/amd-aocl/blas-library/">AMD
+          BLIS/LIBFLAME</link> (optimized for modern AMD x86_64 CPUs)
+         </para>
+         <para>
+          The AMD fork of the BLIS library, with attribute
+          <literal>amd-blis</literal>, extends BLIS with optimizations for
+          modern AMD CPUs. The changes are usually submitted to
+          the upstream BLIS project after some time. However, AMD BLIS
+          typically provides some performance improvements on AMD Zen CPUs.
+          The complementary AMD LIBFLAME library, with attribute
+          <literal>amd-libflame</literal>, provides a LAPACK implementation.
+         </para>
+       </listitem>
      </itemizedlist>
      <para>
        Introduced in <link
        xlink:href="https://github.com/NixOS/nixpkgs/pull/83888">PR
-       #83888</link>, we are able to override the ‘blas’ and ‘lapack’
-       packages to use different implementations, through the
-       ‘blasProvider’ and ‘lapackProvider’ argument. This can be used
+       #83888</link>, we are able to override the <literal>blas</literal>
+       and <literal>lapack</literal> packages to use different implementations,
+       through the <literal>blasProvider</literal> and
+       <literal>lapackProvider</literal> argument. This can be used
        to select a different provider. BLAS providers will have
        symlinks in <literal>$out/lib/libblas.so.3</literal> and
        <literal>$out/lib/libcblas.so.3</literal> to their respective
        BLAS libraries. Likewise, LAPACK providers will have symlinks
        in <literal>$out/lib/liblapack.so.3</literal> and
        <literal>$out/lib/liblapacke.so.3</literal> to their respective
-       LAPCK libraries. For example, Intel MKL is both a BLAS and
+       LAPACK libraries. For example, Intel MKL is both a BLAS and
        LAPACK provider. An overlay can be created to use Intel MKL
        that looks like:
      </para>
@@ -212,16 +240,17 @@ self: super:
     lapackProvider = self.mkl;
   }
 }
-     </programlisting>
+</programlisting>
      <para>
        This overlay uses Intel’s MKL library for both BLAS and LAPACK
        interfaces. Note that the same can be accomplished at runtime
-       using <literal>LD_LIBRARY_PATH</literal> of libblas.so.3 and
-       liblapack.so.3. For instance:
+       using <literal>LD_LIBRARY_PATH</literal> of
+       <literal>libblas.so.3</literal> and
+       <literal>liblapack.so.3</literal>. For instance:
      </para>
-     <programlisting>
-$ LD_LIBRARY_PATH=$(nix-build -A mkl)/lib:$LD_LIBRARY_PATH nix-shell -p octave --run octave
-     </programlisting>
+<screen>
+<prompt>$ </prompt>LD_LIBRARY_PATH=$(nix-build -A mkl)/lib:$LD_LIBRARY_PATH nix-shell -p octave --run octave
+</screen>
      <para>
        Intel MKL requires an <literal>openmp</literal> implementation
        when running with multiple processors. By default,
@@ -259,7 +288,7 @@ assert (!blas.isILP64) &amp;&amp; (!lapack.isILP64);
 stdenv.mkDerivation {
   ...
 }
-     </programlisting>
+</programlisting>
    </section>
  </section>
 </chapter>
author	Alyssa Ross <hi@alyssa.is>	2021-01-10 07:13:44 +0000
committer	Alyssa Ross <hi@alyssa.is>	2021-01-12 14:07:16 +0000
commit	e2698550456abba83c6dcd5d5e5a9990a0b96f8a (patch)
tree	79a56f0df3fa55e470d84b4dff6059fbf487ec18 /nixpkgs/doc
parent	1cdc42df888dc98c347e03bd942ed9825a55bcb3 (diff)
parent	84d74ae9c9cbed73274b8e4e00be14688ffc93fe (diff)
download	nixlib-e2698550456abba83c6dcd5d5e5a9990a0b96f8a.tar nixlib-e2698550456abba83c6dcd5d5e5a9990a0b96f8a.tar.gz nixlib-e2698550456abba83c6dcd5d5e5a9990a0b96f8a.tar.bz2 nixlib-e2698550456abba83c6dcd5d5e5a9990a0b96f8a.tar.lz nixlib-e2698550456abba83c6dcd5d5e5a9990a0b96f8a.tar.xz nixlib-e2698550456abba83c6dcd5d5e5a9990a0b96f8a.tar.zst nixlib-e2698550456abba83c6dcd5d5e5a9990a0b96f8a.zip