Merge commit '84d74ae9c9cbed73274b8e4e00be14688ffc93fe'

12 files changed, 339 insertions, 130 deletions

diff --git a/nixpkgs/doc/languages-frameworks/android.section.md b/nixpkgs/doc/languages-frameworks/android.section.md
index 1a8924082bfb..f4f6c086a805 100644
--- a/nixpkgs/doc/languages-frameworks/android.section.md
+++ b/nixpkgs/doc/languages-frameworks/android.section.md
@@ -191,6 +191,8 @@ androidenv.emulateApp {
 }
 ```
 
+Additional flags may be applied to the Android SDK's emulator through the runtime environment variable `$NIX_ANDROID_EMULATOR_FLAGS`.
+
 It is also possible to specify an APK to deploy inside the emulator
 and the package and activity names to launch it:
 
diff --git a/nixpkgs/doc/languages-frameworks/beam.xml b/nixpkgs/doc/languages-frameworks/beam.xml
index 278535237c2c..addab24f7f6d 100644
--- a/nixpkgs/doc/languages-frameworks/beam.xml
+++ b/nixpkgs/doc/languages-frameworks/beam.xml
@@ -68,13 +68,13 @@
   <title>How to Install BEAM Packages</title>
 
   <para>
-   BEAM builders are not registered at the top level, simply because they are not relevant to the vast majority of Nix users. 
+   BEAM builders are not registered at the top level, simply because they are not relevant to the vast majority of Nix users.
    To install any of those builders into your profile, refer to them by their attribute path <literal>beamPackages.rebar3</literal>:
   </para>
 
-  <screen>
-  <prompt>$ </prompt>nix-env -f &quot;&lt;nixpkgs&gt;&quot; -iA beamPackages.rebar3
-  </screen>
+<screen>
+<prompt>$ </prompt>nix-env -f &quot;&lt;nixpkgs&gt;&quot; -iA beamPackages.rebar3
+</screen>
 </section>
 
  <section xml:id="packaging-beam-applications">
diff --git a/nixpkgs/doc/languages-frameworks/emscripten.section.md b/nixpkgs/doc/languages-frameworks/emscripten.section.md
index 80e1094809ad..3663f962d5f2 100644
--- a/nixpkgs/doc/languages-frameworks/emscripten.section.md
+++ b/nixpkgs/doc/languages-frameworks/emscripten.section.md
@@ -21,11 +21,11 @@ Modes of use of `emscripten`:
 * **Declarative usage**:
 
     This mode is far more power full since this makes use of `nix` for dependency management of emscripten libraries and targets by using the `mkDerivation` which is implemented by `pkgs.emscriptenStdenv` and `pkgs.buildEmscriptenPackage`. The source for the packages is in `pkgs/top-level/emscripten-packages.nix` and the abstraction behind it in `pkgs/development/em-modules/generic/default.nix`.
-    * build and install all packages: 
-        * `nix-env -iA emscriptenPackages` 
-          
-    * dev-shell for zlib implementation hacking: 
-        * `nix-shell -A emscriptenPackages.zlib` 
+    * build and install all packages:
+        * `nix-env -iA emscriptenPackages`
+
+    * dev-shell for zlib implementation hacking:
+        * `nix-shell -A emscriptenPackages.zlib`
 
 
 ## Imperative usage
@@ -90,7 +90,7 @@ See the `zlib` example:
         libz.so.${old.version} -I . -o example.js
 
         echo "Using node to execute the test"
-        ${pkgs.nodejs}/bin/node ./example.js 
+        ${pkgs.nodejs}/bin/node ./example.js
 
         set +x
         if [ $? -ne 0 ]; then
@@ -112,7 +112,7 @@ See the `zlib` example:
 
 ### Usage 2: pkgs.buildEmscriptenPackage
 
-This `xmlmirror` example features a emscriptenPackage which is defined completely from this context and no `pkgs.zlib.override` is used. 
+This `xmlmirror` example features a emscriptenPackage which is defined completely from this context and no `pkgs.zlib.override` is used.
 
     xmlmirror = pkgs.buildEmscriptenPackage rec {
       name = "xmlmirror";
@@ -163,7 +163,7 @@ This `xmlmirror` example features a emscriptenPackage which is defined completel
       checkPhase = ''
 
       '';
-    }; 
+    };
 
 ### Declarative debugging
 
@@ -182,4 +182,3 @@ Use `nix-shell -I nixpkgs=/some/dir/nixpkgs -A emscriptenPackages.libz` and from
 Using this toolchain makes it easy to leverage `nix` from NixOS, MacOSX or even Windows (WSL+ubuntu+nix). This toolchain is reproducible, behaves like the rest of the packages from nixpkgs and contains a set of well working examples to learn and adapt from.
 
 If in trouble, ask the maintainers.
-
diff --git a/nixpkgs/doc/languages-frameworks/go.xml b/nixpkgs/doc/languages-frameworks/go.xml
index ff39276f640e..ebdcf616054c 100644
--- a/nixpkgs/doc/languages-frameworks/go.xml
+++ b/nixpkgs/doc/languages-frameworks/go.xml
@@ -38,7 +38,7 @@ pet = buildGoModule rec {
 
   vendorSha256 = "1879j77k96684wi554rkjxydrj8g3hpp0kvxz03sd8dmwr3lh83j"; <co xml:id='ex-buildGoModule-1' />
 
-  subPackages = [ "." ]; <co xml:id='ex-buildGoModule-2' />
+  runVend = true; <co xml:id='ex-buildGoModule-2' />
 
   meta = with lib; {
     description = "Simple command-line snippet manager, written in Go";
@@ -61,19 +61,14 @@ pet = buildGoModule rec {
     </callout>
     <callout arearefs='ex-buildGoModule-2'>
      <para>
-      <varname>subPackages</varname> limits the builder from building child packages that have not been listed. If <varname>subPackages</varname> is not specified, all child packages will be built.
+      <varname>runVend</varname> runs the vend command to generate the vendor directory. This is useful if your code depends on c code and go mod tidy does not include the needed sources to build.
      </para>
     </callout>
    </calloutlist>
   </para>
 
   <para>
-    <varname>vendorSha256</varname> can also take <varname>null</varname> as an input.
-
-    When `null` is used as a value, rather than fetching the dependencies
-    and vendoring them, we use the vendoring included within the source repo.
-    If you'd like to not have to update this field on dependency changes, 
-    run `go mod vendor` in your source repo and set 'vendorSha256 = null;'
+   <varname>vendorSha256</varname> can also take <varname>null</varname> as an input. When `null` is used as a value, rather than fetching the dependencies and vendoring them, we use the vendoring included within the source repo. If you'd like to not have to update this field on dependency changes, run `go mod vendor` in your source repo and set 'vendorSha256 = null;'
   </para>
  </section>
 
@@ -92,7 +87,6 @@ deis = buildGoPackage rec {
   version = "1.13.0";
 
   goPackagePath = "github.com/deis/deis"; <co xml:id='ex-buildGoPackage-1' />
-  subPackages = [ "client" ]; <co xml:id='ex-buildGoPackage-2' />
 
   src = fetchFromGitHub {
     owner = "deis";
@@ -101,9 +95,7 @@ deis = buildGoPackage rec {
     sha256 = "1qv9lxqx7m18029lj8cw3k7jngvxs4iciwrypdy0gd2nnghc68sw";
   };
 
-  goDeps = ./deps.nix; <co xml:id='ex-buildGoPackage-3' />
-
-  buildFlags = [ "--tags" "release" ]; <co xml:id='ex-buildGoPackage-4' />
+  goDeps = ./deps.nix; <co xml:id='ex-buildGoPackage-2' />
 }
 </programlisting>
   </example>
@@ -118,22 +110,9 @@ deis = buildGoPackage rec {
     </callout>
     <callout arearefs='ex-buildGoPackage-2'>
      <para>
-      <varname>subPackages</varname> limits the builder from building child packages that have not been listed. If <varname>subPackages</varname> is not specified, all child packages will be built.
-     </para>
-     <para>
-      In this example only <literal>github.com/deis/deis/client</literal> will be built.
-     </para>
-    </callout>
-    <callout arearefs='ex-buildGoPackage-3'>
-     <para>
       <varname>goDeps</varname> is where the Go dependencies of a Go program are listed as a list of package source identified by Go import path. It could be imported as a separate <varname>deps.nix</varname> file for readability. The dependency data structure is described below.
      </para>
     </callout>
-    <callout arearefs='ex-buildGoPackage-4'>
-     <para>
-      <varname>buildFlags</varname> is a list of flags passed to the go build command.
-     </para>
-    </callout>
    </calloutlist>
   </para>
 
@@ -200,4 +179,70 @@ done
 </screen>
   </para>
  </section>
+
+ <section xml:id="ssec-go-common-attributes">
+  <title>Attributes used by the builders</title>
+
+  <para>
+   Both <link xlink:href="#ssec-go-modules"><varname>buildGoModule</varname></link> and <link xlink:href="#ssec-go-modules"><varname>buildGoPackage</varname></link> can be tweaked to behave slightly differently, if the following attributes are used:
+  </para>
+
+  <variablelist>
+   <varlistentry xml:id="var-go-buildFlagsArray">
+    <term>
+     <varname>buildFlagsArray</varname> and <varname>buildFlags</varname>
+    </term>
+    <listitem>
+     <para>
+      These attributes set build flags supported by <varname>go build</varname>. We recommend using <varname>buildFlagsArray</varname>. The most common use case of these attributes is to make the resulting executable aware of its own version. For example:
+     </para>
+     <example xml:id='ex-goBuildFlags-nospaces'>
+      <title>buildFlagsArray</title>
+<programlisting>
+  buildFlagsArray = [
+    "-ldflags=-X main.Version=${version} -X main.Commit=${version}" <co xml:id='ex-goBuildFlags-1' />
+  ];
+</programlisting>
+     </example>
+     <calloutlist>
+      <callout arearefs='ex-goBuildFlags-1'>
+       <para>
+        Note: single quotes are not needed.
+       </para>
+      </callout>
+     </calloutlist>
+     <example xml:id='ex-goBuildFlags-noarray'>
+      <title>buildFlagsArray</title>
+<programlisting>
+  buildFlagsArray = ''
+    -ldflags=
+    -X main.Version=${version}
+    -X main.Commit=${version}
+  '';
+</programlisting>
+     </example>
+    </listitem>
+   </varlistentry>
+   <varlistentry xml:id="var-go-deleteVendor">
+    <term>
+     <varname>deleteVendor</varname>
+    </term>
+    <listitem>
+     <para>
+      Removes the pre-existing vendor directory. This should only be used if the dependencies included in the vendor folder are broken or incomplete.
+     </para>
+    </listitem>
+   </varlistentry>
+   <varlistentry xml:id="var-go-subPackages">
+    <term>
+     <varname>subPackages</varname>
+    </term>
+    <listitem>
+     <para>
+      Limits the builder from building child packages that have not been listed. If <varname>subPackages</varname> is not specified, all child packages will be built.
+     </para>
+    </listitem>
+   </varlistentry>
+  </variablelist>
+ </section>
 </section>
diff --git a/nixpkgs/doc/languages-frameworks/node.section.md b/nixpkgs/doc/languages-frameworks/node.section.md
index c1f4294711a1..2120adfc0b49 100644
--- a/nixpkgs/doc/languages-frameworks/node.section.md
+++ b/nixpkgs/doc/languages-frameworks/node.section.md
@@ -25,12 +25,13 @@ build system it uses. Here are some examples:
 
 After you have identified the correct system, you need to override your package
 expression while adding in build system as a build input. For example, `dat`
-requires `node-gyp-build`, so we override its expression in `default.nix`:
+requires `node-gyp-build`, so [we override](https://github.com/NixOS/nixpkgs/blob/32f5e5da4a1b3f0595527f5195ac3a91451e9b56/pkgs/development/node-packages/default.nix#L37-L40) its expression in [`default.nix`](https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/node-packages/default.nix):
 
 ```nix
