path: root/doc/manual/env-common.xml

<sect1 id="sec-common-env"><title>Common environment variables</title>

<para>Most Nix commands interpret the following environment variables:</para>

<variablelist>

  
<varlistentry><term><envar>NIX_ROOT</envar></term>

  <listitem><para>If <envar>NIX_ROOT</envar> is set, the Nix command
  will on startup perform a <function>chroot()</function> to the
  specified directory.  This is useful in certain bootstrapping
  situations (e.g., when installing a Nix installation onto a hard
  disk from CD-ROM).</para></listitem>

</varlistentry>

  
<varlistentry><term><envar>NIX_IGNORE_SYMLINK_STORE</envar></term>

  <listitem>

  <para>Normally, the Nix store directory (typically
  <filename>/nix/store</filename>) is not allowed to contain any
  symlink components.  This is to prevent “impure” builds.  Builders
  sometimes “canonicalise” paths by resolving all symlink components.
  Thus, builds on different machines (with
  <filename>/nix/store</filename> resolving to different locations)
  could yield different results.  This is generally not a problem,
  except when builds are deployed to machines where
  <filename>/nix/store</filename> resolves differently.  If you are
  sure that you’re not going to do that, you can set
  <envar>NIX_IGNORE_SYMLINK_STORE</envar> to <envar>1</envar>.</para>

  <para>Note that if you’re symlinking the Nix store so that you can
  put it on another file system than the root file system, on Linux
  you’re better off using <literal>bind</literal> mount points, e.g.,

  <screen>
$ mkdir /nix   
$ mount -o bind /mnt/otherdisk/nix /nix</screen>

  Consult the <citerefentry><refentrytitle>mount</refentrytitle>
  <manvolnum>8</manvolnum></citerefentry> manual page for details.</para>

  </listitem>

</varlistentry>


<varlistentry><term><envar>NIX_STORE_DIR</envar></term>

  <listitem><para>Overrides the location of the Nix store (default
  <filename><replaceable>prefix</replaceable>/store</filename>).</para></listitem>
  
</varlistentry>


<varlistentry><term><envar>NIX_DATA_DIR</envar></term>

  <listitem><para>Overrides the location of the Nix static data
  directory (default
  <filename><replaceable>prefix</replaceable>/share</filename>).</para></listitem>
  
</varlistentry>


<varlistentry><term><envar>NIX_LOG_DIR</envar></term>

  <listitem><para>Overrides the location of the Nix log directory
  (default <filename><replaceable>prefix</replaceable>/log/nix</filename>).</para></listitem>
  
</varlistentry>


<varlistentry><term><envar>NIX_STATE_DIR</envar></term>

  <listitem><para>Overrides the location of the Nix state directory
  (default <filename><replaceable>prefix</replaceable>/var/nix</filename>).</para></listitem>
  
</varlistentry>


<varlistentry><term><envar>NIX_DB_DIR</envar></term>

  <listitem><para>Overrides the location of the Nix database (default
  <filename><replaceable>$NIX_STATE_DIR</replaceable>/db</filename>, i.e.,
  <filename><replaceable>prefix</replaceable>/var/nix/db</filename>).</para></listitem>
  
</varlistentry>


<varlistentry><term><envar>NIX_CONF_DIR</envar></term>

  <listitem><para>Overrides the location of the Nix configuration
  directory (default
  <filename><replaceable>prefix</replaceable>/etc/nix</filename>).</para></listitem>
  
</varlistentry>


<varlistentry><term><envar>NIX_LOG_TYPE</envar></term>

  <listitem><para>Equivalent to the <link
  linkend="opt-log-type"><option>--log-type</option>
  option</link>.</para></listitem>

</varlistentry>
  

<varlistentry><term><envar>TMPDIR</envar></term>

  <listitem><para>Use the specified directory to store temporary
  files.  In particular, this includes temporary build directories;
  these can take up substantial amounts of disk space.  The default is
  <filename>/tmp</filename>.</para></listitem>
  
</varlistentry>


