Merge commit '683c68232e91f76386db979c461d8fbe2a018782'

14 files changed, 306 insertions, 141 deletions

diff --git a/nixpkgs/doc/contributing/quick-start.xml b/nixpkgs/doc/contributing/quick-start.xml
index 8e4e914d4511..09d60834ec29 100644
--- a/nixpkgs/doc/contributing/quick-start.xml
+++ b/nixpkgs/doc/contributing/quick-start.xml
@@ -111,7 +111,7 @@
     </para>
     <para>
      The exact syntax and semantics of the Nix expression language, including the built-in function, are described in the Nix manual in the <link
-    xlink:href="http://hydra.nixos.org/job/nix/trunk/tarball/latest/download-by-type/doc/manual/#chap-writing-nix-expressions">chapter on writing Nix expressions</link>.
+    xlink:href="https://hydra.nixos.org/job/nix/trunk/tarball/latest/download-by-type/doc/manual/#chap-writing-nix-expressions">chapter on writing Nix expressions</link>.
     </para>
    </listitem>
    <listitem>
diff --git a/nixpkgs/doc/contributing/submitting-changes.xml b/nixpkgs/doc/contributing/submitting-changes.xml
index 73222c1a49ac..a88965f5cc60 100644
--- a/nixpkgs/doc/contributing/submitting-changes.xml
+++ b/nixpkgs/doc/contributing/submitting-changes.xml
@@ -407,23 +407,47 @@ Additional information.
   <section xml:id="submitting-changes-stable-release-branches">
    <title>Stable release branches</title>
 
-   <itemizedlist>
+   <para>
+    For cherry-picking a commit to a stable release branch (<quote>backporting</quote>), use <literal>git cherry-pick -x &lt;original commit&gt;</literal> so that the original commit id is included in the commit.
+   </para>
+
+   <para>
+    Add a reason for the backport by using <literal>git cherry-pick -xe &lt;original commit&gt;</literal> instead when it is not obvious from the original commit message. It is not needed when it’s a minor version update that includes security and bug fixes but don’t add new features or when the commit fixes an otherwise broken package.
+   </para>
+
+   <para>
+    Here is an example of a cherry-picked commit message with good reason description:
+   </para>
+
+<screen>
+zfs: Keep trying root import until it works
+
+Works around #11003.
+
+(cherry picked from commit 98b213a11041af39b39473906b595290e2a4e2f9)
+
+Reason: several people cannot boot with ZFS on NVMe
+</screen>
+
+   <para>
+    Other examples of reasons are:
+   </para>
+
+   <itemizedlist spacing="compact">
     <listitem>
      <para>
-      If you're cherry-picking a commit to a stable release branch (“backporting”), always use <command>git cherry-pick -xe</command> and ensure the message contains a clear description about why this needs to be included in the stable branch.
+      Previously the build would fail due to, e.g., <literal>getaddrinfo</literal> not being defined
      </para>
+    </listitem>
+    <listitem>
      <para>
-      An example of a cherry-picked commit would look like this:
+      The previous download links were all broken
+     </para>
+    </listitem>
+    <listitem>
+     <para>
+      Crash when starting on some X11 systems
      </para>
-<screen>
-nixos: Refactor the world.
-
-The original commit message describing the reason why the world was torn apart.
-
-(cherry picked from commit abcdef)
-Reason: I just had a gut feeling that this would also be wanted by people from
-the stone age.
-</screen>
     </listitem>
    </itemizedlist>
   </section>
diff --git a/nixpkgs/doc/languages-frameworks/android.section.md b/nixpkgs/doc/languages-frameworks/android.section.md
index 6ee450eeb59f..1a8924082bfb 100644
--- a/nixpkgs/doc/languages-frameworks/android.section.md
+++ b/nixpkgs/doc/languages-frameworks/android.section.md
@@ -167,7 +167,7 @@ parameters that the SDK composition function (the function shown in the
 previous section) supports.
 
 This build function is particularly useful when it is desired to use
