Merge commit 'a2e06fc3423c4be53181b15c28dfbe0bcf67dd73'

9 files changed, 356 insertions, 162 deletions

diff --git a/nixpkgs/doc/languages-frameworks/crystal.section.md b/nixpkgs/doc/languages-frameworks/crystal.section.md
index 07bfc65a553f..af0853dbf75b 100644
--- a/nixpkgs/doc/languages-frameworks/crystal.section.md
+++ b/nixpkgs/doc/languages-frameworks/crystal.section.md
@@ -66,6 +66,6 @@ crystal.buildCrystalPackage rec {
   shardsFile = ./shards.nix;
   crystalBinaries.mint.src = "src/mint.cr";
 
-  buildInputs = [ openssl_1_0_2 ];
+  buildInputs = [ openssl ];
 }
 ```
diff --git a/nixpkgs/doc/languages-frameworks/dotnet.section.md b/nixpkgs/doc/languages-frameworks/dotnet.section.md
new file mode 100644
index 000000000000..c56f4728bed8
--- /dev/null
+++ b/nixpkgs/doc/languages-frameworks/dotnet.section.md
@@ -0,0 +1,75 @@
+# Dotnet
+
+## Local Development Workflow
+
+For local development, it's recommended to use nix-shell to create a dotnet environment:
+
+```
+# shell.nix
+with import <nixpkgs> {};
+
+mkShell {
+  name = "dotnet-env";
+  buildInputs = [
+    dotnet-sdk_3
+  ];
+}
+```
+
+### Using many sdks in a workflow
+
+It's very likely that more than one sdk will be needed on a given project. Dotnet provides several different frameworks (E.g dotnetcore, aspnetcore, etc.) as well as many versions for a given framework. Normally, dotnet is able to fetch a framework and install it relative to the executable. However, this would mean writing to the nix store in nixpkgs, which is read-only. To support the many-sdk use case, one can compose an environment using `dotnetCorePackages.combinePackages`:
+
+```
+with import <nixpkgs> {};
+
+mkShell {
+  name = "dotnet-env";
+  buildInputs = [
+    (with dotnetCorePackages; combinePackages [
+      sdk_3_1
+      sdk_3_0
+      sdk_2_1
+    ])
+  ];
+}
+```
+
+This will produce a dotnet installation that has the dotnet 3.1, 3.0, and 2.1 sdk. The first sdk listed will have it's cli utility present in the resulting environment. Example info output:
+
+```
+$ dotnet --info
+.NET Core SDK (reflecting any global.json):
+ Version:   3.1.101
+ Commit:    b377529961
+
+...
+
+.NET Core SDKs installed:
+  2.1.803 [/nix/store/iiv98i2jdi226dgh4jzkkj2ww7f8jgpd-dotnet-core-combined/sdk]
+  3.0.102 [/nix/store/iiv98i2jdi226dgh4jzkkj2ww7f8jgpd-dotnet-core-combined/sdk]
+  3.1.101 [/nix/store/iiv98i2jdi226dgh4jzkkj2ww7f8jgpd-dotnet-core-combined/sdk]
+
+.NET Core runtimes installed:
+  Microsoft.AspNetCore.All 2.1.15 [/nix/store/iiv98i2jdi226dgh4jzkkj2ww7f8jgpd-dotnet-core-combined/shared/Microsoft.AspNetCore.All]
+  Microsoft.AspNetCore.App 2.1.15 [/nix/store/iiv98i2jdi226dgh4jzkkj2ww7f8jgpd-dotnet-core-combined/shared/Microsoft.AspNetCore.App]
+  Microsoft.AspNetCore.App 3.0.2 [/nix/store/iiv98i2jdi226dgh4jzkkj2ww7f8jgpd-dotnet-core-combined/shared/Microsoft.AspNetCore.App]
+  Microsoft.AspNetCore.App 3.1.1 [/nix/store/iiv98i2jdi226dgh4jzkkj2ww7f8jgpd-dotnet-core-combined/shared/Microsoft.AspNetCore.App]
+  Microsoft.NETCore.App 2.1.15 [/nix/store/iiv98i2jdi226dgh4jzkkj2ww7f8jgpd-dotnet-core-combined/shared/Microsoft.NETCore.App]
+  Microsoft.NETCore.App 3.0.2 [/nix/store/iiv98i2jdi226dgh4jzkkj2ww7f8jgpd-dotnet-core-combined/shared/Microsoft.NETCore.App]
+  Microsoft.NETCore.App 3.1.1 [/nix/store/iiv98i2jdi226dgh4jzkkj2ww7f8jgpd-dotnet-core-combined/shared/Microsoft.NETCore.App]
+```
+
+## dotnet-sdk vs dotnetCorePackages.sdk
+
+The `dotnetCorePackages.sdk_X_Y` is preferred over the old dotnet-sdk as both major and minor version are very important for a dotnet environment. If a given minor version isn't present (or was changed), then this will likely break your ability to build a project.
+
+## dotnetCorePackages.sdk vs dotnetCorePackages.netcore vs dotnetCorePackages.aspnetcore
+
+The `dotnetCorePackages.sdk` contains both a runtime and the full sdk of a given version. The `netcore` and `aspnetcore` packages are meant to serve as minimal runtimes to deploy alongside already built applications.
+
+## Packaging a Dotnet Application
+
+Ideally, we would like to build against the sdk, then only have the dotnet runtime available in the runtime closure.
+
+TODO: Create closure-friendly way to package dotnet applications
diff --git a/nixpkgs/doc/languages-frameworks/gnome.xml b/nixpkgs/doc/languages-frameworks/gnome.xml
index bb68d026ae23..7671714d8a9b 100644
--- a/nixpkgs/doc/languages-frameworks/gnome.xml
+++ b/nixpkgs/doc/languages-frameworks/gnome.xml
@@ -233,7 +233,7 @@ mkDerivation {
     </term>
     <listitem>
      <para>
-      You can rely on applications depending on the library set the necessary environment variables but that it often easy to miss. Instead we recommend to patch the paths in the source code whenever possible. Here are some examples:
+      You can rely on applications depending on the library setting the necessary environment variables but that is often easy to miss. Instead we recommend to patch the paths in the source code whenever possible. Here are some examples:
       <itemizedlist>
        <listitem xml:id="ssec-gnome-common-issues-unwrappable-package-gnome-shell-ext">
         <para>
diff --git a/nixpkgs/doc/languages-frameworks/go.xml b/nixpkgs/doc/languages-frameworks/go.xml
index e8cf27d05652..84b146532b14 100644
--- a/nixpkgs/doc/languages-frameworks/go.xml
+++ b/nixpkgs/doc/languages-frameworks/go.xml
@@ -42,7 +42,7 @@ pet = buildGoModule rec {
 
   meta = with lib; {
     description = "Simple command-line snippet manager, written in Go";
-    homepage = https://github.com/knqyf263/pet;
+    homepage = "https://github.com/knqyf263/pet";
     license = licenses.mit;
     maintainers = with maintainers; [ kalbasit ];
     platforms = platforms.linux ++ platforms.darwin;
diff --git a/nixpkgs/doc/languages-frameworks/haskell.section.md b/nixpkgs/doc/languages-frameworks/haskell.section.md
index b485ec583ec3..944c17a137e7 100644
--- a/nixpkgs/doc/languages-frameworks/haskell.section.md
+++ b/nixpkgs/doc/languages-frameworks/haskell.section.md
@@ -84,18 +84,18 @@ nix-env -qaP -A nixos.haskellPackages
 nix-env -iA nixos.haskellPackages.cabal-install
 ```
 
