From f1ae10b992cf8b3b5f13c5bf69f264872c0a4f4f Mon Sep 17 00:00:00 2001 From: Eelco Dolstra Date: Thu, 7 Apr 2005 09:36:35 +0000 Subject: * Build hook documentation. * nix-store options. --- doc/manual/env-common.xml | 152 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 152 insertions(+) (limited to 'doc/manual/env-common.xml') diff --git a/doc/manual/env-common.xml b/doc/manual/env-common.xml index cf84dd054..ec468eba1 100644 --- a/doc/manual/env-common.xml +++ b/doc/manual/env-common.xml @@ -118,6 +118,158 @@ $ mount -o bind /mnt/otherdisk/nix /nix +NIX_BUILD_HOOK + + + + Specifies the location of the build hook, + which is a program (typically some script) that Nix will call + whenever it wants to build a derivation. This is used to implement + distributed builds (see ). The protocol by which the calling Nix process and the build + hook communicate is as follows. + + The build hook is called with the following command-line + arguments: + + + + A boolean value 0 or + 1 specifying whether Nix can locally execute + more builds, as per the option. + The purpose of this argument is to allow the hook to not have to + maintain bookkeeping for the local machine. + + The Nix platform identifier for the local machine + (e.g., i686-linux). + + The Nix platform identifier for the derivation, + i.e., its system + attribute. + + The store path of the derivation. + + + + + + On the basis of this information, and whatever persistent + state the build hook keeps about other machines and their current + load, it has to decide what to do with the build. It should print + out on file descriptor 3 one of the following responses (terminated + by a newline, "\n"): + + + + decline + + The build hook is not willing or able to perform + the build; the calling Nix process should do the build itself, + if possible. + + + + postpone + + The build hook cannot perform the build now, but + can do so in the future (e.g., because all available build slots + on remote machines are in use). The calling Nix process should + postpone this build until at least one currently running build + has terminated. + + + + accept + + The build hook has accepted the + build. + + + + + + + + If the build hook accepts the build, it is possible that it is + no longer necessary to do the build because some other process has + performed the build in the meantime. To prevent races, the hook + must read from file descriptor 4 a single line that tells it whether + to continue: + + + + cancel + + The build has already been done, so the hook + should exit. + + + + okay + + The hook should proceed with the build. At this + point, the calling Nix process has acquired locks on the output + path, so no other Nix process will perform the + build. + + + + + + + + If the hook has been told to proceed, Nix will store in the + hook’s current directory a number of text files that contain + information about the derivation: + + + + inputs + + The set of store paths that are inputs to the + build process (one per line). These have to be copied + to the remote machine (in addition to the + store derivation itself). + + + + outputs + + The set of store paths that are outputs of the + derivation (one per line). These have to be copied + from the remote machine if the build + succeeds. + + + + references + + The reference graph of the inputs, in the format + accepted by the command nix-store + --register-validity. It is necessary to run + this command on the remote machine after copying the inputs to + inform Nix on the remote machine that the inputs are valid + paths. + + + + + + + + The hook should copy the inputs to the remote machine, + register the validity of the inputs, perform the remote build, and + copy the outputs back to the local machine. An exit code other than + 0 indicates that the hook has failed. + + + + + + + -- cgit v1.2.3