Suivant: , Précédent: , Monter: Interface de programmation   [Table des matières][Index]


8.10 Dérivations

Les actions de construction à bas-niveau et l’environnement dans lequel elles sont effectuées sont représentés par des dérivations. Une dérivation contient cet ensemble d’informations :

Les dérivations permettent aux client du démon de communiquer des actions de construction dans le dépôt. Elles existent sous deux formes : en tant que représentation en mémoire, à la fois côté client et démon, et en tant que fichiers dans le dépôt dont le nom finit par .drv — on dit que ce sont des chemins de dérivations. Les chemins de dérivations peuvent être passés à la procédure build-derivations pour effectuer les actions de construction qu’ils prescrivent (voir Le dépôt).

Des opérations comme le téléchargement de fichiers et la récupération de sources gérés par un logiciel de contrôle de version pour lesquels le hash du contenu est connu à l’avance sont modélisés par des dérivations à sortie fixe. Contrairement aux dérivation habituelles, les sorties d’une dérivation à sortie fixe sont indépendantes de ses entrées — p.ex. un code source téléchargé produit le même résultat quelque soit la méthode de téléchargement utilisée.

Les sorties des dérivations — c.-à-d. les résultats de la construction — ont un ensemble de références, comme le rapporte le RPC references ou la commande guix gc --references (voir Invoquer guix gc). Les références sont l’ensemble des dépendances à l’exécution des résultats de la construction. Les références sont un sous-ensemble des entrées de la dérivation ; ce sous-ensemble est automatiquement calculé par le démon de construction en scannant tous les fichiers dans les sorties.

Le module (guix derivations) fournit une représentation des dérivations comme des objets Scheme, avec des procédures pour créer et manipuler des dérivations. La primitive de plus bas-niveau pour créer une dérivation est la procédure derivation :

Procédure :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 '()]

Construit une dérivation avec les arguments donnés et renvoie l’objet <derivation> obtenu.

Lorsque hash et hash-algo sont donnés, une dérivation à sortie fixe est créée — c.-à-d. une dérivation dont le résultat est connu à l’avance, comme dans le cas du téléchargement d’un fichier. Si, en plus, recursive? est vrai, alors la sortie fixe peut être un fichier exécutable ou un répertoire et hash doit être le hash d’une archive contenant la sortie.

Lorsque references-graphs est vrai, il doit s’agir d’une liste de paires de noms de fichiers et de chemins du dépôt. Dans ce cas, le graphe des références de chaque chemin du dépôt est exporté dans l’environnement de construction dans le fichier correspondant, dans un simple format texte.

Lorsque allowed-references est vrai, il doit s’agir d’une liste d’éléments du dépôt ou de sorties auxquelles la sortie de la dérivations peut faire référence. De même, disallowed-references, si vrai, doit être une liste de choses que la sortie ne doit pas référencer.

Lorsque leaked-env-vars est vrai, il doit s’agir d’une liste de chaînes de caractères qui désignent les variables d’environnements qui peuvent « fuiter » de l’environnement du démon dans l’environnement de construction. Ce n’est possible que pour les dérivations à sortie fixe — c.-à-d. lorsque hash est vrai. L’utilisation principale est de permettre à des variables comme http_proxy d’être passées aux dérivations qui téléchargent des fichiers.

Lorsque local-build? est vrai, déclare que la dérivation n’est pas un bon candidat pour le déchargement et devrait plutôt être construit localement (voir Utiliser le dispositif de déchargement). C’est le cas des petites dérivations où le coût du transfert de données est plus important que les bénéfices.

Lorsque que substitutable? est faux, déclare que les substituts de la sortie de la dérivation ne devraient pas être utilisés (voir Substituts). Cela est utile par exemple pour construire des paquets qui utilisent des détails du jeu d’instruction du CPU hôte.

properties doit être une liste d’association décrivant les « propriétés » de la dérivation. Elle est gardée telle-quelle, sans être interprétée, dans la dérivation.

Voici un exemple avec un script shell comme constructeur, en supposant que store est une connexion ouverte au démon et bash pointe vers un exécutable Bash dans le dépôt :

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

(let ((builder   ; ajoute le script Bash au dépôt
        (add-text-to-store store "my-builder.sh"
                           "echo hello world > $out\n" '())))
  (derivation store "toto"
              bash `("-e" ,builder)
              #:inputs `((,bash) (,builder))
              #:env-vars '(("HOME" . "/homeless"))))
 #<derivation /gnu/store/…-toto.drv => /gnu/store/…-toto>

Comme on pourrait s’en douter, cette primitive est difficile à utiliser directement. Une meilleure approche est d’écrire les scripts de construction en Scheme, bien sur ! Le mieux à faire pour cela est d’écrire le code de construction comme une « G-expression » et de la passer à gexp->derivation. Pour plus d’informations, voir G-Expressions.

Il fut un temps où gexp->derivation n’existait pas et où construire une dérivation donc le code de construction était écrit en Scheme se faisait avec build-expression->derivation, documenté plus bas. Cette procédure est maintenant obsolète, remplacée par gexp->derivation qui est meilleure.

Procédure :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]

Renvoie une dérivation qui exécute l’expression Scheme exp comme un constructeur pour la dérivation name. inputs doit être une liste de tuples (name drv-path sub-drv) ; lorsque sub-drv est omis, "out" est utilisé. modules est une liste de noms de modules Guile du chemin de recherche actuel qui seront copiés dans le dépôt, compilés et rendus disponibles dans le chemin de chargement pendant l’exécution de exp — p. ex. ((guix build utils) (guix build gnu-build-system)).

exp est évaluée dans une environnement où %outputs est lié à une liste de paires de sortie/chemin, et où %build-inputs est lié à une liste de paires de chaînes de caractères et de chemin de sortie construite à partir de inputs. Éventuellement, env-vars est une liste de paires de chaînes de caractères spécifiant le nom et la valeur de variables d’environnement visibles pour le constructeur. Le constructeur termine en passant le résultat de exp à exit ; ainsi, lorsque exp renvoie #f, la construction est considérée en échec.

exp est construite avec guile-for-build (une dérivation). Lorsque guile-for-build est omis où est #f, la valeur du fluide %guile-for-build est utilisée à la place.

Voir la procédure derivation pour la signification de references-graph, allowed-references, disallowed-references, local-build? et substitutable?.

Voici un exemple de dérivation à sortie unique qui crée un répertoire avec un fichier :

(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 => …>

Suivant: La monade du dépôt, Précédent: Le dépôt, Monter: Interface de programmation   [Table des matières][Index]