From 0856d5c4add0abe92c1a8d15f95003ce5a2b828d Mon Sep 17 00:00:00 2001
From: Graham Christensen <graham@grahamc.com>
Date: Tue, 2 Oct 2018 14:08:36 -0400
Subject: nixpkgs docs: move fhs-environments to its own file

---
 doc/functions.xml | 142 +-----------------------------------------------------
 1 file changed, 1 insertion(+), 141 deletions(-)

(limited to 'doc/functions.xml')

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>
-- 
cgit v1.2.3