Merge commit '0f5ce2fac0c726036ca69a5524c59a49e2973dd4'

19 files changed, 667 insertions, 308 deletions

diff --git a/nixpkgs/doc/builders/images/appimagetools.xml b/nixpkgs/doc/builders/images/appimagetools.xml
index 0767a509a43..45c5619abd9 100644
--- a/nixpkgs/doc/builders/images/appimagetools.xml
+++ b/nixpkgs/doc/builders/images/appimagetools.xml
@@ -63,7 +63,7 @@ type2.AppImage: ELF 64-bit LSB executable, x86-64, version 1 (SYSV) (Lepton 3.x)
 appimageTools.wrapType2 { # or wrapType1
   name = "patchwork"; <co xml:id='ex-appimageTools-wrapping-1' />
   src = fetchurl { <co xml:id='ex-appimageTools-wrapping-2' />
-    url = https://github.com/ssbc/patchwork/releases/download/v3.11.4/Patchwork-3.11.4-linux-x86_64.AppImage;
+    url = "https://github.com/ssbc/patchwork/releases/download/v3.11.4/Patchwork-3.11.4-linux-x86_64.AppImage";
     sha256 =  "1blsprpkvm0ws9b96gb36f0rbf8f5jgmw4x6dsb1kswr4ysf591s";
   };
   extraPkgs = pkgs: with pkgs; [ ]; <co xml:id='ex-appimageTools-wrapping-3' />
diff --git a/nixpkgs/doc/contributing/quick-start.xml b/nixpkgs/doc/contributing/quick-start.xml
index 8e4e914d451..09d60834ec2 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 73222c1a49a..a88965f5cc6 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/agda.section.md b/nixpkgs/doc/languages-frameworks/agda.section.md
new file mode 100644
index 00000000000..7a5dc767b7c
--- /dev/null
+++ b/nixpkgs/doc/languages-frameworks/agda.section.md
@@ -0,0 +1,96 @@
+---
+title: Agda
+author: Alex Rice (alexarice)
+date: 2020-01-06
+---
+# Agda
+
+## How to use Agda
+
+Agda can be installed from `agda`:
+```
+$ nix-env -iA agda
+```
+
+To use agda with libraries, the `agda.withPackages` function can be used. This function either takes:
++ A list of packages,
++ or a function which returns a list of packages when given the `agdaPackages` attribute set,
++ or an attribute set containing a list of packages and a GHC derivation for compilation (see below).
+
+For example, suppose we wanted a version of agda which has access to the standard library. This can be obtained with the expressions:
+
+```
+agda.withPackages [ agdaPackages.standard-library ]
+```
+
+or
+
+```
+agda.withPackages (p: [ p.standard-library ])
+```
+
+or can be called as in the [Compiling Agda](#compiling-agda) section.
+
+If you want to use a library in your home directory (for instance if it is a development version) then typecheck it manually (using `agda.withPackages` if necessary) and then override the `src` attribute of the package to point to your local repository.
+
+Agda will not by default use these libraries. To tell agda to use the library we have some options:
+- Call `agda` with the library flag:
+```
+$ agda -l standard-library -i . MyFile.agda
+```
+- Write a `my-library.agda-lib` file for the project you are working on which may look like:
+```
+name: my-library
+include: .
+depends: standard-library
+```
+- Create the file `~/.agda/defaults` and add any libraries you want to use by default.
+
+More information can be found in the [official Agda documentation on library management](https://agda.readthedocs.io/en/v2.6.1/tools/package-system.html).
+
+## Compiling Agda
+Agda modules can be compiled with the `--compile` flag. A version of `ghc` with `ieee` is made available to the Agda program via the `--with-compiler` flag.
+This can be overridden by a different version of `ghc` as follows:
+
+```
+agda.withPackages {
+  pkgs = [ ... ];
+  ghc = haskell.compiler.ghcHEAD;
+}
+```
+
+## Writing Agda packages
+To write a nix derivation for an agda library, first check that the library has a `*.agda-lib` file.
+
+A derivation can then be written using `agdaPackages.mkDerivation`. This has similar arguments to `stdenv.mkDerivation` with the following additions:
++ `everythingFile` can be used to specify the location of the `Everything.agda` file, defaulting to `./Everything.agda`. If this file does not exist then either it should be patched in or the `buildPhase` should be overridden (see below).
++ `libraryName` should be the name that appears in the `*.agda-lib` file, defaulting to `pname`.
++ `libraryFile` should be the file name of the `*.agda-lib` file, defaulting to `${libraryName}.agda-lib`.
+
+The build phase for `agdaPackages.mkDerivation` simply runs `agda` on the `Everything.agda` file. If something else is needed to build the package (e.g. `make`) then the `buildPhase` should be overridden (or a `preBuild` or `configurePhase` can be used if there are steps that need to be done prior to checking the `Everything.agda` file). `agda` and the Agda libraries contained in `buildInputs` are made available during the build phase. The install phase simply copies all `.agda`, `.agdai` and `.agda-lib` files to the output directory. Again, this can be overridden.
+
+To add an agda package to `nixpkgs`, the derivation should be written to `pkgs/development/libraries/agda/${library-name}/` and an entry should be added to `pkgs/top-level/agda-packages.nix`. Here it is called in a scope with access to all other agda libraries, so the top line of the `default.nix` can look like:
+```
+{ mkDerivation, standard-library, fetchFromGitHub }:
+```
+and `mkDerivation` should be called instead of `agdaPackages.mkDerivation`. Here is an example skeleton derivation for iowa-stdlib:
+
+```
+mkDerivation {
+  version = "1.5.0";
+  pname = "iowa-stdlib";
+
+  src = ...
+
+  libraryFile = "";
+  libraryName = "IAL-1.3";
+
+  buildPhase = ''
+    patchShebangs find-deps.sh
+    make
+  '';
+}
+```
+This library has a file called `.agda-lib`, and so we give an empty string to `libraryFile` as nothing precedes `.agda-lib` in the filename. This file contains `name: IAL-1.3`, and so we let `libraryName =  "IAL-1.3"`. This library does not use an `Everything.agda` file and instead has a Makefile, so there is no need to set `everythingFile` and we set a custom `buildPhase`.
+
+When writing an agda package it is essential to make sure that no `.agda-lib` file gets added to the store as a single file (for example by using `writeText`). This causes agda to think that the nix store is a agda library and it will attempt to write to it whenever it typechecks something. See [https://github.com/agda/agda/issues/4613](https://github.com/agda/agda/issues/4613).
diff --git a/nixpkgs/doc/languages-frameworks/android.section.md b/nixpkgs/doc/languages-frameworks/android.section.md
index 6ee450eeb59..1a8924082bf 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 7671714d8a9..159216ca981 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 84b146532b1..ff39276f640 100644
--- a/nixpkgs/doc/languages-frameworks/go.xml
+++ b/nixpkgs/doc/languages-frameworks/go.xml
@@ -36,7 +36,7 @@ pet = buildGoModule rec {
     sha256 = "0m2fzpqxk7hrbxsgqplkg7h2p7gv6s1miymv3gvw0cz039skag0s";
   };
 
-  modSha256 = "1879j77k96684wi554rkjxydrj8g3hpp0kvxz03sd8dmwr3lh83j"; <co xml:id='ex-buildGoModule-1' />
+  vendorSha256 = "1879j77k96684wi554rkjxydrj8g3hpp0kvxz03sd8dmwr3lh83j"; <co xml:id='ex-buildGoModule-1' />
 
   subPackages = [ "." ]; <co xml:id='ex-buildGoModule-2' />
 
@@ -56,7 +56,7 @@ pet = buildGoModule rec {
    <calloutlist>
     <callout arearefs='ex-buildGoModule-1'>
      <para>
-      <varname>modSha256</varname> is the hash of the output of the intermediate fetcher derivation.
+      <varname>vendorSha256</varname> is the hash of the output of the intermediate fetcher derivation.
      </para>
     </callout>
     <callout arearefs='ex-buildGoModule-2'>
@@ -68,12 +68,12 @@ pet = buildGoModule rec {
   </para>
 
   <para>
-    <varname>modSha256</varname> can also take <varname>null</varname> as an input.
+    <varname>vendorSha256</varname> can also take <varname>null</varname> as an input.
 
-    When `null` is used as a value, the derivation won't be a
-    fixed-output derivation but disable the build sandbox instead. This can be useful outside
-    of nixpkgs where re-generating the modSha256 on each mod.sum changes is cumbersome,
-    but will fail to build by Hydra, as builds with a disabled sandbox are discouraged.
+    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>
 
@@ -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 54ba8e4786d..cba4d0561b0 100644
--- a/nixpkgs/doc/languages-frameworks/haskell.section.md
+++ b/nixpkgs/doc/languages-frameworks/haskell.section.md
@@ -101,17 +101,15 @@ to compile your Haskell packages with any GHC version you please. The following
 command displays the complete list of available compilers:
 ```
 $ nix-env -f "<nixpkgs>" -qaP -A haskell.compiler
-haskell.compiler.ghc8101                 ghc-8.10.0.20191210
-haskell.compiler.integer-simple.ghc8101  ghc-8.10.0.20191210
-haskell.compiler.ghcHEAD                 ghc-8.10.20191119
-haskell.compiler.integer-simple.ghcHEAD  ghc-8.10.20191119
+haskell.compiler.ghc8101                 ghc-8.10.1
+haskell.compiler.integer-simple.ghc8101  ghc-8.10.1
+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 9364c764bbf..2414956995c 100644
--- a/nixpkgs/doc/languages-frameworks/index.xml
+++ b/nixpkgs/doc/languages-frameworks/index.xml
@@ -5,6 +5,7 @@
  <para>
   The <link linkend="chap-stdenv">standard build environment</link> makes it easy to build typical Autotools-based packages with very little code. Any other kind of package can be accomodated by overriding the appropriate phases of <literal>stdenv</literal>. However, there are specialised functions in Nixpkgs to easily build packages for other programming languages, such as Perl or Haskell. These are described in this chapter.
  </para>
+ <xi:include href="agda.section.xml" />
  <xi:include href="android.section.xml" />
  <xi:include href="beam.xml" />
  <xi:include href="bower.xml" />
@@ -21,6 +22,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 5a81795c004..768e0690b96 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 a302a9a7f87..763beeb5935 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 650ed342858..838426afa04 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
 
@@ -36,121 +36,191 @@ The Nix and NixOS manuals explain how packages are generally installed. In the
 case of Python and Nix, it is important to make a distinction between whether the
 package is considered an application or a library.
 
-Applications on Nix are typically installed into your user
-profile imperatively using `nix-env -i`, and on NixOS declaratively by adding the
-package name to `environment.systemPackages` in `/etc/nixos/configuration.nix`.
-Dependencies such as libraries are automatically installed and should not be
-installed explicitly.
+Applications on Nix are typically installed into your user profile imperatively
+using `nix-env -i`, and on NixOS declaratively by adding the package name to
+`environment.systemPackages` in `/etc/nixos/configuration.nix`. Dependencies
+such as libraries are automatically installed and should not be installed
+explicitly.
 
-The same goes for Python applications and libraries. Python applications can be
-installed in your profile. But Python libraries you would like to use for
-development cannot be installed, at least not individually, because they won't
-be able to find each other resulting in import errors. Instead, it is possible
-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.
+The same goes for Python applications. Python applications can be installed in
+your profile, and will be wrapped to find their exact library dependencies,
+without impacting other applications or polluting your user environment.
 
-In the following examples we create an environment with Python 3.5, `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.
+But Python libraries you would like to use for development cannot be installed,
+at least not individually, because they won't be able to find each other
+resulting in import errors. Instead, it is possible to create an environment
+with `python.buildEnv` or `python.withPackages` where the interpreter and other
+executables are wrapped to be able to find each other and all of the modules.
 
-##### Environment defined in separate `.nix` file
+In the following examples we will start by creating a simple, ad-hoc environment
+with a nix-shell that has `numpy` and `toolz` in Python 3.8; then we will create
+a re-usable environment in a single-file Python script; then we will create a
+full Python environment for development with this same environment.
 
-Create a file, e.g. `build.nix`, with the following expression
-```nix
-with import <nixpkgs> {};
-
-python35.withPackages (ps: with ps; [ numpy toolz ])
-```
-and install it in your profile with
-```shell
-nix-env -if build.nix
-```
-Now you can use the Python interpreter, as well as the extra packages (`numpy`,
-`toolz`) that you added to the environment.
+Philosphically, this should be familiar to users who are used to a `venv` style
+of development: individual projects create their own Python environments without
+impacting the global environment or each other.
 
-##### Environment defined in `~/.config/nixpkgs/config.nix`
+#### Ad-hoc temporary Python environment with `nix-shell`
 
-If you prefer you could also add the environment as a package override to the
-Nixpkgs set, e.g. using `config.nix`,
+The simplest way to start playing with the way nix wraps and sets up Python
+environments is with `nix-shell` at the cmdline. These environments create a
+temporary shell session with a Python and a *precise* list of packages (plus
+their runtime dependencies), with no other Python packages in the Python
+interpreter's scope.
 
-```nix
-{ # ...
+To create a Python 3.8 session with `numpy` and `toolz` available, run:
 
-  packageOverrides = pkgs: with pkgs; {
-    myEnv = python35.withPackages (ps: with ps; [ numpy toolz ]);
-  };
-}
+```sh
+$ nix-shell -p 'python38.withPackages(ps: with ps; [ numpy toolz ])'
 ```
-and install it in your profile with
 
-```shell
-nix-env -iA nixpkgs.myEnv
+By default `nix-shell` will start a `bash` session with this interpreter in our
+`PATH`, so if we then run:
+
+```
+[nix-shell:~/src/nixpkgs]$ python3
+Python 3.8.1 (default, Dec 18 2019, 19:06:26)
+[GCC 9.2.0] on linux
+Type "help", "copyright", "credits" or "license" for more information.
+>>> import numpy; import toolz
 ```
 
-The environment is is installed by referring to the attribute, and considering
-the `nixpkgs` channel was used.
+Note that no other modules are in scope, even if they were imperatively
+installed into our user environment as a dependency of a Python application:
 
-##### Environment defined in `/etc/nixos/configuration.nix`
-
-For the sake of completeness, here's another example how to install the
-environment system-wide.
+```
+>>> import requests
+Traceback (most recent call last):
+  File "<stdin>", line 1, in <module>
+ModuleNotFoundError: No module named 'requests'
+```
 
-```nix
-{ # ...
+We can add as many additional modules onto the `nix-shell` as we need, and we
+will still get 1 wrapped Python interpreter. We can start the interpreter
+directly like so:
 
-  environment.systemPackages = with pkgs; [
-    (python35.withPackages(ps: with ps; [ numpy toolz ]))
-  ];
-}
+```sh
+$ nix-shell -p 'python38.withPackages(ps: with ps; [ numpy toolz requests ])' --run python3
+these derivations will be built:
+  /nix/store/xbdsrqrsfa1yva5s7pzsra8k08gxlbz1-python3-3.8.1-env.drv
+building '/nix/store/xbdsrqrsfa1yva5s7pzsra8k08gxlbz1-python3-3.8.1-env.drv'...
+created 277 symlinks in user environment
+Python 3.8.1 (default, Dec 18 2019, 19:06:26)
+[GCC 9.2.0] on linux
+Type "help", "copyright", "credits" or "license" for more information.
+>>> import requests
+>>>
 ```
 
-#### Temporary Python environment with `nix-shell`
+Notice that this time it built a new Python environment, which now includes
+`requests`. Building an environment just creates wrapper scripts that expose the
+selected dependencies to the interpreter while re-using the actual modules. This
+means if any other env has installed `requests` or `numpy` in a different
+context, we don't need to recompile them -- we just recompile the wrapper script
+that sets up an interpreter pointing to them. This matters much more for "big"
+modules like `pytorch` or `tensorflow`.
+
+Module names usually match their names on [pypi.org](https://pypi.org/), but
+you can use the [Nixpkgs search website](https://nixos.org/nixos/packages.html)
+to find them as well (along with non-python packages).
+
+At this point we can create throwaway experimental Python environments with
+arbitrary dependencies. This is a good way to get a feel for how the Python
+interpreter and dependencies work in Nix and NixOS, but to do some actual
+development, we'll want to make it a bit more persistent.
+
+##### Running Python scripts and using `nix-shell` as shebang
+
+Sometimes, we have a script whose header looks like this:
+
+```python
+#!/usr/bin/env python3
+import numpy as np
+a = np.array([1,2])
+b = np.array([3,4])
+print(f"The dot product of {a} and {b} is: {np.dot(a, b)}")
+```
 
-The examples in the previous section showed how to install a Python environment
-into a profile. For development you may need to use multiple environments.
-`nix-shell` gives the possibility to temporarily load another environment, akin
-to `virtualenv`.
+Executing this script requires a `python3` that has `numpy`. Using what we learned
+in the previous section, we could startup a shell and just run it like so:
 
-There are two methods for loading a shell with Python packages. The first and
-recommended method is to create an environment with `python.buildEnv` or
-`python.withPackages` and load that. E.g.
+```
+nix-shell -p 'python38.withPackages(ps: with ps; [ numpy ])' --run 'python3 foo.py'
+The dot product of [1 2] and [3 4] is: 11
+```
 
-```sh
-$ nix-shell -p 'python35.withPackages(ps: with ps; [ numpy toolz ])'
+But if we maintain the script ourselves, and if there are more dependencies, it
+may be nice to encode those dependencies in source to make the script re-usable
+without that bit of knowledge. That can be done by using `nix-shell` as a
+[shebang](https://en.wikipedia.org/wiki/Shebang_(Unix), like so:
+
+```python
+#!/usr/bin/env nix-shell
+#!nix-shell -i python3 -p "python3.withPackages(ps: [ ps.numpy ])"
+import numpy as np
+a = np.array([1,2])
+b = np.array([3,4])
+print(f"The dot product of {a} and {b} is: {np.dot(a, b)}")
 ```
 
-opens a shell from which you can launch the interpreter
+Then we simply execute it, without requiring any environment setup at all!
 
 ```sh
-[nix-shell:~] python3
+$ ./foo.py
+The dot product of [1 2] and [3 4] is: 11
 ```
 
-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
+If the dependencies are not available on the host where `foo.py` is executed, it
+will build or download them from a Nix binary cache prior to starting up, prior
+that it is executed on a machine with a multi-user nix installation.
+
+This provides a way to ship a self bootstrapping Python script, akin to a
+statically linked binary, where it can be run on any machine (provided nix is
+installed) without having to assume that `numpy` is installed globally on the
+system.
+
+By default it is pulling the import checkout of Nixpkgs itself from our nix
+channel, which is nice as it cache aligns with our other package builds, but we
+can make it fully reproducible by pinning the `nixpkgs` import:
+
+```python
+#!/usr/bin/env nix-shell
+#!nix-shell -i python3 -p "python3.withPackages(ps: [ ps.numpy ])"
+#!nix-shell -I nixpkgs=https://github.com/NixOS/nixpkgs/archive/d373d80b1207d52621961b16aa4a3438e4f98167.tar.gz
+import numpy as np
+a = np.array([1,2])
+b = np.array([3,4])
+print(f"The dot product of {a} and {b} is: {np.dot(a, b)}")
 ```
 
-Again, it is possible to launch the interpreter from the shell. The Python
-interpreter has the attribute `pkgs` which contains all Python libraries for
-that specific interpreter.
+This will execute with the exact same versions of Python 3.8, numpy, and system
+dependencies a year from now as it does today, because it will always use
+exactly git commit `d373d80b1207d52621961b16aa4a3438e4f98167` of Nixpkgs for all
+of the package versions.
+
+This is also a great way to ensure the script executes identically on different
+servers.
 
 ##### 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`
-and `toolz`, like before, in an environment. Consider a `shell.nix` file
-with
+
+We've now seen how to create an ad-hoc temporary shell session, and how to
+create a single script with Python dependencies, but in the course of normal
+development we're usually working in an entire package repository.
+
+As explained in the Nix manual, `nix-shell` can also load an expression from a
+`.nix` file. Say we want to have Python 3.8, `numpy` and `toolz`, like before,
+in an environment. We can add a `shell.nix` file describing our dependencies:
 
 ```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.
+And then at the command line, just typing `nix-shell` produces the same
+environment as before. In a normal project, we'll likely have many more
+dependencies; this can provide a way for developers to share the environments
+with each other and with CI builders.
 
 What's happening here?
 
@@ -158,9 +228,9 @@ 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, as before.
 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
+   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`
    from the package set.
 
@@ -168,59 +238,106 @@ To combine this with `mkShell` you can:
 
 ```nix
 with import <nixpkgs> {};
-
 let
-  pythonEnv = python35.withPackages (ps: [
+  pythonEnv = python38.withPackages (ps: [
     ps.numpy
     ps.toolz
   ]);
 in mkShell {
   buildInputs = [
     pythonEnv
-    hello
+
+    black
+    mypy
+
+    libffi
+    openssl
   ];
 }
 ```
 
-##### Execute command with `--run`
-A convenient option with `nix-shell` is the `--run`
-option, with which you can execute a command in the `nix-shell`. We can
-e.g. directly open a Python shell
+This will create a unified environment that has not just our Python interpreter
+and its Python dependencies, but also tools like `black` or `mypy` and libraries
+like `libffi` the `openssl` in scope. This is generic and can span any number of
+tools or languages across the Nixpkgs ecosystem.
 
-```sh
-$ nix-shell -p python35Packages.numpy python35Packages.toolz --run "python3"
+##### Installing environments globally on the system
+
+Up to now, we've been creating environments scoped to an ad-hoc shell session,
+or a single script, or a single project. This is generally advisable, as it
+avoids pollution across contexts.
+
+However, sometimes we know we will often want a Python with some basic packages,
+and want this available without having to enter into a shell or build context.
+This can be useful to have things like vim/emacs editors and plugins or shell
+tools "just work" without having to set them up, or when running other software
+that expects packages to be installed globally.
+
+To create your own custom environment, create a file in `~/.config/nixpkgs/overlays/`
+that looks like this:
+
+```nix
+# ~/.config/nixpkgs/overlays/myEnv.nix
+self: super: {
+  myEnv = super.buildEnv {
+    name = "myEnv";
+    paths = [
+      # A Python 3 interpreter with some packages
+      (self.python3.withPackages (
+        ps: with ps; [
+          pyflakes
+          pytest
+          python-language-server
+        ]
+      ))
+
+      # Some other packages we'd like as part of this env
+      self.mypy
+      self.black
+      self.ripgrep
+      self.tmux
+    ];
+  };
+}
 ```
 
-or run a script
+You can then build and install this to your profile with:
 
 ```sh
-$ nix-shell -p python35Packages.numpy python35Packages.toolz --run "python3 myscript.py"
+nix-env -iA myEnv
 ```
 
-##### `nix-shell` as shebang
-In fact, for the second use case, there is a more convenient method. You can add
-a [shebang](https://en.wikipedia.org/wiki/Shebang_(Unix)) to your script
-specifying which dependencies `nix-shell` needs. With the following shebang, you
-can just execute `./myscript.py`, and it will make available all dependencies
-and run the script in the `python3` shell.
+One limitation of this is that you can only have 1 Python env installed
+globally, since they conflict on the `python` to load out of your `PATH`.
 
-```py
-#! /usr/bin/env nix-shell
-#! nix-shell -i python3 -p "python3.withPackages(ps: [ps.numpy])"
+If you get a conflict or prefer to keep the setup clean, you can have `nix-env`
+atomically *uninstall* all other imperatively installed packages and replace
+your profile with just `myEnv` by using the `--replace` flag.
 
-import numpy
+##### Environment defined in `/etc/nixos/configuration.nix`
 
-print(numpy.__version__)
+For the sake of completeness, here's how to install the environment system-wide
+on NixOS.
+
+```nix
+{ # ...
+
+  environment.systemPackages = with pkgs; [
+    (python38.withPackages(ps: with ps; [ numpy toolz ]))
+  ];
+}
 ```
 
 ### Developing with Python
 
-Now that you know how to get a working Python environment with Nix, it is time
-to go forward and start actually developing with Python. We will first have a
-look at how Python packages are packaged on Nix. Then, we will look at how you
-can use development mode with your code.
+Above, we were mostly just focused on use cases and what to do to get started
+creating working Python environments in nix.
 
-#### Packaging a library
+Now that you know the basics to be up and running, it is time to take a step
+back and take a deeper look at at how Python packages are packaged on Nix. Then,
+we will look at how you can use development mode with your code.
+
+#### Python library packages in Nixpkgs
 
 With Nix all packages are built by functions. The main function in Nix for
 building Python libraries is `buildPythonPackage`. Let's see how we can build the
@@ -231,11 +348,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 +377,9 @@ 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 +391,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 +408,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
@@ -312,7 +430,7 @@ Our example, `toolz`, does not have any dependencies on other Python packages or
 system libraries. According to the manual, `buildPythonPackage` uses the
 arguments `buildInputs` and `propagatedBuildInputs` to specify dependencies. If
 something is exclusively a build-time dependency, then the dependency should be
-included as a `buildInput`, but if it is (also) a runtime dependency, then it
+included in `buildInputs`, but if it is (also) a runtime dependency, then it
 should be added to `propagatedBuildInputs`. Test dependencies are considered
 build-time dependencies and passed to `checkInputs`.
 
@@ -412,7 +530,7 @@ buildPythonPackage rec {
 
   meta = with lib; {
     description = "A pythonic wrapper around FFTW, the FFT library, presenting a unified interface for all the supported transforms";
-    homepage = http://hgomersall.github.com/pyFFTW;
+    homepage = "http://hgomersall.github.com/pyFFTW";
     license = with licenses; [ bsd2 bsd3 ];
     maintainers = with maintainers; [ fridh ];
   };
@@ -423,10 +541,11 @@ Note also the line `doCheck = false;`, we explicitly disabled running the test-s
 
 #### 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 creates a special link to the project code.
-That way, you can run updated code without having to reinstall after each and every change you make.
-Development mode is also available. Let's see how you can use it.
+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
+creates a special link to the project code. That way, you can run updated code
+without having to reinstall after each and every change you make. Development
+mode is also available. Let's see how you can use it.
 
 In the previous Nix expression the source was fetched from an url. We can also
 refer to a local source instead using `src = ./path/to/source/tree;`
@@ -435,7 +554,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 +562,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";
@@ -455,7 +574,6 @@ buildPythonPackage rec {
 It is important to note that due to how development mode is implemented on Nix
 it is not possible to have multiple packages simultaneously in development mode.
 
-
 ### Organising your packages
 
 So far we discussed how you can use Python on Nix, and how you can develop with
@@ -481,11 +599,11 @@ We first create a function that builds `toolz` in `~/path/to/toolz/release.nix`
 
 buildPythonPackage rec {
   pname = "toolz";
-  version = "0.7.4";
+  version = "0.10.0";
 
   src = fetchPypi {
     inherit pname version;
-    sha256 = "43c2c9e5e7a16b6c88ba3088a9bfc82f7db8e13378be7c78d6c14a5f8ed05afd";
+    sha256 = "08fdd5ef7c96480ad11c12d472de21acd32359996f69a5259299b540feba4560";
   };
 
   meta = with lib; {
@@ -497,17 +615,17 @@ buildPythonPackage rec {
 }
 ```
 
-It takes an argument `buildPythonPackage`.
-We now call this function using `callPackage` in the definition of our environment
+It takes an argument `buildPythonPackage`. We now call this function using
+`callPackage` in the definition of our environment
 
 ```nix
 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 +633,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
 
@@ -548,7 +666,7 @@ Each interpreter has the following attributes:
 - `buildEnv`. Function to build python interpreter environments with extra packages bundled together. See section *python.buildEnv function* for usage and documentation.
 - `withPackages`. Simpler interface to `buildEnv`. See section *python.withPackages function* for usage and documentation.
 - `sitePackages`. Alias for `lib/${libPrefix}/site-packages`.
-- `executable`. Name of the interpreter executable, e.g. `python3.7`.
+- `executable`. Name of the interpreter executable, e.g. `python3.8`.
 - `pkgs`. Set of Python packages for that specific interpreter. The package set can be modified by overriding the interpreter and passing `packageOverrides`.
 
 ### Building packages and applications
@@ -643,7 +761,7 @@ following are specific to `buildPythonPackage`:
   appears more than once in dependency tree. Default is `true`.
 * `disabled` ? false: If `true`, package is not built for the particular Python
   interpreter version.
-* `dontWrapPythonPrograms ? false`: Skip wrapping of python programs.
+* `dontWrapPythonPrograms ? false`: Skip wrapping of Python programs.
 * `permitUserSite ? false`: Skip setting the `PYTHONNOUSERSITE` environment
   variable in wrapped programs.
 * `installFlags ? []`: A list of strings. Arguments to be passed to `pip
@@ -662,7 +780,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`).
@@ -730,7 +848,7 @@ Another difference is that `buildPythonPackage` by default prefixes the names of
 the packages with the version of the interpreter. Because this is irrelevant for
 applications, the prefix is omitted.
 
-When packaging a python application with `buildPythonApplication`, it should be
+When packaging a Python application with `buildPythonApplication`, it should be
 called with `callPackage` and passed `python` or `pythonPackages` (possibly
 specifying an interpreter version), like this:
 
@@ -761,7 +879,7 @@ luigi = callPackage ../applications/networking/cluster/luigi { };
 ```
 
 Since the package is an application, a consumer doesn't need to care about
-python versions or modules, which is why they don't go in `pythonPackages`.
+Python versions or modules, which is why they don't go in `pythonPackages`.
 
 #### `toPythonApplication` function
 
@@ -875,7 +993,7 @@ thus be also written like this:
 ```nix
 with import <nixpkgs> {};
 
-(python36.withPackages (ps: [ps.numpy ps.requests])).env
+(python38.withPackages (ps: [ps.numpy ps.requests])).env
 ```
 
 In contrast to `python.buildEnv`, `python.withPackages` does not support the
@@ -905,7 +1023,8 @@ are used in `buildPythonPackage`.
 - `setuptoolsBuildHook` to build a wheel using `setuptools`.
 - `setuptoolsCheckHook` to run tests with `python setup.py test`.
 - `venvShellHook` to source a Python 3 `venv` at the `venvDir` location. A
-  `venv` is created if it does not yet exist.
+  `venv` is created if it does not yet exist. `postVenvCreation` can be used to
+  to run commands only after venv is first created.
 - `wheelUnpackHook` to move a wheel to the correct folder so it can be installed
   with the `pipInstallHook`.
 
@@ -932,7 +1051,7 @@ pythonPackages.buildPythonPackage {
 Running `nix-shell` with no arguments should give you the environment in which
 the package would be built with `nix-build`.
 
-Shortcut to setup environments with C headers/libraries and python packages:
+Shortcut to setup environments with C headers/libraries and Python packages:
 
 ```shell
 nix-shell -p pythonPackages.pyramid zlib libjpeg git
@@ -960,10 +1079,9 @@ 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`.
 
-
 ### Automatic tests
 
 It is recommended to test packages as part of the build process.
@@ -976,7 +1094,7 @@ example of such a situation is when `py.test` is used.
 #### Common issues
 
 * Non-working tests can often be deselected. By default `buildPythonPackage`
-  runs `python setup.py test`. Most python modules follows the standard test
+  runs `python setup.py test`. Most Python modules follows the standard test
   protocol where the pytest runner can be used instead. `py.test` supports a
   `-k` parameter to ignore test methods or classes:
 
@@ -1014,7 +1132,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 +1154,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 +1167,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;
       };
-    in pkgssuper.python27.override {inherit packageOverrides;};
+    in super.python38.override {inherit packageOverrides;};
   } ) ]; };
 in newpkgs.inkscape
 ```
@@ -1127,14 +1245,14 @@ If you want to create a Python environment for development, then the recommended
 method is to use `nix-shell`, either with or without the `python.buildEnv`
 function.
 
-### How to consume python modules using pip in a virtual environment like I am used to on other Operating Systems?
+### How to consume Python modules using pip in a virtual environment like I am used to on other Operating Systems?
 
 While this approach is not very idiomatic from Nix perspective, it can still be
 useful when dealing with pre-existing projects or in situations where it's not
 feasible or desired to write derivations for all required dependencies.
 
 This is an example of a `default.nix` for a `nix-shell`, which allows to consume
-a virtual environment created by `venv`, and install python modules through
+a virtual environment created by `venv`, and install Python modules through
 `pip` the traditional way.
 
 Create this `default.nix` file, together with a `requirements.txt` and simply
@@ -1149,7 +1267,7 @@ in pkgs.mkShell rec {
   name = "impurePythonEnv";
   venvDir = "./.venv";
   buildInputs = [
-    # A python interpreter including the 'venv' module is required to bootstrap
+    # A Python interpreter including the 'venv' module is required to bootstrap
     # the environment.
     pythonPackages.python
 
@@ -1163,7 +1281,7 @@ in pkgs.mkShell rec {
     pythonPackages.requests
 
     # In this particular example, in order to compile any binary extensions they may
-    # require, the python modules listed in the hypothetical requirements.txt need
+    # require, the Python modules listed in the hypothetical requirements.txt need
     # the following packages to be installed locally:
     taglib
     openssl
@@ -1174,16 +1292,23 @@ in pkgs.mkShell rec {
     zlib
   ];
 
+  # Run this command, only after creating the virtual environment
+  postVenvCreation = ''
+    unset SOURCE_DATE_EPOCH
+    pip install -r requirements.txt
+  '';
+
   # Now we can execute any commands within the virtual environment.
   # This is optional and can be left out to run pip manually.
   postShellHook = ''
-    pip install -r requirements.txt
+    # allow pip to install wheels
+    unset SOURCE_DATE_EPOCH
   '';
 
 }
 ```
 
-In case the supplied venvShellHook is insufficient, or when python 2 support is
+In case the supplied venvShellHook is insufficient, or when Python 2 support is
 needed, you can define your own shell hook and adapt to your needs like in the
 following example:
 
@@ -1229,7 +1354,7 @@ in pkgs.mkShell rec {
 ```
 
 Note that the `pip install` is an imperative action. So every time `nix-shell`
-is executed it will attempt to download the python modules listed in
+is executed it will attempt to download the Python modules listed in
 requirements.txt. However these will be cached locally within the `virtualenv`
 folder and not downloaded again.
 
@@ -1290,32 +1415,8 @@ 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/languages-frameworks/ruby.xml b/nixpkgs/doc/languages-frameworks/ruby.xml
index b28745fd6e2..9b36801fb96 100644
--- a/nixpkgs/doc/languages-frameworks/ruby.xml
+++ b/nixpkgs/doc/languages-frameworks/ruby.xml
@@ -32,7 +32,7 @@ bundlerEnv rec {
 
   meta = with lib; {
     description = "A monitoring framework that aims to be simple, malleable, and scalable";
-    homepage    = http://sensuapp.org/;
+    homepage    = "http://sensuapp.org/";
     license     = with licenses; mit;
     maintainers = with maintainers; [ theuni ];
     platforms   = platforms.unix;
@@ -69,7 +69,7 @@ bundlerApp {
 
   meta = with lib; {
     description = "Tool and libraries for maintaining Ruby gems.";
-    homepage    = https://github.com/nyarly/corundum;
+    homepage    = "https://github.com/nyarly/corundum";
     license     = licenses.mit;
     maintainers = [ maintainers.nyarly ];
     platforms   = platforms.unix;
diff --git a/nixpkgs/doc/languages-frameworks/texlive.xml b/nixpkgs/doc/languages-frameworks/texlive.xml
index 8fa8f963b2f..a581ec5911c 100644
--- a/nixpkgs/doc/languages-frameworks/texlive.xml
+++ b/nixpkgs/doc/languages-frameworks/texlive.xml
@@ -149,31 +149,4 @@ EOF
 ]]></programlisting>
   </para>
  </section>
-
- <section xml:id="sec-language-texlive-known-problems">
-  <title>Known problems</title>
-
-  <itemizedlist>
-   <listitem>
-    <para>
-     Some tools are still missing, e.g. luajittex;
-    </para>
-   </listitem>
-   <listitem>
-    <para>
-     some apps aren't packaged/tested yet (asymptote, biber, etc.);
-    </para>
-   </listitem>
-   <listitem>
-    <para>
-     feature/bug: when a package is rejected by <varname>pkgFilter</varname>, its dependencies are still propagated;
-    </para>
-   </listitem>
-   <listitem>
-    <para>
-     in case of any bugs or feature requests, file a github issue or better a pull request and /cc @vcunat.
-    </para>
-   </listitem>
-  </itemizedlist>
- </section>
 </section>
diff --git a/nixpkgs/doc/old/cross.txt b/nixpkgs/doc/old/cross.txt
index ff9fefb04a8..9dd5b4c9993 100644
--- a/nixpkgs/doc/old/cross.txt
+++ b/nixpkgs/doc/old/cross.txt
@@ -60,7 +60,7 @@ stdenv.mkDerivation {
   name = "binutils-2.16.1-arm";
   builder = ./builder.sh;
   src = fetchurl {
-    url = http://ftp.nluug.nl/gnu/binutils/binutils-2.16.1.tar.bz2;
+    url = "http://ftp.nluug.nl/gnu/binutils/binutils-2.16.1.tar.bz2";
     sha256 = "1ian3kwh2vg6hr3ymrv48s04gijs539vzrq62xr76bxbhbwnz2np";
   };
   inherit noSysDirs;
@@ -84,7 +84,7 @@ stdenv.mkDerivation {
   name = "linux-headers-2.6.13.1-arm";
   builder = ./builder.sh;
   src = fetchurl {
-    url = http://www.kernel.org/pub/linux/kernel/v2.6/linux-2.6.13.1.tar.bz2;
+    url = "http://www.kernel.org/pub/linux/kernel/v2.6/linux-2.6.13.1.tar.bz2";
     sha256 = "12qxmc827fjhaz53kjy7vyrzsaqcg78amiqsb3qm20z26w705lma";
   };
 }
diff --git a/nixpkgs/doc/preface.chapter.md b/nixpkgs/doc/preface.chapter.md
index 7fa65ab1102..549e42de7aa 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 b85f61da079..a15f5466729 100644
--- a/nixpkgs/doc/release-notes.xml
+++ b/nixpkgs/doc/release-notes.xml
@@ -190,7 +190,7 @@ preConfigure = "configureFlagsArray=(\"CFLAGS=-O0 -g\")";</programlisting>
       The function <function>fetchurl</function> now has support for two different kinds of mirroring of files. First, it has support for <emphasis>content-addressable mirrors</emphasis>. For example, given the <function>fetchurl</function> call
 <programlisting>
 fetchurl {
-  url = http://releases.mozilla.org/<replaceable>...</replaceable>/firefox-2.0.0.6-source.tar.bz2;
+  url = "http://releases.mozilla.org/<replaceable>...</replaceable>/firefox-2.0.0.6-source.tar.bz2";
   sha1 = "eb72f55e4a8bf08e8c6ef227c0ade3d068ba1082";
 }</programlisting>
       <function>fetchurl</function> will first try to download this file from <link
@@ -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 b589952743c..65a343d7edd 100644
--- a/nixpkgs/doc/stdenv/stdenv.xml
+++ b/nixpkgs/doc/stdenv/stdenv.xml
@@ -14,7 +14,7 @@
 stdenv.mkDerivation {
   name = "libfoo-1.2.3";
   src = fetchurl {
-    url = http://example.org/libfoo-1.2.3.tar.bz2;
+    url = "http://example.org/libfoo-1.2.3.tar.bz2";
     sha256 = "0x2g1jqygyr5wiwg4ma1nd7w4ydpy82z9gkcv8vh2v8dn3y58v5m";
   };
 }</programlisting>
@@ -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 26a888368ab..3fa68e32a3c 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>