path: root/doc/manual/nix-build.xml

<refentry 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-nix-build">

<refmeta>
  <refentrytitle>nix-build</refentrytitle>
  <manvolnum>1</manvolnum>
  <refmiscinfo class="source">Nix</refmiscinfo>
  <refmiscinfo class="version"><xi:include href="version.txt" parse="text"/></refmiscinfo>
</refmeta>

<refnamediv>
  <refname>nix-build</refname>
  <refpurpose>build a Nix expression</refpurpose>
</refnamediv>

<refsynopsisdiv>
  <cmdsynopsis>
    <command>nix-build</command>
    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="opt-common-syn.xml#xmlns(db=http://docbook.org/ns/docbook)xpointer(/db:nop/*)" />
    <arg><option>--arg</option> <replaceable>name</replaceable> <replaceable>value</replaceable></arg>
    <arg><option>--argstr</option> <replaceable>name</replaceable> <replaceable>value</replaceable></arg>
    <arg>
      <group choice='req'>
        <arg choice='plain'><option>--attr</option></arg>
        <arg choice='plain'><option>-A</option></arg>
      </group>
      <replaceable>attrPath</replaceable>
    </arg>
    <arg><option>--drv-link</option> <replaceable>drvlink</replaceable></arg>
    <arg><option>--add-drv-link</option></arg>
    <arg><option>--no-out-link</option></arg>
    <arg>
      <group choice='req'>
        <arg choice='plain'><option>--out-link</option></arg>
        <arg choice='plain'><option>-o</option></arg>
      </group>
      <replaceable>outlink</replaceable>
    </arg>
    <arg>
      <option>--run-env</option>
      <arg><option>--command</option> <replaceable>cmd</replaceable></arg>
      <arg><option>--exclude</option> <replaceable>regexp</replaceable></arg>
      <arg><option>--pure</option></arg>
    </arg>
    <arg choice='plain' rep='repeat'><replaceable>paths</replaceable></arg>
  </cmdsynopsis>
</refsynopsisdiv>

<refsection><title>Description</title>

<para>The <command>nix-build</command> command builds the derivations
described by the Nix expressions in <replaceable>paths</replaceable>.
If the build succeeds, it places a symlink to the result in the
current directory.  The symlink is called <filename>result</filename>.
If there are multiple Nix expressions, or the Nix expressions evaluate
to multiple derivations, multiple sequentially numbered symlinks are
created (<filename>result</filename>, <filename>result-2</filename>,
and so on).</para>

<para>If no <replaceable>paths</replaceable> are specified, then
<command>nix-build</command> will use <filename>default.nix</filename>
in the current directory, if it exists.</para>

<para><command>nix-build</command> is essentially a wrapper around
<link
linkend="sec-nix-instantiate"><command>nix-instantiate</command></link>
(to translate a high-level Nix expression to a low-level store
derivation) and <link
linkend="rsec-nix-store-realise"><command>nix-store
--realise</command></link> (to build the store derivation).</para>

<warning><para>The result of the build is automatically registered as
a root of the Nix garbage collector.  This root disappears
automatically when the <filename>result</filename> symlink is deleted
or renamed.  So don’t rename the symlink.</para></warning>

<para>The subcommand <command>nix-build --run-env</command> will build
the dependencies of the derivation, but not the derivation itself.  It
will then start an interactive shell in which all environment
variables defined by the derivation have been set to their
corresponding values, and the script <literal>$stdenv/setup</literal>
has been sourced.  This is useful for reproducing the environment of a
derivation for development.</para>

</refsection>


<refsection><title>Options</title>

<para>All options not listed here are passed to <command>nix-store
--realise</command>, except for <option>--arg</option> and
<option>--attr</option> / <option>-A</option> which are passed to
<command>nix-instantiate</command>.  <phrase condition="manual">See
also <xref linkend="sec-common-options" />.</phrase></para>

