forked from lix-project/lix
Update the documentation of build-remote.pl
This commit is contained in:
Eelco Dolstra
parent
46cdc6ad51
commit
82ae0e688c
|
|
@ -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>
|
||||||
|
|
|
||||||
|
|
@ -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:
|
||||||
|
|
|
||||||
|
|
@ -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
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue