Skip to content

Commit b1cf58a

Browse files
Janik-Haagfricklerhandwerk
Janik-Haag
authored and
fricklerhandwerk
committed
extract reference documentation on remote builds
- move all reference documentation to the `builders` configuration setting - reword documentation on machine specification, add examples - disable showing the default value, as it rendered as `@/dummy/machines`, which is wrong - highlight the examples
1 parent 84fe429 commit b1cf58a

File tree

2 files changed

+123
-95
lines changed

2 files changed

+123
-95
lines changed

‎doc/manual/src/advanced-topics/distributed-builds.md

+8-92
Original file line numberDiff line numberDiff line change
@@ -36,16 +36,9 @@ error: cannot connect to 'mac'
3636
then you need to ensure that the `PATH` of non-interactive login shells
3737
contains Nix.
3838

39-
> **Warning**
40-
>
41-
> If you are building via the Nix daemon, it is the Nix daemon user account (that is, `root`) that should have SSH access to a user (not necessarily `root`) on the remote machine.
42-
>
43-
> If you can’t or don’t want to configure `root` to be able to access the remote machine, you can use a private Nix store instead by passing e.g. `--store ~/my-nix` when running a Nix command from the local machine.
44-
45-
The list of remote machines can be specified on the command line or in
46-
the Nix configuration file. The former is convenient for testing. For
47-
example, the following command allows you to build a derivation for
48-
`x86_64-darwin` on a Linux machine:
39+
The [list of remote machines](@docroot@/command-ref/conf-file.md#conf-builders) can be specified on the command line or in the Nix configuration file.
40+
The former is convenient for testing.
41+
For example, the following command allows you to build a derivation for `x86_64-darwin` on a Linux machine:
4942

5043
```console
5144
$ uname
@@ -60,97 +53,20 @@ $ cat ./result
6053
Darwin
6154
```
6255

63-
It is possible to specify multiple builders separated by a semicolon or
64-
a newline, e.g.
56+
It is possible to specify multiple builders separated by a semicolon or a newline, e.g.
6557

6658
```console
6759
--builders 'ssh://mac x86_64-darwin ; ssh://beastie x86_64-freebsd'
6860
```
6961

70-
Each machine specification consists of the following elements, separated
71-
by spaces. Only the first element is required. To leave a field at its
72-
default, set it to `-`.
73-
74-
1. The URI of the remote store in the format
75-
`ssh://[username@]hostname`, e.g. `ssh://nix@mac` or `ssh://mac`.
76-
For backward compatibility, `ssh://` may be omitted. The hostname
77-
may be an alias defined in your `~/.ssh/config`.
78-
79-
2. A comma-separated list of Nix platform type identifiers, such as
80-
`x86_64-darwin`. It is possible for a machine to support multiple
81-
platform types, e.g., `i686-linux,x86_64-linux`. If omitted, this
82-
defaults to the local platform type.
83-
84-
3. The SSH identity file to be used to log in to the remote machine. If
85-
omitted, SSH will use its regular identities.
86-
87-
4. The maximum number of builds that Nix will execute in parallel on
88-
the machine. Typically this should be equal to the number of CPU
89-
cores. For instance, the machine `itchy` in the example will execute
90-
up to 8 builds in parallel.
91-
92-
5. The “speed factor”, indicating the relative speed of the machine. If
93-
there are multiple machines of the right type, Nix will prefer the
94-
fastest, taking load into account.
95-
96-
6. A comma-separated list of *supported features*. If a derivation has
97-
the `requiredSystemFeatures` attribute, then Nix will only perform
98-
the derivation on a machine that has the specified features. For
99-
instance, the attribute
100-
101-
```nix
102-
requiredSystemFeatures = [ "kvm" ];
103-
```
104-
105-
will cause the build to be performed on a machine that has the `kvm`
106-
feature.
107-
108-
7. A comma-separated list of *mandatory features*. A machine will only
109-
be used to build a derivation if all of the machine’s mandatory
110-
features appear in the derivation’s `requiredSystemFeatures`
111-
attribute.
112-
113-
8. The (base64-encoded) public host key of the remote machine. If omitted, SSH
114-
will use its regular known-hosts file. Specifically, the field is calculated
115-
via `base64 -w0 /etc/ssh/ssh_host_ed25519_key.pub`.
116-
117-
For example, the machine specification
118-
119-
[email protected] i686-linux /home/nix/.ssh/id_scratchy_auto 8 1 kvm
120-
[email protected] i686-linux /home/nix/.ssh/id_scratchy_auto 8 2
121-
[email protected] i686-linux /home/nix/.ssh/id_scratchy_auto 1 2 kvm benchmark
122-
123-
specifies several machines that can perform `i686-linux` builds.
124-
However, `poochie` will only do builds that have the attribute
125-
126-
```nix
127-
requiredSystemFeatures = [ "benchmark" ];
128-
```
129-
130-
or
131-
132-
```nix
133-
requiredSystemFeatures = [ "benchmark" "kvm" ];
134-
```
135-
136-
`itchy` cannot do builds that require `kvm`, but `scratchy` does support
137-
such builds. For regular builds, `itchy` will be preferred over
138-
`scratchy` because it has a higher speed factor.
139-
140-
Remote builders can also be configured in `nix.conf`, e.g.
62+
Remote builders can also be configured in [`nix.conf`](@docroot@/command-ref/conf-file.md), e.g.
14163

14264
builders = ssh://mac x86_64-darwin ; ssh://beastie x86_64-freebsd
14365

14466
Finally, remote builders can be configured in a separate configuration
145-
file included in `builders` via the syntax `@file`. For example,
67+
file included in `builders` via the syntax `@/path/to/file`. For example,
14668

14769
builders = @/etc/nix/machines
14870

149-
causes the list of machines in `/etc/nix/machines` to be included. (This
150-
is the default.)
151-
152-
If you want the builders to use caches, you likely want to set the
153-
option `builders-use-substitutes` in your local `nix.conf`.
154-
155-
To build only on remote builders and disable building on the local
156-
machine, you can use the option `--max-jobs 0`.
71+
causes the list of machines in `/etc/nix/machines` to be included.
72+
(This is the default.)

‎src/libstore/globals.hh

+115-3
Original file line numberDiff line numberDiff line change
@@ -261,9 +261,121 @@ public:
261261
Setting<std::string> builders{
262262
this, "@" + nixConfDir + "/machines", "builders",
263263
R"(
264-
A semicolon-separated list of build machines.
265-
For the exact format and examples, see [the manual chapter on remote builds](../advanced-topics/distributed-builds.md)
266-
)"};
264+
A semicolon- or newline-separated list of build machines.
265+
266+
In addition to the [usual ways of setting configuration options](@docroot@/command-ref/conf-file.md), the value can be read from a file by prefixing its absolute path with `@`.
267+
268+
> **Example**
269+
>
270+
> This is the default setting:
271+
>
272+
> ```
273+
> builders = @/etc/nix/machines
274+
> ```
275+
276+
Each machine specification consists of the following elements, separated by spaces.
277+
Only the first element is required.
278+
To leave a field at its default, set it to `-`.
279+
280+
1. The URI of the remote store in the format `ssh://[username@]hostname`.
281+
282+
> **Example**
283+
>
284+
> `ssh://nix@mac`
285+
286+
For backward compatibility, `ssh://` may be omitted.
287+
The hostname may be an alias defined in `~/.ssh/config`.
288+
289+
2. A comma-separated list of [Nix system types](@docroot@/contributing/hacking.md#system-type).
290+
If omitted, this defaults to the local platform type.
291+
292+
> **Example**
293+
>
294+
> `aarch64-darwin`
295+
296+
It is possible for a machine to support multiple platform types.
297+
298+
> **Example**
299+
>
300+
> `i686-linux,x86_64-linux`
301+
302+
3. The SSH identity file to be used to log in to the remote machine.
303+
If omitted, SSH will use its regular identities.
304+
305+
> **Example**
306+
>
307+
> `/home/user/.ssh/id_mac`
308+
309+
4. The maximum number of builds that Nix will execute in parallel on the machine.
310+
Typically this should be equal to the number of CPU cores.
311+
312+
5. The “speed factor”, indicating the relative speed of the machine as a positive integer.
313+
If there are multiple machines of the right type, Nix will prefer the fastest, taking load into account.
314+
315+
6. A comma-separated list of supported [system features](#conf-system-features).
316+
317+
A machine will only be used to build a derivation if all the features in the derivation's [`requiredSystemFeatures`](@docroot@/language/advanced-attributes.html#adv-attr-requiredSystemFeatures) attribute are supported by that machine.
318+
319+
7. A comma-separated list of required [system features](#conf-system-features).
320+
321+
A machine will only be used to build a derivation if all of the machine’s required features appear in the derivation’s [`requiredSystemFeatures`](@docroot@/language/advanced-attributes.html#adv-attr-requiredSystemFeatures) attribute.
322+
323+
8. The (base64-encoded) public host key of the remote machine.
324+
If omitted, SSH will use its regular `known_hosts` file.
325+
326+
The value for this field can be obtained via `base64 -w0`.
327+
328+
> **Example**
329+
>
330+
> Multiple builders specified on the command line:
331+
>
332+
> ```console
333+
> --builders 'ssh://mac x86_64-darwin ; ssh://beastie x86_64-freebsd'
334+
> ```
335+
336+
> **Example**
337+
>
338+
> This specifies several machines that can perform `i686-linux` builds:
339+
>
340+
> ```
341+
> [email protected] i686-linux /home/nix/.ssh/id_scratchy 8 1 kvm
342+
> [email protected] i686-linux /home/nix/.ssh/id_scratchy 8 2
343+
> [email protected] i686-linux /home/nix/.ssh/id_scratchy 1 2 kvm benchmark
344+
> ```
345+
>
346+
> However, `poochie` will only build derivations that have the attribute
347+
>
348+
> ```nix
349+
> requiredSystemFeatures = [ "benchmark" ];
350+
> ```
351+
>
352+
> or
353+
>
354+
> ```nix
355+
> requiredSystemFeatures = [ "benchmark" "kvm" ];
356+
> ```
357+
>
358+
> `itchy` cannot do builds that require `kvm`, but `scratchy` does support such builds.
359+
> For regular builds, `itchy` will be preferred over `scratchy` because it has a higher speed factor.
360+
361+
For Nix to use substituters, the calling user must be in the [`trusted-users`](#conf-trusted-users) list.
362+
363+
> **Note**
364+
>
365+
> A build machine must be accessible via SSH and have Nix installed.
366+
> `nix` must be available in `$PATH` for the user connecting over SSH.
367+
368+
> **Warning**
369+
>
370+
> If you are building via the Nix daemon (default), the Nix daemon user account on the local machine (that is, `root`) requires access to a user account on the remote machine (not necessarily `root`).
371+
>
372+
> If you can’t or don’t want to configure `root` to be able to access the remote machine, set [`store`](#conf-store) to any [local store](store/types/local-store.html), e.g. by passing `--store /tmp` to the command on the local machine.
373+
374+
To build only on remote machines and disable local builds, set [`max-jobs`](#conf-max-jobs) to 0.
375+
376+
If you want the remote machines to use substituters, set [`builders-use-substitutes`](#conf-builders-use-substituters) to `true`.
377+
)",
378+
{}, false};
267379

268380
Setting<bool> alwaysAllowSubstitutes{
269381
this, false, "always-allow-substitutes",

0 commit comments

Comments
 (0)