-dat = nodePackages.dat.override (oldAttrs: {
-  buildInputs = oldAttrs.buildInputs ++ [ nodePackages.node-gyp-build ];
-});
+    dat = super.dat.override {
+      buildInputs = [ self.node-gyp-build pkgs.libtool pkgs.autoconf pkgs.automake ];
+      meta.broken = since "12";
+    };
 ```
 
 To add a package from NPM to nixpkgs:
diff --git a/nixpkgs/doc/languages-frameworks/perl.xml b/nixpkgs/doc/languages-frameworks/perl.xml
index d9b6b2721c67..b017c028f64c 100644
--- a/nixpkgs/doc/languages-frameworks/perl.xml
+++ b/nixpkgs/doc/languages-frameworks/perl.xml
@@ -3,14 +3,47 @@
          xml:id="sec-language-perl">
  <title>Perl</title>
 
- <para>
-  Nixpkgs provides a function <varname>buildPerlPackage</varname>, a generic package builder function for any Perl package that has a standard <varname>Makefile.PL</varname>. It’s implemented in <link
-xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/perl-modules/generic"><filename>pkgs/development/perl-modules/generic</filename></link>.
- </para>
-
- <para>
-  Perl packages from CPAN are defined in <link
-xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/top-level/perl-packages.nix"><filename>pkgs/top-level/perl-packages.nix</filename></link>, rather than <filename>pkgs/all-packages.nix</filename>. Most Perl packages are so straight-forward to build that they are defined here directly, rather than having a separate function for each package called from <filename>perl-packages.nix</filename>. However, more complicated packages should be put in a separate file, typically in <filename>pkgs/development/perl-modules</filename>. Here is an example of the former:
+ <section xml:id="ssec-perl-running">
+  <title>Running perl programs on the shell</title>
+
+  <para>
+   When executing a Perl script, it is possible you get an error such as <literal>./myscript.pl: bad interpreter: /usr/bin/perl: no such file or directory</literal>. This happens when the script expects Perl to be installed at <filename>/usr/bin/perl</filename>, which is not the case when using Perl from nixpkgs. You can fix the script by changing the first line to:
+<programlisting>
+#!/usr/bin/env perl
+</programlisting>
+  to take the Perl installation from the <literal>PATH</literal> environment variable, or invoke Perl directly with:
+<screen>
+<prompt>$ </prompt>perl ./myscript.pl
+</screen>
+  </para>
+
+  <para>
+   When the script is using a Perl library that is not installed globally, you might get an error such as <literal>Can't locate DB_File.pm in @INC (you may need to install the DB_File module)</literal>. In that case, you can use <command>nix-shell</command> to start an ad-hoc shell with that library installed, for instance:
+<screen>
+<prompt>$ </prompt>nix-shell -p perl perlPackages.DBFile --run ./myscript.pl
+</screen>
+  </para>
+
+  <para>
+  If you are always using the script in places where <command>nix-shell</command> is available, you can embed the <command>nix-shell</command> invocation in the shebang like this:
+<programlisting>
+#!/usr/bin/env nix-shell
+#! nix-shell -i perl -p perl perlPackages.DBFile
+</programlisting>
+  </para>
+ </section>
+
+ <section xml:id="ssec-perl-packaging">
+  <title>Packaging Perl programs</title>
+
+  <para>
+   Nixpkgs provides a function <varname>buildPerlPackage</varname>, a generic package builder function for any Perl package that has a standard <varname>Makefile.PL</varname>. It’s implemented in <link
+ xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/perl-modules/generic"><filename>pkgs/development/perl-modules/generic</filename></link>.
+  </para>
+
+  <para>
+   Perl packages from CPAN are defined in <link
+ xlink:href="https://github.com/NixOS/nixpkgs/blob/master/pkgs/top-level/perl-packages.nix"><filename>pkgs/top-level/perl-packages.nix</filename></link>, rather than <filename>pkgs/all-packages.nix</filename>. Most Perl packages are so straight-forward to build that they are defined here directly, rather than having a separate function for each package called from <filename>perl-packages.nix</filename>. However, more complicated packages should be put in a separate file, typically in <filename>pkgs/development/perl-modules</filename>. Here is an example of the former:
 <programlisting>
 ClassC3 = buildPerlPackage rec {
   name = "Class-C3-0.21";
@@ -20,47 +53,47 @@ ClassC3 = buildPerlPackage rec {
   };
 };
 </programlisting>
-  Note the use of <literal>mirror://cpan/</literal>, and the <literal>${name}</literal> in the URL definition to ensure that the name attribute is consistent with the source that we’re actually downloading. Perl packages are made available in <filename>all-packages.nix</filename> through the variable <varname>perlPackages</varname>. For instance, if you have a package that needs <varname>ClassC3</varname>, you would typically write
+   Note the use of <literal>mirror://cpan/</literal>, and the <literal>${name}</literal> in the URL definition to ensure that the name attribute is consistent with the source that we’re actually downloading. Perl packages are made available in <filename>all-packages.nix</filename> through the variable <varname>perlPackages</varname>. For instance, if you have a package that needs <varname>ClassC3</varname>, you would typically write
 <programlisting>
 foo = import ../path/to/foo.nix {
   inherit stdenv fetchurl ...;
   inherit (perlPackages) ClassC3;
 };
 </programlisting>
-  in <filename>all-packages.nix</filename>. You can test building a Perl package as follows:
+   in <filename>all-packages.nix</filename>. You can test building a Perl package as follows:
 <screen>
 <prompt>$ </prompt>nix-build -A perlPackages.ClassC3
 </screen>
-  <varname>buildPerlPackage</varname> adds <literal>perl-</literal> to the start of the name attribute, so the package above is actually called <literal>perl-Class-C3-0.21</literal>. So to install it, you can say:
+   <varname>buildPerlPackage</varname> adds <literal>perl-</literal> to the start of the name attribute, so the package above is actually called <literal>perl-Class-C3-0.21</literal>. So to install it, you can say:
 <screen>
 <prompt>$ </prompt>nix-env -i perl-Class-C3
 </screen>
-  (Of course you can also install using the attribute name: <literal>nix-env -i -A perlPackages.ClassC3</literal>.)
- </para>
-
- <para>
-  So what does <varname>buildPerlPackage</varname> do? It does the following:
-  <orderedlist>
-   <listitem>
-    <para>
-     In the configure phase, it calls <literal>perl Makefile.PL</literal> to generate a Makefile. You can set the variable <varname>makeMakerFlags</varname> to pass flags to <filename>Makefile.PL</filename>
-    </para>
-   </listitem>
-   <listitem>
-    <para>
-     It adds the contents of the <envar>PERL5LIB</envar> environment variable to <literal>#! .../bin/perl</literal> line of Perl scripts as <literal>-I<replaceable>dir</replaceable></literal> flags. This ensures that a script can find its dependencies. (This can cause this shebang line to become too long for Darwin to handle; see the note below.)
-    </para>
-   </listitem>
-   <listitem>
-    <para>
-     In the fixup phase, it writes the propagated build inputs (<varname>propagatedBuildInputs</varname>) to the file <filename>$out/nix-support/propagated-user-env-packages</filename>. <command>nix-env</command> recursively installs all packages listed in this file when you install a package that has it. This ensures that a Perl package can find its dependencies.
-    </para>
-   </listitem>
-  </orderedlist>
- </para>
-
- <para>
-  <varname>buildPerlPackage</varname> is built on top of <varname>stdenv</varname>, so everything can be customised in the usual way. For instance, the <literal>BerkeleyDB</literal> module has a <varname>preConfigure</varname> hook to generate a configuration file used by <filename>Makefile.PL</filename>:
+   (Of course you can also install using the attribute name: <literal>nix-env -i -A perlPackages.ClassC3</literal>.)
+  </para>
+
+  <para>
+   So what does <varname>buildPerlPackage</varname> do? It does the following:
+   <orderedlist>
+    <listitem>
+     <para>
+      In the configure phase, it calls <literal>perl Makefile.PL</literal> to generate a Makefile. You can set the variable <varname>makeMakerFlags</varname> to pass flags to <filename>Makefile.PL</filename>
+     </para>
+    </listitem>
+    <listitem>
+     <para>
+      It adds the contents of the <envar>PERL5LIB</envar> environment variable to <literal>#! .../bin/perl</literal> line of Perl scripts as <literal>-I<replaceable>dir</replaceable></literal> flags. This ensures that a script can find its dependencies. (This can cause this shebang line to become too long for Darwin to handle; see the note below.)
+     </para>
+    </listitem>
+    <listitem>
+     <para>
+      In the fixup phase, it writes the propagated build inputs (<varname>propagatedBuildInputs</varname>) to the file <filename>$out/nix-support/propagated-user-env-packages</filename>. <command>nix-env</command> recursively installs all packages listed in this file when you install a package that has it. This ensures that a Perl package can find its dependencies.
+     </para>
+    </listitem>
+   </orderedlist>
+  </para>
+
+  <para>
+   <varname>buildPerlPackage</varname> is built on top of <varname>stdenv</varname>, so everything can be customised in the usual way. For instance, the <literal>BerkeleyDB</literal> module has a <varname>preConfigure</varname> hook to generate a configuration file used by <filename>Makefile.PL</filename>:
 <programlisting>
 { buildPerlPackage, fetchurl, db }:
 
@@ -78,10 +111,10 @@ buildPerlPackage rec {
   '';
 }
 </programlisting>
- </para>
+  </para>
 
- <para>
-  Dependencies on other Perl packages can be specified in the <varname>buildInputs</varname> and <varname>propagatedBuildInputs</varname> attributes. If something is exclusively a build-time dependency, use <varname>buildInputs</varname>; if it’s (also) a runtime dependency, use <varname>propagatedBuildInputs</varname>. For instance, this builds a Perl module that has runtime dependencies on a bunch of other modules:
+  <para>
+   Dependencies on other Perl packages can be specified in the <varname>buildInputs</varname> and <varname>propagatedBuildInputs</varname> attributes. If something is exclusively a build-time dependency, use <varname>buildInputs</varname>; if it’s (also) a runtime dependency, use <varname>propagatedBuildInputs</varname>. For instance, this builds a Perl module that has runtime dependencies on a bunch of other modules:
 <programlisting>
 ClassC3Componentised = buildPerlPackage rec {
   name = "Class-C3-Componentised-1.0004";
@@ -94,10 +127,10 @@ ClassC3Componentised = buildPerlPackage rec {
   ];
 };
 </programlisting>
- </para>
+  </para>
 
- <para>
-  On Darwin, if a script has too many <literal>-I<replaceable>dir</replaceable></literal> flags in its first line (its “shebang line”), it will not run. This can be worked around by calling the <literal>shortenPerlShebang</literal> function from the <literal>postInstall</literal> phase:
+  <para>
+   On Darwin, if a script has too many <literal>-I<replaceable>dir</replaceable></literal> flags in its first line (its “shebang line”), it will not run. This can be worked around by calling the <literal>shortenPerlShebang</literal> function from the <literal>postInstall</literal> phase:
 <programlisting>
 { stdenv, buildPerlPackage, fetchurl, shortenPerlShebang }:
 
@@ -116,22 +149,22 @@ ImageExifTool = buildPerlPackage {
   '';
 };
 </programlisting>
-  This will remove the <literal>-I</literal> flags from the shebang line, rewrite them in the <literal>use lib</literal> form, and put them on the next line instead. This function can be given any number of Perl scripts as arguments; it will modify them in-place.
- </para>
+   This will remove the <literal>-I</literal> flags from the shebang line, rewrite them in the <literal>use lib</literal> form, and put them on the next line instead. This function can be given any number of Perl scripts as arguments; it will modify them in-place.
+  </para>
 
- <section xml:id="ssec-generation-from-CPAN">
-  <title>Generation from CPAN</title>
+  <section xml:id="ssec-generation-from-CPAN">
+   <title>Generation from CPAN</title>
 
-  <para>
-   Nix expressions for Perl packages can be generated (almost) automatically from CPAN. This is done by the program <command>nix-generate-from-cpan</command>, which can be installed as follows:
-  </para>
+   <para>
+    Nix expressions for Perl packages can be generated (almost) automatically from CPAN. This is done by the program <command>nix-generate-from-cpan</command>, which can be installed as follows:
+   </para>
 
 <screen>
 <prompt>$ </prompt>nix-env -i nix-generate-from-cpan
 </screen>
 
-  <para>
-   This program takes a Perl module name, looks it up on CPAN, fetches and unpacks the corresponding package, and prints a Nix expression on standard output. For example:
+   <para>
+    This program takes a Perl module name, looks it up on CPAN, fetches and unpacks the corresponding package, and prints a Nix expression on standard output. For example:
 <screen>
 <prompt>$ </prompt>nix-generate-from-cpan XML::Simple
   XMLSimple = buildPerlPackage rec {
@@ -147,15 +180,16 @@ ImageExifTool = buildPerlPackage {
     };
   };
 </screen>
-   The output can be pasted into <filename>pkgs/top-level/perl-packages.nix</filename> or wherever else you need it.
-  </para>
- </section>
+    The output can be pasted into <filename>pkgs/top-level/perl-packages.nix</filename> or wherever else you need it.
+   </para>
+  </section>
 
- <section xml:id="ssec-perl-cross-compilation">
-  <title>Cross-compiling modules</title>
+  <section xml:id="ssec-perl-cross-compilation">
+   <title>Cross-compiling modules</title>
 
-  <para>
-   Nixpkgs has experimental support for cross-compiling Perl modules. In many cases, it will just work out of the box, even for modules with native extensions. Sometimes, however, the Makefile.PL for a module may (indirectly) import a native module. In that case, you will need to make a stub for that module that will satisfy the Makefile.PL and install it into <filename>lib/perl5/site_perl/cross_perl/${perl.version}</filename>. See the <varname>postInstall</varname> for <varname>DBI</varname> for an example.
-  </para>
+   <para>
+    Nixpkgs has experimental support for cross-compiling Perl modules. In many cases, it will just work out of the box, even for modules with native extensions. Sometimes, however, the Makefile.PL for a module may (indirectly) import a native module. In that case, you will need to make a stub for that module that will satisfy the Makefile.PL and install it into <filename>lib/perl5/site_perl/cross_perl/${perl.version}</filename>. See the <varname>postInstall</varname> for <varname>DBI</varname> for an example.
+   </para>
+  </section>
  </section>
 </section>
diff --git a/nixpkgs/doc/languages-frameworks/python.section.md b/nixpkgs/doc/languages-frameworks/python.section.md
index dc10483ce694..e2d9172919ef 100644
--- a/nixpkgs/doc/languages-frameworks/python.section.md
+++ b/nixpkgs/doc/languages-frameworks/python.section.md
@@ -538,8 +538,123 @@ buildPythonPackage rec {
 ```
 Note also the line `doCheck = false;`, we explicitly disabled running the test-suite.
 