-[Hydra](http://nixos.org/hydra): the Nix-based continuous integration solution
+[Hydra](https://nixos.org/hydra): the Nix-based continuous integration solution
 to build Android apps. An Android APK gets exposed as a build product and can be
 installed on any Android device with a web browser by navigating to the build
 result page.
diff --git a/nixpkgs/doc/languages-frameworks/gnome.xml b/nixpkgs/doc/languages-frameworks/gnome.xml
index 7671714d8a9b..159216ca981f 100644
--- a/nixpkgs/doc/languages-frameworks/gnome.xml
+++ b/nixpkgs/doc/languages-frameworks/gnome.xml
@@ -40,6 +40,23 @@
    </para>
   </section>
 
+  <section xml:id="ssec-icon-theme-packaging">
+    <title>Packaging icon themes</title>
+
+    <para>
+      Icon themes may inherit from other icon themes. The inheritance is specified using the <literal>Inherits</literal> key in the <filename>index.theme</filename> file distributed with the icon theme. According to the <link xlink:href="https://specifications.freedesktop.org/icon-theme-spec/icon-theme-spec-latest.html">icon theme specification</link>, icons not provided by the theme are looked for in its parent icon themes. Therefore the parent themes should be installed as dependencies for a more complete experience regarding the icon sets used.
+    </para>
+
+    <para>
+      The package <package>hicolor-icon-theme</package> provides a setup hook which makes symbolic links for the parent themes into the directory <filename>share/icons</filename> of the current theme directory in the nix store, making sure they can be found at runtime. For that to work the packages providing parent icon themes should be listed as propagated build dependencies, together with <package>hicolor-icon-theme</package>.
+    </para>
+
+    <para>
+      Also make sure that <filename>icon-theme.cache</filename> is installed for each theme provided by the package, and set <code>dontDropIconThemeCache</code> to <code>true</code> so that the cache file is not removed by the <package>gtk3</package> setup hook.
+    </para>
+
+  </section>
+
   <section xml:id="ssec-gnome-themes">
    <title>GTK Themes</title>
 
diff --git a/nixpkgs/doc/languages-frameworks/go.xml b/nixpkgs/doc/languages-frameworks/go.xml
index 84b146532b14..70c135555ea4 100644
--- a/nixpkgs/doc/languages-frameworks/go.xml
+++ b/nixpkgs/doc/languages-frameworks/go.xml
@@ -192,18 +192,6 @@ deis = buildGoPackage rec {
   </para>
 
   <para>
-   <varname>buildGoPackage</varname> produces <xref linkend='chap-multiple-output' xrefstyle="select: title" /> where <varname>bin</varname> includes program binaries. You can test build a Go binary as follows:
-<screen>
-<prompt>$ </prompt>nix-build -A deis.bin
-</screen>
-   or build all outputs with:
-<screen>
-<prompt>$ </prompt>nix-build -A deis.all
-</screen>
-   <varname>bin</varname> output will be installed by default with <varname>nix-env -i</varname> or <varname>systemPackages</varname>.
-  </para>
-
-  <para>
    You may use Go packages installed into the active Nix profiles by adding the following to your ~/.bashrc:
 <screen>
 for p in $NIX_PROFILES; do
diff --git a/nixpkgs/doc/languages-frameworks/haskell.section.md b/nixpkgs/doc/languages-frameworks/haskell.section.md
index 733e75c16a79..cba4d0561b07 100644
--- a/nixpkgs/doc/languages-frameworks/haskell.section.md
+++ b/nixpkgs/doc/languages-frameworks/haskell.section.md
@@ -103,15 +103,13 @@ command displays the complete list of available compilers:
 $ nix-env -f "<nixpkgs>" -qaP -A haskell.compiler
 haskell.compiler.ghc8101                 ghc-8.10.1
 haskell.compiler.integer-simple.ghc8101  ghc-8.10.1
-haskell.compiler.ghcHEAD                 ghc-8.11.20200403
-haskell.compiler.integer-simple.ghcHEAD  ghc-8.11.20200403
+haskell.compiler.ghcHEAD                 ghc-8.11.20200505
+haskell.compiler.integer-simple.ghcHEAD  ghc-8.11.20200505
 haskell.compiler.ghc822Binary            ghc-8.2.2-binary
 haskell.compiler.ghc844                  ghc-8.4.4
 haskell.compiler.ghc863Binary            ghc-8.6.3-binary
 haskell.compiler.ghc865                  ghc-8.6.5
 haskell.compiler.integer-simple.ghc865   ghc-8.6.5
-haskell.compiler.ghc881                  ghc-8.8.1
-haskell.compiler.integer-simple.ghc881   ghc-8.8.1
 haskell.compiler.ghc882                  ghc-8.8.2
 haskell.compiler.integer-simple.ghc882   ghc-8.8.2
 haskell.compiler.ghc883                  ghc-8.8.3
diff --git a/nixpkgs/doc/languages-frameworks/index.xml b/nixpkgs/doc/languages-frameworks/index.xml
index 9364c764bbf9..a6f56d791c54 100644
--- a/nixpkgs/doc/languages-frameworks/index.xml
+++ b/nixpkgs/doc/languages-frameworks/index.xml
@@ -21,6 +21,7 @@
  <xi:include href="node.section.xml" />
  <xi:include href="ocaml.xml" />
  <xi:include href="perl.xml" />
+ <xi:include href="php.section.xml" />
  <xi:include href="python.section.xml" />
  <xi:include href="qt.xml" />
  <xi:include href="r.section.xml" />
diff --git a/nixpkgs/doc/languages-frameworks/ios.section.md b/nixpkgs/doc/languages-frameworks/ios.section.md
index 5a81795c004a..768e0690b962 100644
--- a/nixpkgs/doc/languages-frameworks/ios.section.md
+++ b/nixpkgs/doc/languages-frameworks/ios.section.md
@@ -18,7 +18,7 @@ The primary objective of this project is to use the Nix expression language to
 specify how iOS apps can be built from source code, and to automatically spawn
 iOS simulator instances for testing.
 
-This component also makes it possible to use [Hydra](http://nixos.org/hydra),
+This component also makes it possible to use [Hydra](https://nixos.org/hydra),
 the Nix-based continuous integration server to regularly build iOS apps and to
 do wireless ad-hoc installations of enterprise IPAs on iOS devices through
 Hydra.
diff --git a/nixpkgs/doc/languages-frameworks/php.section.md b/nixpkgs/doc/languages-frameworks/php.section.md
index a302a9a7f87d..763beeb59358 100644
--- a/nixpkgs/doc/languages-frameworks/php.section.md
+++ b/nixpkgs/doc/languages-frameworks/php.section.md
@@ -1,26 +1,30 @@
-# PHP
+# PHP {#sec-php}
 
-## User Guide
+## User Guide {#ssec-php-user-guide}
 
-### Using PHP
-
-#### Overview
+### Overview {#ssec-php-user-guide-overview}
 
 Several versions of PHP are available on Nix, each of which having a
 wide variety of extensions and libraries available.
 
-The attribute `php` refers to the version of PHP considered most
-stable and thoroughly tested in nixpkgs for any given release of
-NixOS. Note that while this version of PHP may not be the latest major
-release from upstream, any version of PHP supported in nixpkgs may be
-utilized by specifying the desired attribute by version, such as
-`php74`.
+The different versions of PHP that nixpkgs provides are located under
+attributes named based on major and minor version number; e.g.,
+`php74` is PHP 7.4.
 
 Only versions of PHP that are supported by upstream for the entirety
 of a given NixOS release will be included in that release of
 NixOS. See [PHP Supported
 Versions](https://www.php.net/supported-versions.php).
 
+The attribute `php` refers to the version of PHP considered most
+stable and thoroughly tested in nixpkgs for any given release of
+NixOS - not necessarily the latest major release from upstream.
+
+All available PHP attributes are wrappers around their respective
+binary PHP package and provide commonly used extensions this way. The
+real PHP 7.4 package, i.e. the unwrapped one, is available as
+`php74.unwrapped`; see the next section for more details.
+
 Interactive tools built on PHP are put in `php.packages`; composer is
 for example available at `php.packages.composer`.
 
@@ -30,39 +34,44 @@ opcache extension shipped with PHP is available at
 `php.extensions.opcache` and the third-party ImageMagick extension at
 `php.extensions.imagick`.
 
-The different versions of PHP that nixpkgs provides is located under
-attributes named based on major and minor version number; e.g.,
-`php74` is PHP 7.4 with commonly used extensions installed,
-`php74base` is the same PHP runtime without extensions.
-
-#### Installing PHP with packages
+### Installing PHP with extensions {#ssec-php-user-guide-installing-with-extensions}
 
 A PHP package with specific extensions enabled can be built using
 `php.withExtensions`. This is a function which accepts an anonymous
-function as its only argument; the function should take one argument,
-the set of all extensions, and return a list of wanted extensions. For
-example, a PHP package with the opcache and ImageMagick extensions
-enabled:
+function as its only argument; the function should accept two named
+parameters: `enabled` - a list of currently enabled extensions and
+`all` - the set of all extensions, and return a list of wanted
+extensions. For example, a PHP package with all default extensions and
+ImageMagick enabled:
 
 ```nix
-php.withExtensions (e: with e; [ imagick opcache ])
+php.withExtensions ({ enabled, all }:
+  enabled ++ [ all.imagick ])
 ```
 
-Note that this will give you a package with _only_ opcache and
-ImageMagick, none of the other extensions which are enabled by default
-in the `php` package will be available.
+To exclude some, but not all, of the default extensions, you can
+filter the `enabled` list like this:
 
-To enable building on a previous PHP package, the currently enabled
-extensions are made available in its `enabledExtensions`
-attribute. For example, to generate a package with all default
-extensions enabled, except opcache, but with ImageMagick:
+```nix
+php.withExtensions ({ enabled, all }:
+  (lib.filter (e: e != php.extensions.opcache) enabled)
+  ++ [ all.imagick ])
+```
+
+To build your list of extensions from the ground up, you can simply
+ignore `enabled`:
 
 ```nix
-php.withExtensions (e:
-  (lib.filter (e: e != php.extensions.opcache) php.enabledExtensions)
-  ++ [ e.imagick ])
+php.withExtensions ({ all, ... }: with all; [ imagick opcache ])
 ```
 
+`php.withExtensions` provides extensions by wrapping a minimal php
+base package, providing a `php.ini` file listing all extensions to be
+loaded. You can access this package through the `php.unwrapped`
+attribute; useful if you, for example, need access to the `dev`
+output. The generated `php.ini` file can be accessed through the
+`php.phpIni` attribute.
+
 If you want a PHP build with extra configuration in the `php.ini`
 file, you can use `php.buildEnv`. This function takes two named and
 optional parameters: `extensions` and `extraConfig`. `extensions`
@@ -73,19 +82,19 @@ and ImageMagick extensions enabled, and `memory_limit` set to `256M`:
 
 ```nix
 php.buildEnv {
-  extensions = e: with e; [ imagick opcache ];
+  extensions = { all, ... }: with all; [ imagick opcache ];
   extraConfig = "memory_limit=256M";
 }
 ```
 
-##### Example setup for `phpfpm`
+#### Example setup for `phpfpm` {#ssec-php-user-guide-installing-with-extensions-phpfpm}
 
 You can use the previous examples in a `phpfpm` pool called `foo` as
 follows:
 
 ```nix
 let
-  myPhp = php.withExtensions (e: with e; [ imagick opcache ]);
+  myPhp = php.withExtensions ({ all, ... }: with all; [ imagick opcache ]);
 in {
   services.phpfpm.pools."foo".phpPackage = myPhp;
 };
@@ -94,7 +103,7 @@ in {
 ```nix
 let
   myPhp = php.buildEnv {
-    extensions = e: with e; [ imagick opcache ];
+    extensions = { all, ... }: with all; [ imagick opcache ];
     extraConfig = "memory_limit=256M";
   };
 in {
@@ -102,11 +111,27 @@ in {
 };
 ```
 
-##### Example usage with `nix-shell`
+#### Example usage with `nix-shell` {#ssec-php-user-guide-installing-with-extensions-nix-shell}
 
 This brings up a temporary environment that contains a PHP interpreter
-with the extensions `imagick` and `opcache` enabled.
+with the extensions `imagick` and `opcache` enabled:
 
 ```sh
-nix-shell -p 'php.buildEnv { extensions = e: with e; [ imagick opcache ]; }'
+nix-shell -p 'php.withExtensions ({ all, ... }: with all; [ imagick opcache ])'
+```
+
+### Installing PHP packages with extensions {#ssec-php-user-guide-installing-packages-with-extensions}
+
+All interactive tools use the PHP package you get them from, so all
+packages at `php.packages.*` use the `php` package with its default
+extensions. Sometimes this default set of extensions isn't enough and
+you may want to extend it. A common case of this is the `composer`
+package: a project may depend on certain extensions and `composer`
+won't work with that project unless those extensions are loaded.
+
+Example of building `composer` with additional extensions:
+```nix
+(php.withExtensions ({ all, enabled }:
+  enabled ++ (with all; [ imagick redis ]))
+).packages.composer
 ```
diff --git a/nixpkgs/doc/languages-frameworks/python.section.md b/nixpkgs/doc/languages-frameworks/python.section.md
index f8884785e90d..00d5d0ff04cf 100644
--- a/nixpkgs/doc/languages-frameworks/python.section.md
+++ b/nixpkgs/doc/languages-frameworks/python.section.md
@@ -9,7 +9,7 @@
 Several versions of the Python interpreter are available on Nix, as well as a
 high amount of packages. The attribute `python` refers to the default
 interpreter, which is currently CPython 2.7. It is also possible to refer to
-specific versions, e.g. `python35` refers to CPython 3.5, and `pypy` refers to
+specific versions, e.g. `python38` refers to CPython 3.8, and `pypy` refers to
 the default PyPy interpreter.
 
 Python is used a lot, and in different ways. This affects also how it is
@@ -25,10 +25,10 @@ however, are in separate sets, with one set per interpreter version.
 The interpreters have several common attributes. One of these attributes is
 `pkgs`, which is a package set of Python libraries for this specific
 interpreter. E.g., the `toolz` package corresponding to the default interpreter
-is `python.pkgs.toolz`, and the CPython 3.5 version is `python35.pkgs.toolz`.
+is `python.pkgs.toolz`, and the CPython 3.8 version is `python38.pkgs.toolz`.
 The main package set contains aliases to these package sets, e.g.
-`pythonPackages` refers to `python.pkgs` and `python35Packages` to
-`python35.pkgs`.
+`pythonPackages` refers to `python.pkgs` and `python38Packages` to
+`python38.pkgs`.
 
 #### Installing Python and packages
 
@@ -50,7 +50,7 @@ to create an environment with `python.buildEnv` or `python.withPackages` where
 the interpreter and other executables are able to find each other and all of the
 modules.
 
-In the following examples we create an environment with Python 3.5, `numpy` and
+In the following examples we create an environment with Python 3.8, `numpy` and
 `toolz`. As you may imagine, there is one limitation here, and that's that
 you can install only one environment at a time. You will notice the complaints
 about collisions when you try to install a second environment.
@@ -61,7 +61,7 @@ Create a file, e.g. `build.nix`, with the following expression
 ```nix
 with import <nixpkgs> {};
 
-python35.withPackages (ps: with ps; [ numpy toolz ])
+python38.withPackages (ps: with ps; [ numpy toolz ])
 ```
 and install it in your profile with
 ```shell
@@ -79,7 +79,7 @@ Nixpkgs set, e.g. using `config.nix`,
 { # ...
 
   packageOverrides = pkgs: with pkgs; {
-    myEnv = python35.withPackages (ps: with ps; [ numpy toolz ]);
+    myEnv = python38.withPackages (ps: with ps; [ numpy toolz ]);
   };
 }
 ```
@@ -101,7 +101,7 @@ environment system-wide.
 { # ...
 
   environment.systemPackages = with pkgs; [
-    (python35.withPackages(ps: with ps; [ numpy toolz ]))
+    (python38.withPackages(ps: with ps; [ numpy toolz ]))
   ];
 }
 ```
@@ -118,7 +118,7 @@ recommended method is to create an environment with `python.buildEnv` or
 `python.withPackages` and load that. E.g.
 
 ```sh
-$ nix-shell -p 'python35.withPackages(ps: with ps; [ numpy toolz ])'
+$ nix-shell -p 'python38.withPackages(ps: with ps; [ numpy toolz ])'
 ```
 
 opens a shell from which you can launch the interpreter
@@ -131,7 +131,7 @@ The other method, which is not recommended, does not create an environment and
 requires you to list the packages directly,
 
 ```sh
-$ nix-shell -p python35.pkgs.numpy python35.pkgs.toolz
+$ nix-shell -p python38.pkgs.numpy python38.pkgs.toolz
 ```
 
 Again, it is possible to launch the interpreter from the shell. The Python
@@ -140,14 +140,14 @@ that specific interpreter.
 
 ##### Load environment from `.nix` expression
 As explained in the Nix manual, `nix-shell` can also load an
-expression from a `.nix` file. Say we want to have Python 3.5, `numpy`
+expression from a `.nix` file. Say we want to have Python 3.8, `numpy`
 and `toolz`, like before, in an environment. Consider a `shell.nix` file
 with
 
 ```nix
 with import <nixpkgs> {};
 
-(python35.withPackages (ps: [ps.numpy ps.toolz])).env
+(python38.withPackages (ps: [ps.numpy ps.toolz])).env
 ```
 
 Executing `nix-shell` gives you again a Nix shell from which you can run Python.
@@ -158,7 +158,7 @@ What's happening here?
    imports the `<nixpkgs>` function, `{}` calls it and the `with` statement
    brings all attributes of `nixpkgs` in the local scope. These attributes form
    the main package set.
-2. Then we create a Python 3.5 environment with the `withPackages` function.
+2. Then we create a Python 3.8 environment with the `withPackages` function.
 3. The `withPackages` function expects us to provide a function as an argument
    that takes the set of all python packages and returns a list of packages to
    include in the environment. Here, we select the packages `numpy` and `toolz`
@@ -170,7 +170,7 @@ To combine this with `mkShell` you can:
 with import <nixpkgs> {};
 
 let
-  pythonEnv = python35.withPackages (ps: [
+  pythonEnv = python38.withPackages (ps: [
     ps.numpy
     ps.toolz
   ]);
@@ -188,13 +188,13 @@ option, with which you can execute a command in the `nix-shell`. We can
 e.g. directly open a Python shell
 
 ```sh
-$ nix-shell -p python35Packages.numpy python35Packages.toolz --run "python3"
+$ nix-shell -p python38Packages.numpy python38Packages.toolz --run "python3"
 ```
 
 or run a script
 
 ```sh
-$ nix-shell -p python35Packages.numpy python35Packages.toolz --run "python3 myscript.py"
+$ nix-shell -p python38Packages.numpy python38Packages.toolz --run "python3 myscript.py"
 ```
 
 ##### `nix-shell` as shebang
@@ -231,11 +231,11 @@ building Python libraries is `buildPythonPackage`. Let's see how we can build th
 
 buildPythonPackage rec {
   pname = "toolz";
-  version = "0.7.4";
+  version = "0.10.0";
 
   src = fetchPypi {
     inherit pname version;
-    sha256 = "43c2c9e5e7a16b6c88ba3088a9bfc82f7db8e13378be7c78d6c14a5f8ed05afd";
+    sha256 = "08fdd5ef7c96480ad11c12d472de21acd32359996f69a5259299b540feba4560";
   };
 
   doCheck = false;
@@ -260,8 +260,8 @@ information. The output of the function is a derivation.
 
 An expression for `toolz` can be found in the Nixpkgs repository. As explained
 in the introduction of this Python section, a derivation of `toolz` is available
-for each interpreter version, e.g. `python35.pkgs.toolz` refers to the `toolz`
-derivation corresponding to the CPython 3.5 interpreter.
+for each interpreter version, e.g. `python38.pkgs.toolz` refers to the `toolz`
+derivation corresponding to the CPython 3.8 interpreter.
 The above example works when you're directly working on
 `pkgs/top-level/python-packages.nix` in the Nixpkgs repository. Often though,
 you will want to test a Nix expression outside of the Nixpkgs tree.
@@ -273,13 +273,13 @@ and adds it along with a `numpy` package to a Python environment.
 with import <nixpkgs> {};
 
 ( let
-    my_toolz = python35.pkgs.buildPythonPackage rec {
+    my_toolz = python38.pkgs.buildPythonPackage rec {
       pname = "toolz";
-      version = "0.7.4";
+      version = "0.10.0";
 
-      src = python35.pkgs.fetchPypi {
+      src = python38.pkgs.fetchPypi {
         inherit pname version;
-        sha256 = "43c2c9e5e7a16b6c88ba3088a9bfc82f7db8e13378be7c78d6c14a5f8ed05afd";
+        sha256 = "08fdd5ef7c96480ad11c12d472de21acd32359996f69a5259299b540feba4560";
       };
 
       doCheck = false;
@@ -290,12 +290,12 @@ with import <nixpkgs> {};
       };
     };
 
-  in python35.withPackages (ps: [ps.numpy my_toolz])
+  in python38.withPackages (ps: [ps.numpy my_toolz])
 ).env
 ```
 
 Executing `nix-shell` will result in an environment in which you can use
-Python 3.5 and the `toolz` package. As you can see we had to explicitly mention
+Python 3.8 and the `toolz` package. As you can see we had to explicitly mention
 for which Python version we want to build a package.
 
 So, what did we do here? Well, we took the Nix expression that we used earlier
@@ -435,7 +435,7 @@ If we create a `shell.nix` file which calls `buildPythonPackage`, and if `src`
 is a local source, and if the local source has a `setup.py`, then development
 mode is activated.
 
-In the following example we create a simple environment that has a Python 3.5
+In the following example we create a simple environment that has a Python 3.8
 version of our package in it, as well as its dependencies and other packages we
 like to have in the environment, all specified with `propagatedBuildInputs`.
 Indeed, we can just add any package we like to have in our environment to
@@ -443,7 +443,7 @@ Indeed, we can just add any package we like to have in our environment to
 
 ```nix
 with import <nixpkgs> {};
-with python35Packages;
+with python38Packages;
 
 buildPythonPackage rec {
   name = "mypackage";
@@ -505,9 +505,9 @@ with import <nixpkgs> {};
 
 ( let
     toolz = callPackage /path/to/toolz/release.nix {
-      buildPythonPackage = python35Packages.buildPythonPackage;
+      buildPythonPackage = python38Packages.buildPythonPackage;
     };
-  in python35.withPackages (ps: [ ps.numpy toolz ])
+  in python38.withPackages (ps: [ ps.numpy toolz ])
 ).env
 ```
 
@@ -515,8 +515,8 @@ Important to remember is that the Python version for which the package is made
 depends on the `python` derivation that is passed to `buildPythonPackage`. Nix
 tries to automatically pass arguments when possible, which is why generally you
 don't explicitly define which `python` derivation should be used. In the above
-example we use `buildPythonPackage` that is part of the set `python35Packages`,
-and in this case the `python35` interpreter is automatically used.
+example we use `buildPythonPackage` that is part of the set `python38Packages`,
+and in this case the `python38` interpreter is automatically used.
 
 ## Reference
 
@@ -662,7 +662,7 @@ following are specific to `buildPythonPackage`:
   variables which will be available when the binary is run. For example,
   `makeWrapperArgs = ["--set FOO BAR" "--set BAZ QUX"]`.
 * `namePrefix`: Prepends text to `${name}` parameter. In case of libraries, this
-  defaults to `"python3.5-"` for Python 3.5, etc., and in case of applications
+  defaults to `"python3.8-"` for Python 3.8, etc., and in case of applications
   to `""`.
 * `pythonPath ? []`: List of packages to be added into `$PYTHONPATH`. Packages
   in `pythonPath` are not propagated (contrary to `propagatedBuildInputs`).
@@ -960,7 +960,7 @@ has security implications and is relevant for those using Python in a
 
 When the environment variable `DETERMINISTIC_BUILD` is set, all bytecode will
 have timestamp 1. The `buildPythonPackage` function sets `DETERMINISTIC_BUILD=1`
-and [PYTHONHASHSEED=0](https://docs.python.org/3.5/using/cmdline.html#envvar-PYTHONHASHSEED).
+and [PYTHONHASHSEED=0](https://docs.python.org/3.8/using/cmdline.html#envvar-PYTHONHASHSEED).
 Both are also exported in `nix-shell`.
 
 
@@ -1014,7 +1014,7 @@ with import <nixpkgs> {};
     packageOverrides = self: super: {
       pandas = super.pandas.overridePythonAttrs(old: {name="foo";});
     };
-  in pkgs.python35.override {inherit packageOverrides;};
+  in pkgs.python38.override {inherit packageOverrides;};
 
 in python.withPackages(ps: [ps.pandas])).env
 ```
@@ -1036,7 +1036,7 @@ with import <nixpkgs> {};
     packageOverrides = self: super: {
       scipy = super.scipy_0_17;
     };
-  in (pkgs.python35.override {inherit packageOverrides;}).withPackages (ps: [ps.blaze])
+  in (pkgs.python38.override {inherit packageOverrides;}).withPackages (ps: [ps.blaze])
 ).env
 ```
 
@@ -1049,12 +1049,12 @@ If you want the whole of Nixpkgs to use your modifications, then you can use
 ```nix
 let
   pkgs = import <nixpkgs> {};
-  newpkgs = import pkgs.path { overlays = [ (pkgsself: pkgssuper: {
-    python27 = let
-      packageOverrides = self: super: {
-        numpy = super.numpy_1_10;
+  newpkgs = import pkgs.path { overlays = [ (self: super: {
+    python38 = let
+      packageOverrides = python-self: python-super: {
+        numpy = python-super.numpy_1_18.3;
       };
-    in pkgssuper.python27.override {inherit packageOverrides;};
+    in super.python38.override {inherit packageOverrides;};
   } ) ]; };
 in newpkgs.inkscape
 ```
@@ -1290,32 +1290,9 @@ self: super: {
 
 ### How to use Intel's MKL with numpy and scipy?
 
-A `site.cfg` is created that configures BLAS based on the `blas` parameter of
-the `numpy` derivation. By passing in `mkl`, `numpy` and packages depending on
-`numpy` will be built with `mkl`.
-
-The following is an overlay that configures `numpy` to use `mkl`:
-
-```nix
-self: super: {
-  python37 = super.python37.override {
-    packageOverrides = python-self: python-super: {
-      numpy = python-super.numpy.override {
-        blas = super.pkgs.mkl;
-      };
-    };
-  };
-}
-```
-
-`mkl` requires an `openmp` implementation when running with multiple processors.
-By default, `mkl` will use Intel's `iomp` implementation if no other is
-specified, but this is a runtime-only dependency and binary compatible with the
-LLVM implementation. To use that one instead, Intel recommends users set it with
-`LD_PRELOAD`.
-
-Note that `mkl` is only available on `x86_64-{linux,darwin}` platforms;
-moreover, Hydra is not building and distributing pre-compiled binaries using it.
+MKL can be configured using an overlay. See the section “[Using
+overlays to configure
+alternatives](#sec-overlays-alternatives-blas-lapack)”.
 
 ### What inputs do `setup_requires`, `install_requires` and `tests_require` map to?
 
diff --git a/nixpkgs/doc/preface.chapter.md b/nixpkgs/doc/preface.chapter.md
index 7fa65ab11021..549e42de7aa0 100644
--- a/nixpkgs/doc/preface.chapter.md
+++ b/nixpkgs/doc/preface.chapter.md
@@ -42,7 +42,7 @@ distributed as soon as all tests for that channel pass, e.g.
 [this table](https://hydra.nixos.org/job/nixpkgs/trunk/unstable#tabs-constituents)
 shows the status of tests for the `nixpkgs` channel.
 
-The tests are conducted by a cluster called [Hydra](http://nixos.org/hydra/),
+The tests are conducted by a cluster called [Hydra](https://nixos.org/hydra/),
 which also builds binary packages from the Nix expressions in Nixpkgs for
 `x86_64-linux`, `i686-linux` and `x86_64-darwin`.
 The binaries are made available via a [binary cache](https://cache.nixos.org).
diff --git a/nixpkgs/doc/release-notes.xml b/nixpkgs/doc/release-notes.xml
index 7575289e7559..a15f54667290 100644
--- a/nixpkgs/doc/release-notes.xml
+++ b/nixpkgs/doc/release-notes.xml
@@ -286,7 +286,7 @@ export NIX_MIRRORS_sourceforge=http://osdn.dl.sourceforge.net/sourceforge/</prog
   <note>
    <para>
     This release of Nixpkgs requires <link
-xlink:href='http://nixos.org/releases/nix/nix-0.10/'>Nix 0.10</link> or higher.
+xlink:href='https://nixos.org/releases/nix/nix-0.10/'>Nix 0.10</link> or higher.
    </para>
   </note>
 
@@ -436,7 +436,7 @@ stdenv.mkDerivation {
    <listitem>
     <para>
      Distribution files have been moved to <link
-  xlink:href="http://nixos.org/" />.
+  xlink:href="https://nixos.org/" />.
     </para>
    </listitem>
    <listitem>
diff --git a/nixpkgs/doc/stdenv/stdenv.xml b/nixpkgs/doc/stdenv/stdenv.xml
index e4cbdd4abb57..65a343d7edd8 100644
--- a/nixpkgs/doc/stdenv/stdenv.xml
+++ b/nixpkgs/doc/stdenv/stdenv.xml
@@ -145,7 +145,7 @@ genericBuild
     </listitem>
     <listitem>
      <para>
-      GNU Make. It has been patched to provide <quote>nested</quote> output that can be fed into the <command>nix-log2xml</command> command and <command>log2html</command> stylesheet to create a structured, readable output of the build steps performed by Make.
+      GNU Make.
      </para>
     </listitem>
     <listitem>
@@ -729,6 +729,16 @@ passthru.updateScript = [ ../../update.sh pname "--requested-release=unstable" ]
     <title>Variables controlling the patch phase</title>
     <varlistentry>
      <term>
+      <varname>dontPatch</varname>
+     </term>
+     <listitem>
+      <para>
+       Set to true to skip the patch phase.
+      </para>
+     </listitem>
+    </varlistentry>
+    <varlistentry>
+     <term>
       <varname>patches</varname>
      </term>
      <listitem>
diff --git a/nixpkgs/doc/using/overlays.xml b/nixpkgs/doc/using/overlays.xml
index 26a888368abf..3fa68e32a3c5 100644
--- a/nixpkgs/doc/using/overlays.xml
+++ b/nixpkgs/doc/using/overlays.xml
@@ -137,4 +137,129 @@ self: super:
    Overlays are similar to other methods for customizing Nixpkgs, in particular the <literal>packageOverrides</literal> attribute described in <xref linkend="sec-modify-via-packageOverrides"/>. Indeed, <literal>packageOverrides</literal> acts as an overlay with only the <varname>super</varname> argument. It is therefore appropriate for basic use, but overlays are more powerful and easier to distribute.
   </para>
  </section>
+ <section xml:id="sec-overlays-alternatives">
+   <title>Using overlays to configure alternatives</title>
+   <para>
+     Certain software packages have different implementations of the
+     same interface. Other distributions have functionality to switch
+     between these. For example, Debian provides <link
+     xlink:href="https://wiki.debian.org/DebianAlternatives">DebianAlternatives</link>.
+     Nixpkgs has what we call <literal>alternatives</literal>, which
+     are configured through overlays.
+   </para>
+   <section xml:id="sec-overlays-alternatives-blas-lapack">
+     <title>BLAS/LAPACK</title>
+     <para>
+       In Nixpkgs, we have multiple implementations of the BLAS/LAPACK
+       numerical linear algebra interfaces. They are:
+     </para>
+     <itemizedlist>
+       <listitem>
+         <para>
+           <link xlink:href="https://www.openblas.net/">OpenBLAS</link>
+         </para>
+         <para>
+           The Nixpkgs attribute is <literal>openblas</literal> for
+           ILP64 (integer width = 64 bits) and
+           <literal>openblasCompat</literal> for LP64 (integer width =
+           32 bits). <literal>openblasCompat</literal> is the default.
+         </para>
+       </listitem>
+       <listitem>
+         <para>
+           <link xlink:href="http://www.netlib.org/lapack/">LAPACK
+           reference</link> (also provides BLAS)
+         </para>
+         <para>
+           The Nixpkgs attribute is <literal>lapack-reference</literal>.
+         </para>
+       </listitem>
+       <listitem>
+         <para>
+           <link
+           xlink:href="https://software.intel.com/en-us/mkl">Intel
+           MKL</link> (only works on x86 architecture, unfree)
+         </para>
+         <para>
+           The Nixpkgs attribute is <literal>mkl</literal>.
+         </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
+       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 provider. An overlay can be created to use Intel MKL
+       that looks like:
+     </para>
+     <programlisting>
+self: super:
+
+{
+  blas = super.blas.override {
+    blasProvider = self.mkl;
+  }
+  lapack = super.lapack.override {
+    lapackProvider = self.mkl;
+  }
+}
+     </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:
+     </para>
+     <programlisting>
+$ LD_LIBRARY_PATH=$(nix-build -A mkl)/lib:$LD_LIBRARY_PATH nix-shell -p octave --run octave
+     </programlisting>
+     <para>
+       Intel MKL requires an <literal>openmp</literal> implementation
+       when running with multiple processors. By default,
+       <literal>mkl</literal> will use Intel’s <literal>iomp</literal>
+       implementation if no other is specified, but this is a
+       runtime-only dependency and binary compatible with the LLVM
+       implementation. To use that one instead, Intel recommends users
+       set it with <literal>LD_PRELOAD</literal>. Note that
+       <literal>mkl</literal> is only available on
+       <literal>x86_64-linux</literal> and
+       <literal>x86_64-darwin</literal>. Moreover, Hydra is not
+       building and distributing pre-compiled binaries using it.
+     </para>
+     <para>
+       For BLAS/LAPACK switching to work correctly, all packages must
+       depend on <literal>blas</literal> or <literal>lapack</literal>.
+       This ensures that only one BLAS/LAPACK library is used at one
+       time. There are two versions versions of BLAS/LAPACK currently
+       in the wild, <literal>LP64</literal> (integer size = 32 bits)
+       and <literal>ILP64</literal> (integer size = 64 bits). Some
+       software needs special flags or patches to work with
+       <literal>ILP64</literal>. You can check if
+       <literal>ILP64</literal> is used in Nixpkgs with
+       <varname>blas.isILP64</varname> and
+       <varname>lapack.isILP64</varname>. Some software does NOT work
+       with <literal>ILP64</literal>, and derivations need to specify
+       an assertion to prevent this. You can prevent
+       <literal>ILP64</literal> from being used with the following:
+     </para>
+     <programlisting>
+{ stdenv, blas, lapack, ... }:
+
+assert (!blas.isILP64) &amp;&amp; (!lapack.isILP64);
+
+stdenv.mkDerivation {
+  ...
+}
+     </programlisting>
+   </section>
+ </section>
 </chapter>