diff --git a/doc/manual/Makefile.am b/doc/manual/Makefile.am index 28ebb4d155..0d1e85cc84 100644 --- a/doc/manual/Makefile.am +++ b/doc/manual/Makefile.am @@ -12,6 +12,7 @@ man1_MANS = nix-env.1 nix-store.1 nix-instantiate.1 \ SOURCES = manual.xml introduction.xml installation.xml \ package-management.xml writing-nix-expressions.xml \ + build-farm.xml \ $(man1_MANS:.1=.xml) \ troubleshooting.xml bugs.xml opt-common.xml opt-common-syn.xml \ quick-start.xml nix-lang-ref.xml style.css images diff --git a/doc/manual/build-farm.xml b/doc/manual/build-farm.xml new file mode 100644 index 0000000000..2dd0932fc2 --- /dev/null +++ b/doc/manual/build-farm.xml @@ -0,0 +1,129 @@ +Setting up a Build Farm + +This chapter provides some sketchy information on how to set up +a Nix-based build farm. Nix is particularly suited as a basis for a +build farm, since: + + + + Nix supports distributed builds: a local Nix + installation can forward Nix builds to other machines over the + network. This allows multiple builds to be performed in parallel + (thus improving performce), 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 + powerpc-darwin on an + i686-linux machine, Nix can automatically forward + to build to a powerpc-darwin machine, if + available. + + The Nix expression language is ideal for providing + 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. + + 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's hashing scheme uniquely identifies builds, and Nix expressions + are self-contained. + + Nix will only rebuild things that have actually + changed. For instance, if the sources of a component haven't + changed between runs of the build farm, the component won't be + rebuild (unless it was garbage-collected). Also, dependencies + typically don't change very often, so they only need to be built + once. + + The results of a Nix build farm can be made + available through a channel, so that users can use succesfull builds + immediately. + + + + + + +
Overview + +TODO + +The sources of the Nix build farm are at . + +
+ + +
Setting up distributed builds + +You can enable distributed builds by setting the environment +variable NIX_BUILD_HOOK to point to a program that Nix +will call whenever it wants to build a derivation. The build hook +(typically a shell or Perl script) can decline the build, in which Nix +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. + +Remote machine configuration: +<filename>remote-systems.conf</filename> + +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 + + + +An example build hook can be found in the Nix build farm +sources: . It should be suitable for most purposes, with maybe some minor +adjustments. It uses ssh and +rsync to copy the build inputs and outputs and +perform the remote build. You should define a list of available build +machines and set the environment variable +REMOTE_SYSTEMS to point to it. An example +configuration is shown in . Each +line in the file specifies a machine, with the following bits of +information: + + + + The name of the remote machine, with optionally the + user under which the remote build should be performed. This is + actually passed as an argument to ssh, so it can + be an alias defined in your + ~/.ssh/config. + + The Nix platform type identifier, such as + powerpc-darwin. + + The SSH private key to be used to log in to the + remote machine. Since builds should be non-interactive, this key + should not have a passphrase! + + The maximum load of the remote + machine. This is just the maximum number of jobs that + build-remote.pl will execute in parallel on the + machine. Typically this should be equal to the number of + CPUs. + + + +You should also set up the environment variable +CURRENT_LOAD to point at a file that +build-remote.pl uses to remember how many jobs it +is currently executing remotely. It doesn't look at the actual load +on the remote machine, so if you have multiple instances of Nix +running, they should use the same CURRENT_LOAD +fileAlthough there are probably some race conditions +in the script right now.. Maybe in the future +build-remote.pl will look at the actual remote +load. The load file should exist, so you should just create it as an +empty file initially. + +
+ + + diff --git a/doc/manual/manual.xml b/doc/manual/manual.xml index d2f19f0309..84357e7fda 100644 --- a/doc/manual/manual.xml +++ b/doc/manual/manual.xml @@ -11,6 +11,7 @@ + @@ -47,6 +48,7 @@ &installation; &package-management; &writing-nix-expressions; + &build-farm; Command Reference