Merge commit '891f607d5301d6730cb1f9dcf3618bcb1ab7f10e'

21 files changed, 390 insertions, 132 deletions

diff --git a/nixpkgs/doc/builders/packages/emacs.section.md b/nixpkgs/doc/builders/packages/emacs.section.md
index e9b89d086d68..b4723a22bb1c 100644
--- a/nixpkgs/doc/builders/packages/emacs.section.md
+++ b/nixpkgs/doc/builders/packages/emacs.section.md
@@ -2,12 +2,12 @@
 
 ## Configuring Emacs {#sec-emacs-config}
 
-The Emacs package comes with some extra helpers to make it easier to configure. `emacsWithPackages` allows you to manage packages from ELPA. This means that you will not have to install that packages from within Emacs. For instance, if you wanted to use `company` `counsel`, `flycheck`, `ivy`, `magit`, `projectile`, and `use-package` you could use this as a `~/.config/nixpkgs/config.nix` override:
+The Emacs package comes with some extra helpers to make it easier to configure. `emacs.pkgs.withPackages` allows you to manage packages from ELPA. This means that you will not have to install that packages from within Emacs. For instance, if you wanted to use `company` `counsel`, `flycheck`, `ivy`, `magit`, `projectile`, and `use-package` you could use this as a `~/.config/nixpkgs/config.nix` override:
 
 ```nix
 {
   packageOverrides = pkgs: with pkgs; {
-    myEmacs = emacsWithPackages (epkgs: (with epkgs.melpaStablePackages; [
+    myEmacs = emacs.pkgs.withPackages (epkgs: (with epkgs.melpaStablePackages; [
       company
       counsel
       flycheck
@@ -84,7 +84,7 @@ You can install it like any other packages via `nix-env -iA myEmacs`. However, t
         (projectile-global-mode))
     '';
 
-    myEmacs = emacsWithPackages (epkgs: (with epkgs.melpaStablePackages; [
+    myEmacs = emacs.pkgs.withPackages (epkgs: (with epkgs.melpaStablePackages; [
       (runCommand "default.el" {} ''
          mkdir -p $out/share/emacs/site-lisp
          cp ${myEmacsConfig} $out/share/emacs/site-lisp/default.el
@@ -103,14 +103,14 @@ You can install it like any other packages via `nix-env -iA myEmacs`. However, t
 
 This provides a fairly full Emacs start file. It will load in addition to the user's presonal config. You can always disable it by passing `-q` to the Emacs command.
 
-Sometimes `emacsWithPackages` is not enough, as this package set has some priorities imposed on packages (with the lowest priority assigned to Melpa Unstable, and the highest for packages manually defined in `pkgs/top-level/emacs-packages.nix`). But you can't control this priorities when some package is installed as a dependency. You can override it on per-package-basis, providing all the required dependencies manually - but it's tedious and there is always a possibility that an unwanted dependency will sneak in through some other package. To completely override such a package you can use `overrideScope'`.
+Sometimes `emacs.pkgs.withPackages` is not enough, as this package set has some priorities imposed on packages (with the lowest priority assigned to Melpa Unstable, and the highest for packages manually defined in `pkgs/top-level/emacs-packages.nix`). But you can't control this priorities when some package is installed as a dependency. You can override it on per-package-basis, providing all the required dependencies manually - but it's tedious and there is always a possibility that an unwanted dependency will sneak in through some other package. To completely override such a package you can use `overrideScope'`.
 
 ```nix
 overrides = self: super: rec {
   haskell-mode = self.melpaPackages.haskell-mode;
   ...
 };
-((emacsPackagesGen emacs).overrideScope' overrides).emacsWithPackages
+((emacsPackagesFor emacs).overrideScope' overrides).emacs.pkgs.withPackages
   (p: with p; [
     # here both these package will use haskell-mode of our own choice
     ghc-mod
diff --git a/nixpkgs/doc/builders/packages/fish.section.md b/nixpkgs/doc/builders/packages/fish.section.md
new file mode 100644
index 000000000000..3086bd68348f
--- /dev/null
+++ b/nixpkgs/doc/builders/packages/fish.section.md
@@ -0,0 +1,50 @@
+# Fish {#sec-fish}
+
+Fish is a "smart and user-friendly command line shell" with support for plugins.
+
+
+## Vendor Fish scripts {#sec-fish-vendor}
+
+Any package may ship its own Fish completions, configuration snippets, and
+functions. Those should be installed to
+`$out/share/fish/vendor_{completions,conf,functions}.d` respectively.
+
+When the `programs.fish.enable` and
+`programs.fish.vendor.{completions,config,functions}.enable` options from the
+NixOS Fish module are set to true, those paths are symlinked in the current
+system environment and automatically loaded by Fish.
+
+
+## Packaging Fish plugins {#sec-fish-plugins-pkg}
+
+While packages providing standalone executables belong to the top level,
+packages which have the sole purpose of extending Fish belong to the
+`fishPlugins` scope and should be registered in
+`pkgs/shells/fish/plugins/default.nix`.
+
+The `buildFishPlugin` utility function can be used to automatically copy Fish
+scripts from `$src/{completions,conf,conf.d,functions}` to the standard vendor
+installation paths. It also sets up the test environment so that the optional
+`checkPhase` is executed in a Fish shell with other already packaged plugins
+and package-local Fish functions specified in `checkPlugins` and
+`checkFunctionDirs` respectively.
+
+See `pkgs/shells/fish/plugins/pure.nix` for an example of Fish plugin package
+using `buildFishPlugin` and running unit tests with the `fishtape` test runner.
+
+
+## Fish wrapper {#sec-fish-wrapper}
+
+The `wrapFish` package is a wrapper around Fish which can be used to create
+Fish shells initialised with some plugins as well as completions, configuration
+snippets and functions sourced from the given paths. This provides a convenient
+way to test Fish plugins and scripts without having to alter the environment.
+
+```nix
+wrapFish {
+  pluginPkgs = with fishPlugins; [ pure foreign-env ];
+  completionDirs = [];
+  functionDirs = [];
+  confDirs = [ "/path/to/some/fish/init/dir/" ];
+}
+```
diff --git a/nixpkgs/doc/builders/packages/index.xml b/nixpkgs/doc/builders/packages/index.xml
index 732560ec1992..ab335e24ff99 100644
--- a/nixpkgs/doc/builders/packages/index.xml
+++ b/nixpkgs/doc/builders/packages/index.xml
@@ -11,6 +11,7 @@
  <xi:include href="elm.xml" />
  <xi:include href="emacs.section.xml" />
  <xi:include href="firefox.section.xml" />
+ <xi:include href="fish.section.xml" />
  <xi:include href="ibus.xml" />
  <xi:include href="kakoune.section.xml" />
  <xi:include href="linux.section.xml" />
diff --git a/nixpkgs/doc/contributing/coding-conventions.xml b/nixpkgs/doc/contributing/coding-conventions.xml
index e587275a6383..9005a9ebafd6 100644
--- a/nixpkgs/doc/contributing/coding-conventions.xml
+++ b/nixpkgs/doc/contributing/coding-conventions.xml
@@ -178,6 +178,21 @@ args.stdenv.mkDerivation (args // {
 </programlisting>
     </para>
    </listitem>
+   <listitem>
+    <para>
+     Arguments should be listed in the order they are used, with the
+     exception of <varname>lib</varname>, which always goes first.
+    </para>
+   </listitem>
+   <listitem>
+    <para>
+     Prefer using the top-level <varname>lib</varname> over its alias
+     <literal>stdenv.lib</literal>.  <varname>lib</varname> is unrelated to
+     <varname>stdenv</varname>, and so <literal>stdenv.lib</literal> should only
+     be used as a convenience alias when developing to avoid having to modify
+     the function inputs just to test something out.
+    </para>
+   </listitem>
   </itemizedlist>
  </section>
  <section xml:id="sec-package-naming">
diff --git a/nixpkgs/doc/languages-frameworks/android.section.md b/nixpkgs/doc/languages-frameworks/android.section.md
index cfbacf1bccdc..62e544cd48b6 100644
--- a/nixpkgs/doc/languages-frameworks/android.section.md
+++ b/nixpkgs/doc/languages-frameworks/android.section.md
@@ -13,21 +13,19 @@ with import <nixpkgs> {};
 
 let
   androidComposition = androidenv.composeAndroidPackages {
-    toolsVersion = "25.2.5";
-    platformToolsVersion = "27.0.1";
-    buildToolsVersions = [ "27.0.3" ];
+    toolsVersion = "26.1.1";
+    platformToolsVersion = "30.0.5";
+    buildToolsVersions = [ "30.0.3" ];
     includeEmulator = false;
-    emulatorVersion = "27.2.0";
-    platformVersions = [ "24" ];
+    emulatorVersion = "30.3.4";
+    platformVersions = [ "28" "29" "30" ];
     includeSources = false;
-    includeDocs = false;
     includeSystemImages = false;
-    systemImageTypes = [ "default" ];
-    abiVersions = [ "armeabi-v7a" ];
-    lldbVersions = [ "2.0.2558144" ];
-    cmakeVersions = [ "3.6.4111459" ];
-    includeNDK = false;
-    ndkVersion = "16.1.4479499";
+    systemImageTypes = [ "google_apis_playstore" ];
+    abiVersions = [ "armeabi-v7a" "arm64-v8a" ];
+    cmakeVersions = [ "3.10.2" ];
+    includeNDK = true;
+    ndkVersion = "22.0.7026061";
     useGoogleAPIs = false;
     useGoogleTVAddOns = false;
     includeExtras = [
@@ -46,13 +44,11 @@ The following parameters are supported:
 
 * `toolsVersion`, specifies the version of the tools package to use
 * `platformsToolsVersion` specifies the version of the `platform-tools` plugin
-* `buildToolsVersion` specifies the versions of the `build-tools` plugins to
+* `buildToolsVersions` specifies the versions of the `build-tools` plugins to
   use.
 * `includeEmulator` specifies whether to deploy the emulator package (`false`
   by default). When enabled, the version of the emulator to deploy can be
   specified by setting the `emulatorVersion` parameter.
-* `includeDocs` specifies whether the documentation catalog should be included.
-* `lldbVersions` specifies what LLDB versions should be deployed.
 * `cmakeVersions` specifies which CMake versions should be deployed.
 * `includeNDK` specifies that the Android NDK bundle should be included.
   Defaults to: `false`.
@@ -82,6 +78,38 @@ For each requested system image we can specify the following options:
 
 Most of the function arguments have reasonable default settings.
 
+You can specify license names:
+
+* `extraLicenses` is a list of of license names.
+  You can get these names from repo.json or `querypackages.sh licenses`. The SDK
+  license (`android-sdk-license`) is accepted for you if you set accept_license
+  to true. If you are doing something like working with preview SDKs, you will
+  want to add `android-sdk-preview-license` or whichever license applies here.
+
+Additionally, you can override the repositories that composeAndroidPackages will
+pull from:
+
+* `repoJson` specifies a path to a generated repo.json file. You can generate this
+  by running `generate.sh`, which in turn will call into `mkrepo.rb`.
+* `repoXmls` is an attribute set containing paths to repo XML files. If specified,
+  it takes priority over `repoJson`, and will trigger a local build writing out a
+  repo.json to the Nix store based on the given repository XMLs.
+
+```nix
+repoXmls = {
+  packages = [ ./xml/repository2-1.xml ];
+  images = [
+    ./xml/android-sys-img2-1.xml
+    ./xml/android-tv-sys-img2-1.xml
+    ./xml/android-wear-sys-img2-1.xml
+    ./xml/android-wear-cn-sys-img2-1.xml
+    ./xml/google_apis-sys-img2-1.xml
+    ./xml/google_apis_playstore-sys-img2-1.xml
+  ];
+  addons = [ ./xml/addon2-1.xml ];
+};
+```
+
 When building the above expression with:
 
 ```bash