+#### Testing Python Packages
+
+It is highly encouraged to have testing as part of the package build. This
+helps to avoid situations where the package was able to build and install,
+but is not usable at runtime. Currently, all packages will use the `test`
+command provided by the setup.py (i.e. `python setup.py test`). However,
+this is currently deprecated https://github.com/pypa/setuptools/pull/1878
+and your package should provide its own checkPhase.
+
+*NOTE:* The `checkPhase` for python maps to the `installCheckPhase` on a
+normal derivation. This is due to many python packages not behaving well
+to the pre-installed version of the package. Version info, and natively
+compiled extensions generally only exist in the install directory, and
+thus can cause issues when a test suite asserts on that behavior.
+
+*NOTE:* Tests should only be disabled if they don't agree with nix
+(e.g. external dependencies, network access, flakey tests), however,
+as many tests should be enabled as possible. Failing tests can still be
+a good indication that the package is not in a valid state.
+
+#### Using pytest
+
+Pytest is the most common test runner for python repositories. A trivial
+test run would be:
+```
+  checkInputs = [ pytest ];
+  checkPhase = "pytest";
+```
+
+However, many repositories' test suites do not translate well to nix's build
+sandbox, and will generally need many tests to be disabled.
+
+To filter tests using pytest, one can do the following:
+```
+  checkInputs = [ pytest ];
+  # avoid tests which need additional data or touch network
+  checkPhase = ''
+    pytest tests/ --ignore=tests/integration -k 'not download and not update'
+  '';
+```
+
+`--ignore` will tell pytest to ignore that file or directory from being
+collected as part of a test run. This is useful is a file uses a package
+which is not available in nixpkgs, thus skipping that test file is much
+easier than having to create a new package.
+
+`-k` is used to define a predicate for test names. In this example, we are
+filtering out tests which contain `download` or `update` in their test case name.
+Only one `-k` argument is allows, and thus a long predicate should be concatenated
+with "\" and wrapped to the next line.
+
+*NOTE:* In pytest==6.0.1, the use of "\" to continue a line (e.g. `-k 'not download \'`) has
+been removed, in this case, it's recommended to use `pytestCheckHook`.
+
+#### Using pytestCheckHook
+
+`pytestCheckHook` is a convenient hook which will substitute the setuptools
+`test` command for a checkPhase which runs `pytest`. This is also beneficial
+when a package may need many items disabled to run the test suite.
+
+Using the example above, the analagous pytestCheckHook usage would be:
+```
+  checkInputs = [ pytestCheckHook ];
+
+  # requires additional data
+  pytestFlagsArray = [ "tests/" "--ignore=tests/integration" ];
+
+  disabledTests = [
+    # touches network
+    "download"
+    "update"
+  ];
+```
+
+This is expecially useful when tests need to be conditionallydisabled,
+for example:
+
+```
+  disabledTests = [
+    # touches network
+    "download"
+    "update"
+  ] ++ lib.optionals (pythonAtLeast "3.8") [
+    # broken due to python3.8 async changes
+    "async"
+  ] ++ lib.optionals stdenv.isDarwin [
+    # can fail when building with other packages
+    "socket"
+  ];
+```
+Trying to concatenate the related strings to disable tests in a regular checkPhase
+would be much harder to read. This also enables us to comment on why specific tests
+are disabled.
+
+#### Using pythonImportsCheck
+
+Although unit tests are highly prefered to valid correctness of a package. Not
+all packages have test suites that can be ran easily, and some have none at all.
+To help ensure the package still works, `pythonImportsCheck` can attempt to import
+the listed modules.
+
+```
+  pythonImportsCheck = [ "requests" "urllib" ];
+```
+roughly translates to:
+```
+  postCheck = ''
+    PYTHONPATH=$out/${python.sitePackages}:$PYTHONPATH
+    python -c "import requests; import urllib"
+  '';
+```
+However, this is done in it's own phase, and not dependent on whether `doCheck = true;`
+
+This can also be useful in verifying that the package doesn't assume commonly
+present packages (e.g. `setuptools`)
 
