From 75ea0523c41372cea4450f748c5ef59b0d01702e Mon Sep 17 00:00:00 2001
From: Nikolay Amiantov <ab@fmap.me>
Date: Thu, 9 Jun 2016 18:20:56 +0300
Subject: doc: update buildFHSUserEnv documentation

---
 doc/functions.xml | 84 ++++++++++++++++++++++---------------------------------
 1 file changed, 33 insertions(+), 51 deletions(-)

(limited to 'doc/functions.xml')

diff --git a/doc/functions.xml b/doc/functions.xml
index e6bb6b7deefb..73b178b061f9 100644
--- a/doc/functions.xml
+++ b/doc/functions.xml
@@ -171,42 +171,18 @@ c = lib.makeOverridable f { a = 1; b = 2; }</programlisting>
 
 
 <section xml:id="sec-fhs-environments">
-  <title>buildFHSChrootEnv/buildFHSUserEnv</title>
+  <title>buildFHSUserEnv</title>
 
   <para>
-    <function>buildFHSChrootEnv</function> and
-    <function>buildFHSUserEnv</function> provide a way to build and run
-    FHS-compatible lightweight sandboxes. They get their own isolated root with
-    binded <filename>/nix/store</filename>, so their footprint in terms of disk
+    <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.
-  </para>
-
-  <para>
-    <function>buildFHSChrootEnv</function> allows to create persistent
-    environments, which can be constructed, deconstructed and entered by
-    multiple users at once. A downside is that it requires
-    <literal>root</literal> access for both those who create and destroy and
-    those who enter it. It can be useful to create environments for daemons that
-    one can enter and observe.
-  </para>
-
-  <para>
-    <function>buildFHSUserEnv</function> uses Linux namespaces feature to create
+    self-updated binaries. It uses Linux namespaces feature to create
     temporary lightweight environments which are destroyed after all child
-    processes exit. It does not require root access, and can be useful to create
-    sandboxes and wrap applications.
-  </para>
-
-  <para>
-    Those functions both rely on <function>buildFHSEnv</function>, which creates
-    an actual directory structure given a list of necessary packages and extra
-    build commands.
-    <function>buildFHSChrootEnv</function> and <function>buildFHSUserEnv</function>
-    both accept those arguments which are passed to
-    <function>buildFHSEnv</function>:
+    processes exit, without root user rights requirement. Accepted arguments are:
   </para>
 
   <variablelist>
@@ -220,14 +196,16 @@ c = lib.makeOverridable f { a = 1; b = 2; }</programlisting>
     <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).</para></listitem>
+    (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).</para></listitem>
+    a host (i.e. i686 and x86_64 on x86_64 installations). Only libraries are
+    installed by default.</para></listitem>
     </varlistentry>
 
     <varlistentry>
@@ -240,29 +218,33 @@ c = lib.makeOverridable f { a = 1; b = 2; }</programlisting>
     <varlistentry>
     <term><literal>extraBuildCommandsMulti</literal></term>
 
-    <listitem><para>Like <literal>extraBuildCommandsMulti</literal>, but
+    <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>
-    Additionally, <function>buildFHSUserEnv</function> accepts
-    <literal>runScript</literal> parameter, which is a command that would be
-    executed inside the sandbox and passed all the command line arguments. It
-    default to <literal>bash</literal>.
-  </para>
-  <para>
-    It also uses <literal>CHROOTENV_EXTRA_BINDS</literal> environment variable
-    for binding extra directories in the sandbox to outside places. The format of
-    the variable is <literal>/mnt=test-mnt:/data</literal>, where
-    <literal>/mnt</literal> would be mounted as <literal>/test-mnt</literal>
-    and <literal>/data</literal> would be mounted as <literal>/data</literal>.
-    <literal>extraBindMounts</literal> array argument to
-    <function>buildFHSUserEnv</function> function is prepended to this variable.
-    Latter entries take priority if defined several times -- i.e. in case of
-    <literal>/data=data1:/data=data2</literal> the actual bind path would be
-    <literal>/data2</literal>.
-  </para>
   <para>
     One can create a simple environment using a <literal>shell.nix</literal>
     like that:
-- 
cgit 1.4.1