<variablelist>

  <varlistentry><term><option>--drv-link</option> <replaceable>drvlink</replaceable></term>

    <listitem><para>Add a symlink named
    <replaceable>drvlink</replaceable> to the store derivation
    produced by <command>nix-instantiate</command>.  The derivation is
    a root of the garbage collector until the symlink is deleted or
    renamed.  If there are multiple derivations, numbers are suffixed
    to <replaceable>drvlink</replaceable> to distinguish between
    them.</para></listitem>

  </varlistentry>

  <varlistentry><term><option>--add-drv-link</option></term>

    <listitem><para>Shorthand for <option>--drv-link</option>
    <filename>./derivation</filename>.</para></listitem>

  </varlistentry>

  <varlistentry><term><option>--no-out-link</option></term>

    <listitem><para>Do not create a symlink to the output path.  Note
    that as a result the output does not become a root of the garbage
    collector, and so might be deleted by <command>nix-store
    --gc</command>.</para></listitem>

  </varlistentry>

  <varlistentry xml:id='opt-out-link'><term><option>--out-link</option> /
  <option>-o</option> <replaceable>outlink</replaceable></term>

    <listitem><para>Change the name of the symlink to the output path
    created from <filename>result</filename> to
    <replaceable>outlink</replaceable>.</para></listitem>

  </varlistentry>

</variablelist>

<variablelist condition="manpage">
  <xi:include href="opt-common.xml#xmlns(db=http://docbook.org/ns/docbook)xpointer(//db:variablelist[@xml:id='opt-common']/*)" />
</variablelist>

<para>The following options apply to <command>nix-build --run-env</command>.</para>

<variablelist>

  <varlistentry><term><option>--command</option> <replaceable>cmd</replaceable></term>

    <listitem><para>In the environment of the derivation, run the
    shell command <replaceable>cmd</replaceable> instead of starting
    an interactive shell.  However, if you end the shell command with
    <literal>return</literal>, you still get an interactive shell.
    This can be useful for doing any additional
    initialisation.</para></listitem>

  </varlistentry>

  <varlistentry><term><option>--exclude</option> <replaceable>regexp</replaceable></term>

    <listitem><para>Do not build any dependencies whose store path
    matches the regular expression <replaceable>regexp</replaceable>.
    This option may be specified multiple times.</para></listitem>

  </varlistentry>

  <varlistentry><term><option>--pure</option></term>

    <listitem><para>If this flag is specified, the environment is
    almost entirely cleared before the interactive shell is started,
    so you get an environment that more closely corresponds to the
    “real” Nix build.  A few variables, in particular
    <envar>HOME</envar>, <envar>USER</envar> and
    <envar>DISPLAY</envar>, are retained.  Note that
    <filename>~/.bashrc</filename> and (depending on your Bash
    installation) <filename>/etc/bashrc</filename> are still sourced,
    so any variables set there will affect the interactive
    shell.</para></listitem>

  </varlistentry>

</variablelist>

</refsection>


<refsection><title>Examples</title>

<screen>
$ nix-build '&lt;nixpkgs>' -A firefox
store derivation is /nix/store/qybprl8sz2lc...-firefox-1.5.0.7.drv
/nix/store/d18hyl92g30l...-firefox-1.5.0.7

$ ls -l result
lrwxrwxrwx  <replaceable>...</replaceable>  result -> /nix/store/d18hyl92g30l...-firefox-1.5.0.7

$ ls ./result/bin/
firefox  firefox-config</screen>

<para>To build the dependencies of the package Pan, and start an
interactive shell in which to build it:

<screen>
$ nix-build '&lt;nixpkgs>' --run-env -A pan
$ unpackPhase
$ cd pan-*
$ configurePhase
$ buildPhase
$ ./pan/gui/pan
</screen>

To clear the environment first, and do some additional automatic
initialisation of the interactive shell:

<screen>
$ nix-build '&lt;nixpkgs>' --run-env -A pan --pure \
    --command 'export NIX_DEBUG=1; export NIX_CORES=8; return'
</screen>

</para>

<para>If a derivation has multiple outputs,
<command>nix-build</command> will build the default (first) output.
You can also build all outputs:
<screen>
$ nix-build '&lt;nixpkgs>' -A openssl.all
</screen>
This will create a symlink for each output named
<filename>result-<replaceable>outputname</replaceable></filename>.
The suffix is omitted if the output name is <literal>out</literal>.
So if <literal>openssl</literal> has outputs <literal>out</literal>,
<literal>bin</literal> and <literal>man</literal>,
<command>nix-build</command> will create symlinks
<literal>result</literal>, <literal>result-bin</literal> and
<literal>result-man</literal>.  It’s also possible to build a specific
output:
<screen>
$ nix-build '&lt;nixpkgs>' -A openssl.man
</screen>
This will create a symlink <literal>result-man</literal>.</para>

</refsection>


<refsection condition="manpage"><title>Environment variables</title>

<variablelist>
  <xi:include href="env-common.xml#xmlns(db=http://docbook.org/ns/docbook)xpointer(//db:variablelist[@xml:id='env-common']/*)" />
</variablelist>

</refsection>


</refentry>