lix-project/lix
20
55
Fork 31
Code Issues 344 Code Review (Gerrit) Projects 3 Releases Wiki Activity

Update the documentation of build-remote.pl

Browse source
This commit is contained in:
Eelco Dolstra 2012-04-30 16:49:00 -04:00
parent 46cdc6ad51
commit 82ae0e688c
3 changed files with 62 additions and 96 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

149
doc/manual/build-farm.xml
View file

@ -1,67 +1,17 @@
<chapter xmlns="http://docbook.org/ns/docbook" <chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xlink="http://www.w3.org/1999/xlink"
xml:id='chap-build-farm'> xml:id='chap-distributed-builds'>
<title>Setting up a Build Farm</title> <title>Setting Up Distributed Builds</title>
<para>Nix supports distributed builds: a local Nix installation can
<para>This chapter provides some sketchy information on how to set up forward Nix builds to other machines over the network. This allows
a Nix-based build farm. Nix is particularly suited as a basis for a multiple builds to be performed in parallel (thus improving
build farm, since: performance) and allows Nix to perform multi-platform builds in a
semi-transparent way. For instance, if you perform a build for a
<itemizedlist> <literal>powerpc-darwin</literal> on an <literal>i686-linux</literal>
machine, Nix can automatically forward the build to a
<listitem><para>Nix supports distributed builds: a local Nix <literal>powerpc-darwin</literal> machine, if available.</para>
installation can forward Nix builds to other machines over the
network. This allows multiple builds to be performed in parallel
(thus improving performance), but more in importantly, it allows Nix
to perform multi-platform builds in a semi-transparent way. For
instance, if you perform a build for a
<literal>powerpc-darwin</literal> on an
<literal>i686-linux</literal> machine, Nix can automatically forward
the build to a <literal>powerpc-darwin</literal> machine, if
available.</para></listitem>
<listitem><para>The Nix expression language is ideal for describing
build jobs, plus all their dependencies. For instance, if your
package has some dependency, you don't have to manually install it
on all the machines in the build farm; they will be built
automatically.</para></listitem>
<listitem><para>Proper release management requires that builds (if
deployed) are traceable: it should be possible to figure out from
exactly what sources they were built, in what configuration, etc.;
and it should be possible to reproduce the build, if necessary. Nix
makes this possible since Nix's hashing scheme uniquely identifies
builds, and Nix expressions are self-contained.</para></listitem>
<listitem><para>Nix will only rebuild things that have actually
changed. For instance, if the sources of a package haven't changed
between runs of the build farm, the package won't be rebuilt (unless
it was garbage-collected). Also, dependencies typically don't
change very often, so they only need to be built
once.</para></listitem>
<listitem><para>The results of a Nix build farm can be made
available through a channel, so successful builds can be deployed to
users immediately.</para></listitem>
</itemizedlist>
</para>
<section><title>Overview</title>
<para>TODO</para>
<para>The sources of the Nix build farm are at <link
xlink:href='https://svn.nixos.org/repos/nix/release/trunk'/>.</para>
</section>
<section xml:id='sec-distributed-builds'><title>Setting up distributed builds</title>
<para>You can enable distributed builds by setting the environment <para>You can enable distributed builds by setting the environment
variable <envar>NIX_BUILD_HOOK</envar> to point to a program that Nix variable <envar>NIX_BUILD_HOOK</envar> to point to a program that Nix
@ -79,22 +29,22 @@ variable</link>.</para>
<filename>remote-systems.conf</filename></title> <filename>remote-systems.conf</filename></title>
<programlisting> <programlisting>
nix@mcflurry.labs.cs.uu.nl powerpc-darwin /home/nix/.ssh/id_quarterpounder_auto 2 nix@mcflurry.labs.cs.uu.nl powerpc-darwin /home/nix/.ssh/id_quarterpounder_auto 2
nix@scratchy.labs.cs.uu.nl i686-linux /home/nix/.ssh/id_scratchy_auto 1 nix@scratchy.labs.cs.uu.nl i686-linux /home/nix/.ssh/id_scratchy_auto 8 1 kvm
nix@itchy.labs.cs.uu.nl i686-linux /home/nix/.ssh/id_scratchy_auto 8 2
</programlisting> </programlisting>
</example> </example>
<para>An example build hook can be found in the Nix build farm <para>Nix ships with a build hook that should be suitable for most
sources: <link purposes. It uses <command>ssh</command> and
xlink:href='https://svn.nixos.org/repos/nix/release/trunk/common/distributed/build-remote.pl' <command>nix-copy-closure</command> to copy the build inputs and
/>. It should be suitable for most purposes, with maybe some minor outputs and perform the remote build. To use it, you should set
adjustments. It uses <command>ssh</command> and <envar>NIX_BUILD_HOOK</envar> to
<command>rsync</command> to copy the build inputs and outputs and <filename><replaceable>prefix</replaceable>/libexec/nix/build-remote.pl</filename>.
perform the remote build. You should define a list of available build You should also define a list of available build machines and point
machines and set the environment variable the environment variable <envar>NIX_REMOTE_SYSTEMS</envar> to it. An
<envar>REMOTE_SYSTEMS</envar> to point to it. An example example configuration is shown in <xref linkend='ex-remote-systems'
configuration is shown in <xref linkend='ex-remote-systems' />. Each />. Each line in the file specifies a machine, with the following
line in the file specifies a machine, with the following bits of bits of information:
information:
<orderedlist> <orderedlist>
@ -104,34 +54,49 @@ information:
be an alias defined in your be an alias defined in your
<filename>~/.ssh/config</filename>.</para></listitem> <filename>~/.ssh/config</filename>.</para></listitem>
<listitem><para>The Nix platform type identifier, such as <listitem><para>A comma-separated list of Nix platform type
<literal>powerpc-darwin</literal>.</para></listitem> identifiers, such as <literal>powerpc-darwin</literal>. It is
possible for a machine to support multiple platform types, e.g.,
<literal>i686-linux,x86_64-linux</literal>.</para></listitem>
<listitem><para>The SSH private key to be used to log in to the <listitem><para>The SSH private key to be used to log in to the
remote machine. Since builds should be non-interactive, this key remote machine. Since builds should be non-interactive, this key
should not have a passphrase!</para></listitem> should not have a passphrase!</para></listitem>
<listitem><para>The maximum <quote>load</quote> of the remote <listitem><para>The maximum number of builds that
machine. This is just the maximum number of jobs that
<filename>build-remote.pl</filename> will execute in parallel on the <filename>build-remote.pl</filename> will execute in parallel on the
machine. Typically this should be equal to the number of machine. Typically this should be equal to the number of CPU cores.
CPUs.</para></listitem> For instance, the machine <literal>itchy</literal> in the example
will execute up to 8 builds in parallel.</para></listitem>
<listitem><para>The “speed factor”, indicating the relative speed of
the machine. If there are multiple machines of the right type, Nix
will prefer the fastest, taking load into account.</para></listitem>
<listitem><para>A comma-separated list of
<emphasis>features</emphasis>. If a derivation has the
<varname>requiredSystemFeatures</varname> attribute, then
<filename>build-remote.pl</filename> will only perform the
derivation on a machine that has the specified features. For instance, the attribute
<programlisting>
requiredSystemFeatures = [ "kvm" ];
</programlisting>
will cause the build to be performed on a machine that has the
<literal>kvm</literal> feature (i.e., <literal>scratchy</literal> in
the example above).</para></listitem>
</orderedlist> </orderedlist>
You should also set up the environment variable You should also set up the environment variable
<envar>CURRENT_LOAD</envar> to point at a file that <envar>NIX_CURRENT_LOAD</envar> to point at a directory (e.g.,
<filename>build-remote.pl</filename> uses to remember how many jobs it <filename>/var/run/nix/current-load</filename>) that
is currently executing remotely. It doesn't look at the actual load <filename>build-remote.pl</filename> uses to remember how many builds
on the remote machine, so if you have multiple instances of Nix it is currently executing remotely. It doesn't look at the actual
running, they should use the same <envar>CURRENT_LOAD</envar> load on the remote machine, so if you have multiple instances of Nix
file<footnote><para>Although there are probably some race conditions running, they should use the same <envar>NIX_CURRENT_LOAD</envar>
in the script right now.</para></footnote>. Maybe in the future file. Maybe in the future <filename>build-remote.pl</filename> will
<filename>build-remote.pl</filename> will look at the actual remote look at the actual remote load.</para>
load. The load file should exist, so you should just create it as an
empty file initially.</para>
</section>
</chapter> </chapter>

