nixpkgs docs: move fhs-environments to its own file

2 files changed, 145 insertions, 141 deletions

diff --git a/doc/functions.xml b/doc/functions.xml
index b710d30e1081..ac75c4fc10e4 100644
--- a/doc/functions.xml
+++ b/doc/functions.xml
@@ -11,147 +11,7 @@
  <xi:include href="functions/overrides.xml" />
  <xi:include href="functions/generators.xml" />
  <xi:include href="functions/debug.xml" />
- <section xml:id="sec-fhs-environments">
-  <title>buildFHSUserEnv</title>
-
-  <para>
-   <function>buildFHSUserEnv</function> provides a way to build and run
-   FHS-compatible lightweight sandboxes. It creates an isolated root with bound
-   <filename>/nix/store</filename>, so its footprint in terms of disk space
-   needed is quite small. This allows one to run software which is hard or
-   unfeasible to patch for NixOS -- 3rd-party source trees with FHS
-   assumptions, games distributed as tarballs, software with integrity checking
-   and/or external self-updated binaries. It uses Linux namespaces feature to
-   create temporary lightweight environments which are destroyed after all
-   child processes exit, without root user rights requirement. Accepted
-   arguments are:
-  </para>
-
-  <variablelist>
-   <varlistentry>
-    <term>
-     <literal>name</literal>
-    </term>
-    <listitem>
-     <para>
-      Environment name.
-     </para>
-    </listitem>
-   </varlistentry>
-   <varlistentry>
-    <term>
-     <literal>targetPkgs</literal>
-    </term>
-    <listitem>
-     <para>
-      Packages to be installed for the main host's architecture (i.e. x86_64 on
-      x86_64 installations). Along with libraries binaries are also installed.
-     </para>
-    </listitem>
-   </varlistentry>
-   <varlistentry>
-    <term>
-     <literal>multiPkgs</literal>
-    </term>
-    <listitem>
-     <para>
-      Packages to be installed for all architectures supported by a host (i.e.
-      i686 and x86_64 on x86_64 installations). Only libraries are installed by
-      default.
-     </para>
-    </listitem>
-   </varlistentry>
-   <varlistentry>
-    <term>
-     <literal>extraBuildCommands</literal>
-    </term>
-    <listitem>
-     <para>
-      Additional commands to be executed for finalizing the directory
-      structure.
-     </para>
-    </listitem>
-   </varlistentry>
-   <varlistentry>
-    <term>
-     <literal>extraBuildCommandsMulti</literal>
-    </term>
-    <listitem>
-     <para>
-      Like <literal>extraBuildCommands</literal>, but executed only on multilib
-      architectures.
-     </para>
-    </listitem>
-   </varlistentry>
-   <varlistentry>
-    <term>
-     <literal>extraOutputsToInstall</literal>
-    </term>
-    <listitem>
-     <para>
-      Additional derivation outputs to be linked for both target and
-      multi-architecture packages.
-     </para>
-    </listitem>
-   </varlistentry>
-   <varlistentry>
-    <term>
-     <literal>extraInstallCommands</literal>
-    </term>
-    <listitem>
-     <para>
-      Additional commands to be executed for finalizing the derivation with
-      runner script.
-     </para>
-    </listitem>
-   </varlistentry>
-   <varlistentry>
-    <term>
-     <literal>runScript</literal>
-    </term>
-    <listitem>
-     <para>
-      A command that would be executed inside the sandbox and passed all the
-      command line arguments. It defaults to <literal>bash</literal>.
-     </para>
-    </listitem>
-   </varlistentry>
-  </variablelist>
-
-  <para>
-   One can create a simple environment using a <literal>shell.nix</literal>
-   like that:
-  </para>
-
-<programlisting><![CDATA[
-{ pkgs ? import <nixpkgs> {} }:
-
-(pkgs.buildFHSUserEnv {
-  name = "simple-x11-env";
-  targetPkgs = pkgs: (with pkgs;
-    [ udev
-      alsaLib
-    ]) ++ (with pkgs.xorg;
-    [ libX11
-      libXcursor
-      libXrandr
-    ]);
-  multiPkgs = pkgs: (with pkgs;
-    [ udev
-      alsaLib
-    ]);
-  runScript = "bash";
-}).env
-]]></programlisting>
-
-  <para>
-   Running <literal>nix-shell</literal> would then drop you into a shell with
-   these libraries and binaries available. You can use this to run
-   closed-source applications which expect FHS structure without hassles:
-   simply change <literal>runScript</literal> to the application path, e.g.
-   <filename>./bin/start.sh</filename> -- relative paths are supported.
-  </para>
- </section>
+ <xi:include href="functions/fhs-environments.xml" />
  <xi:include href="shell.section.xml" />
  <section xml:id="sec-pkgs-dockerTools">
   <title>pkgs.dockerTools</title>
