path: root/doc/functions.xml

<chapter xmlns="http://docbook.org/ns/docbook"
         xmlns:xlink="http://www.w3.org/1999/xlink"
         xmlns:xi="http://www.w3.org/2001/XInclude"
         xml:id="chap-functions">
 <title>Functions reference</title>
 <para>
  The nixpkgs repository has several utility functions to manipulate Nix
  expressions.
 </para>

 <xi:include href="functions/overrides.xml" />
 <section xml:id="sec-generators">
  <title>Generators</title>

  <para>
   Generators are functions that create file formats from nix data structures,
   e. g. for configuration files. There are generators available for:
   <literal>INI</literal>, <literal>JSON</literal> and <literal>YAML</literal>
  </para>

  <para>
   All generators follow a similar call interface: <code>generatorName
   configFunctions data</code>, where <literal>configFunctions</literal> is an
   attrset of user-defined functions that format nested parts of the content.
   They each have common defaults, so often they do not need to be set
   manually. An example is <code>mkSectionName ? (name: libStr.escape [ "[" "]"
   ] name)</code> from the <literal>INI</literal> generator. It receives the
   name of a section and sanitizes it. The default
   <literal>mkSectionName</literal> escapes <literal>[</literal> and
   <literal>]</literal> with a backslash.
  </para>

  <para>
   Generators can be fine-tuned to produce exactly the file format required by
   your application/service. One example is an INI-file format which uses
   <literal>: </literal> as separator, the strings
   <literal>"yes"</literal>/<literal>"no"</literal> as boolean values and
   requires all string values to be quoted:
  </para>

<programlisting>
with lib;
let
  customToINI = generators.toINI {
    # specifies how to format a key/value pair
    mkKeyValue = generators.mkKeyValueDefault {
      # specifies the generated string for a subset of nix values
      mkValueString = v:
             if v == true then ''"yes"''
        else if v == false then ''"no"''
        else if isString v then ''"${v}"''
        # and delegats all other values to the default generator
        else generators.mkValueStringDefault {} v;
    } ":";
  };

# the INI file can now be given as plain old nix values
in customToINI {
  main = {
    pushinfo = true;
    autopush = false;
    host = "localhost";
    port = 42;
  };
  mergetool = {
    merge = "diff3";
  };
}
</programlisting>

  <para>
   This will produce the following INI file as nix string:
  </para>

<programlisting>
[main]
autopush:"no"
host:"localhost"
port:42
pushinfo:"yes"
str\:ange:"very::strange"

[mergetool]
merge:"diff3"
</programlisting>

  <note>
   <para>
    Nix store paths can be converted to strings by enclosing a derivation
    attribute like so: <code>"${drv}"</code>.
   </para>
  </note>

  <para>
   Detailed documentation for each generator can be found in
   <literal>lib/generators.nix</literal>.
  </para>
 </section>
 <section xml:id="sec-debug">
  <title>Debugging Nix Expressions</title>

  <para>
   Nix is a unityped, dynamic language, this means every value can potentially
   appear anywhere. Since it is also non-strict, evaluation order and what
   ultimately is evaluated might surprise you. Therefore it is important to be
   able to debug nix expressions.
  </para>

  <para>
   In the <literal>lib/debug.nix</literal> file you will find a number of
   functions that help (pretty-)printing values while evaluation is runnnig.
   You can even specify how deep these values should be printed recursively,
   and transform them on the fly. Please consult the docstrings in
   <literal>lib/debug.nix</literal> for usage information.
  </para>
 </section>
 <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