-#### Develop local package
+### Develop local package
 
 As a Python developer you're likely aware of [development mode](http://setuptools.readthedocs.io/en/latest/setuptools.html#development-mode)
 (`python setup.py develop`); instead of installing the package this command
@@ -640,8 +755,8 @@ and in this case the `python38` interpreter is automatically used.
 
 ### Interpreters
 
-Versions 2.7, 3.5, 3.6, 3.7 and 3.8 of the CPython interpreter are available as
-respectively `python27`, `python35`, `python36`, `python37` and `python38`. The
+Versions 2.7, 3.6, 3.7 and 3.8 of the CPython interpreter are available as
+respectively `python27`, `python36`, `python37` and `python38`. The
 aliases `python2` and `python3` correspond to respectively `python27` and
 `python38`. The default interpreter, `python`, maps to `python2`. The PyPy
 interpreters compatible with Python 2.7 and 3 are available as `pypy27` and
@@ -689,15 +804,16 @@ attribute set is created for each available Python interpreter. The available
 sets are
 
 * `pkgs.python27Packages`
-* `pkgs.python35Packages`
 * `pkgs.python36Packages`
 * `pkgs.python37Packages`
+* `pkgs.python38Packages`
+* `pkgs.python39Packages`
 * `pkgs.pypyPackages`
 
 and the aliases
 
 * `pkgs.python2Packages` pointing to `pkgs.python27Packages`
