9.10 Derivações

Low-level build actions and the environment in which they are performed are represented by derivations. A derivation contains the following pieces of information:

• The outputs of the derivation—derivations produce at least one file or directory in the store, but may produce more.
• The inputs of the derivations—i.e., its build-time dependencies—which may be other derivations or plain files in the store (patches, build scripts, etc.).
• The system type targeted by the derivation—e.g., x86_64-linux.
• The file name of a build script in the store, along with the arguments to be passed.
• A list of environment variables to be defined.

Derivations allow clients of the daemon to communicate build actions to the store. They exist in two forms: as an in-memory representation, both on the client- and daemon-side, and as files in the store whose name end in .drv—these files are referred to as derivation paths. Derivations paths can be passed to the build-derivations procedure to perform the build actions they prescribe (see O armazém).

Operations such as file downloads and version-control checkouts for which the expected content hash is known in advance are modeled as fixed-output derivations. Unlike regular derivations, the outputs of a fixed-output derivation are independent of its inputs—e.g., a source code download produces the same result regardless of the download method and tools being used.

The outputs of derivations—i.e., the build results—have a set of references, as reported by the references RPC or the guix gc --references command (see Invocando guix gc). References are the set of run-time dependencies of the build results. References are a subset of the inputs of the derivation; this subset is automatically computed by the build daemon by scanning all the files in the outputs.

The (guix derivations) module provides a representation of derivations as Scheme objects, along with procedures to create and otherwise manipulate derivations. The lowest-level primitive to create a derivation is the derivation procedure:

Scheme Procedure: derivation store name builder args [#:outputs '("out")] [#:hash #f] [#:hash-algo #f]  [#:recursive?

#f] [#:inputs ’()] [#:env-vars ’()]  [#:system (%current-system)] [#:references-graphs #f]  [#:allowed-references #f] [#:disallowed-references #f]  [#:leaked-env-vars #f] [#:local-build? #f]  [#:substitutable? #t] [#:properties ’()] Build a derivation with the given arguments, and return the resulting <derivation> object.

When hash and hash-algo are given, a fixed-output derivation is created—i.e., one whose result is known in advance, such as a file download. If, in addition, recursive? is true, then that fixed output may be an executable file or a directory and hash must be the hash of an archive containing this output.

When references-graphs is true, it must be a list of file name/store path pairs. In that case, the reference graph of each store path is exported in the build environment in the corresponding file, in a simple text format.

When allowed-references is true, it must be a list of store items or outputs that the derivation’s output may refer to. Likewise, disallowed-references, if true, must be a list of things the outputs may not refer to.

When leaked-env-vars is true, it must be a list of strings denoting environment variables that are allowed to “leak” from the daemon’s environment to the build environment. This is only applicable to fixed-output derivations—i.e., when hash is true. The main use is to allow variables such as http_proxy to be passed to derivations that download files.

When local-build? is true, declare that the derivation is not a good candidate for offloading and should rather be built locally (see Usando o recurso de descarregamento). This is the case for small derivations where the costs of data transfers would outweigh the benefits.

When substitutable? is false, declare that substitutes of the derivation’s output should not be used (see Substitutos). This is useful, for instance, when building packages that capture details of the host CPU instruction set.

properties must be an association list describing “properties” of the derivation. It is kept as-is, uninterpreted, in the derivation.

Here’s an example with a shell script as its builder, assuming store is an open connection to the daemon, and bash points to a Bash executable in the store:

(use-modules (guix utils)
             (guix store)
             (guix derivations))

(let ((builder   ; add the Bash script to the store
        (add-text-to-store store "my-builder.sh"
                           "echo hello world > $out\n" '())))
  (derivation store "foo"
              bash `("-e" ,builder)
              #:inputs `((,bash) (,builder))
              #:env-vars '(("HOME" . "/homeless"))))
⇒ #<derivation /gnu/store/…-foo.drv => /gnu/store/…-foo>

As can be guessed, this primitive is cumbersome to use directly. A better approach is to write build scripts in Scheme, of course! The best course of action for that is to write the build code as a “G-expression”, and to pass it to gexp->derivation. For more information, see Expressões-G.

Once upon a time, gexp->derivation did not exist and constructing derivations with build code written in Scheme was achieved with build-expression->derivation, documented below. This procedure is now deprecated in favor of the much nicer gexp->derivation.

Scheme Procedure: build-expression->derivation store name exp  [#:system (%current-system)] [#:inputs '()] [#:outputs '("out")] [#:hash #f] [#:hash-algo #f]  [#:recursive? #f]

[#:env-vars ’()] [#:modules ’()]  [#:references-graphs #f] [#:allowed-references #f]  [#:disallowed-references #f]  [#:local-build? #f] [#:substitutable? #t] [#:guile-for-build #f] Return a derivation that executes Scheme expression exp as a builder for derivation name. inputs must be a list of (name drv-path sub-drv) tuples; when sub-drv is omitted, "out" is assumed. modules is a list of names of Guile modules from the current search path to be copied in the store, compiled, and made available in the load path during the execution of exp—e.g., ((guix build utils) (guix build gnu-build-system)).

exp is evaluated in an environment where %outputs is bound to a list of output/path pairs, and where %build-inputs is bound to a list of string/output-path pairs made from inputs. Optionally, env-vars is a list of string pairs specifying the name and value of environment variables visible to the builder. The builder terminates by passing the result of exp to exit; thus, when exp returns #f, the build is considered to have failed.

exp is built using guile-for-build (a derivation). When guile-for-build is omitted or is #f, the value of the %guile-for-build fluid is used instead.

See the derivation procedure for the meaning of references-graphs, allowed-references, disallowed-references, local-build?, and substitutable?.

Here’s an example of a single-output derivation that creates a directory containing one file:

(let ((builder '(let ((out (assoc-ref %outputs "out")))
                  (mkdir out)    ; create /gnu/store/…-goo
                  (call-with-output-file (string-append out "/test")
                    (lambda (p)
                      (display '(hello guix) p))))))
  (build-expression->derivation store "goo" builder))

⇒ #<derivation /gnu/store/…-goo.drv => …>