Merge branch 'staging-next' into staging

9 files changed, 256 insertions, 295 deletions

diff --git a/doc/builders/packages/emacs.section.md b/doc/builders/packages/emacs.section.md
new file mode 100644
index 000000000000..3829b3575bb1
--- /dev/null
+++ b/doc/builders/packages/emacs.section.md
@@ -0,0 +1,119 @@
+# Emacs {#sec-emacs}
+
+## Configuring Emacs
+
+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:
+
+```nix
+{
+  packageOverrides = pkgs: with pkgs; {
+    myEmacs = emacsWithPackages (epkgs: (with epkgs.melpaStablePackages; [
+      company
+      counsel
+      flycheck
+      ivy
+      magit
+      projectile
+      use-package
+    ]));
+  }
+}
+```
+
+You can install it like any other packages via `nix-env -iA myEmacs`. However, this will only install those packages. It will not `configure` them for us. To do this, we need to provide a configuration file. Luckily, it is possible to do this from within Nix! By modifying the above example, we can make Emacs load a custom config file. The key is to create a package that provide a `default.el` file in `/share/emacs/site-start/`. Emacs knows to load this file automatically when it starts.
+
+```nix
+{
+  packageOverrides = pkgs: with pkgs; rec {
+    myEmacsConfig = writeText "default.el" ''
+      ;; initialize package
+
+      (require 'package)
+      (package-initialize 'noactivate)
+      (eval-when-compile
+        (require 'use-package))
+
+      ;; load some packages
+
+      (use-package company
+        :bind ("<C-tab>" . company-complete)
+        :diminish company-mode
+        :commands (company-mode global-company-mode)
+        :defer 1
+        :config
+        (global-company-mode))
+
+      (use-package counsel
+        :commands (counsel-descbinds)
+        :bind (([remap execute-extended-command] . counsel-M-x)
+               ("C-x C-f" . counsel-find-file)
+               ("C-c g" . counsel-git)
+               ("C-c j" . counsel-git-grep)
+               ("C-c k" . counsel-ag)
+               ("C-x l" . counsel-locate)
+               ("M-y" . counsel-yank-pop)))
+
+      (use-package flycheck
+        :defer 2
+        :config (global-flycheck-mode))
+
+      (use-package ivy
+        :defer 1
+        :bind (("C-c C-r" . ivy-resume)
+               ("C-x C-b" . ivy-switch-buffer)
+               :map ivy-minibuffer-map
+               ("C-j" . ivy-call))
+        :diminish ivy-mode
+        :commands ivy-mode
+        :config
+        (ivy-mode 1))
+
+      (use-package magit
+        :defer
+        :if (executable-find "git")
+        :bind (("C-x g" . magit-status)
+               ("C-x G" . magit-dispatch-popup))
+        :init
+        (setq magit-completing-read-function 'ivy-completing-read))
+
+      (use-package projectile
+        :commands projectile-mode
+        :bind-keymap ("C-c p" . projectile-command-map)
+        :defer 5
+        :config
+        (projectile-global-mode))
+    '';
+
+    myEmacs = emacsWithPackages (epkgs: (with epkgs.melpaStablePackages; [
+      (runCommand "default.el" {} ''
+         mkdir -p $out/share/emacs/site-lisp
+         cp ${myEmacsConfig} $out/share/emacs/site-lisp/default.el
+       '')
+      company
+      counsel
+      flycheck
+      ivy
+      magit
+      projectile
+      use-package
+    ]));
+  };
+}
+```
+
+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'`.
+
+```nix
+overrides = self: super: rec {
+  haskell-mode = self.melpaPackages.haskell-mode;
+  ...
+};
+((emacsPackagesGen emacs).overrideScope' overrides).emacsWithPackages
+  (p: with p; [
+    # here both these package will use haskell-mode of our own choice
+    ghc-mod
+    dante
+  ])
+```
diff --git a/doc/builders/packages/emacs.xml b/doc/builders/packages/emacs.xml
deleted file mode 100644
index 9cce7c40863a..000000000000
--- a/doc/builders/packages/emacs.xml
+++ /dev/null
@@ -1,131 +0,0 @@
-<section xmlns="http://docbook.org/ns/docbook"
-         xmlns:xlink="http://www.w3.org/1999/xlink"
-         xml:id="sec-emacs">
- <title>Emacs</title>
-
- <section xml:id="sec-emacs-config">
-  <title>Configuring Emacs</title>
-
-  <para>
-   The Emacs package comes with some extra helpers to make it easier to configure. <varname>emacsWithPackages</varname> 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 <literal>company</literal>, <literal>counsel</literal>, <literal>flycheck</literal>, <literal>ivy</literal>, <literal>magit</literal>, <literal>projectile</literal>, and <literal>use-package</literal> you could use this as a <filename>~/.config/nixpkgs/config.nix</filename> override:
-  </para>
-
-<screen>
-{
-  packageOverrides = pkgs: with pkgs; {
-    myEmacs = emacsWithPackages (epkgs: (with epkgs.melpaStablePackages; [
-      company
-      counsel
-      flycheck
-      ivy
-      magit
-      projectile
-      use-package
-    ]));
-  }
-}
-</screen>
-
-  <para>
-   You can install it like any other packages via <command>nix-env -iA myEmacs</command>. However, this will only install those packages. It will not <literal>configure</literal> them for us. To do this, we need to provide a configuration file. Luckily, it is possible to do this from within Nix! By modifying the above example, we can make Emacs load a custom config file. The key is to create a package that provide a <filename>default.el</filename> file in <filename>/share/emacs/site-start/</filename>. Emacs knows to load this file automatically when it starts.
-  </para>
-
-<screen>
-{
-  packageOverrides = pkgs: with pkgs; rec {
-    myEmacsConfig = writeText "default.el" ''
-;; initialize package
-
-(require 'package)
-(package-initialize 'noactivate)
-(eval-when-compile
-  (require 'use-package))
-
-;; load some packages
-
-(use-package company
-  :bind ("&lt;C-tab&gt;" . company-complete)
-  :diminish company-mode
-  :commands (company-mode global-company-mode)
-  :defer 1
-  :config
-  (global-company-mode))
-
-(use-package counsel
-  :commands (counsel-descbinds)
-  :bind (([remap execute-extended-command] . counsel-M-x)
-         ("C-x C-f" . counsel-find-file)
-         ("C-c g" . counsel-git)
-         ("C-c j" . counsel-git-grep)
-         ("C-c k" . counsel-ag)
-         ("C-x l" . counsel-locate)
-         ("M-y" . counsel-yank-pop)))
-
-(use-package flycheck
-  :defer 2
-  :config (global-flycheck-mode))
-
-(use-package ivy
-  :defer 1
-  :bind (("C-c C-r" . ivy-resume)
-         ("C-x C-b" . ivy-switch-buffer)
-         :map ivy-minibuffer-map
-         ("C-j" . ivy-call))
-  :diminish ivy-mode
-  :commands ivy-mode
-  :config
-  (ivy-mode 1))
-
-(use-package magit
-  :defer
-  :if (executable-find "git")
-  :bind (("C-x g" . magit-status)
-         ("C-x G" . magit-dispatch-popup))
-  :init
-  (setq magit-completing-read-function 'ivy-completing-read))
-
-(use-package projectile
-  :commands projectile-mode
-  :bind-keymap ("C-c p" . projectile-command-map)
-  :defer 5
-  :config
-  (projectile-global-mode))
-    '';
-    myEmacs = emacsWithPackages (epkgs: (with epkgs.melpaStablePackages; [
-      (runCommand "default.el" {} ''
-mkdir -p $out/share/emacs/site-lisp
-cp ${myEmacsConfig} $out/share/emacs/site-lisp/default.el
-'')
-      company
-      counsel
-      flycheck
-      ivy
-      magit
-      projectile
-      use-package
-    ]));
-  };
-}
-</screen>
-
-  <para>
-   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 <command>-q</command> to the Emacs command.
-  </para>
-
-  <para>
-   Sometimes <varname>emacsWithPackages</varname> 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 <filename>pkgs/top-level/emacs-packages.nix</filename>). 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 <varname>overrideScope'</varname>.
-  </para>
-
-<screen>
-overrides = self: super: rec {
-  haskell-mode = self.melpaPackages.haskell-mode;
-  ...
-};
-((emacsPackagesGen emacs).overrideScope' overrides).emacsWithPackages (p: with p; [
-  # here both these package will use haskell-mode of our own choice
-  ghc-mod
-  dante
-])
-</screen>
- </section>
-</section>
diff --git a/doc/builders/packages/index.xml b/doc/builders/packages/index.xml
index e20b0c689a80..3a7ca59505cf 100644
--- a/doc/builders/packages/index.xml
+++ b/doc/builders/packages/index.xml
@@ -9,9 +9,9 @@
  <xi:include href="dlib.xml" />
  <xi:include href="eclipse.xml" />
  <xi:include href="elm.xml" />
- <xi:include href="emacs.xml" />
+ <xi:include href="emacs.section.xml" />
  <xi:include href="ibus.xml" />
- <xi:include href="kakoune.xml" />
+ <xi:include href="kakoune.section.xml" />
  <xi:include href="linux.xml" />
  <xi:include href="locales.xml" />
  <xi:include href="nginx.xml" />
diff --git a/doc/builders/packages/kakoune.section.md b/doc/builders/packages/kakoune.section.md
new file mode 100644
index 000000000000..8e054777a757
--- /dev/null
+++ b/doc/builders/packages/kakoune.section.md
@@ -0,0 +1,9 @@
+# Kakoune {#sec-kakoune}
+
+Kakoune can be built to autoload plugins:
+
+```nix
+(kakoune.override {
+  plugins = with pkgs.kakounePlugins; [ parinfer-rust ];
+})
+```
diff --git a/doc/builders/packages/kakoune.xml b/doc/builders/packages/kakoune.xml
deleted file mode 100644
index 045dbd0a653b..000000000000
--- a/doc/builders/packages/kakoune.xml
+++ /dev/null
@@ -1,12 +0,0 @@
-<section xmlns="http://docbook.org/ns/docbook"
-         xmlns:xlink="http://www.w3.org/1999/xlink"
-         xml:id="sec-kakoune">
- <title>Kakoune</title>
-
- <para>
-  Kakoune can be built to autoload plugins:
-<programlisting>(kakoune.override {
-  plugins = with pkgs.kakounePlugins; [ parinfer-rust ];
-})</programlisting>
- </para>
-</section>
diff --git a/doc/languages-frameworks/index.xml b/doc/languages-frameworks/index.xml
index 7a4c54fca8d0..22bc6e1baaaf 100644
--- a/doc/languages-frameworks/index.xml
+++ b/doc/languages-frameworks/index.xml
@@ -25,7 +25,7 @@
  <xi:include href="perl.xml" />
  <xi:include href="php.section.xml" />
  <xi:include href="python.section.xml" />
- <xi:include href="qt.xml" />
+ <xi:include href="qt.section.xml" />
  <xi:include href="r.section.xml" />
  <xi:include href="ruby.section.xml" />
  <xi:include href="rust.section.xml" />
diff --git a/doc/languages-frameworks/qt.section.md b/doc/languages-frameworks/qt.section.md
new file mode 100644
index 000000000000..4a37eb4ef7db
--- /dev/null
+++ b/doc/languages-frameworks/qt.section.md
@@ -0,0 +1,124 @@
+# Qt {#sec-language-qt}
+
+This section describes the differences between Nix expressions for Qt libraries and applications and Nix expressions for other C++ software. Some knowledge of the latter is assumed.
+
+There are primarily two problems which the Qt infrastructure is designed to address: ensuring consistent versioning of all dependencies and finding dependencies at runtime.
+
+## Nix expression for a Qt package (default.nix) {#qt-default-nix}
+
+```{=docbook}
+<programlisting>
+{ mkDerivation, lib, qtbase }: <co xml:id='qt-default-nix-co-1' />
+
+mkDerivation { <co xml:id='qt-default-nix-co-2' />
+  pname = "myapp";
+  version = "1.0";
+
+  buildInputs = [ qtbase ]; <co xml:id='qt-default-nix-co-3' />
+}
+</programlisting>
+
+ <calloutlist>
+  <callout arearefs='qt-default-nix-co-1'>
+   <para>
+    Import <literal>mkDerivation</literal> and Qt (such as <literal>qtbase</literal> modules directly. <emphasis>Do not</emphasis> import Qt package sets; the Qt versions of dependencies may not be coherent, causing build and runtime failures.
+   </para>
+  </callout>
+  <callout arearefs='qt-default-nix-co-2'>
+   <para>
+    Use <literal>mkDerivation</literal> instead of <literal>stdenv.mkDerivation</literal>. <literal>mkDerivation</literal> is a wrapper around <literal>stdenv.mkDerivation</literal> which applies some Qt-specific settings. This deriver accepts the same arguments as <literal>stdenv.mkDerivation</literal>; refer to <xref linkend='chap-stdenv' /> for details.
+   </para>
+   <para>
+    To use another deriver instead of <literal>stdenv.mkDerivation</literal>, use <literal>mkDerivationWith</literal>:
+<programlisting>
+mkDerivationWith myDeriver {
+  # ...
+}
+</programlisting>
+    If you cannot use <literal>mkDerivationWith</literal>, please refer to <xref linkend='qt-runtime-dependencies' />.
+   </para>
+  </callout>
+  <callout arearefs='qt-default-nix-co-3'>
+   <para>
+    <literal>mkDerivation</literal> accepts the same arguments as <literal>stdenv.mkDerivation</literal>, such as <literal>buildInputs</literal>.
+   </para>
+  </callout>
+ </calloutlist>
+```
+
+## Locating runtime dependencies {#qt-runtime-dependencies}
+Qt applications need to be wrapped to find runtime dependencies. If you cannot use `mkDerivation` or `mkDerivationWith` above, include `wrapQtAppsHook` in `nativeBuildInputs`:
+
+```nix
+stdenv.mkDerivation {
+  # ...
+
+  nativeBuildInputs = [ wrapQtAppsHook ];
+}
+```
+Entries added to `qtWrapperArgs` are used to modify the wrappers created by `wrapQtAppsHook`. The entries are passed as arguments to [wrapProgram executable makeWrapperArgs](#fun-wrapProgram).
+
+```nix
+mkDerivation {
+  # ...
+
+  qtWrapperArgs = [ ''--prefix PATH : /path/to/bin'' ];
+}
+```
+
+Set `dontWrapQtApps` to stop applications from being wrapped automatically. It is required to wrap applications manually with `wrapQtApp`, using the syntax of [wrapProgram executable makeWrapperArgs](#fun-wrapProgram):
+
+```nix
+mkDerivation {
+  # ...
+
+  dontWrapQtApps = true;
+  preFixup = ''
+      wrapQtApp "$out/bin/myapp" --prefix PATH : /path/to/bin
+  '';
+}
+```
+
+> Note: `wrapQtAppsHook` ignores files that are non-ELF executables. This means that scripts won't be automatically wrapped so you'll need to manually wrap them as previously mentioned. An example of when you'd always need to do this is with Python applications that use PyQT.
+
+Libraries are built with every available version of Qt. Use the `meta.broken` attribute to disable the package for unsupported Qt versions:
+
+```nix
+mkDerivation {
+  # ...
+
+  # Disable this library with Qt &lt; 5.9.0
+  meta.broken = builtins.compareVersions qtbase.version "5.9.0" &lt; 0;
+}
+```
+## 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}
+
+```
+{
+  # ...
+
+  mkLibsForQt5 = self: with self; {
+    # ...
+
+    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.
+
+### Example Adding a QT application to all-packages.nix {#qt-application-all-packages-nix}
+```nix
+{
+  # ...
+
+  myapp = libsForQt5.callPackage ../path/to/myapp/ {};
+
+  # ...
+}
+```
diff --git a/doc/languages-frameworks/qt.xml b/doc/languages-frameworks/qt.xml
deleted file mode 100644
index ec95621d8ff2..000000000000
--- a/doc/languages-frameworks/qt.xml
+++ /dev/null
@@ -1,149 +0,0 @@
-<section xmlns="http://docbook.org/ns/docbook"
-         xmlns:xlink="http://www.w3.org/1999/xlink"
-         xml:id="sec-language-qt">
- <title>Qt</title>
-
- <para>
-  This section describes the differences between Nix expressions for Qt libraries and applications and Nix expressions for other C++ software. Some knowledge of the latter is assumed. There are primarily two problems which the Qt infrastructure is designed to address: ensuring consistent versioning of all dependencies and finding dependencies at runtime.
- </para>
-
- <example xml:id='qt-default-nix'>
-  <title>Nix expression for a Qt package (<filename>default.nix</filename>)</title>
-<programlisting>
-{ mkDerivation, lib, qtbase }: <co xml:id='qt-default-nix-co-1' />
-
-mkDerivation { <co xml:id='qt-default-nix-co-2' />
-  pname = "myapp";
-  version = "1.0";
-
-  buildInputs = [ qtbase ]; <co xml:id='qt-default-nix-co-3' />
-}
-</programlisting>
- </example>
-
- <calloutlist>
-  <callout arearefs='qt-default-nix-co-1'>
-   <para>
-    Import <literal>mkDerivation</literal> and Qt (such as <literal>qtbase</literal> modules directly. <emphasis>Do not</emphasis> import Qt package sets; the Qt versions of dependencies may not be coherent, causing build and runtime failures.
-   </para>
-  </callout>
-  <callout arearefs='qt-default-nix-co-2'>
-   <para>
-    Use <literal>mkDerivation</literal> instead of <literal>stdenv.mkDerivation</literal>. <literal>mkDerivation</literal> is a wrapper around <literal>stdenv.mkDerivation</literal> which applies some Qt-specific settings. This deriver accepts the same arguments as <literal>stdenv.mkDerivation</literal>; refer to <xref linkend='chap-stdenv' /> for details.
-   </para>
-   <para>
-    To use another deriver instead of <literal>stdenv.mkDerivation</literal>, use <literal>mkDerivationWith</literal>:
-<programlisting>
-mkDerivationWith myDeriver {
-  # ...
-}
-</programlisting>
-    If you cannot use <literal>mkDerivationWith</literal>, please refer to <xref linkend='qt-runtime-dependencies' />.
-   </para>
-  </callout>
-  <callout arearefs='qt-default-nix-co-3'>
-   <para>
-    <literal>mkDerivation</literal> accepts the same arguments as <literal>stdenv.mkDerivation</literal>, such as <literal>buildInputs</literal>.
-   </para>
-  </callout>
- </calloutlist>
-
- <formalpara xml:id='qt-runtime-dependencies'>
-  <title>Locating runtime dependencies</title>
-  <para>
-   Qt applications need to be wrapped to find runtime dependencies. If you cannot use <literal>mkDerivation</literal> or <literal>mkDerivationWith</literal> above, include <literal>wrapQtAppsHook</literal> in <literal>nativeBuildInputs</literal>:
-<programlisting>
-stdenv.mkDerivation {
-  # ...
-
-  nativeBuildInputs = [ wrapQtAppsHook ];
-}
-</programlisting>
-  </para>
- </formalpara>
-
- <para>
-  Entries added to <literal>qtWrapperArgs</literal> are used to modify the wrappers created by <literal>wrapQtAppsHook</literal>. The entries are passed as arguments to <xref linkend='fun-wrapProgram' />.
-<programlisting>
-mkDerivation {
-  # ...
-
-  qtWrapperArgs = [ ''--prefix PATH : /path/to/bin'' ];
-}
-</programlisting>
- </para>
-
- <para>
-  Set <literal>dontWrapQtApps</literal> to stop applications from being wrapped automatically. It is required to wrap applications manually with <literal>wrapQtApp</literal>, using the syntax of <xref linkend='fun-wrapProgram' />:
-<programlisting>
-mkDerivation {
-  # ...
-
-  dontWrapQtApps = true;
-  preFixup = ''
-      wrapQtApp "$out/bin/myapp" --prefix PATH : /path/to/bin
-  '';
-}
-</programlisting>
- </para>
-
- <note>
-  <para>
-   <literal>wrapQtAppsHook</literal> ignores files that are non-ELF executables. This means that scripts won't be automatically wrapped so you'll need to manually wrap them as previously mentioned. An example of when you'd always need to do this is with Python applications that use PyQT.
-  </para>
- </note>
-
- <para>
-  Libraries are built with every available version of Qt. Use the <literal>meta.broken</literal> attribute to disable the package for unsupported Qt versions:
-<programlisting>
-mkDerivation {
-  # ...
-
-  # Disable this library with Qt &lt; 5.9.0
-  meta.broken = builtins.compareVersions qtbase.version "5.9.0" &lt; 0;
-}
-</programlisting>
- </para>
-
- <formalpara>
-  <title>Adding a library to Nixpkgs</title>
-  <para>
-   Add a Qt library to <filename>all-packages.nix</filename> by adding it to the collection inside <literal>mkLibsForQt5</literal>. This ensures that the library is built with every available version of Qt as needed.
-   <example xml:id='qt-library-all-packages-nix'>
-    <title>Adding a Qt library to <filename>all-packages.nix</filename></title>
-<programlisting>
-{
-  # ...
-
-  mkLibsForQt5 = self: with self; {
-    # ...
-
-    mylib = callPackage ../path/to/mylib {};
-  };
-
-  # ...
-}
-</programlisting>
-   </example>
-  </para>
- </formalpara>
-
- <formalpara>
-  <title>Adding an application to Nixpkgs</title>
-  <para>
-   Add a Qt application to <filename>all-packages.nix</filename> using <literal>libsForQt5.callPackage</literal> instead of the usual <literal>callPackage</literal>. The former ensures that all dependencies are built with the same version of Qt.
-   <example xml:id='qt-application-all-packages-nix'>
-    <title>Adding a Qt application to <filename>all-packages.nix</filename></title>
-<programlisting>
-{
-  # ...
-
-  myapp = libsForQt5.callPackage ../path/to/myapp/ {};
-
-  # ...
-}
-</programlisting>
-   </example>
-  </para>
- </formalpara>
-</section>
diff --git a/doc/using/overlays.xml b/doc/using/overlays.xml
index 4937e9508857..caacb0a04622 100644
--- a/doc/using/overlays.xml
+++ b/doc/using/overlays.xml
@@ -28,6 +28,7 @@
    </para>
 
    <para>
+    NOTE: DO NOT USE THIS in nixpkgs.
     Further overlays can be added by calling the <literal>pkgs.extend</literal> or <literal>pkgs.appendOverlays</literal>, although it is often preferable to avoid these functions, because they recompute the Nixpkgs fixpoint, which is somewhat expensive to do.
    </para>
   </section>