diff --git a/doc/functions/fhs-environments.xml b/doc/functions/fhs-environments.xml
new file mode 100644
index 000000000000..bfe0db522a1d
--- /dev/null
+++ b/doc/functions/fhs-environments.xml
@@ -0,0 +1,144 @@
+<section xmlns="http://docbook.org/ns/docbook"
+         xmlns:xlink="http://www.w3.org/1999/xlink"
+         xmlns:xi="http://www.w3.org/2001/XInclude"
+         xml:id="sec-fhs-environments">
+  <title>buildFHSUserEnv</title>
+
+  <para>
+   <function>buildFHSUserEnv</function> provides a way to build and run
+   FHS-compatible lightweight sandboxes. It creates an isolated root with bound
+   <filename>/nix/store</filename>, so its footprint in terms of disk space
+   needed is quite small. This allows one to run software which is hard or
+   unfeasible to patch for NixOS -- 3rd-party source trees with FHS
+   assumptions, games distributed as tarballs, software with integrity checking
+   and/or external self-updated binaries. It uses Linux namespaces feature to
+   create temporary lightweight environments which are destroyed after all
+   child processes exit, without root user rights requirement. Accepted
+   arguments are:
+  </para>
+
+  <variablelist>
+   <varlistentry>
+    <term>
+     <literal>name</literal>
+    </term>
+    <listitem>
+     <para>
+      Environment name.
+     </para>
+    </listitem>
+   </varlistentry>
+   <varlistentry>
+    <term>
+     <literal>targetPkgs</literal>
+    </term>
+    <listitem>
+     <para>
+      Packages to be installed for the main host's architecture (i.e. x86_64 on
+      x86_64 installations). Along with libraries binaries are also installed.
+     </para>
+    </listitem>
+   </varlistentry>
+   <varlistentry>
+    <term>
+     <literal>multiPkgs</literal>
+    </term>
+    <listitem>
+     <para>
+      Packages to be installed for all architectures supported by a host (i.e.
+      i686 and x86_64 on x86_64 installations). Only libraries are installed by
+      default.
+     </para>
+    </listitem>
+   </varlistentry>
+   <varlistentry>
+    <term>
+     <literal>extraBuildCommands</literal>
+    </term>
+    <listitem>
+     <para>
+      Additional commands to be executed for finalizing the directory
+      structure.
+     </para>
+    </listitem>
+   </varlistentry>
+   <varlistentry>
+    <term>
+     <literal>extraBuildCommandsMulti</literal>
+    </term>
+    <listitem>
+     <para>
+      Like <literal>extraBuildCommands</literal>, but executed only on multilib
+      architectures.
+     </para>
+    </listitem>
+   </varlistentry>
+   <varlistentry>
+    <term>
+     <literal>extraOutputsToInstall</literal>
+    </term>
+    <listitem>
+     <para>
+      Additional derivation outputs to be linked for both target and
+      multi-architecture packages.
+     </para>
+    </listitem>
+   </varlistentry>
+   <varlistentry>
+    <term>
+     <literal>extraInstallCommands</literal>
+    </term>
+    <listitem>
+     <para>
+      Additional commands to be executed for finalizing the derivation with
+      runner script.
+     </para>
+    </listitem>
+   </varlistentry>
+   <varlistentry>
+    <term>
+     <literal>runScript</literal>
+    </term>
+    <listitem>
+     <para>
+      A command that would be executed inside the sandbox and passed all the
+      command line arguments. It defaults to <literal>bash</literal>.
+     </para>
+    </listitem>
+   </varlistentry>
+  </variablelist>
+
+  <para>
+   One can create a simple environment using a <literal>shell.nix</literal>
+   like that:
+  </para>
+
+<programlisting><![CDATA[
+{ pkgs ? import <nixpkgs> {} }:
+
+(pkgs.buildFHSUserEnv {
+  name = "simple-x11-env";
+  targetPkgs = pkgs: (with pkgs;
+    [ udev
+      alsaLib
+    ]) ++ (with pkgs.xorg;
+    [ libX11
+      libXcursor
+      libXrandr
+    ]);
+  multiPkgs = pkgs: (with pkgs;
+    [ udev
+      alsaLib
+    ]);
+  runScript = "bash";
+}).env
+]]></programlisting>
+
+  <para>
+   Running <literal>nix-shell</literal> would then drop you into a shell with
+   these libraries and binaries available. You can use this to run
+   closed-source applications which expect FHS structure without hassles:
+   simply change <literal>runScript</literal> to the application path, e.g.
+   <filename>./bin/start.sh</filename> -- relative paths are supported.
+  </para>
+ </section>