forked from lix-project/lix
656390062a
This ensures that not just environment variables are set, but also shell functions such as unpackPhase, configurePhase and so on.
227 lines
7.9 KiB
XML
227 lines
7.9 KiB
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>
|
||
<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.</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>
|
||
|
||
</variablelist>
|
||
|
||
</refsection>
|
||
|
||
|
||
<refsection><title>Examples</title>
|
||
|
||
<screen>
|
||
$ nix-build '<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 '<nixpkgs>' --run-env -A pan
|
||
$ unpackPhase
|
||
$ cd pan-*
|
||
$ configurePhase
|
||
$ buildPhase
|
||
$ ./pan/gui/pan
|
||
</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 '<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 '<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>
|