nixpkgs docs: move fhs-environments to its own file

1 files changed, 144 insertions, 0 deletions

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>