@@ -104,8 +132,8 @@ in
 androidComposition.platform-tools
 ```
 
-Using predefine Android package compositions
---------------------------------------------
+Using predefined Android package compositions
+---------------------------------------------
 In addition to composing an Android package set manually, it is also possible
 to use a predefined composition that contains all basic packages for a specific
 Android version, such as version 9.0 (API-level 28).
@@ -209,27 +237,104 @@ androidenv.emulateApp {
 In addition to prebuilt APKs, you can also bind the APK parameter to a
 `buildApp {}` function invocation shown in the previous example.
 
+Notes on environment variables in Android projects
+--------------------------------------------------
+* `ANDROID_SDK_ROOT` should point to the Android SDK. In your Nix expressions, this should be
+  `${androidComposition.androidsdk}/libexec/android-sdk`. Note that `ANDROID_HOME` is deprecated,
+  but if you rely on tools that need it, you can export it too.
+* `ANDROID_NDK_ROOT` should point to the Android NDK, if you're doing NDK development.
+  In your Nix expressions, this should be `${ANDROID_SDK_ROOT}/ndk-bundle`.
+
+If you are running the Android Gradle plugin, you need to export GRADLE_OPTS to override aapt2
+to point to the aapt2 binary in the Nix store as well, or use a FHS environment so the packaged
+aapt2 can run. If you don't want to use a FHS environment, something like this should work:
+
+```nix
+let
+  buildToolsVersion = "30.0.3";
+
+  # Use buildToolsVersion when you define androidComposition
+  androidComposition = <...>;
+in
+pkgs.mkShell rec {
+  ANDROID_SDK_ROOT = "${androidComposition.androidsdk}/libexec/android-sdk";
+  ANDROID_NDK_ROOT = "${ANDROID_SDK_ROOT}/ndk-bundle";
+
+  # Use the same buildToolsVersion here
+  GRADLE_OPTS = "-Dorg.gradle.project.android.aapt2FromMavenOverride=${ANDROID_SDK_ROOT}/build-tools/${buildToolsVersion}/aapt2";
+}
+```
+
+If you are using cmake, you need to add it to PATH in a shell hook or FHS env profile.
+The path is suffixed with a build number, but properly prefixed with the version.
+So, something like this should suffice:
+
+```nix
+let
+  cmakeVersion = "3.10.2";
+
+  # Use cmakeVersion when you define androidComposition
+  androidComposition = <...>;
+in
+pkgs.mkShell rec {
+  ANDROID_SDK_ROOT = "${androidComposition.androidsdk}/libexec/android-sdk";
+  ANDROID_NDK_ROOT = "${ANDROID_SDK_ROOT}/ndk-bundle";
+
+  # Use the same cmakeVersion here
+  shellHook = ''
+    export PATH="$(echo "$ANDROID_SDK_ROOT/cmake/${cmakeVersion}".*/bin):$PATH"
+  '';
+}
+```
+
+Note that running Android Studio with ANDROID_SDK_ROOT set will automatically write a
+`local.properties` file with `sdk.dir` set to $ANDROID_SDK_ROOT if one does not already
+exist. If you are using the NDK as well, you may have to add `ndk.dir` to this file.
+
+An example shell.nix that does all this for you is provided in examples/shell.nix.
+This shell.nix includes a shell hook that overwrites local.properties with the correct
+sdk.dir and ndk.dir values. This will ensure that the SDK and NDK directories will
+both be correct when you run Android Studio inside nix-shell.
+
+Notes on improving build.gradle compatibility
+---------------------------------------------
+Ensure that your buildToolsVersion and ndkVersion match what is declared in androidenv.
+If you are using cmake, make sure its declared version is correct too.
+
+Otherwise, you may get cryptic errors from aapt2 and the Android Gradle plugin warning
+that it cannot install the build tools because the SDK directory is not writeable.
+
+```gradle
+android {
+    buildToolsVersion "30.0.3"
+    ndkVersion = "22.0.7026061"
+    externalNativeBuild {
+        cmake {
+            version "3.10.2"
+        }
+    }
+}
+
+```
+
 Querying the available versions of each plugin
 ----------------------------------------------
-When using any of the previously shown functions, it may be a bit inconvenient
-to find out what options are supported, since the Android SDK provides many
-plugins.
+repo.json provides all the options in one file now.
 
-A shell script in the `pkgs/development/mobile/androidenv/` sub directory can be used to retrieve all
+A shell script in the `pkgs/development/mobile/androidenv/` subdirectory can be used to retrieve all
 possible options:
 
 ```bash
