* Build hook documentation.

* nix-store options.
This commit is contained in:
Eelco Dolstra 2005-04-07 09:36:35 +00:00
parent 806b91f104
commit f1ae10b992
5 changed files with 320 additions and 261 deletions

View file

@ -65,7 +65,10 @@ will call whenever it wants to build a derivation. The build hook
will perform it in the usual way if possible, or it can accept it, in
which case it is responsible for somehow getting the inputs of the
build to another machine, doing the build there, and getting the
results back.</para>
results back. The details of the build hook protocol are described in
the documentation of the <link
linkend="envar-build-hook"><envar>NIX_BUILD_HOOK</envar>
variable</link>.</para>
<example id='ex-remote-systems'><title>Remote machine configuration:
<filename>remote-systems.conf</filename></title>

View file

@ -118,6 +118,158 @@ $ mount -o bind /mnt/otherdisk/nix /nix</screen>
</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
hooks 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 <link
linkend="rsec-nix-store-reg-val"><command>nix-store
--register-validity</command></link>. 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>

View file

@ -262,11 +262,10 @@ $ nix-store --gc</screen>
<!--######################################################################-->
<refsection>
<title>Operation <option>--query</option></title>
<refsection><title>Operation <option>--query</option></title>
<refsection><title>Synopsis</title>
<refsection>
<title>Synopsis</title>
<cmdsynopsis>
<command>nix-store</command>
<group choice='req'>
@ -287,55 +286,38 @@ $ nix-store --gc</screen>
<arg><option>-f</option></arg>
<arg choice='plain' rep='repeat'><replaceable>args</replaceable></arg>
</cmdsynopsis>
</refsection>
<refsection>
<title>Description</title>
<para>
The operation <option>--query</option> displays various bits
of information about store expressions or store paths. The
queries are described below. At most one query can be
specified. The default query is <option>--list</option>.
</para>
</refsection>
<refsection>
<title>Common query options</title>
<refsection><title>Description</title>
<para>The operation <option>--query</option> displays various bits of
information about store paths. The queries are described below. At
most one query can be specified. The default query is
<option>--list</option>.</para>
</refsection>
<refsection><title>Common query options</title>
<variablelist>
<varlistentry>
<term><option>--normalise</option> / <option>-n</option></term>
<listitem>
<para>
For those queries that take a Nix store expression, this
option causes those expressions to be normalised first.
</para>
</listitem>
<varlistentry><term><option>--use-output</option> / <option>-u</option></term>
<listitem><para>For each argument to the query that is a store
derivation, apply the query to the output path of the derivation
instead.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--force-realise</option> / <option>-f</option></term>
<listitem>
<para>
For those queries that take a Nix store expression, this
option causes those expressions to be realised first.
This is just a short-cut for the common idiom
</para>
<screen>
nix-store --realise /nix/store/bla.store
x=`nix-store --query --normalise /nix/store/bla.store`
<emphasis>(do something with the path $x</emphasis></screen>
<para>
which using this flag can be written as
</para>
<screen>
x=`nix-store --query --normalise --force-realise /nix/store/bla.store`
<emphasis>(do something with the path $x</emphasis></screen>
</listitem>
<varlistentry><term><option>--force-realise</option> / <option>-f</option></term>
<listitem><para>Realise each argument to the query first (see
<link linkend="rsec-nix-store-realise"><command>nix-store
--realise</command></link>).</para></listitem>
</varlistentry>
</variablelist>
@ -343,173 +325,103 @@ x=`nix-store --query --normalise --force-realise /nix/store/bla.store`
</refsection>
<refsection id='nixref-queries'>
<title>Queries</title>
<refsection id='nixref-queries'><title>Queries</title>
<variablelist>
<varlistentry>
<term><option>--list</option> / <option>-l</option></term>
<listitem>
<para>
Prints out the <emphasis>output paths</emphasis> of the
store expressions indicated by the identifiers
<replaceable>args</replaceable>. In the case of a
derivation expression, these are the paths that will be
produced when the derivation is realised. In the case
of a closure expression, these are the paths that were
produced the derivation expression of which the closure
expression is a successor.
</para>
</listitem>
<varlistentry><term><option>--list</option> / <option>-l</option></term>
<listitem><para>Prints out the <emphasis>output paths</emphasis>
of the store expressions indicated by the identifiers
<replaceable>args</replaceable>. In the case of a derivation
expression, these are the paths that will be produced when the
derivation is realised. In the case of a closure expression,
these are the paths that were produced the derivation expression
of which the closure expression is a successor.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--requisites</option> / <option>-R</option></term>
<listitem>
<para>
Prints out the requisite paths of the store expressions
indicated by the identifiers
<replaceable>args</replaceable>. The requisite paths of
a Nix expression are the paths that need to be present
in the system to be able to realise the expression.
That is, they form the <emphasis>closure</emphasis> of
the expression in the file system (i.e., no path in the
set of requisite paths points to anything outside the
set of requisite paths).
</para>
<varlistentry><term><option>--requisites</option> / <option>-R</option></term>
<para>
The notion of requisite paths is very useful when one
wants to distribute store expressions. Since they form a
closure, they are the only paths one needs to distribute
to another system to be able to realise the expression
on the other system.
</para>
<listitem><para>Prints out the requisite paths of the store
expressions indicated by the identifiers
<replaceable>args</replaceable>. The requisite paths of a Nix
expression are the paths that need to be present in the system to
be able to realise the expression. That is, they form the
<emphasis>closure</emphasis> of the expression in the file system
(i.e., no path in the set of requisite paths points to anything
outside the set of requisite paths).</para>
<para>
This query is generally used to implement various kinds
of deployment. A <emphasis>source deployment</emphasis>
is obtained by distributing the requisite paths of a
derivation expression. A <emphasis>binary
deployment</emphasis> is obtained by distributing the
requisite paths of a closure expression. A
<emphasis>cache deployment</emphasis> is obtained by
distributing the requisite paths of a derivation
expression and specifying the option
<option>--include-successors</option>. This will
include not just the paths of a source and binary
deployment, but also all expressions and paths of
subterms of the source. This is useful if one wants to
realise on the target system a Nix expression that is
similar but not quite the same as the one being
distributed, since any common subterms will be reused.
</para>
<para>The notion of requisite paths is very useful when one wants
to distribute store expressions. Since they form a closure, they
are the only paths one needs to distribute to another system to be
able to realise the expression on the other system.</para>
<para>
This query has a number of options:
</para>
<para>This query is generally used to implement various kinds of
deployment. A <emphasis>source deployment</emphasis> is obtained
by distributing the requisite paths of a derivation expression. A
<emphasis>binary deployment</emphasis> is obtained by distributing
the requisite paths of a closure expression. A <emphasis>cache
deployment</emphasis> is obtained by distributing the requisite
paths of a derivation expression and specifying the option
<option>--include-successors</option>. This will include not just
the paths of a source and binary deployment, but also all
expressions and paths of subterms of the source. This is useful
if one wants to realise on the target system a Nix expression that
is similar but not quite the same as the one being distributed,
since any common subterms will be reused.</para>
<para>This query has one option:</para>
<variablelist>
<varlistentry>
<term><option>--exclude-exprs</option></term>
<listitem>
<para>
Excludes the paths of store expressions. This
causes the closure property to be lost, that is,
the resulting set of paths is not enough to ensure
realisibility.
</para>
</listitem>
</varlistentry>
<varlistentry><term><option>--include-outputs</option></term>
<varlistentry>
<term><option>--include-successors</option></term>
<listitem>
<para>
Also include the requisites of successors (normal forms).
Only the requisites of <emphasis>known</emphasis>
successors are included, i.e., the normal forms of
derivation expressions that have never been normalised will
not be included.
</para>
<listitem><para>Also include the output path of store
derivations, and their closures.</para></listitem>
<para>
Note that not just the successor of a derivation expression
will be included, but also the successors of all input
expressions of that derivation expression. I.e., all
normal forms of subterms involved in the normalisation of
the top-level term are included.
</para>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--predecessors</option></term>
<listitem>
<para>
For each store expression stored at paths
<replaceable>args</replaceable>, prints its
<emphasis>predecessors</emphasis>. A derivation
expression <varname>p</varname> is a predecessor of a
store expression <varname>q</varname> iff
<varname>q</varname> is a successor of
<varname>p</varname>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--graph</option></term>
<listitem>
<para>
Prints a graph of the closure of the store expressions
identified by <replaceable>args</replaceable> in the
format of the <command>dot</command> tool of AT&amp;T's
GraphViz package.
</para>
</listitem>
<varlistentry><term><option>--graph</option></term>
<listitem><para>Prints a graph of the closure of the store
expressions identified by <replaceable>args</replaceable> in the
format of the <command>dot</command> tool of AT&amp;T's GraphViz
package.</para></listitem>
</varlistentry>
</variablelist>
</refsection>
</refsection>
<!--######################################################################-->
<refsection>
<title>Operation <option>--successor</option></title>
<refsection id="rsec-nix-store-reg-val"><title>Operation <option>--register-validity</option></title>
<refsection><title>Synopsis</title>
<refsection>
<title>Synopsis</title>
<cmdsynopsis>
<command>nix-store</command>
<arg choice='req'><option>--successor</option></arg>
<arg choice='plain'
rep='repeat'><replaceable>srcpath</replaceable> <replaceable>sucpath</replaceable></arg>
<arg choice='req'><option>--register-validity</option></arg>
</cmdsynopsis>
</refsection>
<refsection>
<title>Description</title>
<refsection><title>Description</title>
<para>
The operation <option>--successor</option> registers that the
closure expression in <replaceable>sucpath</replaceable> is a
successor of the derivation expression in
<replaceable>srcpath</replaceable>. This is used to implement
binary deployment.
</para>
<para>TODO</para>
</refsection>
@ -519,11 +431,10 @@ x=`nix-store --query --normalise --force-realise /nix/store/bla.store`
<!--######################################################################-->
<refsection>
<title>Operation <option>--substitute</option></title>
<refsection><title>Operation <option>--substitute</option></title>
<refsection><title>Synopsis</title>
<refsection>
<title>Synopsis</title>
<cmdsynopsis>
<command>nix-store</command>
<arg choice='req'><option>--substitute</option></arg>
@ -532,16 +443,13 @@ x=`nix-store --query --normalise --force-realise /nix/store/bla.store`
</cmdsynopsis>
</refsection>
<refsection>
<title>Description</title>
<refsection><title>Description</title>
<para>
The operation <option>--substitute</option> registers that the
<para>The operation <option>--substitute</option> registers that the
store path <replaceable>srcpath</replaceable> can be built by
realising the derivation expression in
<replaceable>subpath</replaceable>. This is used to implement
binary deployment.
</para>
<replaceable>subpath</replaceable>. This is used to implement binary
deployment.</para>
</refsection>
@ -551,8 +459,7 @@ x=`nix-store --query --normalise --force-realise /nix/store/bla.store`
<!--######################################################################-->
<refsection>
<title>Operation <option>--verify</option></title>
<refsection><title>Operation <option>--verify</option></title>
<refsection>
<title>Synopsis</title>
@ -562,17 +469,14 @@ x=`nix-store --query --normalise --force-realise /nix/store/bla.store`
</cmdsynopsis>
</refsection>
<refsection>
<title>Description</title>
<refsection><title>Description</title>
<para>
The operation <option>--verify</option> verifies the internal
consistency of the Nix database, and the consistency between
the Nix database and the Nix store. Any inconsistencies
encountered are automatically repaired. Inconsistencies are
generally the result of the Nix store or database being
modified by non-Nix tools, or of bugs in Nix itself.
</para>
<para>The operation <option>--verify</option> verifies the internal
consistency of the Nix database, and the consistency between the Nix
database and the Nix store. Any inconsistencies encountered are
automatically repaired. Inconsistencies are generally the result of
the Nix store or database being modified by non-Nix tools, or of bugs
in Nix itself.</para>
</refsection>

View file

@ -84,7 +84,7 @@
</varlistentry>
<varlistentry><term><option>--max-jobs</option> / <option>-j</option></term>
<varlistentry id="opt-max-jobs"><term><option>--max-jobs</option> / <option>-j</option></term>
<listitem><para>Sets the maximum number of build jobs that Nix will
perform in parallel to the specified number. The default is 1. A

View file

@ -1112,7 +1112,7 @@ set, the attributes of which specify the inputs of the build.</para>
<itemizedlist>
<listitem><para>There must be an attribute named
<listitem id="attr-system"><para>There must be an attribute named
<varname>system</varname> whose value must be a string specifying a
Nix platform identifier, such as <literal>"i686-linux"</literal> or
<literal>"powerpc-darwin"</literal><footnote><para>To figure out