diff options
Diffstat (limited to 'doc/manual/src/advanced-topics/distributed-builds.md')
| -rw-r--r-- | doc/manual/src/advanced-topics/distributed-builds.md | 140 |
1 files changed, 140 insertions, 0 deletions
diff --git a/doc/manual/src/advanced-topics/distributed-builds.md b/doc/manual/src/advanced-topics/distributed-builds.md new file mode 100644 index 000000000..76a5380bf --- /dev/null +++ b/doc/manual/src/advanced-topics/distributed-builds.md @@ -0,0 +1,140 @@ +# Remote Builds + +Nix supports remote builds, where a local Nix installation can forward +Nix builds to other machines. This allows multiple builds to be +performed in parallel and allows Nix to perform multi-platform builds in +a semi-transparent way. For instance, if you perform a build for a +`x86_64-darwin` on an `i686-linux` machine, Nix can automatically +forward the build to a `x86_64-darwin` machine, if available. + +To forward a build to a remote machine, it’s required that the remote +machine is accessible via SSH and that it has Nix installed. You can +test whether connecting to the remote Nix instance works, e.g. + + $ nix ping-store --store ssh://mac + +will try to connect to the machine named `mac`. It is possible to +specify an SSH identity file as part of the remote store URI, e.g. + + $ nix ping-store --store ssh://mac?ssh-key=/home/alice/my-key + +Since builds should be non-interactive, the key should not have a +passphrase. Alternatively, you can load identities ahead of time into +`ssh-agent` or `gpg-agent`. + +If you get the error + + bash: nix-store: command not found + error: cannot connect to 'mac' + +then you need to ensure that the `PATH` of non-interactive login shells +contains Nix. + +> **Warning** +> +> If you are building via the Nix daemon, it is the Nix daemon user +> account (that is, `root`) that should have SSH access to the remote +> machine. If you can’t or don’t want to configure `root` to be able to +> access to remote machine, you can use a private Nix store instead by +> passing e.g. `--store ~/my-nix`. + +The list of remote machines can be specified on the command line or in +the Nix configuration file. The former is convenient for testing. For +example, the following command allows you to build a derivation for +`x86_64-darwin` on a Linux machine: + + $ uname + Linux + + $ nix build \ + '(with import <nixpkgs> { system = "x86_64-darwin"; }; runCommand "foo" {} "uname > $out")' \ + --builders 'ssh://mac x86_64-darwin' + [1/0/1 built, 0.0 MiB DL] building foo on ssh://mac + + $ cat ./result + Darwin + +It is possible to specify multiple builders separated by a semicolon or +a newline, e.g. + +``` + --builders 'ssh://mac x86_64-darwin ; ssh://beastie x86_64-freebsd' +``` + +Each machine specification consists of the following elements, separated +by spaces. Only the first element is required. To leave a field at its +default, set it to `-`. + +1. The URI of the remote store in the format + `ssh://[username@]hostname`, e.g. `ssh://nix@mac` or `ssh://mac`. + For backward compatibility, `ssh://` may be omitted. The hostname + may be an alias defined in your `~/.ssh/config`. + +2. A comma-separated list of Nix platform type identifiers, such as + `x86_64-darwin`. It is possible for a machine to support multiple + platform types, e.g., `i686-linux,x86_64-linux`. If omitted, this + defaults to the local platform type. + +3. The SSH identity file to be used to log in to the remote machine. If + omitted, SSH will use its regular identities. + +4. The maximum number of builds that Nix will execute in parallel on + the machine. Typically this should be equal to the number of CPU + cores. For instance, the machine `itchy` in the example will execute + up to 8 builds in parallel. + +5. 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. + +6. A comma-separated list of *supported features*. If a derivation has + the `requiredSystemFeatures` attribute, then Nix will only perform + the derivation on a machine that has the specified features. For + instance, the attribute + + requiredSystemFeatures = [ "kvm" ]; + + will cause the build to be performed on a machine that has the `kvm` + feature. + +7. A comma-separated list of *mandatory features*. A machine will only + be used to build a derivation if all of the machine’s mandatory + features appear in the derivation’s `requiredSystemFeatures` + attribute.. + +For example, the machine specification + + 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 + nix@poochie.labs.cs.uu.nl i686-linux /home/nix/.ssh/id_scratchy_auto 1 2 kvm benchmark + +specifies several machines that can perform `i686-linux` builds. +However, `poochie` will only do builds that have the attribute + + requiredSystemFeatures = [ "benchmark" ]; + +or + + requiredSystemFeatures = [ "benchmark" "kvm" ]; + +`itchy` cannot do builds that require `kvm`, but `scratchy` does support +such builds. For regular builds, `itchy` will be preferred over +`scratchy` because it has a higher speed factor. + +Remote builders can also be configured in `nix.conf`, e.g. + + builders = ssh://mac x86_64-darwin ; ssh://beastie x86_64-freebsd + +Finally, remote builders can be configured in a separate configuration +file included in `builders` via the syntax `@file`. For example, + + builders = @/etc/nix/machines + +causes the list of machines in `/etc/nix/machines` to be included. (This +is the default.) + +If you want the builders to use caches, you likely want to set the +option `builders-use-substitutes` in your local `nix.conf`. + +To build only on remote builders and disable building on the local +machine, you can use the option `--max-jobs 0`. |