<varlistentry id="envar-build-hook"><term><envar>NIX_BUILD_HOOK</envar></term>

  <listitem>

  <para>Specifies the location of the <emphasis>build hook</emphasis>,
  which is a program (typically some script) that Nix will call
  whenever it wants to build a derivation.  This is used to implement
  distributed builds (see <xref linkend="sec-distributed-builds"
  />).  The protocol by which the calling Nix process and the build
  hook communicate is as follows.</para>

  <para>The build hook is called with the following command-line
  arguments:

  <orderedlist>

    <listitem><para>A boolean value <literal>0</literal> or
    <literal>1</literal> specifying whether Nix can locally execute
    more builds, as per the <link
    linkend="opt-max-jobs"><option>--max-jobs</option> option</link>.
    The purpose of this argument is to allow the hook to not have to
    maintain bookkeeping for the local machine.</para></listitem>

    <listitem><para>The Nix platform identifier for the local machine
    (e.g., <literal>i686-linux</literal>).</para></listitem>

    <listitem><para>The Nix platform identifier for the derivation,
    i.e., its <link linkend="attr-system"><varname>system</varname>
    attribute</link>.</para></listitem>

    <listitem><para>The store path of the derivation.</para></listitem>

  </orderedlist>

  </para>

  <para>On the basis of this information, and whatever persistent
  state the build hook keeps about other machines and their current
  load, it has to decide what to do with the build.  It should print
  out on file descriptor 3 one of the following responses (terminated
  by a newline, <literal>"\n"</literal>):

  <variablelist>

    <varlistentry><term><literal>decline</literal></term>

      <listitem><para>The build hook is not willing or able to perform
      the build; the calling Nix process should do the build itself,
      if possible.</para></listitem>

    </varlistentry>

    <varlistentry><term><literal>postpone</literal></term>

      <listitem><para>The build hook cannot perform the build now, but
      can do so in the future (e.g., because all available build slots
      on remote machines are in use).  The calling Nix process should
      postpone this build until at least one currently running build
      has terminated.</para></listitem>

    </varlistentry>

    <varlistentry><term><literal>accept</literal></term>

      <listitem><para>The build hook has accepted the
      build.</para></listitem>

    </varlistentry>

  </variablelist>

  </para>

  <para>If the build hook accepts the build, it is possible that it is
  no longer necessary to do the build because some other process has
  performed the build in the meantime.  To prevent races, the hook
  must read from file descriptor 4 a single line that tells it whether
  to continue:

  <variablelist>

    <varlistentry><term><literal>cancel</literal></term>

      <listitem><para>The build has already been done, so the hook
      should exit.</para></listitem>

    </varlistentry>
  
    <varlistentry><term><literal>okay</literal></term>

      <listitem><para>The hook should proceed with the build.  At this
      point, the calling Nix process has acquired locks on the output
      path, so no other Nix process will perform the
      build.</para></listitem>

    </varlistentry>

  </variablelist>

  </para>

  <para>If the hook has been told to proceed, Nix will store in the
  hook’s current directory a number of text files that contain
  information about the derivation:

  <variablelist>

    <varlistentry><term><filename>inputs</filename></term>

      <listitem><para>The set of store paths that are inputs to the
      build process (one per line).  These have to be copied
      <emphasis>to</emphasis> the remote machine (in addition to the
      store derivation itself).</para></listitem>

    </varlistentry>
  
    <varlistentry><term><filename>outputs</filename></term>

      <listitem><para>The set of store paths that are outputs of the
      derivation (one per line).  These have to be copied
      <emphasis>from</emphasis> the remote machine if the build
      succeeds.</para></listitem>

    </varlistentry>

    <varlistentry><term><filename>references</filename></term>

      <listitem><para>The reference graph of the inputs, in the format
      accepted by the command <command>nix-store
      --register-validity</command>.  It is necessary to run this
      command on the remote machine after copying the inputs to inform
      Nix on the remote machine that the inputs are valid
      paths.</para></listitem>

    </varlistentry>

  </variablelist>

  </para>

  <para>The hook should copy the inputs to the remote machine,
  register the validity of the inputs, perform the remote build, and
  copy the outputs back to the local machine.  An exit code other than
  <literal>0</literal> indicates that the hook has failed.</para>

  </listitem>


</varlistentry>


</variablelist>

</sect1>