-sh ./querypackages.sh packages build-tools
+./querypackages.sh packages
 ```
 
-The above command-line instruction queries all build-tools versions in the
-generated `packages.nix` expression.
+The above command-line instruction queries all package versions in repo.json.
 
 Updating the generated expressions
 ----------------------------------
-Most of the Nix expressions are generated from XML files that the Android
-package manager uses. To update the expressions run the `generate.sh` script
-that is stored in the `pkgs/development/mobile/androidenv/` sub directory:
+repo.json is generated from XML files that the Android Studio package manager uses.
+To update the expressions run the `generate.sh` script that is stored in the
+`pkgs/development/mobile/androidenv/` subdirectory:
 
 ```bash
 ./generate.sh
diff --git a/nixpkgs/doc/languages-frameworks/coq.section.md b/nixpkgs/doc/languages-frameworks/coq.section.md
index 714e84efc8db..8f564c6e46b6 100644
--- a/nixpkgs/doc/languages-frameworks/coq.section.md
+++ b/nixpkgs/doc/languages-frameworks/coq.section.md
@@ -1,40 +1,79 @@
-# Coq {#sec-language-coq}
+# Coq and coq packages {#sec-language-coq}
 
-Coq libraries should be installed in `$(out)/lib/coq/${coq.coq-version}/user-contrib/`. Such directories are automatically added to the `$COQPATH` environment variable by the hook defined in the Coq derivation.
+## Coq derivation: `coq`
 
-Some extensions (plugins) might require OCaml and sometimes other OCaml packages. The `coq.ocamlPackages` attribute can be used to depend on the same package set Coq was built against.
+The Coq derivation is overridable through the `coq.override overrides`, where overrides is an attribute set which contains the arguments to override. We recommend overriding either of the following
 
-Coq libraries may be compatible with some specific versions of Coq only. The `compatibleCoqVersions` attribute is used to precisely select those versions of Coq that are compatible with this derivation.
+* `version` (optional, defaults to the latest version of Coq selected for nixpkgs, see `pkgs/top-level/coq-packages` to witness this choice), which follows the conventions explained in the `coqPackages` section below,
+* `customOCamlPackage` (optional, defaults to `null`, which lets Coq choose a version automatically), which can be set to any of the ocaml packages attribute of `ocaml-ng` (such as `ocaml-ng.ocamlPackages_4_10` which is the default for Coq 8.11 for example).
+* `coq-version` (optional, defaults to the short version e.g. "8.10"), is a version number of the form "x.y" that indicates which Coq's version build behavior to mimic when using a source which is not a release. E.g. `coq.override { version = "d370a9d1328a4e1cdb9d02ee032f605a9d94ec7a"; coq-version = "8.10"; }`.
 