7
doc/manual/env-common.xml
View file

@ -119,9 +119,10 @@ $ mount -o bind /mnt/otherdisk/nix /nix</screen>
<para>Specifies the location of the <emphasis>build hook</emphasis>, <para>Specifies the location of the <emphasis>build hook</emphasis>,
which is a program (typically some script) that Nix will call which is a program (typically some script) that Nix will call
whenever it wants to build a derivation. This is used to implement whenever it wants to build a derivation. This is used to implement
distributed builds (see <xref linkend="sec-distributed-builds" distributed builds<phrase condition="manual"> (see <xref
/>). The protocol by which the calling Nix process and the build linkend="chap-distributed-builds" />)</phrase>. The protocol by
hook communicate is as follows.</para> 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 <para>The build hook is called with the following command-line
arguments: arguments:

2
doc/manual/writing-nix-expressions.xml
View file

@ -1293,7 +1293,7 @@ set, the attributes of which specify the inputs of the build.</para>
can only be performed on a machine and operating system matching the can only be performed on a machine and operating system matching the
platform identifier. (Nix can automatically forward builds for platform identifier. (Nix can automatically forward builds for
other platforms by forwarding them to other machines; see <xref other platforms by forwarding them to other machines; see <xref
linkend='sec-distributed-builds' />.)</para></listitem> linkend='chap-distributed-builds' />.)</para></listitem>
<listitem><para>There must be an attribute named <listitem><para>There must be an attribute named
<varname>name</varname> whose value must be a string. This is used <varname>name</varname> whose value must be a string. This is used