-* `pkgs.python3Packages` pointing to `pkgs.python37Packages`
+* `pkgs.python3Packages` pointing to `pkgs.python38Packages`
 * `pkgs.pythonPackages` pointing to `pkgs.python2Packages`
 
 #### `buildPythonPackage` function
@@ -1016,7 +1132,7 @@ are used in `buildPythonPackage`.
 - `pipBuildHook` to build a wheel using `pip` and PEP 517. Note a build system
   (e.g. `setuptools` or `flit`) should still be added as `nativeBuildInput`.
 - `pipInstallHook` to install wheels.
-- `pytestCheckHook` to run tests with `pytest`.
+- `pytestCheckHook` to run tests with `pytest`. See [example usage](#using-pytestcheckhook).
 - `pythonCatchConflictsHook` to check whether a Python package is not already existing.
 - `pythonImportsCheckHook` to check whether importing the listed modules works.
 - `pythonRemoveBinBytecode` to remove bytecode from the `/bin` folder.
diff --git a/nixpkgs/doc/languages-frameworks/qt.xml b/nixpkgs/doc/languages-frameworks/qt.xml
index 8d97de504ad3..ec95621d8ff2 100644
--- a/nixpkgs/doc/languages-frameworks/qt.xml
+++ b/nixpkgs/doc/languages-frameworks/qt.xml
@@ -18,7 +18,7 @@ mkDerivation { <co xml:id='qt-default-nix-co-2' />
 
   buildInputs = [ qtbase ]; <co xml:id='qt-default-nix-co-3' />
 }
-   </programlisting>
+</programlisting>
  </example>
 
  <calloutlist>
diff --git a/nixpkgs/doc/languages-frameworks/ruby.xml b/nixpkgs/doc/languages-frameworks/ruby.xml
index 9b36801fb966..9b579d6804f4 100644
--- a/nixpkgs/doc/languages-frameworks/ruby.xml
+++ b/nixpkgs/doc/languages-frameworks/ruby.xml
@@ -12,14 +12,14 @@
  </para>
 
 <screen>
-<![CDATA[$ cd pkgs/servers/monitoring
-$ mkdir sensu
-$ cd sensu
-$ cat > Gemfile
+<prompt>$ </prompt>cd pkgs/servers/monitoring
+<prompt>$ </prompt>mkdir sensu
+<prompt>$ </prompt>cd sensu
+<prompt>$ </prompt>cat > Gemfile
 source 'https://rubygems.org'
 gem 'sensu'
-$ $(nix-build '<nixpkgs>' -A bundix --no-out-link)/bin/bundix --magic
-$ cat > default.nix
+<prompt>$ </prompt>$(nix-build '&lt;nixpkgs>' -A bundix --no-out-link)/bin/bundix --magic
+<prompt>$ </prompt>cat > default.nix
 { lib, bundlerEnv, ruby }:
 
 bundlerEnv rec {
@@ -37,7 +37,7 @@ bundlerEnv rec {
     maintainers = with maintainers; [ theuni ];
     platforms   = platforms.unix;
   };
-}]]>
+}
 </screen>
 
  <para>