-Here is a simple package example. It is a pure Coq library, thus it depends on Coq. It builds on the Mathematical Components library, thus it also takes `mathcomp` as `buildInputs`. Its `Makefile` has been generated using `coq_makefile` so we only have to set the `$COQLIB` variable at install time.
+## Coq packages attribute sets: `coqPackages`
+
+The recommended way of defining a derivation for a Coq library, is to use the `coqPackages.mkCoqDerivation` function, which is essentially a specialization of `mkDerivation` taking into account most of the specifics of Coq libraries. The following attributes are supported:
+
+* `pname` (required) is the name of the package,
+* `version` (optional, defaults to `null`), is the version to fetch and build,
+  this attribute is interpreted in several ways depending on its type and pattern:
+  * if it is a known released version string, i.e. from the `release` attribute below, the according release is picked, and the `version` attribute of the resulting derivation is set to this release string,
+  * if it is a majorMinor `"x.y"` prefix of a known released version (as defined above), then the latest `"x.y.z"` known released version is selected (for the ordering given by `versionAtLeast`),
+  * if it is a path or a string representing an absolute path (i.e. starting with `"/"`), the provided path is selected as a source, and the `version` attribute of the resulting derivation is set to `"dev"`,
+  * if it is a string of the form `owner:branch` then it tries to download the `branch` of owner `owner` for a project of the same name using the same vcs, and the `version` attribute of the resulting derivation is set to `"dev"`, additionally if the owner is not provided (i.e. if the `owner:` prefix is missing), it defaults to the original owner of the package (see below),
+  * if it is a string of the form `"#N"`, and the domain is github, then it tries to download the current head of the pull request `#N` from github,
+* `defaultVersion` (optional). Coq libraries may be compatible with some specific versions of Coq only. The `defaultVersion` attribute is used when no `version` is provided (or if `version = null`) to select the version of the library to use by default, depending on the context. This selection will mainly depend on a `coq` version number but also possibly on other packages versions (e.g. `mathcomp`). If its value ends up to be `null`, the package is marked for removal in end-user `coqPackages` attribute set.
+* `release` (optional, defaults to `{}`), lists all the known releases of the library and for each of them provides an attribute set with at least a `sha256` attribute (you may use the shell command `nix-prefetch-url --unpack <archive-url>` to find it, where `<archive-url>` is for example `https://github.com/owner/repo/archive/version.tar.gz`), each attribute set of the list of releases also takes optional overloading arguments for the fetcher as below (i.e.`domain`, `owner`, `repo`, `rev` assuming the default fetcher is used) and optional overrides for the result of the fetcher (i.e. `version` and `src`).
+* `fetcher` (optional, default to a generic fetching mechanism supporting github or gitlab based infrastructures), is a function that takes at least an `owner`, a `repo`, a `rev`, and a `sha256` and returns an attribute set with a `version` and `src`.
+* `repo` (optional, defaults to the value of `pname`),
+* `owner` (optional, defaults to `"coq-community"`).
+* `domain` (optional, defaults to `"github.com"`), domains including the strings `"github"` or `"gitlab"` in their names are automatically supported, otherwise, one must change the `fetcher` argument to support them (cf `pkgs/development/coq-modules/heq/default.nix` for an example),
+* `releaseRev` (optional, defaults to `(v: v)`), provides a default mapping from release names to revision hashes/branch names/tags,
+* `displayVersion` (optional), provides a way to alter the computation of `name` from `pname`, by explaining how to display version numbers,
+* `namePrefix` (optional), provides a way to alter the computation of `name` from `pname`, by explaining which dependencies must occur in `name`,
+* `extraBuildInputs` (optional), by default `buildInputs` just contains `coq`, this allows to add more build inputs,
+* `mlPlugin` (optional, defaults to `false`). Some extensions (plugins) might require OCaml and sometimes other OCaml packages. Standard dependencies can be added by setting the current option to `true`. For a finer grain control, the `coq.ocamlPackages` attribute can be used in `extraBuildInputs` to depend on the same package set Coq was built against.
+* `enableParallelBuilding` (optional, defaults to `true`), since it is activated by default, we provide a way to disable it.
+* `extraInstallFlags` (optional), allows to extend `installFlags` which initializes the variable `COQMF_COQLIB` so as to install in the proper subdirectory. Indeed Coq libraries should be installed in `$(out)/lib/coq/${coq.coq-version}/user-contrib/`. Such directories are automatically added to the `$COQPATH` environment variable by the hook defined in the Coq derivation.
+* `setCOQBIN` (optional, defaults to `true`), by default, the environment variable `$COQBIN` is set to the current Coq's binary, but one can disable this behavior by setting it to `false`,
+* `useMelquiondRemake` (optional, default to `null`) is an attribute set, which, if given, overloads the `preConfigurePhases`, `configureFlags`, `buildPhase`, and `installPhase` attributes of the derivation for a specific use in libraries using `remake` as set up by Guillaume Melquiond for `flocq`, `gappalib`, `interval`, and `coquelicot` (see the corresponding derivation for concrete examples of use of this option). For backward compatibility, the attribute `useMelquiondRemake.logpath` must be set to the logical root of the library (otherwise, one can pass `useMelquiondRemake = {}` to activate this without backward compatibility).
+* `dropAttrs`, `keepAttrs`, `dropDerivationAttrs` are all optional and allow to tune which attribute is added or removed from the final call to `mkDerivation`.
+
+It also takes other standard `mkDerivation` attributes, they are added as such, except for `meta` which extends an automatically computed `meta` (where the `platform` is the same as `coq` and the homepage is automatically computed).
+
+Here is a simple package example. It is a pure Coq library, thus it depends on Coq. It builds on the Mathematical Components library, thus it also takes some `mathcomp` derivations as `extraBuildInputs`.
 
 ```nix
-{ stdenv, fetchFromGitHub, coq, mathcomp }:
-
-stdenv.mkDerivation rec {
-  name = "coq${coq.coq-version}-multinomials-${version}";
-  version = "1.0";
-  src = fetchFromGitHub {
-    owner = "math-comp";
-    repo = "multinomials";
-    rev = version;
-    sha256 = "1qmbxp1h81cy3imh627pznmng0kvv37k4hrwi2faa101s6bcx55m";
+{ lib, mkCoqDerivation, version ? null
+, coq, mathcomp, mathcomp-finmap, mathcomp-bigenough }:
+with lib; mkCoqDerivation {
+  /* namePrefix leads to e.g. `name = coq8.11-mathcomp1.11-multinomials-1.5.2` */
+  namePrefix = [ "coq" "mathcomp" ];
+  pname = "multinomials";
+  owner = "math-comp";
+  inherit version;
+  defaultVersion =  with versions; switch [ coq.version mathcomp.version ] [
+      { cases = [ (range "8.7" "8.12")  "1.11.0" ];             out = "1.5.2"; }
+      { cases = [ (range "8.7" "8.11")  (range "1.8" "1.10") ]; out = "1.5.0"; }
+      { cases = [ (range "8.7" "8.10")  (range "1.8" "1.10") ]; out = "1.4"; }
+      { cases = [ "8.6"                 (range "1.6" "1.7") ];  out = "1.1"; }
+    ] null;
+  release = {
+    "1.5.2".sha256 = "15aspf3jfykp1xgsxf8knqkxv8aav2p39c2fyirw7pwsfbsv2c4s";
+    "1.5.1".sha256 = "13nlfm2wqripaq671gakz5mn4r0xwm0646araxv0nh455p9ndjs3";
+    "1.5.0".sha256 = "064rvc0x5g7y1a0nip6ic91vzmq52alf6in2bc2dmss6dmzv90hw";
+    "1.5.0".rev    = "1.5";
+    "1.4".sha256   = "0vnkirs8iqsv8s59yx1fvg1nkwnzydl42z3scya1xp1b48qkgn0p";
+    "1.3".sha256   = "0l3vi5n094nx3qmy66hsv867fnqm196r8v605kpk24gl0aa57wh4";
+    "1.2".sha256   = "1mh1w339dslgv4f810xr1b8v2w7rpx6fgk9pz96q0fyq49fw2xcq";
+    "1.1".sha256   = "1q8alsm89wkc0lhcvxlyn0pd8rbl2nnxg81zyrabpz610qqjqc3s";
+    "1.0".sha256   = "1qmbxp1h81cy3imh627pznmng0kvv37k4hrwi2faa101s6bcx55m";
   };
 
-  buildInputs = [ coq ];
-  propagatedBuildInputs = [ mathcomp ];
-
-  installFlags = "COQLIB=$(out)/lib/coq/${coq.coq-version}/";
+  propagatedBuildInputs =
+    [ mathcomp.ssreflect mathcomp.algebra mathcomp-finmap mathcomp-bigenough ];
 
   meta = {
     description = "A Coq/SSReflect Library for Monoidal Rings and Multinomials";
-    inherit (src.meta) homepage;
-    license = stdenv.lib.licenses.cecill-b;
-    inherit (coq.meta) platforms;
-  };
-
-  passthru = {
-    compatibleCoqVersions = v: builtins.elem v [ "8.5" "8.6" "8.7" ];
+    license = licenses.cecill-c;
   };
 }
 ```
