1 files changed, 142 insertions, 0 deletions
diff --git a/nixpkgs/doc/functions/fhs-environments.xml b/nixpkgs/doc/functions/fhs-environments.xml
new file mode 100644
index 000000000000..79682080be31
--- /dev/null
+++ b/nixpkgs/doc/functions/fhs-environments.xml
@@ -0,0 +1,142 @@
+<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>