lix/doc/manual/nix-build.xml

227 lines
7.9 KiB
XML
Raw Normal View History

<refentry xmlns="http://docbook.org/ns/docbook"
2007-09-19 14:01:41 +00:00
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
xml:id="sec-nix-build">
2007-09-19 14:01:41 +00:00
<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>
2005-04-07 10:47:58 +00:00
<refnamediv>
<refname>nix-build</refname>
<refpurpose>build a Nix expression</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>nix-build</command>
2007-02-05 12:10:10 +00:00
<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/*)" />
2006-10-05 09:08:52 +00:00
<arg><option>--arg</option> <replaceable>name</replaceable> <replaceable>value</replaceable></arg>
2007-12-31 02:52:17 +00:00
<arg><option>--argstr</option> <replaceable>name</replaceable> <replaceable>value</replaceable></arg>
2006-10-05 20:07:41 +00:00
<arg>
<group choice='req'>
<arg choice='plain'><option>--attr</option></arg>
<arg choice='plain'><option>-A</option></arg>
</group>
<replaceable>attrPath</replaceable>
</arg>
2012-05-10 23:29:36 +00:00
<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>
2012-05-10 23:29:36 +00:00
<arg>
<option>--run-env</option>
<arg><option>--command</option> <replaceable>cmd</replaceable></arg>
<arg><option>--exclude</option> <replaceable>regexp</replaceable></arg>
</arg>
2005-04-07 10:47:58 +00:00
<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
2005-04-07 10:47:58 +00:00
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>
2005-04-07 10:47:58 +00:00
<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 dont rename the symlink.</para></warning>
2012-05-10 23:29:36 +00:00
<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>
2012-05-10 23:29:36 +00:00
2005-04-07 10:47:58 +00:00
</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>
2006-10-05 09:08:52 +00:00
2005-04-07 10:47:58 +00:00
<variablelist>
<varlistentry><term><option>--drv-link</option> <replaceable>drvlink</replaceable></term>
2012-12-04 15:03:56 +00:00
<listitem><para>Add a symlink named
<replaceable>drvlink</replaceable> to the store derivation
produced by <command>nix-instantiate</command>. The derivation is
2005-04-07 10:47:58 +00:00
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>
2005-04-07 10:47:58 +00:00
</varlistentry>
<varlistentry><term><option>--add-drv-link</option></term>
2012-12-04 15:03:56 +00:00
<listitem><para>Shorthand for <option>--drv-link</option>
<filename>./derivation</filename>.</para></listitem>
2012-12-04 15:03:56 +00:00
</varlistentry>
<varlistentry><term><option>--no-out-link</option></term>
2012-12-04 15:03:56 +00:00
2005-04-07 10:47:58 +00:00
<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>
2012-12-04 15:03:56 +00:00
<listitem><para>Change the name of the symlink to the output path
created from <filename>result</filename> to
<replaceable>outlink</replaceable>.</para></listitem>
</varlistentry>
2005-04-07 10:47:58 +00:00
</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>
2012-05-10 23:29:36 +00:00
<para>The following options apply to <command>nix-build --run-env</command>.</para>
<variablelist>
<varlistentry><term><option>--command</option> <replaceable>cmd</replaceable></term>
2012-12-04 15:03:56 +00:00
<listitem><para>In the environment of the derivation, run the
shell command <replaceable>cmd</replaceable> instead of starting
an interactive shell.</para></listitem>
2012-05-10 23:29:36 +00:00
</varlistentry>
<varlistentry><term><option>--exclude</option> <replaceable>regexp</replaceable></term>
2012-12-04 15:03:56 +00:00
2012-05-10 23:29:36 +00:00
<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>
</variablelist>
2005-04-07 10:47:58 +00:00
</refsection>
<refsection><title>Examples</title>
<screen>
2012-05-09 23:06:39 +00:00
$ 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>
2012-05-10 23:29:36 +00:00
<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
2012-05-10 23:29:36 +00:00
$ cd pan-*
$ configurePhase
$ buildPhase
2012-05-10 23:29:36 +00:00
$ ./pan/gui/pan
</screen>
</para>
2012-12-04 15:03:56 +00:00
<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>. Its 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>
2012-05-10 23:29:36 +00:00
</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>
2012-12-04 15:03:56 +00:00
2005-04-07 10:47:58 +00:00
</refentry>