diff --git a/nixpkgs/doc/languages-frameworks/emscripten.section.md b/nixpkgs/doc/languages-frameworks/emscripten.section.md
index 8a47a7b320aa..d391e038070d 100644
--- a/nixpkgs/doc/languages-frameworks/emscripten.section.md
+++ b/nixpkgs/doc/languages-frameworks/emscripten.section.md
@@ -60,7 +60,7 @@ See the `zlib` example:
       stdenv = pkgs.emscriptenStdenv;
     }).overrideDerivation
     (old: rec {
-      buildInputs = old.buildInputs ++ [ pkgconfig ];
+      buildInputs = old.buildInputs ++ [ pkg-config ];
       # we need to reset this setting!
       NIX_CFLAGS_COMPILE="";
       configurePhase = ''
@@ -102,7 +102,7 @@ See the `zlib` example:
         echo "================= /testing zlib using node ================="
       '';
 
-      postPatch = pkgs.stdenv.lib.optionalString pkgs.stdenv.isDarwin ''
+      postPatch = pkgs.lib.optionalString pkgs.stdenv.isDarwin ''
         substituteInPlace configure \
           --replace '/usr/bin/libtool' 'ar' \
           --replace 'AR="libtool"' 'AR="ar"' \
@@ -117,8 +117,8 @@ This `xmlmirror` example features a emscriptenPackage which is defined completel
     xmlmirror = pkgs.buildEmscriptenPackage rec {
       name = "xmlmirror";
 
-      buildInputs = [ pkgconfig autoconf automake libtool gnumake libxml2 nodejs openjdk json_c ];
-      nativeBuildInputs = [ pkgconfig zlib ];
+      buildInputs = [ pkg-config autoconf automake libtool gnumake libxml2 nodejs openjdk json_c ];
+      nativeBuildInputs = [ pkg-config zlib ];
 
       src = pkgs.fetchgit {
         url = "https://gitlab.com/odfplugfest/xmlmirror.git";
diff --git a/nixpkgs/doc/languages-frameworks/idris.section.md b/nixpkgs/doc/languages-frameworks/idris.section.md
index 2d06c4a19de5..41e4f7ec3127 100644
--- a/nixpkgs/doc/languages-frameworks/idris.section.md
+++ b/nixpkgs/doc/languages-frameworks/idris.section.md
@@ -69,11 +69,11 @@ prelude
 As an example of how a Nix expression for an Idris package can be created, here is the one for `idrisPackages.yaml`:
 
 ```nix
-{ build-idris-package
+{ lib
+, build-idris-package
 , fetchFromGitHub
 , contrib
 , lightyear
-, lib
 }:
 build-idris-package  {
   name = "yaml";
@@ -94,11 +94,11 @@ build-idris-package  {
     sha256 = "1g4pi0swmg214kndj85hj50ccmckni7piprsxfdzdfhg87s0avw7";
   };
 
-  meta = {
+  meta = with lib; {
     description = "Idris YAML lib";
     homepage = "https://github.com/Heather/Idris.Yaml";
-    license = lib.licenses.mit;
-    maintainers = [ lib.maintainers.brainrape ];
+    license = licenses.mit;
+    maintainers = [ maintainers.brainrape ];
   };
 }
 ```
diff --git a/nixpkgs/doc/languages-frameworks/lua.section.md b/nixpkgs/doc/languages-frameworks/lua.section.md
index 248e5971818b..d81949c75f69 100644
--- a/nixpkgs/doc/languages-frameworks/lua.section.md
+++ b/nixpkgs/doc/languages-frameworks/lua.section.md
@@ -181,7 +181,7 @@ luaposix = buildLuarocksPackage {
   disabled = (luaOlder "5.1") || (luaAtLeast "5.4");
   propagatedBuildInputs = [ bit32 lua std_normalize ];
 
-  meta = with stdenv.lib; {
+  meta = with lib; {
     homepage = "https://github.com/luaposix/luaposix/";
     description = "Lua bindings for POSIX";
     maintainers = with maintainers; [ vyp lblasc ];
@@ -243,4 +243,3 @@ Following rules should be respected:
 
 * Make sure libraries build for all Lua interpreters.
 * Commit names of Lua libraries should reflect that they are Lua libraries, so write for example `luaPackages.luafilesystem: 1.11 -> 1.12`.
-
diff --git a/nixpkgs/doc/languages-frameworks/maven.section.md b/nixpkgs/doc/languages-frameworks/maven.section.md
index 5f3979d69fdd..d66931e808d7 100644
--- a/nixpkgs/doc/languages-frameworks/maven.section.md
+++ b/nixpkgs/doc/languages-frameworks/maven.section.md
@@ -116,7 +116,7 @@ The first step will be to build the Maven project as a fixed-output derivation i
 > Traditionally the Maven repository is at `~/.m2/repository`. We will override this to be the `$out` directory.
 
 ```nix
-{ stdenv, maven }:
+{ lib, stdenv, maven }:
 stdenv.mkDerivation {
   name = "maven-repository";
   buildInputs = [ maven ];
@@ -139,7 +139,7 @@ stdenv.mkDerivation {
   outputHashAlgo = "sha256";
   outputHashMode = "recursive";
   # replace this with the correct SHA256
-  outputHash = stdenv.lib.fakeSha256;
+  outputHash = lib.fakeSha256;
 }
 ```
 
@@ -168,7 +168,7 @@ If your package uses _SNAPSHOT_ dependencies or _version ranges_; there is a str
 Regardless of which strategy is chosen above, the step to build the derivation is the same.
 
 ```nix
-{ stdenv, lib, maven, callPackage }:
+{ stdenv, maven, callPackage }:
 # pick a repository derivation, here we will use buildMaven
 let repository = callPackage ./build-maven-repository.nix { };
 in stdenv.mkDerivation rec {
@@ -222,7 +222,7 @@ We will read the Maven repository and flatten it to a single list. This list wil
 We make sure to provide this classpath to the `makeWrapper`.
 
 ```nix
-{ stdenv, lib, maven, callPackage, makeWrapper, jre }:
+{ stdenv, maven, callPackage, makeWrapper, jre }:
 let
   repository = callPackage ./build-maven-repository.nix { };
 in stdenv.mkDerivation rec {
@@ -298,7 +298,7 @@ Main-Class: Main
 We will modify the derivation above to add a symlink to our repository so that it's accessible to our JAR during the `installPhase`.
 
 ```nix
-{ stdenv, lib, maven, callPackage, makeWrapper, jre }:
+{ stdenv, maven, callPackage, makeWrapper, jre }:
 # pick a repository derivation, here we will use buildMaven
 let repository = callPackage ./build-maven-repository.nix { };
 in stdenv.mkDerivation rec {
diff --git a/nixpkgs/doc/languages-frameworks/ocaml.section.md b/nixpkgs/doc/languages-frameworks/ocaml.section.md
index 1c5a5473a05e..9b92a80f4712 100644
--- a/nixpkgs/doc/languages-frameworks/ocaml.section.md
+++ b/nixpkgs/doc/languages-frameworks/ocaml.section.md
@@ -7,7 +7,7 @@ Given that most of the OCaml ecosystem is now built with dune, nixpkgs includes
 Here is a simple package example. It defines an (optional) attribute `minimumOCamlVersion` that will be used to throw a descriptive evaluation error if building with an older OCaml is attempted. It uses the `fetchFromGitHub` fetcher to get its source. It sets the `doCheck` (optional) attribute to `true` which means that tests will be run with `dune runtest -p angstrom` after the build (`dune build -p angstrom`) is complete. It uses `alcotest` as a build input (because it is needed to run the tests) and `bigstringaf` and `result` as propagated build inputs (thus they will also be available to libraries depending on this library). The library will be installed using the `angstrom.install` file that dune generates.
 
 ```nix
-{ stdenv
+{ lib
 , fetchFromGitHub
 , buildDunePackage
 , alcotest
@@ -32,11 +32,11 @@ buildDunePackage rec {
   propagatedBuildInputs = [ bigstringaf result ];
   doCheck = true;
 
-  meta = {
+  meta = with lib; {
     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 ];
+    license = licenses.bsd3;
+    maintainers = with maintainers; [ sternenseemann ];
   };
 }
 ```
@@ -44,7 +44,7 @@ buildDunePackage rec {
 Here is a second example, this time using a source archive generated with `dune-release`. It is a good idea to use this archive when it is available as it will usually contain substituted variables such as a `%%VERSION%%` field. This library does not depend on any other OCaml library and no tests are run after building it.
 
 ```nix
-{ stdenv
+{ lib
 , fetchurl
 , buildDunePackage
 }:
@@ -60,7 +60,7 @@ buildDunePackage rec {
     sha256 = "1msg3vycd3k8qqj61sc23qks541cxpb97vrnrvrhjnqxsqnh6ygq";
   };
 
-  meta = with stdenv.lib; {
+  meta = with lib; {
     homepage = "https://github.com/flowtype/ocaml-wtf8";
     description = "WTF-8 is a superset of UTF-8 that allows unpaired surrogates.";
     license = licenses.mit;
diff --git a/nixpkgs/doc/languages-frameworks/perl.section.md b/nixpkgs/doc/languages-frameworks/perl.section.md
index 2b31da84553e..dcb7dcb77b65 100644
--- a/nixpkgs/doc/languages-frameworks/perl.section.md
+++ b/nixpkgs/doc/languages-frameworks/perl.section.md
@@ -110,7 +110,7 @@ ClassC3Componentised = buildPerlPackage rec {
 On Darwin, if a script has too many `-Idir` flags in its first line (its “shebang line”), it will not run. This can be worked around by calling the `shortenPerlShebang` function from the `postInstall` phase:
 
 ```nix
-{ stdenv, buildPerlPackage, fetchurl, shortenPerlShebang }:
+{ lib, stdenv, buildPerlPackage, fetchurl, shortenPerlShebang }:
 
 ImageExifTool = buildPerlPackage {
   pname = "Image-ExifTool";
@@ -121,8 +121,8 @@ ImageExifTool = buildPerlPackage {
     sha256 = "0d8v48y94z8maxkmw1rv7v9m0jg2dc8xbp581njb6yhr7abwqdv3";
   };
 
-  buildInputs = stdenv.lib.optional stdenv.isDarwin shortenPerlShebang;
-  postInstall = stdenv.lib.optional stdenv.isDarwin ''
+  buildInputs = lib.optional stdenv.isDarwin shortenPerlShebang;
+  postInstall = lib.optional stdenv.isDarwin ''
     shortenPerlShebang $out/bin/exiftool
   '';
 };
@@ -151,7 +151,7 @@ $ nix-generate-from-cpan XML::Simple
     propagatedBuildInputs = [ XMLNamespaceSupport XMLSAX XMLSAXExpat ];
     meta = {
       description = "An API for simple XML files";
-      license = with stdenv.lib.licenses; [ artistic1 gpl1Plus ];
+      license = with lib.licenses; [ artistic1 gpl1Plus ];
     };
   };
 ```
diff --git a/nixpkgs/doc/languages-frameworks/qt.section.md b/nixpkgs/doc/languages-frameworks/qt.section.md
index 4a37eb4ef7db..5dd415852c10 100644
--- a/nixpkgs/doc/languages-frameworks/qt.section.md
+++ b/nixpkgs/doc/languages-frameworks/qt.section.md
@@ -8,7 +8,7 @@ There are primarily two problems which the Qt infrastructure is designed to addr
 
 ```{=docbook}
 <programlisting>
-{ mkDerivation, lib, qtbase }: <co xml:id='qt-default-nix-co-1' />
+{ mkDerivation, qtbase }: <co xml:id='qt-default-nix-co-1' />
 
 mkDerivation { <co xml:id='qt-default-nix-co-2' />
   pname = "myapp";
@@ -92,32 +92,43 @@ mkDerivation {
 }
 ```
 ## Adding a library to Nixpkgs
-   Add a Qt library to all-packages.nix by adding it to the collection inside `mkLibsForQt5`. This ensures that the library is built with every available version of Qt as needed.
-
-### Example Adding a Qt library to all-packages.nix {#qt-library-all-packages-nix}
+Qt libraries are added to `qt5-packages.nix` and are made available for every Qt
+version supported.
+### Example adding a Qt library {#qt-library-all-packages-nix}
 
+The following represents the contents of `qt5-packages.nix`.
 ```
 {
   # ...
 
-  mkLibsForQt5 = self: with self; {
-    # ...
-
-    mylib = callPackage ../path/to/mylib {};
-  };
+  mylib = callPackage ../path/to/mylib {};
 
   # ...
 }
 ```
 ## Adding an application to Nixpkgs
-Add a Qt application to *all-packages.nix* using `libsForQt5.callPackage` instead of the usual `callPackage`. The former ensures that all dependencies are built with the same version of Qt.
+Applications that use Qt are also added to `qt5-packages.nix`. An alias is added
+in the top-level `all-packages.nix` pointing to the package with the desired Qt5 version.
 
-### Example Adding a QT application to all-packages.nix {#qt-application-all-packages-nix}
-```nix
+### Example adding a Qt application {#qt-application-all-packages-nix}
+
+The following represents the contents of `qt5-packages.nix`.
+```
+{
+  # ...
+
+  myapp = callPackage ../path/to/myapp {};
+
+  # ...
+}
+```
+
+The following represents the contents of `all-packages.nix`.
+```
 {
   # ...
 
-  myapp = libsForQt5.callPackage ../path/to/myapp/ {};
+  myapp = libsForQt5.myapp;
 
   # ...
 }
diff --git a/nixpkgs/doc/languages-frameworks/r.section.md b/nixpkgs/doc/languages-frameworks/r.section.md
index d7154adc55bc..c420d112c91e 100644
--- a/nixpkgs/doc/languages-frameworks/r.section.md
+++ b/nixpkgs/doc/languages-frameworks/r.section.md
@@ -32,14 +32,12 @@ However, if you'd like to add a file to your project source to make the
 environment available for other contributors, you can create a `default.nix`
 file like so:
 ```nix
-let
-  pkgs = import <nixpkgs> {};
-  stdenv = pkgs.stdenv;
-in with pkgs; {
+with import <nixpkgs> {};
+{
   myProject = stdenv.mkDerivation {
     name = "myProject";
     version = "1";
-    src = if pkgs.lib.inNixShell then null else nix;
+    src = if lib.inNixShell then null else nix;
 
     buildInputs = with rPackages; [
       R
@@ -105,6 +103,12 @@ mv cran-packages.nix.new cran-packages.nix
 
 Rscript generate-r-packages.R bioc  > bioc-packages.nix.new
 mv bioc-packages.nix.new bioc-packages.nix
+
+Rscript generate-r-packages.R bioc-annotation > bioc-annotation-packages.nix.new
+mv bioc-annotation-packages.nix.new bioc-annotation-packages.nix
+
+Rscript generate-r-packages.R bioc-experiment > bioc-experiment-packages.nix.new
+mv bioc-experiment-packages.nix.new bioc-experiment-packages.nix
 ```
 
 `generate-r-packages.R <repo>` reads  `<repo>-packages.nix`, therefor the renaming.
diff --git a/nixpkgs/doc/languages-frameworks/ruby.section.md b/nixpkgs/doc/languages-frameworks/ruby.section.md
index e292b3110ff4..aeec154586c7 100644
--- a/nixpkgs/doc/languages-frameworks/ruby.section.md
+++ b/nixpkgs/doc/languages-frameworks/ruby.section.md
@@ -232,7 +232,7 @@ If you want to package a specific version, you can use the standard Gemfile synt
 Now you can also also make a `default.nix` that looks like this:
 
 ```nix
-{ lib, bundlerApp }:
+{ bundlerApp }:
 
 bundlerApp {
   pname = "mdl";
diff --git a/nixpkgs/doc/languages-frameworks/rust.section.md b/nixpkgs/doc/languages-frameworks/rust.section.md
index 231cbe900e7d..8f6db28ab4d6 100644
--- a/nixpkgs/doc/languages-frameworks/rust.section.md
+++ b/nixpkgs/doc/languages-frameworks/rust.section.md
@@ -19,6 +19,8 @@ or use Mozilla's [Rust nightlies overlay](#using-the-rust-nightlies-overlay).
 Rust applications are packaged by using the `buildRustPackage` helper from `rustPlatform`:
 
 ```
+{ lib, rustPlatform }:
+
 rustPlatform.buildRustPackage rec {
   pname = "ripgrep";
   version = "12.1.1";
@@ -32,7 +34,7 @@ rustPlatform.buildRustPackage rec {
 
   cargoSha256 = "03wf9r2csi6jpa7v5sw5lpxkrk4wfzwmzx7k3991q3bdjzcwnnwp";
 
-  meta = with stdenv.lib; {
+  meta = with lib; {
     description = "A fast line-oriented regex search tool, similar to ag and ack";
     homepage = "https://github.com/BurntSushi/ripgrep";
     license = licenses.unlicense;
@@ -58,13 +60,13 @@ then be taken from the failed build. A fake hash can be used for
 `cargoSha256` as follows:
 
 ```
-  cargoSha256 = stdenv.lib.fakeSha256;
+  cargoSha256 = lib.fakeSha256;
 ```
 
 For `cargoHash` you can use:
 
 ```
-  cargoHash = stdenv.lib.fakeHash;
+  cargoHash = lib.fakeHash;
 ```
 
 Per the instructions in the [Cargo Book](https://doc.rust-lang.org/cargo/guide/cargo-toml-vs-cargo-lock.html)
@@ -226,8 +228,6 @@ source code in a reproducible way. If it is missing or out-of-date one can use
 the `cargoPatches` attribute to update or add it.
 
 ```
-{ lib, rustPlatform, fetchFromGitHub }:
-
 rustPlatform.buildRustPackage rec {
   (...)
   cargoPatches = [
@@ -263,7 +263,7 @@ Now, the file produced by the call to `carnix`, called `hello.nix`, looks like:
 
 ```
 # Generated by carnix 0.6.5: carnix -o hello.nix --src ./. Cargo.lock --standalone
-{ lib, stdenv, buildRustCrate, fetchgit }:
+{ stdenv, buildRustCrate, fetchgit }:
 let kernel = stdenv.buildPlatform.parsed.kernel.name;
     # ... (content skipped)
 in
@@ -292,7 +292,7 @@ following nix file:
 
 ```
 # Generated by carnix 0.6.5: carnix -o hello.nix --src ./. Cargo.lock --standalone
-{ lib, stdenv, buildRustCrate, fetchgit }:
+{ stdenv, buildRustCrate, fetchgit }:
 let kernel = stdenv.buildPlatform.parsed.kernel.name;
     # ... (content skipped)
 in
@@ -480,7 +480,7 @@ stdenv.mkDerivation {
     rustc cargo
 
     # Example Build-time Additional Dependencies
-    pkgconfig
+    pkg-config
   ];
   buildInputs = [
     # Example Run-time Additional Dependencies
@@ -522,7 +522,7 @@ stdenv.mkDerivation {
     latest.rustChannels.nightly.rust
 
     # Add some extra dependencies from `pkgs`
-    pkgconfig openssl
+    pkg-config openssl
   ];
 
   # Set Environment Variables
@@ -567,12 +567,13 @@ in the `~/.config/nixpkgs/overlays` directory.
 Add the following to your `configuration.nix`, `home-configuration.nix`, `shell.nix`, or similar:
 
 ```
-  nixpkgs = {
+{ pkgs ? import <nixpkgs> {
     overlays = [
       (import (builtins.fetchTarball https://github.com/mozilla/nixpkgs-mozilla/archive/master.tar.gz))
       # Further overlays go here
     ];
   };
+};
 ```
 
 Note that this will fetch the latest overlay version when rebuilding your system.
diff --git a/nixpkgs/doc/shell.nix b/nixpkgs/doc/shell.nix
index 8ac2019f9d66..5fa2b4424899 100644
--- a/nixpkgs/doc/shell.nix
+++ b/nixpkgs/doc/shell.nix
@@ -1,5 +1,3 @@
-{ pkgs ? import ../. {} }:
-(import ./default.nix {}).overrideAttrs (x: {
-  buildInputs = x.buildInputs ++ [ pkgs.xmloscopy pkgs.ruby ];
-
-})
+{ pkgs ? import ../. { } }:
+(import ./default.nix { }).overrideAttrs
+(x: { buildInputs = (x.buildInputs or [ ]) ++ [ pkgs.xmloscopy pkgs.ruby ]; })
diff --git a/nixpkgs/doc/stdenv/meta.xml b/nixpkgs/doc/stdenv/meta.xml
index c9d1b1362193..10802d1af59f 100644
--- a/nixpkgs/doc/stdenv/meta.xml
+++ b/nixpkgs/doc/stdenv/meta.xml
@@ -5,7 +5,7 @@
  <para>
   Nix packages can declare <emphasis>meta-attributes</emphasis> that contain information about a package such as a description, its homepage, its license, and so on. For instance, the GNU Hello package has a <varname>meta</varname> declaration like this:
 <programlisting>
-meta = with stdenv.lib; {
+meta = with lib; {
   description = "A program that produces a familiar, friendly greeting";
   longDescription = ''
     GNU Hello is a program that prints "Hello, world!" when you run it.
@@ -155,7 +155,7 @@ hello-2.3  A program that produces a familiar, friendly greeting
       <itemizedlist>
        <listitem>
         <para>
-         Single license referenced by attribute (preferred) <literal>stdenv.lib.licenses.gpl3Only</literal>.
+         Single license referenced by attribute (preferred) <literal>lib.licenses.gpl3Only</literal>.
         </para>
        </listitem>
        <listitem>
@@ -170,7 +170,7 @@ hello-2.3  A program that produces a familiar, friendly greeting
        </listitem>
        <listitem>
         <para>
-         Multiple licenses referenced by attribute (preferred) <literal>with stdenv.lib.licenses; [ asl20 free ofl ]</literal>.
+         Multiple licenses referenced by attribute (preferred) <literal>with lib.licenses; [ asl20 free ofl ]</literal>.
         </para>
        </listitem>
        <listitem>
@@ -211,9 +211,9 @@ hello-2.3  A program that produces a familiar, friendly greeting
      <para>
       The list of Nix platform types on which the package is supported. Hydra builds packages according to the platform specified. If no platform is specified, the package does not have prebuilt binaries. An example is:
 <programlisting>
-meta.platforms = stdenv.lib.platforms.linux;
+meta.platforms = lib.platforms.linux;
 </programlisting>
-      Attribute Set <varname>stdenv.lib.platforms</varname> defines <link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/lib/systems/doubles.nix"> various common lists</link> of platforms types.
+      Attribute Set <varname>lib.platforms</varname> defines <link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/lib/systems/doubles.nix"> various common lists</link> of platforms types.
      </para>
     </listitem>
    </varlistentry>
@@ -262,7 +262,7 @@ meta.platforms = stdenv.lib.platforms.linux;
      <para>
       The list of Nix platform types for which the Hydra instance at <literal>hydra.nixos.org</literal> will build the package. (Hydra is the Nix-based continuous build system.) It defaults to the value of <varname>meta.platforms</varname>. Thus, the only reason to set <varname>meta.hydraPlatforms</varname> is if you want <literal>hydra.nixos.org</literal> to build the package on a subset of <varname>meta.platforms</varname>, or not at all, e.g.
 <programlisting>
-meta.platforms = stdenv.lib.platforms.linux;
+meta.platforms = lib.platforms.linux;
 meta.hydraPlatforms = [];
 </programlisting>
      </para>
@@ -294,7 +294,7 @@ meta.hydraPlatforms = [];
   <title>Licenses</title>
 
   <para>
-   The <varname>meta.license</varname> attribute should preferrably contain a value from <varname>stdenv.lib.licenses</varname> defined in <link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/lib/licenses.nix"> <filename>nixpkgs/lib/licenses.nix</filename></link>, or in-place license description of the same format if the license is unlikely to be useful in another expression.
+   The <varname>meta.license</varname> attribute should preferrably contain a value from <varname>lib.licenses</varname> defined in <link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/lib/licenses.nix"> <filename>nixpkgs/lib/licenses.nix</filename></link>, or in-place license description of the same format if the license is unlikely to be useful in another expression.
   </para>
 
   <para>
@@ -302,7 +302,7 @@ meta.hydraPlatforms = [];
    <variablelist>
     <varlistentry>
      <term>
-      <varname>stdenv.lib.licenses.free</varname>, <varname>"free"</varname>
+      <varname>lib.licenses.free</varname>, <varname>"free"</varname>
      </term>
      <listitem>
       <para>
@@ -312,7 +312,7 @@ meta.hydraPlatforms = [];
     </varlistentry>
     <varlistentry>
      <term>
-      <varname>stdenv.lib.licenses.unfreeRedistributable</varname>, <varname>"unfree-redistributable"</varname>
+      <varname>lib.licenses.unfreeRedistributable</varname>, <varname>"unfree-redistributable"</varname>
      </term>
      <listitem>
       <para>
@@ -325,7 +325,7 @@ meta.hydraPlatforms = [];
     </varlistentry>
     <varlistentry>
      <term>
-      <varname>stdenv.lib.licenses.unfree</varname>, <varname>"unfree"</varname>
+      <varname>lib.licenses.unfree</varname>, <varname>"unfree"</varname>
      </term>
      <listitem>
       <para>
@@ -335,7 +335,7 @@ meta.hydraPlatforms = [];
     </varlistentry>
     <varlistentry>
      <term>
-      <varname>stdenv.lib.licenses.unfreeRedistributableFirmware</varname>, <varname>"unfree-redistributable-firmware"</varname>
+      <varname>lib.licenses.unfreeRedistributableFirmware</varname>, <varname>"unfree-redistributable-firmware"</varname>
      </term>
      <listitem>
       <para>
diff --git a/nixpkgs/doc/stdenv/platform-notes.xml b/nixpkgs/doc/stdenv/platform-notes.xml
index 5a266fdc0eea..cc8efaece129 100644
--- a/nixpkgs/doc/stdenv/platform-notes.xml
+++ b/nixpkgs/doc/stdenv/platform-notes.xml
@@ -32,7 +32,7 @@ stdenv.mkDerivation {
 stdenv.mkDerivation {
   name = "libfoo-1.2.3";
   # ...
-  makeFlags = stdenv.lib.optional stdenv.isDarwin "LDFLAGS=-Wl,-install_name,$(out)/lib/libfoo.dylib";
+  makeFlags = lib.optional stdenv.isDarwin "LDFLAGS=-Wl,-install_name,$(out)/lib/libfoo.dylib";
 }
 </programlisting>
    </listitem>
diff --git a/nixpkgs/doc/using/configuration.xml b/nixpkgs/doc/using/configuration.xml
index 336bdf5b2656..1e1df867e08e 100644
--- a/nixpkgs/doc/using/configuration.xml
+++ b/nixpkgs/doc/using/configuration.xml
@@ -157,7 +157,7 @@
      The following example configuration whitelists the licenses <literal>amd</literal> and <literal>wtfpl</literal>:
 <programlisting>
 {
-  whitelistedLicenses = with stdenv.lib.licenses; [ amd wtfpl ];
+  whitelistedLicenses = with lib.licenses; [ amd wtfpl ];
 }
 </programlisting>
     </para>
@@ -165,7 +165,7 @@
      The following example configuration blacklists the <literal>gpl3Only</literal> and <literal>agpl3Only</literal> licenses:
 <programlisting>
 {
-  blacklistedLicenses = with stdenv.lib.licenses; [ agpl3Only gpl3Only ];
+  blacklistedLicenses = with lib.licenses; [ agpl3Only gpl3Only ];
 }
 </programlisting>
     </para>
diff --git a/nixpkgs/doc/using/overlays.xml b/nixpkgs/doc/using/overlays.xml
index caacb0a04622..9ffbb4edd989 100644
--- a/nixpkgs/doc/using/overlays.xml
+++ b/nixpkgs/doc/using/overlays.xml
@@ -291,5 +291,40 @@ stdenv.mkDerivation {
 }
 </programlisting>
    </section>
+   <section xml:id="sec-overlays-alternatives-mpi">
+     <title>Switching the MPI implementation</title>
+     <para>
+       All programs that are built with
+       <link xlink:href="https://en.wikipedia.org/wiki/Message_Passing_Interface">MPI</link>
+       support use the generic attribute <varname>mpi</varname>
+       as an input. At the moment Nixpkgs natively provides two different
+       MPI implementations:
+       <itemizedlist>
+         <listitem>
+           <para>
+             <link xlink:href="https://www.open-mpi.org/">Open MPI</link>
+             (default), attribute name <varname>openmpi</varname>
+           </para>
+         </listitem>
+         <listitem>
+           <para>
+             <link xlink:href="https://www.mpich.org/">MPICH</link>,
+             attribute name <varname>mpich</varname>
+           </para>
+         </listitem>
+       </itemizedlist>
+     </para>
+     <para>
+       To provide MPI enabled applications that use <literal>MPICH</literal>, instead
+       of the default <literal>Open MPI</literal>, simply use the following overlay:
+     </para>
+     <programlisting>
+self: super:
+
+{
+  mpi = self.mpich;
+}
+     </programlisting>
+   </section>
  </section>
 </chapter>