@@ -49,17 +49,16 @@ bundlerEnv rec {
  </para>
 
 <screen>
-<![CDATA[$ cd pkgs/servers/monitoring/sensu
-$ nix-shell -p bundler --run 'bundle lock --update'
-$ nix-shell -p bundix --run 'bundix'
-]]>
+<prompt>$ </prompt>cd pkgs/servers/monitoring/sensu
+<prompt>$ </prompt>nix-shell -p bundler --run 'bundle lock --update'
+<prompt>$ </prompt>nix-shell -p bundix --run 'bundix'
 </screen>
 
  <para>
   For tools written in Ruby - i.e. where the desire is to install a package and then execute e.g. <command>rake</command> at the command line, there is an alternative builder called <literal>bundlerApp</literal>. Set up the <filename>gemset.nix</filename> the same way, and then, for example:
  </para>
 
-<screen>
+<programlisting>
 <![CDATA[{ lib, bundlerApp }:
 
 bundlerApp {
@@ -75,7 +74,7 @@ bundlerApp {
     platforms   = platforms.unix;
   };
 }]]>
-</screen>
+</programlisting>
 
  <para>
   The chief advantage of <literal>bundlerApp</literal> over <literal>bundlerEnv</literal> is the executables introduced in the environment are precisely those selected in the <literal>exes</literal> list, as opposed to <literal>bundlerEnv</literal> which adds all the executables made available by gems in the gemset, which can mean e.g. <command>rspec</command> or <command>rake</command> in unpredictable versions available from various packages.
diff --git a/nixpkgs/doc/languages-frameworks/rust.section.md b/nixpkgs/doc/languages-frameworks/rust.section.md
index ec418c563359..0e1d59e1a952 100644
--- a/nixpkgs/doc/languages-frameworks/rust.section.md
+++ b/nixpkgs/doc/languages-frameworks/rust.section.md
@@ -43,7 +43,6 @@ rustPlatform.buildRustPackage rec {
     homepage = "https://github.com/BurntSushi/ripgrep";
     license = licenses.unlicense;
     maintainers = [ maintainers.tailhook ];
-    platforms = platforms.all;
   };
 }
 ```
@@ -51,7 +50,7 @@ rustPlatform.buildRustPackage rec {
 `buildRustPackage` requires a `cargoSha256` attribute which is computed over
 all crate sources of this package. Currently it is obtained by inserting a
 fake checksum into the expression and building the package once. The correct
-checksum can be then take from the failed build.
+checksum can then be taken from the failed build.
 
 Per the instructions in the [Cargo Book](https://doc.rust-lang.org/cargo/guide/cargo-toml-vs-cargo-lock.html)
 best practices guide, Rust applications should always commit the `Cargo.lock`
@@ -79,7 +78,7 @@ pkgs.rustPlatform.buildRustPackage {
 
 When using `buildRustPackage`, the `checkPhase` is enabled by default and runs
 `cargo test` on the package to build. To make sure that we don't compile the
-sources twice and to actually test the artifacts that will be used at runtime, 
+sources twice and to actually test the artifacts that will be used at runtime,
 the tests will be ran in the `release` mode by default.
 
 However, in some cases the test-suite of a package doesn't work properly in the
@@ -120,6 +119,18 @@ The above are just guidelines, and exceptions may be granted on a case-by-case b
 However, please check if it's possible to disable a problematic subset of the
 test suite and leave a comment explaining your reasoning.
 
+#### Setting `test-threads`
+
+`buildRustPackage` will use parallel test threads by default,
+sometimes it may be necessary to disable this so the tests run consecutively.
+
+```nix
+rustPlatform.buildRustPackage {
+  /* ... */
+  cargoParallelTestThreads = false;
+}
+```
+
 ### Building a package in `debug` mode
 
 By default, `buildRustPackage` will use `release` mode for builds. If a package
diff --git a/nixpkgs/doc/languages-frameworks/texlive.xml b/nixpkgs/doc/languages-frameworks/texlive.xml
index a581ec5911cb..141c46e5a623 100644
--- a/nixpkgs/doc/languages-frameworks/texlive.xml
+++ b/nixpkgs/doc/languages-frameworks/texlive.xml
@@ -44,11 +44,11 @@ texlive.combine {
    <listitem>
     <para>
      You can list packages e.g. by <command>nix repl</command>.
-<programlisting><![CDATA[
-$ nix repl
-nix-repl> :l <nixpkgs>
-nix-repl> texlive.collection-<TAB>
-]]></programlisting>
+<programlisting>
+<prompt>$ </prompt>nix repl
+<prompt>nix-repl> </prompt>:l &lt;nixpkgs>
+<prompt>nix-repl> </prompt>texlive.collection-<keycap function="tab" />
+</programlisting>
     </para>
    </listitem>
    <listitem>
diff --git a/nixpkgs/doc/languages-frameworks/vim.section.md b/nixpkgs/doc/languages-frameworks/vim.section.md
index 4911509212e6..8e4826232e1a 100644
--- a/nixpkgs/doc/languages-frameworks/vim.section.md
+++ b/nixpkgs/doc/languages-frameworks/vim.section.md
@@ -263,6 +263,8 @@ Sometimes plugins require an override that must be changed when the plugin is up
 
 To add a new plugin, run `./update.py --add "[owner]/[name]"`. **NOTE**: This script automatically commits to your git repository. Be sure to check out a fresh branch before running.
 
+Finally, there are some plugins that are also packaged in nodePackages because they have Javascript-related build steps, such as running webpack. Those plugins are not listed in `vim-plugin-names` or managed by `update.py` at all, and are included separately in `overrides.nix`. Currently, all these plugins are related to the `coc.nvim` ecosystem of Language Server Protocol integration with vim/neovim.
+
 ## Important repositories
 
 - [vim-pi](https://bitbucket.org/vimcommunity/vim-pi) is a plugin repository