-Our current default compiler is GHC 8.6.x and the `haskellPackages` set
+Our current default compiler is GHC 8.8.x and the `haskellPackages` set
 contains packages built with that particular version. Nixpkgs contains the last
 three major releases of GHC and there is a whole family of package sets
 available that defines Hackage packages built with each of those compilers,
 too:
 ```shell
-nix-env -f "<nixpkgs>" -qaP -A haskell.packages.ghc844
-nix-env -f "<nixpkgs>" -qaP -A haskell.packages.ghc882
+nix-env -f "<nixpkgs>" -qaP -A haskell.packages.ghc865
+nix-env -f "<nixpkgs>" -qaP -A haskell.packages.ghc8101
 ```
 
 The name `haskellPackages` is really just a synonym for
-`haskell.packages.ghc865`, because we prefer that package set internally and
+`haskell.packages.ghc882`, because we prefer that package set internally and
 recommend it to our users as their default choice, but ultimately you are free
 to compile your Haskell packages with any GHC version you please. The following
 command displays the complete list of available compilers:
@@ -112,8 +112,10 @@ 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.1.20191211
-haskell.compiler.integer-simple.ghc882   ghc-8.8.1.20191211
+haskell.compiler.ghc882                  ghc-8.8.2
+haskell.compiler.integer-simple.ghc882   ghc-8.8.2
+haskell.compiler.ghc883                  ghc-8.8.3
+haskell.compiler.integer-simple.ghc883   ghc-8.8.3
 haskell.compiler.ghcjs                   ghcjs-8.6.0.1
 ```
 
diff --git a/nixpkgs/doc/languages-frameworks/idris.section.md b/nixpkgs/doc/languages-frameworks/idris.section.md
index 8d7962d7fb9b..f071b9ce1785 100644
--- a/nixpkgs/doc/languages-frameworks/idris.section.md
+++ b/nixpkgs/doc/languages-frameworks/idris.section.md
@@ -96,7 +96,7 @@ build-idris-package  {
 
   meta = {
     description = "Idris YAML lib";
-    homepage = https://github.com/Heather/Idris.Yaml;
+    homepage = "https://github.com/Heather/Idris.Yaml";
     license = lib.licenses.mit;
     maintainers = [ lib.maintainers.brainrape ];
   };
diff --git a/nixpkgs/doc/languages-frameworks/ocaml.xml b/nixpkgs/doc/languages-frameworks/ocaml.xml
index a0ea209b493c..3f72092ec150 100644
--- a/nixpkgs/doc/languages-frameworks/ocaml.xml
+++ b/nixpkgs/doc/languages-frameworks/ocaml.xml
@@ -36,7 +36,7 @@ buildDunePackage rec {
   doCheck = true;
 
   meta = {
-    homepage = https://github.com/inhabitedtype/angstrom;
+    homepage = "https://github.com/inhabitedtype/angstrom";
     description = "OCaml parser combinators built for speed and memory efficiency";
     license = stdenv.lib.licenses.bsd3;
     maintainers = with stdenv.lib.maintainers; [ sternenseemann ];
@@ -63,7 +63,7 @@ buildDunePackage rec {
   };
 
   meta = with stdenv.lib; {
-    homepage = https://github.com/flowtype/ocaml-wtf8;
+    homepage = "https://github.com/flowtype/ocaml-wtf8";
     description = "WTF-8 is a superset of UTF-8 that allows unpaired surrogates.";
     license = licenses.mit;
     maintainers = [ maintainers.eqyiel ];
diff --git a/nixpkgs/doc/languages-frameworks/python.section.md b/nixpkgs/doc/languages-frameworks/python.section.md
index 9b6de47c8e86..650ed3428584 100644
--- a/nixpkgs/doc/languages-frameworks/python.section.md
+++ b/nixpkgs/doc/languages-frameworks/python.section.md
@@ -72,8 +72,9 @@ Now you can use the Python interpreter, as well as the extra packages (`numpy`,
 
 ##### Environment defined in `~/.config/nixpkgs/config.nix`
 
-If you prefer to, you could also add the environment as a package override to the Nixpkgs set, e.g.
-using `config.nix`,
+If you prefer you could also add the environment as a package override to the
+Nixpkgs set, e.g. using `config.nix`,
+
 ```nix
 { # ...
 
@@ -83,15 +84,18 @@ using `config.nix`,
 }
 ```
 and install it in your profile with
+
 ```shell
 nix-env -iA nixpkgs.myEnv
 ```
+
 The environment is is installed by referring to the attribute, and considering
 the `nixpkgs` channel was used.
 
 ##### Environment defined in `/etc/nixos/configuration.nix`
 
-For the sake of completeness, here's another example how to install the environment system-wide.
+For the sake of completeness, here's another example how to install the
+environment system-wide.
 
 ```nix
 { # ...
@@ -109,40 +113,56 @@ 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`.
 
-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.
+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.
+
 ```sh
 $ nix-shell -p 'python35.withPackages(ps: with ps; [ numpy toolz ])'
 ```
+
 opens a shell from which you can launch the interpreter
+
 ```sh
 [nix-shell:~] python3
 ```
-The other method, which is not recommended, does not create an environment and requires you to list the packages directly,
+
+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
 ```
-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.
+
+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.
 
 ##### 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
+
 ```nix
 with import <nixpkgs> {};
 
 (python35.withPackages (ps: [ps.numpy ps.toolz])).env
 ```
+
 Executing `nix-shell` gives you again a Nix shell from which you can run Python.
 
 What's happening here?
 
-1. We begin with importing the Nix Packages collections. `import <nixpkgs>` 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.
+1. We begin with importing the Nix Packages collections. `import <nixpkgs>`
+   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.
-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` from the package set.
+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`
+   from the package set.
 
 To combine this with `mkShell` you can:
 
@@ -166,20 +186,23 @@ in mkShell {
 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
+
 ```sh
 $ nix-shell -p python35Packages.numpy python35Packages.toolz --run "python3"
 ```
+
 or run a script
+
 ```sh
 $ nix-shell -p python35Packages.numpy python35Packages.toolz --run "python3 myscript.py"
 ```
 
 ##### `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
+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.
+can just execute `./myscript.py`, and it will make available all dependencies
+and run the script in the `python3` shell.
 
 ```py
 #! /usr/bin/env nix-shell
@@ -218,7 +241,7 @@ buildPythonPackage rec {
   doCheck = false;
 
   meta = with lib; {
-    homepage = https://github.com/pytoolz/toolz;
+    homepage = "https://github.com/pytoolz/toolz";
     description = "List processing tools and functional utilities";
     license = licenses.bsd3;
     maintainers = with maintainers; [ fridh ];
@@ -270,6 +293,7 @@ with import <nixpkgs> {};
   in python35.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
 for which Python version we want to build a package.
@@ -311,7 +335,7 @@ buildPythonPackage rec {
   propagatedBuildInputs = [ numpy multipledispatch dateutil ];
 
   meta = with lib; {
-    homepage = https://github.com/ContinuumIO/datashape;
+    homepage = "https://github.com/ContinuumIO/datashape";
     description = "A data description language";
     license = licenses.bsd2;
     maintainers = with maintainers; [ fridh ];
@@ -345,7 +369,7 @@ buildPythonPackage rec {
 
   meta = with lib; {
     description = "Pythonic binding for the libxml2 and libxslt libraries";
-    homepage = https://lxml.de;
+    homepage = "https://lxml.de";
     license = licenses.bsd3;
     maintainers = with maintainers; [ sjourdois ];
   };
@@ -355,12 +379,12 @@ buildPythonPackage rec {
 In this example `lxml` and Nix are able to work out exactly where the relevant
 files of the dependencies are. This is not always the case.
 
-The example below shows bindings to The Fastest Fourier Transform in the West, commonly known as
-FFTW. On Nix we have separate packages of FFTW for the different types of floats
-(`"single"`, `"double"`, `"long-double"`). The bindings need all three types,
-and therefore we add all three as `buildInputs`. The bindings don't expect to
-find each of them in a different folder, and therefore we have to set `LDFLAGS`
-and `CFLAGS`.
+The example below shows bindings to The Fastest Fourier Transform in the West,
+commonly known as FFTW. On Nix we have separate packages of FFTW for the
+different types of floats (`"single"`, `"double"`, `"long-double"`). The
+bindings need all three types, and therefore we add all three as `buildInputs`.
+The bindings don't expect to find each of them in a different folder, and
+therefore we have to set `LDFLAGS` and `CFLAGS`.
 
 ```nix
 { lib, pkgs, buildPythonPackage, fetchPypi, numpy, scipy }:
@@ -404,17 +428,18 @@ instead of installing the package this command creates a special link to the pro
 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;`
+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;`
 
 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 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 `propagatedBuildInputs`.
+In the following example we create a simple environment that has a Python 3.5
+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
+`propagatedBuildInputs`.
 
 ```nix
 with import <nixpkgs> {};
@@ -427,7 +452,8 @@ 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.
+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
@@ -497,13 +523,13 @@ and in this case the `python35` interpreter is automatically used.
 ### Interpreters
 
 Versions 2.7, 3.5, 3.6, 3.7 and 3.8 of the CPython interpreter are available as
-respectively `python27`, `python35`, `python36`, `python37` and `python38`. The aliases
-`python2` and `python3` correspond to respectively `python27` and
+respectively `python27`, `python35`, `python36`, `python37` and `python38`. The
+aliases `python2` and `python3` correspond to respectively `python27` and
 `python37`. The default interpreter, `python`, maps to `python2`. The PyPy
 interpreters compatible with Python 2.7 and 3 are available as `pypy27` and
-`pypy3`, with aliases `pypy2` mapping to `pypy27` and `pypy` mapping to
-`pypy2`. The Nix expressions for the interpreters can be
-found in `pkgs/development/interpreters/python`.
+`pypy3`, with aliases `pypy2` mapping to `pypy27` and `pypy` mapping to `pypy2`.
+The Nix expressions for the interpreters can be found in
+`pkgs/development/interpreters/python`.
 
 All packages depending on any Python interpreter get appended
 `out/{python.sitePackages}` to `$PYTHONPATH` if such directory
@@ -532,9 +558,10 @@ Python libraries and applications that use `setuptools` or
 `buildPythonApplication` functions. These two functions also support installing a `wheel`.
 
 All Python packages reside in `pkgs/top-level/python-packages.nix` and all
-applications elsewhere. In case a package is used as both a library and an application,
-then the package should be in `pkgs/top-level/python-packages.nix` since only those packages are made
-available for all interpreter versions. The preferred location for library expressions is in
+applications elsewhere. In case a package is used as both a library and an
+application, then the package should be in `pkgs/top-level/python-packages.nix`
+since only those packages are made available for all interpreter versions. The
+preferred location for library expressions is in
 `pkgs/development/python-modules`. It is important that these packages are
 called from `pkgs/top-level/python-packages.nix` and not elsewhere, to guarantee
 the right version of the package is built.
@@ -562,6 +589,7 @@ The `buildPythonPackage` function is implemented in
 using setup hooks.
 
 The following is an example:
+
 ```nix
 { lib, buildPythonPackage, fetchPypi, hypothesis, setuptools_scm, attrs, py, setuptools, six, pluggy }:
 
@@ -608,38 +636,67 @@ as the interpreter unless overridden otherwise.
 
 ##### `buildPythonPackage` parameters
 
-All parameters from `stdenv.mkDerivation` function are still supported. The following are specific to `buildPythonPackage`:
+All parameters from `stdenv.mkDerivation` function are still supported. The
+following are specific to `buildPythonPackage`:
 
-* `catchConflicts ? true`: If `true`, abort package build if a package name appears more than once in dependency tree. Default is `true`.
-* `disabled` ? false: If `true`, package is not built for the particular Python interpreter version.
+* `catchConflicts ? true`: If `true`, abort package build if a package name
+  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.
-* `permitUserSite ? false`: Skip setting the `PYTHONNOUSERSITE` environment variable in wrapped programs.
-* `installFlags ? []`: A list of strings. Arguments to be passed to `pip install`. To pass options to `python setup.py install`, use `--install-option`. E.g., `installFlags=["--install-option='--cpp_implementation'"]`.
-* `format ? "setuptools"`: Format of the source. Valid options are `"setuptools"`, `"pyproject"`, `"flit"`, `"wheel"`, and `"other"`. `"setuptools"` is for when the source has a `setup.py` and `setuptools` is used to build a wheel, `flit`, in case `flit` should be used to build a wheel, and `wheel` in case a wheel is provided. Use `other` when a custom `buildPhase` and/or `installPhase` is needed.
-* `makeWrapperArgs ? []`: A list of strings. Arguments to be passed to `makeWrapper`, which wraps generated binaries. By default, the arguments to `makeWrapper` set `PATH` and `PYTHONPATH` environment variables before calling the binary. Additional arguments here can allow a developer to set environment 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 to `""`.
-* `pythonPath ? []`: List of packages to be added into `$PYTHONPATH`. Packages in `pythonPath` are not propagated (contrary to `propagatedBuildInputs`).
+* `permitUserSite ? false`: Skip setting the `PYTHONNOUSERSITE` environment
+  variable in wrapped programs.
+* `installFlags ? []`: A list of strings. Arguments to be passed to `pip
+  install`. To pass options to `python setup.py install`, use
+  `--install-option`. E.g., `installFlags=["--install-option='--cpp_implementation'"]`.
+* `format ? "setuptools"`: Format of the source. Valid options are
+  `"setuptools"`, `"pyproject"`, `"flit"`, `"wheel"`, and `"other"`.
+  `"setuptools"` is for when the source has a `setup.py` and `setuptools` is
+  used to build a wheel, `flit`, in case `flit` should be used to build a wheel,
+  and `wheel` in case a wheel is provided. Use `other` when a custom
+  `buildPhase` and/or `installPhase` is needed.
+* `makeWrapperArgs ? []`: A list of strings. Arguments to be passed to
+  `makeWrapper`, which wraps generated binaries. By default, the arguments to
+  `makeWrapper` set `PATH` and `PYTHONPATH` environment variables before calling
+  the binary. Additional arguments here can allow a developer to set environment
+  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
+  to `""`.
+* `pythonPath ? []`: List of packages to be added into `$PYTHONPATH`. Packages
+  in `pythonPath` are not propagated (contrary to `propagatedBuildInputs`).
 * `preShellHook`: Hook to execute commands before `shellHook`.
 * `postShellHook`: Hook to execute commands after `shellHook`.
-* `removeBinByteCode ? true`: Remove bytecode from `/bin`. Bytecode is only created when the filenames end with `.py`.
+* `removeBinByteCode ? true`: Remove bytecode from `/bin`. Bytecode is only
+  created when the filenames end with `.py`.
 * `setupPyGlobalFlags ? []`: List of flags passed to `setup.py` command.
 * `setupPyBuildFlags ? []`: List of flags passed to `setup.py build_ext` command.
 
-The `stdenv.mkDerivation` function accepts various parameters for describing build inputs (see "Specifying dependencies"). The following are of special
-interest for Python packages, either because these are primarily used, or because their behaviour is different:
-
-* `nativeBuildInputs ? []`: Build-time only dependencies. Typically executables as well as the items listed in `setup_requires`.
-* `buildInputs ? []`: Build and/or run-time dependencies that need to be be compiled for the host machine. Typically non-Python libraries which are being linked.
-* `checkInputs ? []`: Dependencies needed for running the `checkPhase`. These are added to `nativeBuildInputs` when `doCheck = true`. Items listed in `tests_require` go here.
-* `propagatedBuildInputs ? []`: Aside from propagating dependencies, `buildPythonPackage` also injects code into and wraps executables with the paths included in this list. Items listed in `install_requires` go here.
+The `stdenv.mkDerivation` function accepts various parameters for describing
+build inputs (see "Specifying dependencies"). The following are of special
+interest for Python packages, either because these are primarily used, or
+because their behaviour is different:
+
+* `nativeBuildInputs ? []`: Build-time only dependencies. Typically executables
+  as well as the items listed in `setup_requires`.
+* `buildInputs ? []`: Build and/or run-time dependencies that need to be be
+  compiled for the host machine. Typically non-Python libraries which are being
+  linked.
+* `checkInputs ? []`: Dependencies needed for running the `checkPhase`. These
+  are added to `nativeBuildInputs` when `doCheck = true`. Items listed in
+  `tests_require` go here.
+* `propagatedBuildInputs ? []`: Aside from propagating dependencies,
+  `buildPythonPackage` also injects code into and wraps executables with the
+  paths included in this list. Items listed in `install_requires` go here.
 
 ##### Overriding Python packages
 
-The `buildPythonPackage` function has a `overridePythonAttrs` method that
-can be used to override the package. In the following example we create an
-environment where we have the `blaze` package using an older version of `pandas`.
-We override first the Python interpreter and pass
-`packageOverrides` which contains the overrides for packages in the package set.
+The `buildPythonPackage` function has a `overridePythonAttrs` method that can be
+used to override the package. In the following example we create an environment
+where we have the `blaze` package using an older version of `pandas`. We
+override first the Python interpreter and pass `packageOverrides` which contains
+the overrides for packages in the package set.
 
 ```nix
 with import <nixpkgs> {};
@@ -725,15 +782,18 @@ youtube-dl = with pythonPackages; toPythonApplication youtube-dl;
 #### `toPythonModule` function
 
 In some cases, such as bindings, a package is created using
-`stdenv.mkDerivation` and added as attribute in `all-packages.nix`.
-The Python bindings should be made available from `python-packages.nix`.
-The `toPythonModule` function takes a derivation and makes certain Python-specific modifications.
+`stdenv.mkDerivation` and added as attribute in `all-packages.nix`. The Python
+bindings should be made available from `python-packages.nix`. The
+`toPythonModule` function takes a derivation and makes certain Python-specific
+modifications.
+
 ```nix
 opencv = toPythonModule (pkgs.opencv.override {
   enablePython = true;
   pythonPackages = self;
 });
 ```
+
 Do pay attention to passing in the right Python version!
 
 #### `python.buildEnv` function
@@ -741,6 +801,7 @@ Do pay attention to passing in the right Python version!
 Python environments can be created using the low-level `pkgs.buildEnv` function.
 This example shows how to create an environment that has the Pyramid Web Framework.
 Saving the following as `default.nix`
+
 ```nix
 with import <nixpkgs> {};
 
@@ -751,6 +812,7 @@ python.buildEnv.override {
 ```
 
 and running `nix-build` will create
+
 ```
 /nix/store/cf1xhjwzmdki7fasgr4kz6di72ykicl5-python-2.7.8-env
 ```
@@ -760,6 +822,7 @@ with wrapped binaries in `bin/`.
 You can also use the `env` attribute to create local environments with needed
 packages installed. This is somewhat comparable to `virtualenv`. For example,
 running `nix-shell` with the following `shell.nix`
+
 ```nix
 with import <nixpkgs> {};
 
@@ -777,7 +840,8 @@ specified packages in its path.
 * `extraLibs`: List of packages installed inside the environment.
 * `postBuild`: Shell command executed after the build of environment.
 * `ignoreCollisions`: Ignore file collisions inside the environment (default is `false`).
-* `permitUserSite`: Skip setting the `PYTHONNOUSERSITE` environment variable in wrapped binaries in the environment.
+* `permitUserSite`: Skip setting the `PYTHONNOUSERSITE` environment variable in
+  wrapped binaries in the environment.
 
 #### `python.withPackages` function
 
@@ -785,15 +849,17 @@ The `python.withPackages` function provides a simpler interface to the `python.b
 It takes a function as an argument that is passed the set of python packages and returns the list
 of the packages to be included in the environment. Using the `withPackages` function, the previous
 example for the Pyramid Web Framework environment can be written like this:
+
 ```nix
 with import <nixpkgs> {};
 
 python.withPackages (ps: [ps.pyramid])
 ```
 
-`withPackages` passes the correct package set for the specific interpreter version as an
-argument to the function. In the above example, `ps` equals `pythonPackages`.
-But you can also easily switch to using python3:
+`withPackages` passes the correct package set for the specific interpreter
+version as an argument to the function. In the above example, `ps` equals
+`pythonPackages`. But you can also easily switch to using python3:
+
 ```nix
 with import <nixpkgs> {};
 
@@ -802,30 +868,35 @@ python3.withPackages (ps: [ps.pyramid])
 
 Now, `ps` is set to `python3Packages`, matching the version of the interpreter.
 
-As `python.withPackages` simply uses `python.buildEnv` under the hood, it also supports the `env`
-attribute. The `shell.nix` file from the previous section can thus be also written like this:
+As `python.withPackages` simply uses `python.buildEnv` under the hood, it also
+supports the `env` attribute. The `shell.nix` file from the previous section can
+thus be also written like this:
+
 ```nix
 with import <nixpkgs> {};
 
 (python36.withPackages (ps: [ps.numpy ps.requests])).env
 ```
 
-In contrast to `python.buildEnv`, `python.withPackages` does not support the more advanced options
-such as `ignoreCollisions = true` or `postBuild`. If you need them, you have to use `python.buildEnv`.
+In contrast to `python.buildEnv`, `python.withPackages` does not support the
+more advanced options such as `ignoreCollisions = true` or `postBuild`. If you
+need them, you have to use `python.buildEnv`.
 
-Python 2 namespace packages may provide `__init__.py` that collide. In that case `python.buildEnv`
-should be used with `ignoreCollisions = true`.
+Python 2 namespace packages may provide `__init__.py` that collide. In that case
+`python.buildEnv` should be used with `ignoreCollisions = true`.
 
 #### Setup hooks
 
-The following are setup hooks specifically for Python packages. Most of these are
-used in `buildPythonPackage`.
+The following are setup hooks specifically for Python packages. Most of these
+are used in `buildPythonPackage`.
 
-- `eggUnpackhook` to move an egg to the correct folder so it can be installed with the `eggInstallHook`
+- `eggUnpackhook` to move an egg to the correct folder so it can be installed
+  with the `eggInstallHook`
 - `eggBuildHook` to skip building for eggs.
 - `eggInstallHook` to install eggs.
 - `flitBuildHook` to build a wheel using `flit`.
-- `pipBuildHook` to build a wheel using `pip` and PEP 517. Note a build system (e.g. `setuptools` or `flit`) should still be added as `nativeBuildInput`.
+- `pipBuildHook` to build a wheel using `pip` and PEP 517. Note a build system
+  (e.g. `setuptools` or `flit`) should still be added as `nativeBuildInput`.
 - `pipInstallHook` to install wheels.
 - `pytestCheckHook` to run tests with `pytest`.
 - `pythonCatchConflictsHook` to check whether a Python package is not already existing.
@@ -833,8 +904,10 @@ used in `buildPythonPackage`.
 - `pythonRemoveBinBytecode` to remove bytecode from the `/bin` folder.
 - `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.
-- `wheelUnpackHook` to move a wheel to the correct folder so it can be installed with the `pipInstallHook`.
+- `venvShellHook` to source a Python 3 `venv` at the `venvDir` location. A
+  `venv` is created if it does not yet exist.
+- `wheelUnpackHook` to move a wheel to the correct folder so it can be installed
+  with the `pipInstallHook`.
 
 ### Development mode
 
@@ -856,11 +929,11 @@ pythonPackages.buildPythonPackage {
 }
 ```
 
-Running `nix-shell` with no arguments should give you
-the environment in which the package would be built with
-`nix-build`.
+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:
+
 ```shell
 nix-shell -p pythonPackages.pyramid zlib libjpeg git
 ```
@@ -872,19 +945,22 @@ Note: There is a boolean value `lib.inNixShell` set to `true` if nix-shell is in
 Packages inside nixpkgs are written by hand. However many tools exist in
 community to help save time. No tool is preferred at the moment.
 
-- [pypi2nix](https://github.com/nix-community/pypi2nix): Generate Nix expressions for your Python project. Note that [sharing derivations from pypi2nix with nixpkgs is possible but not encouraged](https://github.com/nix-community/pypi2nix/issues/222#issuecomment-443497376).
+- [pypi2nix](https://github.com/nix-community/pypi2nix): Generate Nix
+  expressions for your Python project. Note that [sharing derivations from
+  pypi2nix with nixpkgs is possible but not
+  encouraged](https://github.com/nix-community/pypi2nix/issues/222#issuecomment-443497376).
 - [python2nix](https://github.com/proger/python2nix) by Vladimir Kirillov.
 
 ### Deterministic builds
 
-The Python interpreters are now built deterministically.
-Minor modifications had to be made to the interpreters in order to generate
-deterministic bytecode. This has security implications and is relevant for
-those using Python in a `nix-shell`.
+The Python interpreters are now built deterministically. Minor modifications had
+to be made to the interpreters in order to generate deterministic bytecode. This
+has security implications and is relevant for those using Python in a
+`nix-shell`.
 
-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).
+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).
 Both are also exported in `nix-shell`.
 
 
@@ -899,9 +975,10 @@ 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 protocol where the pytest runner can be used instead.
-  `py.test` supports a `-k` parameter to ignore test methods or classes:
+* Non-working tests can often be deselected. By default `buildPythonPackage`
+  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:
 
   ```nix
   buildPythonPackage {
@@ -913,7 +990,8 @@ example of such a situation is when `py.test` is used.
     '';
   }
   ```
-- Tests that attempt to access `$HOME` can be fixed by using the following work-around before running tests (e.g. `preCheck`): `export HOME=$(mktemp -d)`
+* Tests that attempt to access `$HOME` can be fixed by using the following
+  work-around before running tests (e.g. `preCheck`): `export HOME=$(mktemp -d)`
 
 ## FAQ
 
@@ -925,8 +1003,9 @@ should also be done when packaging `A`.
 
 ### How to override a Python package?
 
-We can override the interpreter and pass `packageOverrides`.
-In the following example we rename the `pandas` package and build it.
+We can override the interpreter and pass `packageOverrides`. In the following
+example we rename the `pandas` package and build it.
+
 ```nix
 with import <nixpkgs> {};
 
@@ -939,14 +1018,16 @@ with import <nixpkgs> {};
 
 in python.withPackages(ps: [ps.pandas])).env
 ```
+
 Using `nix-build` on this expression will build an environment that contains the
 package `pandas` but with the new name `foo`.
 
-All packages in the package set will use the renamed package.
-A typical use case is to switch to another version of a certain package.
-For example, in the Nixpkgs repository we have multiple versions of `django` and `scipy`.
-In the following example we use a different version of `scipy` and create an environment that uses it.
-All packages in the Python package set will now use the updated `scipy` version.
+All packages in the package set will use the renamed package. A typical use case
+is to switch to another version of a certain package. For example, in the
+Nixpkgs repository we have multiple versions of `django` and `scipy`. In the
+following example we use a different version of `scipy` and create an
+environment that uses it. All packages in the Python package set will now use
+the updated `scipy` version.
 
 ```nix
 with import <nixpkgs> {};
@@ -958,10 +1039,13 @@ with import <nixpkgs> {};
   in (pkgs.python35.override {inherit packageOverrides;}).withPackages (ps: [ps.blaze])
 ).env
 ```
+
 The requested package `blaze` depends on `pandas` which itself depends on `scipy`.
 
-If you want the whole of Nixpkgs to use your modifications, then you can use `overlays`
-as explained in this manual. In the following example we build a `inkscape` using a different version of `numpy`.
+If you want the whole of Nixpkgs to use your modifications, then you can use
+`overlays` as explained in this manual. In the following example we build a
+`inkscape` using a different version of `numpy`.
+
 ```nix
 let
   pkgs = import <nixpkgs> {};
@@ -982,19 +1066,28 @@ Executing `python setup.py bdist_wheel` in a `nix-shell `fails with
 ValueError: ZIP does not support timestamps before 1980
 ```
 
-This is because files from the Nix store (which have a timestamp of the UNIX epoch of January 1, 1970) are included in the .ZIP, but .ZIP archives follow the DOS convention of counting timestamps from 1980.
+This is because files from the Nix store (which have a timestamp of the UNIX
+epoch of January 1, 1970) are included in the .ZIP, but .ZIP archives follow the
+DOS convention of counting timestamps from 1980.
 
-The command `bdist_wheel` reads the `SOURCE_DATE_EPOCH` environment variable, which `nix-shell` sets to 1. Unsetting this variable or giving it a value corresponding to 1980 or later enables building wheels.
+The command `bdist_wheel` reads the `SOURCE_DATE_EPOCH` environment variable,
+which `nix-shell` sets to 1. Unsetting this variable or giving it a value
+corresponding to 1980 or later enables building wheels.
 
 Use 1980 as timestamp:
+
 ```shell
 nix-shell --run "SOURCE_DATE_EPOCH=315532800 python3 setup.py bdist_wheel"
 ```
+
 or the current time:
+
 ```shell
 nix-shell --run "SOURCE_DATE_EPOCH=$(date +%s) python3 setup.py bdist_wheel"
 ```
+
 or unset `SOURCE_DATE_EPOCH`:
+
 ```shell
 nix-shell --run "unset SOURCE_DATE_EPOCH; python3 setup.py bdist_wheel"
 ```
@@ -1002,13 +1095,18 @@ nix-shell --run "unset SOURCE_DATE_EPOCH; python3 setup.py bdist_wheel"
 ### `install_data` / `data_files` problems
 
 If you get the following error:
+
 ```
 could not create '/nix/store/6l1bvljpy8gazlsw2aw9skwwp4pmvyxw-python-2.7.8/etc':
 Permission denied
 ```
-This is a [known bug](https://github.com/pypa/setuptools/issues/130) in `setuptools`.
-Setuptools `install_data` does not respect `--prefix`. An example of such package using the feature is `pkgs/tools/X11/xpra/default.nix`.
+
+This is a [known bug](https://github.com/pypa/setuptools/issues/130) in
+`setuptools`. Setuptools `install_data` does not respect `--prefix`. An example
+of such package using the feature is `pkgs/tools/X11/xpra/default.nix`.
+
 As workaround install it as an extra `preInstall` step:
+
 ```shell
 ${python.interpreter} setup.py install_data --install-dir=$out --root=$out
 sed -i '/ = data\_files/d' setup.py
@@ -1031,13 +1129,16 @@ function.
 
 ### 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.
+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 `pip` the traditional way.
+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
+`pip` the traditional way.
 
-Create this `default.nix` file, together with a `requirements.txt` and simply execute `nix-shell`.
+Create this `default.nix` file, together with a `requirements.txt` and simply
+execute `nix-shell`.
 
 ```nix
 with import <nixpkgs> { };
@@ -1061,11 +1162,9 @@ in pkgs.mkShell rec {
     pythonPackages.numpy
     pythonPackages.requests
 
-    # the following packages are related to the dependencies of your python
-    # project.
-    # In this particular example the python modules listed in the
-    # requirements.txt require the following packages to be installed locally
-    # in order to compile any binary extensions they may require.
+    # In this particular example, in order to compile any binary extensions they may
+    # require, the python modules listed in the hypothetical requirements.txt need
+    # the following packages to be installed locally:
     taglib
     openssl
     git
@@ -1075,7 +1174,8 @@ in pkgs.mkShell rec {
     zlib
   ];
 
-  # Now we can execute any commands within the virtual environment
+  # 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
   '';
@@ -1083,20 +1183,23 @@ in pkgs.mkShell rec {
 }
 ```
 
-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:
+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:
 
 ```nix
 with import <nixpkgs> { };
 
 let
   venvDir = "./.venv";
+  pythonPackages = python3Packages;
 in pkgs.mkShell rec {
   name = "impurePythonEnv";
   buildInputs = [
-    python3Packages.python
-    python3Packages.virtualenv
-    ...
+    pythonPackages.python
+    # Needed when using python 2.7
+    # pythonPackages.virtualenv
+    # ...
   ];
 
   # This is very close to how venvShellHook is implemented, but
@@ -1108,14 +1211,18 @@ in pkgs.mkShell rec {
       echo "Skipping venv creation, '${venvDir}' already exists"
     else
       echo "Creating new venv environment in path: '${venvDir}'"
+      # Note that the module venv was only introduced in python 3, so for 2.7
+      # this needs to be replaced with a call to virtualenv
       ${pythonPackages.python.interpreter} -m venv "${venvDir}"
     fi
 
     # Under some circumstances it might be necessary to add your virtual
     # environment to PYTHONPATH, which you can do here too;
-    # PYTHONPATH=$PWD/${venvDir}/${python.sitePackages}/:$PYTHONPATH
+    # PYTHONPATH=$PWD/${venvDir}/${pythonPackages.python.sitePackages}/:$PYTHONPATH
 
     source "${venvDir}/bin/activate"
+
+    # As in the previous example, this is optional.
     pip install -r requirements.txt
   '';
 }
@@ -1147,11 +1254,11 @@ If you need to change a package's attribute(s) from `configuration.nix` you coul
 ```
 
 `pythonPackages.zerobin` is now globally overridden. All packages and also the
-`zerobin` NixOS service use the new definition.
-Note that `python-super` refers to the old package set and `python-self`
-to the new, overridden version.
+`zerobin` NixOS service use the new definition. Note that `python-super` refers
+to the old package set and `python-self` to the new, overridden version.
 
-To modify only a Python package set instead of a whole Python derivation, use this snippet:
+To modify only a Python package set instead of a whole Python derivation, use
+this snippet:
 
 ```nix
   myPythonPackages = pythonPackages.override {
@@ -1183,11 +1290,12 @@ 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`.
+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 {
@@ -1223,10 +1331,21 @@ In a `setup.py` or `setup.cfg` it is common to declare dependencies:
 
 Following rules are desired to be respected:
 
-* Python libraries are called from `python-packages.nix` and packaged with `buildPythonPackage`. The expression of a library should be in `pkgs/development/python-modules/<name>/default.nix`. Libraries in `pkgs/top-level/python-packages.nix` are sorted quasi-alphabetically to avoid merge conflicts.
-* Python applications live outside of `python-packages.nix` and are packaged with `buildPythonApplication`.
+* Python libraries are called from `python-packages.nix` and packaged with
+  `buildPythonPackage`. The expression of a library should be in
+  `pkgs/development/python-modules/<name>/default.nix`. Libraries in
+  `pkgs/top-level/python-packages.nix` are sorted quasi-alphabetically to avoid
+  merge conflicts.
+* Python applications live outside of `python-packages.nix` and are packaged
+  with `buildPythonApplication`.
 * Make sure libraries build for all Python interpreters.
-* By default we enable tests. Make sure the tests are found and, in the case of libraries, are passing for all interpreters. If certain tests fail they can be disabled individually. Try to avoid disabling the tests altogether. In any case, when you disable tests, leave a comment explaining why.
-* Commit names of Python libraries should reflect that they are Python libraries, so write for example `pythonPackages.numpy: 1.11 -> 1.12`.
-* Attribute names in `python-packages.nix` should be normalized according to [PEP 0503](https://www.python.org/dev/peps/pep-0503/#normalized-names).
-  This means that characters should be converted to lowercase and `.` and `_` should be replaced by a single `-` (foo-bar-baz instead of Foo__Bar.baz )
+* By default we enable tests. Make sure the tests are found and, in the case of
+  libraries, are passing for all interpreters. If certain tests fail they can be
+  disabled individually. Try to avoid disabling the tests altogether. In any
+  case, when you disable tests, leave a comment explaining why.
+* Commit names of Python libraries should reflect that they are Python
+  libraries, so write for example `pythonPackages.numpy: 1.11 -> 1.12`.
+* Attribute names in `python-packages.nix` should be normalized according to
+  [PEP 0503](https://www.python.org/dev/peps/pep-0503/#normalized-names). This
+  means that characters should be converted to lowercase and `.` and `_` should
+  be replaced by a single `-` (foo-bar-baz instead of Foo__Bar.baz )
diff --git a/nixpkgs/doc/languages-frameworks/rust.section.md b/nixpkgs/doc/languages-frameworks/rust.section.md
index 3332dff1eb07..97dc9e2ff531 100644
--- a/nixpkgs/doc/languages-frameworks/rust.section.md
+++ b/nixpkgs/doc/languages-frameworks/rust.section.md
@@ -37,11 +37,10 @@ rustPlatform.buildRustPackage rec {
   };
 
   cargoSha256 = "17ldqr3asrdcsh4l29m3b5r37r5d0b3npq1lrgjmxb6vlx6a36qh";
-  verifyCargoDeps = true;
 
   meta = with stdenv.lib; {
     description = "A fast line-oriented regex search tool, similar to ag and ack";
-    homepage = https://github.com/BurntSushi/ripgrep;
+    homepage = "https://github.com/BurntSushi/ripgrep";
     license = licenses.unlicense;
     maintainers = [ maintainers.tailhook ];
     platforms = platforms.all;
@@ -54,17 +53,16 @@ all crate sources of this package. Currently it is obtained by inserting a
 fake checksum into the expression and building the package once. The correct
 checksum can be then take from the failed build.
 
-When the `Cargo.lock`, provided by upstream, is not in sync with the
-`Cargo.toml`, it is possible to use `cargoPatches` to update it. All patches
-added in `cargoPatches` will also be prepended to the patches in `patches` at
-build-time.
-
-When `verifyCargoDeps` is set to `true`, the build will also verify that the
-`cargoSha256` is not out of date by comparing the `Cargo.lock` file in both the
-`cargoDeps` and `src`. Note that this option changes the value of `cargoSha256`
-since it also copies the `Cargo.lock` in it. To avoid breaking
-backward-compatibility this option is not enabled by default but hopefully will
-be in the future.
+Per the instructions in the [Cargo Book](https://doc.rust-lang.org/cargo/guide/cargo-toml-vs-cargo-lock.html)
+best practices guide, Rust applications should always commit the `Cargo.lock`
+file in git to ensure a reproducible build. However, a few packages do not, and
+Nix depends on this file, so if it missing you can use `cargoPatches` to apply
+it in the `patchPhase`. Consider sending a PR upstream with a note to the
+maintainer describing why it's important to include in the application.
+
+Unless `legacyCargoFetcher` is set to `true`, the fetcher will also verify that
+the `Cargo.lock` file is in sync with the `src` attribute, and will compress the
+vendor directory into a tar.gz archive.
 
 ### Building a crate for a different target