This is guix.fr.info, produced by makeinfo version 6.7 from
guix.fr.texi.

Copyright © 2012-2022 Ludovic Courtès
Copyright © 2013, 2014, 2016 Andreas Enge
Copyright © 2013 Nikita Karetnikov
Copyright © 2014, 2015, 2016 Alex Kost
Copyright © 2015, 2016 Mathieu Lirzin
Copyright © 2014 Pierre-Antoine Rault
Copyright © 2015 Taylan Ulrich Bayırlı/Kammer
Copyright © 2015, 2016, 2017, 2019, 2020, 2021 Leo Famulari
Copyright © 2015, 2016, 2017, 2018, 2019, 2020, 2021, 2022 Ricardo
Wurmus
Copyright © 2016 Ben Woodcroft
Copyright © 2016, 2017, 2018, 2021 Chris Marusich
Copyright © 2016, 2017, 2018, 2019, 2020, 2021, 2022 Efraim Flashner
Copyright © 2016 John Darrington
Copyright © 2016, 2017 Nikita Gillmann
Copyright © 2016, 2017, 2018, 2019, 2020 Jan Nieuwenhuizen
Copyright © 2016, 2017, 2018, 2019, 2020, 2021 Julien Lepiller
Copyright © 2016 Alex ter Weele
Copyright © 2016, 2017, 2018, 2019, 2020, 2021 Christopher Baines
Copyright © 2017, 2018, 2019 Clément Lassieur
Copyright © 2017, 2018, 2020, 2021, 2022 Mathieu Othacehe
Copyright © 2017 Federico Beffa
Copyright © 2017, 2018 Carlo Zancanaro
Copyright © 2017 Thomas Danckaert
Copyright © 2017 humanitiesNerd
Copyright © 2017, 2021 Christine Lemmer-Webber
Copyright © 2017, 2018, 2019, 2020, 2021, 2022 Marius Bakke
Copyright © 2017, 2019, 2020, 2022 Hartmut Goebel
Copyright © 2017, 2019, 2020, 2021, 2022 Maxim Cournoyer
Copyright © 2017–2022 Tobias Geerinckx-Rice
Copyright © 2017 George Clemmer
Copyright © 2017 Andy Wingo
Copyright © 2017, 2018, 2019, 2020 Arun Isaac
Copyright © 2017 nee
Copyright © 2018 Rutger Helling
Copyright © 2018, 2021 Oleg Pykhalov
Copyright © 2018 Mike Gerwitz
Copyright © 2018 Pierre-Antoine Rouby
Copyright © 2018, 2019 Gábor Boskovits
Copyright © 2018, 2019, 2020, 2022 Florian Pelz
Copyright © 2018 Laura Lazzati
Copyright © 2018 Alex Vong
Copyright © 2019 Josh Holland
Copyright © 2019, 2020 Diego Nicola Barbato
Copyright © 2019 Ivan Petkov
Copyright © 2019 Jakob L. Kreuze
Copyright © 2019 Kyle Andrews
Copyright © 2019 Alex Griffin
Copyright © 2019, 2020, 2021, 2022 Guillaume Le Vaillant
Copyright © 2020 Liliana Marie Prikler
Copyright © 2019, 2020, 2021, 2022 Simon Tournier
Copyright © 2020 Wiktor Żelazny
Copyright © 2020 Damien Cassou
Copyright © 2020 Jakub Kądziołka
Copyright © 2020 Jack Hill
Copyright © 2020 Naga Malleswari
Copyright © 2020, 2021 Brice Waegeneire
Copyright © 2020 R Veera Kumar
Copyright © 2020, 2021 Pierre Langlois
Copyright © 2020 pinoaffe
Copyright © 2020 André Batista
Copyright © 2020, 2021 Alexandru-Sergiu Marton
Copyright © 2020 raingloom
Copyright © 2020 Daniel Brooks
Copyright © 2020 John Soo
Copyright © 2020 Jonathan Brielmaier
Copyright © 2020 Edgar Vincent
Copyright © 2021, 2022 Maxime Devos
Copyright © 2021 B. Wilson
Copyright © 2021 Xinglu Chen
Copyright © 2021 Raghav Gururajan
Copyright © 2021 Domagoj Stolfa
Copyright © 2021 Hui Lu
Copyright © 2021 pukkamustard
Copyright © 2021 Alice Brenon
Copyright © 2021, 2022 Josselin Poiret
Copyright © 2021 muradm
Copyright © 2021, 2022 Andrew Tropin
Copyright © 2021 Sarah Morgensen
Copyright © 2022 Remco van ’t Veer
Copyright © 2022 Aleksandr Vityazev
Copyright © 2022 Philip M^{c}Grath
Copyright © 2022 Karl Hallsby
Copyright © 2022 Justin Veilleux
Copyright © 2022 Reily Siegel
Copyright © 2022 Simon Streit
Copyright © 2022 (
Copyright © 2022 John Kehayias

   Vous avez la permission de copier, distribuer ou modifier ce document
sous les termes de la Licence GNU Free Documentation, version 1.3 ou
toute version ultérieure publiée par la Free Software Foundation ; sans
section invariante, texte de couverture et sans texte de quatrième de
couverture. Une copie de la licence est incluse dans la section
intitulée « GNU Free Documentation License ».
INFO-DIR-SECTION Administration système
START-INFO-DIR-ENTRY
* Guix: (guix.fr).           Gérer les logiciels installés et la
                               configuration du système.
* guix package : (guix.fr)Invoquer guix package.  Installer, supprimer et
                                                      mettre à jour des
                                                      paquets.
* guix gc : (guix.fr)Invoquer guix gc.  Récupérer de l’espace disque
                                            inutilisé.
* guix pull : (guix.fr)Invoquer guix pull.  Mettre à jour la liste des
                                                paquets disponibles.
* guix system : (guix.fr)Invoquer guix system.  Gérer la configuration du
                                                    système d’exploitation.
* guix deploy: (guix.fr)Invoquer guix deploy.  Gérer la configuration du
                                                 système d’exploitation
                                                 d’hôtes distants.
END-INFO-DIR-ENTRY

INFO-DIR-SECTION Développement logiciel
START-INFO-DIR-ENTRY
* guix shell: (guix.fr)Invoquer guix shell.  Créer des environnements
                                               logiciels.
* guix environment : (guix.fr)Invoquer guix environment.  Construire des
                                                              environnements
                                                              de construction
                                                              avec Guix.
* guix build : (guix.fr)Invoquer guix build.  Construire des paquets.
* guix pack : (guix.fr) Invoquer guix pack.  Créer des lots binaires.
END-INFO-DIR-ENTRY


File: guix.fr.info,  Node: Invoquer guix pack,  Next: La chaîne d'outils GCC,  Prev: Invoquer guix environment,  Up: Développement

8.3 Invoquer ‘guix pack’
========================

Parfois vous voulez passer un logiciel à des gens qui n’ont pas (encore
!) la chance d’utiliser Guix. Vous leur diriez bien de lancer ‘guix
package -i QUELQUE CHOSE’ mais ce n’est pas possible dans ce cas. C’est
là que ‘guix pack’ entre en jeu.

     Remarque : Si vous cherchez comment échanger des binaires entre des
     machines où Guix est déjà installé, *note Invoquer guix copy::,
     *note Invoquer guix publish::, et *note Invoquer guix archive::.

   La commande ‘guix pack’ crée un “pack” ou “lot de logiciels” : elle
crée une archive tar ou un autre type d’archive contenant les binaires
pour le logiciel qui vous intéresse ainsi que ses dépendances. L’archive
qui en résulte peut être utilisée sur toutes les machines qui n’ont pas
Guix et les gens peuvent lancer exactement les mêmes binaires que ceux
que vous avez avec Guix. Le pack lui-même est créé d’une manière
reproductible au bit près, pour que n’importe qui puisse vérifier qu’il
contient bien les résultats que vous prétendez proposer.

   Par exemple, pour créer un lot contenant Guile, Emacs, Geiser et
toutes leurs dépendances, vous pouvez lancer :

     $ guix pack guile emacs emacs-geiser
     ...
     /gnu/store/...-pack.tar.gz

   Le résultat ici est une archive tar contenant un répertoire
‘/gnu/store’ avec tous les paquets nécessaires. L’archive qui en résulte
contient un “profil” avec les trois paquets qui vous intéressent ; le
profil est le même qui celui qui aurait été créé avec ‘guix package -i’.
C’est ce mécanisme qui est utilisé pour créer les archives tar binaires
indépendantes de Guix (*note Installation binaire::).

   Les utilisateurs de ce pack devraient lancer
‘/gnu/store/...-profile/bin/guile’ pour lancer Guile, ce qui n’est pas
très pratique. Pour éviter cela, vous pouvez créer, disons, un lien
symbolique ‘/opt/gnu/bin’ vers le profil :

     guix pack -S /opt/gnu/bin=bin guile emacs emacs-geiser

De cette façon, les utilisateurs peuvent joyeusement taper
‘/opt/gnu/bin/guile’ et profiter.

   Et si le destinataire de votre pack n’a pas les privilèges root sur
sa machine, et ne peut donc pas le décompresser dans le système de
fichiers root ? Dans ce cas, vous pourriez utiliser l’option
‘--relocatable’ (voir plus bas). Cette option produit des “binaires
repositionnables”, ce qui signifie qu’ils peuvent être placés n’importe
où dans l’arborescence du système de fichiers : dans l’exemple
au-dessus, les utilisateur·rice·s peuvent décompresser votre archive
dans leur répertoire personnel et lancer directement
‘./opt/gnu/bin/guile’.

   Autrement, vous pouvez produire un pack au format d’image Docker avec
la commande suivante :

     guix pack -f docker -S /bin=bin guile guile-readline

Le résultat est une archive tar qui peut être passée à la commande
‘docker load’, puis à ‘docker run’ :

     docker load < FILE
     docker run -ti guile-guile-readline /bin/guile

où FICHIER est l’image renvoyée par GUIX PACK et ‘guile-guile-readline’
est son « tag d’image ». Voir la documentation de Docker
(https://docs.docker.com/engine/reference/commandline/load/) pour plus
d’informations.

   Autrement, vous pouvez produire une image SquashFS avec la commande
suivante :

     guix pack -f squashfs bash guile emacs emacs-geiser

Le résultat est une image de système de fichiers SquashFS qui peut soit
être montée directement soit être utilisée comme image de conteneur de
système de fichiers avec l’Singularity container execution environment
(https://singularity.lbl.gov), avec des commandes comme ‘singularity
shell’ ou ‘singularity exec’.

   Diverses options en ligne de commande vous permettent de
personnaliser votre pack :

‘--format=FORMAT’
‘-f FORMAT’
     Produire un pack dans le FORMAT donné.

     Les formats disponibles sont :

     ‘tarball’
          C’est le format par défaut. Il produit une archive tar
          contenant tous les binaires et les liens symboliques
          spécifiés.

     ‘docker’
          Cela produit une archive tar qui suit la spécification des
          images Docker
          (https://github.com/docker/docker/blob/master/image/spec/v1.2.md).
          Le « nom de dépôt » qui apparaît dans la sortie de la commande
          ‘docker images’ est calculé à partir des noms des paquets
          passés sur la ligne de commande ou dans le fichier manifeste.

     ‘squashfs’
          Cela produit une image SquashFS contenant tous les binaires et
          liens symboliques spécifiés, ainsi que des points de montages
          vides pour les systèmes de fichiers virtuels comme procfs.

               Remarque : Singularity _requiert_ que vous fournissiez
               ‘/bin/sh’ dans l’image. Pour cette raison, ‘guix pack -f
               squashfs’ implique toujours ‘-S /bin=bin’. Ainsi, votre
               invocation ‘guix pack’ doit toujours commencer par
               quelque chose comme :

                    guix pack -f squashfs bash ...

               Si vous oubliez le paquet ‘bash’ (ou similaire),
               ‘singularity run’ et ‘singularity exec’ vont échouer avec
               un message « no such file or directory » peu utile.

     ‘deb’
          Cela produit une archive Debian (un paquet avec l’extension
          ‘.deb’) contenant tous les binaires et les liens symboliques
          spécifiés, qui peut être installée sur n’importe quelle
          distribution GNU(/Linux) basée sur dpkg. Vous trouverez des
          options avancées avec l’option ‘--help-deb-format’. Elles
          permettent d’insérer des fichiers control pour un contrôle
          plus fin, comme pour activer des trigger ou fournir un script
          de configuration pour mainteneur pour lancer du code de
          configuration arbitraire à l’installation.

               guix pack -f deb -C xz -S /usr/bin/hello=bin/hello hello

               Remarque : Comme les archives produites par ‘guix pack’
               contiennent une collection d’objets du dépôt et comme
               chaque paquet ‘dpkg’ ne doit pas avoir de conflits de
               fichiers, en pratique cela signifie que vous ne pourrez
               sans doute pas installer plus d’une archive de ce genre
               sur un système donné.

               Attention : ‘dpkg’ prendra possession de tout fichier
               contenu dans le pack qu’il ne connaît _pas_. Il est peu
               avisé d’installer des fichiers ‘.deb’ produits par Guix
               sur un système où ‘/gnu/store’ est partagé avec un autre
               logiciel, comme une installation de Guix ou d’autres
               packs non deb.

‘--relocatable’
‘-R’
     Produire des “binaires repositionnables” — c.-à-d. des binaires que
     vous pouvez placer n’importe où dans l’arborescence du système de
     fichiers et les lancer à partir de là.

     Lorsque vous passez cette option une fois, les binaires qui en
     résultent demandent le support des “espaces de nom utilisateurs”
     dans le noyau Linux ; lorsque vous la passez _deux fois_(1), les
     binaires repositionnables utilisent PRoot si les espaces de noms ne
     sont pas utilisables, et ça fonctionne à peu près partout — voir
     plus bas pour comprendre les implications.

     Par exemple, si vous créez un pack contenant Bash avec :

          guix pack -RR -S /mybin=bin bash

     … vous pouvez copier ce pack sur une machine qui n’a pas Guix et
     depuis votre répertoire personnel en tant qu’utilisateur
     non-privilégié, lancer :

          tar xf pack.tar.gz
          ./mybin/sh

     Dans ce shell, si vous tapez ‘ls /gnu/store’, vous remarquerez que
     ‘/gnu/store’ apparaît et contient toutes les dépendances de ‘bash’,
     même si la machine n’a pas du tout de ‘/gnu/store’ ! C’est sans
     doute la manière la plus simple de déployer du logiciel construit
     avec Guix sur une machine sans Guix.

          Remarque : Par défaut ,les binaires repositionnables
          s’appuient sur les “espaces de noms utilisateurs” du noyau
          Linux, qui permet à des utilisateurs non-privilégiés
          d’effectuer des montages et de changer de racine. Les
          anciennes versions de Linux ne le supportait pas et certaines
          distributions GNU/Linux le désactive.

          Pour produire des binaires repositionnables qui fonctionnent
          même sans espace de nom utilisatrice·eur, passez
          ‘--relocatable’ ou ‘-R’ _deux fois_. Dans ce cas, les binaires
          testeront la prise en charge des espaces de noms
          utilisatrice·eur·s et utiliseront PRoot s’ils ne sont pas pris
          en charge. Les moteurs d’exécution suivants sont pris en
          charge :

          ‘default’
               Essayez les espaces de noms utilisateur·rice·s et revenez
               à PRoot si les espaces de noms utilisateur·rice·s ne sont
               pas pris en charge (voir ci-dessous).

          ‘performance’
               Essayez les espaces de noms utilisateur·rice·s et revenez
               à Fakechroot si les espaces de noms utilisateur·rice·s ne
               sont pas pris en charge (voir ci-dessous).

          ‘users’
               Lance le programme à travers les espaces de nom
               utilisateur·rice et échoue s’ils ne sont pas supportés.

          ‘proot’
               Passez à travers PRoot. Le programme PRoot
               (https://proot-me.github.io/) fournit la prise en charge
               nécessaire pour la virtualisation du système de fichier.
               Il y parvient en utilisant l’appel système ‘ptrace’ sur
               le programme courant. Cette approche a l’avantage de
               fonctionner sans demander de support spécial de la part
               du noyau, mais occasionne un coût supplémentaire en temps
               pour chaque appel système effectué.

          ‘fakechroot’
               Passez à travers Fakechroot. Fakechroot
               (https://github.com/dex4er/fakechroot/) virtualise les
               accès au système de fichier en interceptant les appels
               vers les fonctions de la bibliothèque C telles que
               ‘open’, ‘stat’, ‘exec’, et ainsi de suite. Contrairement
               à PRoot, il n’engendre que très peu de coûts généraux.
               Cependant, il ne fonctionne pas encore tout-à-fait : par
               exemple, certains accès au système de fichier effectués à
               partir de la bibliothèque C ne sont pas interceptés, et
               les accès au système de fichier effectués via les appels
               système directs ne sont pas non plus interceptés,
               conduisant à un comportement erratique.

          Lors de l’exécution d’un programme complet, vous pouvez
          demander explicitement l’un des moteurs d’exécution énumérés
          ci-dessus en définissant en conséquence la variable
          d’environnement ‘GUIX_EXECUTION_ENGINE’.

‘--entry-point=COMMANDE’
     Utiliser COMMANDE comme “point d’entrée” du paquet résultant, si le
     format du paquet le supporte–actuellement ‘docker’ et ‘squashfs’
     (Singularity) la supportent. COMMAND doit être relatif au profil
     contenu dans le pack.

     Le point d’entrée spécifie la commande que des outils comme ‘docker
     run’ or ‘singularity run’ lancent automatiquement par défaut. Par
     exemple, vous pouvez faire :

          guix pack -f docker --entry-point=bin/guile guile

     Le pack résultant peut être facilement chargé et ‘docker run’ sans
     arguments supplémentaires engendrera ‘bin/guile’ :

          docker load -i pack.tar.gz
          docker run IMAGE-ID

‘--expression=EXPR’
‘-e EXPR’
     Considérer le paquet évalué par EXPR.

     Cela a le but identique que l’option de même nom de ‘guix build’
     (*note ‘--expression’ dans ‘guix build’: Options de construction
     supplémentaires.).

‘--manifest=FICHIER’
‘-m FICHIER’
     Utiliser les paquets contenus dans l’objet manifeste renvoyé par le
     code Scheme dans FICHIER. Vous pouvez répéter cette option
     plusieurs fois, auquel cas les manifestes sont concaténés.

     Elle a un but similaire à l’option de même nom dans ‘guix package’
     (*note ‘--manifest’: profile-manifest.) et utilise les mêmes
     fichiers manifeste. Ils vous permettent de définir une collection
     de paquets une fois et de l’utiliser aussi bien pour créer des
     profils que pour créer des archives pour des machines qui n’ont pas
     Guix d’installé. Remarquez que vous pouvez spécifier _soit_ un
     fichier manifeste, _soit_ une liste de paquet, mais pas les deux.

     *Note Écrire un manifeste:: pour des informations sur l’écriture
     d’un manifeste. *Note ‘guix shell --export-manifest’:
     shell-export-manifest, pour des informations sur la « conversion »
     des options de la ligne de commande en un manifeste.

‘--system=SYSTÈME’
‘-s SYSTÈME’
     Tenter de construire pour le SYSTÈME — p. ex. ‘i686-linux’ — plutôt
     que pour le type de système de l’hôte de construction.

‘--target=TRIPLET’
     Effectuer une compilation croisée pour TRIPLET qui doit être un
     triplet GNU valide, comme ‘""aarch64-linux-gnu""’ (*note GNU
     configuration triplets: (autoconf)Specifying target triplets.).

‘--compression=OUTIL’
‘-C OUTIL’
     Compresser l’archive résultante avec OUTIL — l’un des outils parmi
     ‘gzip’, ‘zstd’, ‘bzip2’, ‘xz’, ‘lzip’, ou ‘none’ pour aucune
     compression.

‘--symlink=SPEC’
‘-S SPEC’
     Ajouter les liens symboliques spécifiés par SPEC dans le pack.
     Cette option peut apparaître plusieurs fois.

     SPEC a la forme ‘SOURCE=CIBLE’, où SOURCE est le lien symbolique
     qui sera créé et CIBLE est la cible du lien.

     Par exemple, ‘-S /opt/gnu/bin=bin’ crée un lien symbolique
     ‘/opt/gnu/bin’ qui pointe vers le sous-répertoire ‘bin’ du profil.

‘--save-provenance’
     Sauvegarder les informations de provenance des paquets passés sur
     la ligne de commande. Les informations de provenance contiennent
     l’URL et le commit des canaux utilisés (*note Canaux::).

     Les informations de provenance sont sauvegardées dans le fichier
     ‘/gnu/store/...-profile/manifest’ du pack, avec les métadonnées de
     paquets habituelles — le nom et la version de chaque paquet, leurs
     entrées propagées, etc. Ce sont des informations utiles pour le
     destinataire du pack, qui sait alors comment le pack a
     (normalement) été obtenu.

     Cette option n’est pas activée par défaut car, comme l’horodatage,
     les informations de provenance ne contribuent en rien au processus
     de construction. En d’autres termes, il y a une infinité d’URL et
     d’ID de commit qui permettent d’obtenir le même pack. Enregistrer
     de telles métadonnées « silencieuses » dans la sortie casse donc
     éventuellement la propriété de reproductibilité au bit près.

‘--root=FICHIER’
‘-r FICHIER’
     Fait de FICHIER un lien symbolique vers le résultat, et
     l’enregistre en tant que racine du ramasse-miettes.

‘--localstatedir’
‘--profile-name=NOM’
     Inclus le « répertoire d’état local », ‘/var/guix’, dans le lot qui
     en résulte, et notamment le profil
     ‘/var/guix/profiles/per-user/root/NOM’ — par défaut NOM est
     ‘guix-profile’, ce qui correspond à ‘~root/.guix-profile’.

     ‘/var/guix’ contient la base de données du dépôt (*note Le dépôt::)
     ainsi que les racines du ramasse-miettes (*note Invoquer guix
     gc::). Le fournir dans le pack signifie que le dépôt et « complet »
     et gérable par Guix ; ne pas le fournir dans le pack signifie que
     le dépôt est « mort » : aucun élément ne peut être ajouté ni enlevé
     après l’extraction du pack.

     Un cas d’utilisation est l’archive binaire indépendante de Guix
     (*note Installation binaire::).

‘--derivation’
‘-d’
     Affiche le nom de la dérivation que le pack construit.

‘--bootstrap’
     Utiliser les programmes d’amorçage pour construire le pack. Cette
     option n’est utile que pour les personnes qui développent Guix.

   En plus, ‘guix pack’ supporte toutes les options de construction
communes (*note Options de construction communes::) et toutes les
options de transformation de paquets (*note Options de transformation de
paquets::).

   ---------- Footnotes ----------

   (1) Il y a une astuce pour s’en souvenir : on peut envisager ‘-RR’,
qui ajoute le support PRoot, comme étant l’abréviation de « Réellement
Repositionnable ». Pas mal, hein ?


File: guix.fr.info,  Node: La chaîne d'outils GCC,  Next: Invoquer guix git authenticate,  Prev: Invoquer guix pack,  Up: Développement

8.4 La chaîne d’outils GCC
==========================

Guix offre des paquets de compilateurs individuels comme ‘gcc’ mais si
vous avez besoin d’une chaîne de compilation complète pour compiler et
lier du code source, utilisez le paquet ‘gcc-toolchain’. Ce paquet
fournit une chaîne d’outils complète GCC pour le développement C/C++,
dont GCC lui-même, la bibliothèque C de GNU (les en-têtes et les
binaires, plus les symboles de débogage dans la sortie ‘debug’),
Binutils et un wrapper pour l’éditeur de liens.

   Le rôle de l’enveloppe est d’inspecter les paramètres ‘-L’ et ‘-l’
passés à l’éditeur de liens, d’ajouter des arguments ‘-rpath’
correspondants et d’invoquer l’actuel éditeur de liens avec ce nouvel
ensemble d’arguments. Vous pouvez dire au wrapper de refuser de lier les
programmes à des bibliothèques en dehors du dépôt en paramétrant la
variable d’environnement ‘GUIX_LD_WRAPPER_ALLOW_IMPURITIES’ sur ‘no’.

   Le paquet ‘gfortran-toolchain’ fournit une chaîne d’outils GCC
complète pour le développement en Fortran. Pour d’autres langages,
veuillez utiliser ‘guix search gcc toolchain’ (*note Invoquer guix
package: guix-search.).


File: guix.fr.info,  Node: Invoquer guix git authenticate,  Prev: La chaîne d'outils GCC,  Up: Développement

8.5 Invoquer ‘guix git authenticate’
====================================

La commande ‘guix git authenticate’ authentifie un checkout Git en
suivant la même règle que pour les canaux (*note channel authentication:
channel-authentication.). C’est-à-dire qu’à partir d’un commit donné, il
s’assure que tous les commit suivants sont signés par une clé OpenPGP
dont l’empreinte digitale apparaît dans le fichier
‘.guix-authorizations’ de son ou ses commit(s) parent(s).

   Vous allez trouver cette commande utile si vous maintenez un canal.
Mais en fait, ce mécanisme d’authentification est utile dans un contexte
plus large, Vous pourriez donc vouloir l’utiliser pour des dépôts Git
qui n’ont rien à voir avec Guix.

   La syntaxe générale est :

     guix git authenticate COMMIT SIGNER [OPTIONS...]

   Par défaut, cette commande authentifie le chekout Git dans le
répertoire courant ; il ne produit rien et sort avec le code de sortie
zéro en cas de succès et non zéro en cas d’échec. COMMIT ci-dessus
désigne le premier commit où l’authentification a lieu, et SIGNER est
l’empreinte OpenPGP de la clé publique utilisée pour signer COMMIT.
Ensemble, ils forment une «introduction de canal» (*note introduction de
canal: channel-authentication.). Les options ci-dessous vous permettent
d’affiner le processus.

‘--repository=RÉPERTOIRE’
‘-r RÉPERTOIRE’
     Ouvre le dépôt Git dans DIRECTORY au lieu du répertoire courant.

‘--keyring=RÉFÉRENCE’
‘-k FÉFÉRENCE’
     Chargez le porte-clés OpenPGP à partir de RÉFÉRENCE, la référence
     d’une branche telle que ‘origin/keyring’ ou ‘my-keyring’. La
     branche doit contenir des clés publiques OpenPGP dans des fichiers
     ‘.key’, soit sous forme binaire, soit "blindée ASCII". Par défaut,
     le porte-clés est chargé à partir de la branche nommée ‘keyring’.

‘--stats’
     Affiche les statistiques sur les signatures de commits à l’issue de
     la procédure.

‘--cache-key=KEY’
     Les commits préalablement authentifiés sont mis en cache dans un
     fichier sous ‘~/.cache/guix/authentication’. Cette option force le
     cache à être stocké dans le fichier KEY de ce répertoire.

‘--historical-authorizations=FICHIER’
     Par défaut, tout commit dont le(s) commit(s) parent(s) ne
     contient(nt) pas le fichier ‘.guix-authorizations’ est considéré
     comme non authentique. En revanche, cette option considère les
     autorisations dans FILE pour tout commit dont le fichier
     ‘.guix-authorizations’ est manquant. Le format de FILE est le même
     que celui de ‘.guix-authorizations’ (au format *note
     ‘.guix-autorizations’: channel-authorizations.).


File: guix.fr.info,  Node: Interface de programmation,  Next: Utilitaires,  Prev: Développement,  Up: Top

9 Interface de programmation
****************************

GNU Guix fournit diverses interface de programmation Scheme (API) qui
pour définir, construire et faire des requêtes sur des paquets. La
première interface permet aux utilisateurs d’écrire des définitions de
paquets de haut-niveau. Ces définitions se réfèrent à des concepts de
création de paquets familiers, comme le nom et la version du paquet, son
système de construction et ses dépendances. Ces définitions peuvent
ensuite être transformées en actions concrètes lors de la construction.

   Les actions de construction sont effectuées par le démon Guix, pour
le compte des utilisateur·rice·s. Dans un environnement standard, le
démon possède les droits en écriture sur le dépôt — le répertoire
‘/gnu/store’ — mais pas les utilisateur·rice·s. La configuration
recommandée permet aussi au démon d’effectuer la construction dans des
chroots, à l’adresse des utilisateur·rice·s de construction spécifiques,
pour minimiser les interférences avec le reste du système.

   Il y a des API de plus bas niveau pour interagir avec le démon et le
dépôt. Pour demander au démon d’effectuer une action de construction,
les utilisateurs lui donnent en fait une “dérivation”. Une dérivation
est une représentation à bas-niveau des actions de construction à
entreprendre et l’environnement dans lequel elles devraient avoir lieu —
les dérivations sont aux définitions de paquets ce que l’assembleur est
aux programmes C. Le terme de « dérivation » vient du fait que les
résultats de la construction en _dérivent_.

   Ce chapitre décrit toutes ces API tour à tour, à partir des
définitions de paquets à haut-niveau.

* Menu:

* Modules de paquets::       Les paquets du point de vu du programmeur.
* Définition des paquets::  Définir de nouveaux paquets.
* Définition de variantes de paquets::  Créer des paquets personnalisés.
* Écrire un manifeste::     La nomenclature de votre environnement.
* Systèmes de construction::  Spécifier comment construire les paquets.
* Phases de construction::   Phases du processus de construction d’un
                               paquet.
* Utilitaires de construction::  Des aides pour les définitions de vos
                                   paquets et plus encore.
* Chemins de recherche::     Déclarer les variables d’environnements pour
                               les chemins de recherche.
* Le dépôt::               Manipuler le dépôt de paquets.
* Dérivations::             Interface de bas-niveau avec les dérivations
                               de paquets.
* La monade du dépôt::     Interface purement fonctionnelle avec le
                               dépôt.
* G-Expressions::            Manipuler les expressions de construction.
* Invoquer guix repl::       Programmer Guix dans Guile
* Utiliser Guix de manière interactive::  Interaction fine à travers la
                                             REPL.


File: guix.fr.info,  Node: Modules de paquets,  Next: Définition des paquets,  Up: Interface de programmation

9.1 Modules de paquets
======================

D’un point de vue programmatique, les définitions de paquets de la
distribution GNU sont fournies par des modules Guile dans l’espace de
noms ‘(gnu packages ...)’(1) (*note Guile modules: (guile)Modules.). Par
exemple, le module ‘(gnu packages emacs)’ exporte une variable nommée
‘emacs’, qui est liée à un objet ‘<package>’ (*note Définition des
paquets::).

   L’espace de nom ‘(gnu packages ...)’ est automatiquement scanné par
les outils en ligne de commande. Par exemple, lorsque vous lancez ‘guix
install emacs’, tous les modules ‘(gnu packages ...)’ sont scannés
jusqu’à en trouver un qui exporte un objet de paquet dont le nom est
‘emacs’. Cette capacité à chercher des paquets est implémentée dans le
module ‘(gnu packages)’.

   Les utilisateur·rice·s peuvent stocker les définitions de paquets
dans des modules ayant des noms différents—par exemple, ‘(my-packages
emacs)’(2). Il y a deux façons de rendre ces définitions de paquets
visibles pour les interfaces utilisateur·rice :

  1. En ajoutant le répertoire contenant vos modules de paquets au
     chemin de recherche avec le tag ‘-L’ de ‘guix package’ et des
     autres commandes (*note Options de construction communes::) ou en
     indiquant la variable d’environnement ‘GUIX_PACKAGE_PATH’ décrite
     plus bas.

  2. En définissant un “canal” et en configurant ‘guix pull’ pour qu’il
     l’utilise. Un canal est en substance un dépôt Git contenant des
     modules de paquets. *Note Canaux::, pour plus d’informations sur
     comment définir et utiliser des canaux.

   ‘GUIX_PACKAGE_PATH’ fonctionne comme les autres variables de chemins
de recherche :

 -- Variable d'environnement : GUIX_PACKAGE_PATH
     C’est une liste séparée par des deux-points de répertoires dans
     lesquels trouver des modules de paquets supplémentaires. Les
     répertoires listés dans cette variable sont prioritaires par
     rapport aux paquets de la distribution.

   La distribution est entièrement “bootstrappée” et “auto-contenue” :
chaque paquet est construit uniquement à partir d’autres paquets de la
distribution. La racine de ce graphe de dépendance est un petit ensemble
de “binaires de bootstrap” fournis par le module ‘(gnu packages
bootstrap)’. Pour plus d’informations sur le bootstrap, *note
Bootstrapping::.

   ---------- Footnotes ----------

   (1) Remarquez que les paquets sous l’espace de nom ‘(gnu packages
...)’ ne sont pas nécessairement des « paquets GNU ». Le nom de ce
module suit la convention de nommage usuelle de Guile : ‘gnu’ signifie
que ces modules sont distribués dans le système GNU, et ‘packages’
identifie les modules qui définissent les paquets.

   (2) Remarquez que le nom du fichier et le nom du module doivent
correspondre. Par exemple, le module ‘(my-packages emacs)’ doit être
stocké dans un fichier ‘my-packages/emacs.scm’ relatif au chemin de
chargement spécifié avec ‘--load-path’ ou ‘GUIX_PACKAGE_PATH’. *Note
(guile)Modules and the File System::, pour plus de détails.


File: guix.fr.info,  Node: Définition des paquets,  Next: Définition de variantes de paquets,  Prev: Modules de paquets,  Up: Interface de programmation

9.2 Définition des paquets
==========================

L’interface de haut-niveau pour les définitions de paquets est
implémentée dans les modules ‘(guix packages)’ et ‘(guix build-system)’.
Par exemple, la définition du paquet, ou la “recette”, du paquet GNU
Hello ressemble à cela :

     (define-module (gnu packages hello)
       #:use-module (guix packages)
       #:use-module (guix download)
       #:use-module (guix build-system gnu)
       #:use-module (guix licenses)
       #:use-module (gnu packages gawk))

     (define-public hello
       (package
         (name "hello")
         (version "2.10")
         (source (origin
                   (method url-fetch)
                   (uri (string-append "mirror://gnu/hello/hello-" version
                                       ".tar.gz"))
                   (sha256
                    (base32
                     "0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i"))))
         (build-system gnu-build-system)
         (arguments '(#:configure-flags '("--enable-silent-rules")))
         (inputs (list gawk))
         (synopsis "Hello, GNU world: An example GNU package")
         (description "Guess what GNU Hello prints!")
         (home-page "https://www.gnu.org/software/hello/")
         (license gpl3+)))

Sans être expert·e en Scheme, on peut comprendre la signification des
différents champs présents. Cette expression lie la variable ‘hello’ à
un objet ‘<package>’, qui est en substance un enregistrement (*note
Scheme records: (guile)SRFI-9.). On peut inspecter cet objet de paquet
avec les procédures qui se trouvent dans le module ‘(guix packages)’ ;
par exemple, ‘(package-name hello)’ renvoie — ô surprise ! — ‘"hello"’.

   Avec un peu de chance, vous pourrez importer tout ou partie de la
définition du paquet qui vous intéresse depuis un autre répertoire avec
la commande ‘guix import’ (*note Invoquer guix import::).

   Dans l’exemple précédent, ‘hello’ est défini dans un module à part,
‘(gnu packages hello)’. Techniquement, cela n’est pas strictement
nécessaire, mais c’est pratique : tous les paquets définis dans des
modules sous ‘(gnu packages ...)’ sont automatiquement connus des outils
en ligne de commande (*note Modules de paquets::).

   Il y a quelques points à remarquer dans la définition de paquet
précédente :

   • Le champ ‘source’ du paquet est un objet ‘<origin>’ (*note
     référence de origin::, pour la référence complète). Ici, on utilise
     la méthode ‘url-fetch’ de ‘(guix download)’, ce qui signifie que la
     source est un fichier à télécharger par FTP ou HTTP.

     Le préfixe ‘mirror://gnu’ demande à ‘url-fetch’ d’utiliser l’un des
     miroirs GNU définis dans ‘(guix download)’.

     Le champ ‘sha256’ spécifie le hash SHA256 attendu pour le fichier
     téléchargé. Il est requis et permet à Guix de vérifier l’intégrité
     du fichier. La forme ‘(base32 ...)’ introduit a représentation en
     base32 du hash. Vous pouvez obtenir cette information avec ‘guix
     download’ (*note Invoquer guix download::) et ‘guix hash’ (*note
     Invoquer guix hash::).

     Lorsque cela est requis, la forme ‘origin’ peut aussi avec un champ
     ‘patches’ qui liste les correctifs à appliquer et un champ
     ‘snippet’ qui donne une expression Scheme pour modifier le code
     source.

   • Le champ ‘build-system’ spécifie la procédure pour construire le
     paquet (*note Systèmes de construction::). Ici, ‘gnu-build-system’
     représente le système de construction GNU familier, où les paquets
     peuvent être configurés, construits et installés avec la séquence
     ‘./configure && make && make check && make install’ habituelle.

     Lorsque vous commencez à empaqueter des logiciels non triviaux,
     vous pouvez avoir besoin d’outils pour manipuler ces phases de
     construction, manipuler des fichiers, etc. *Note Utilitaires de
     construction::, pour en savoir plus.

   • Le champ ‘arguments’ spécifie des options pour le système de
     construction (*note Systèmes de construction::). Ici il est
     interprété par ‘gnu-build-system’ comme une demande de lancer
     ‘configure’ avec le tag ‘--enable-silent-rules’.

     Que sont ces apostrophes (‘'’) ? C’est de la syntaxe Scheme pour
     introduire une liste ; ‘'’ est synonyme de la fonction ‘quote’.
     Parfois vous verrez aussi ‘`’ (un accent grave synonyme de
     ‘quasiquote’) et ‘,’ (une virgule, synonyme de ‘unquote’). *Note
     quoting: (guile)Expression Syntax, pour des détails. Ice la valeur
     du champ ‘arguments’ est une liste d’arguments passés au système de
     construction plus tard, comme avec ‘apply’ (*note ‘apply’:
     (guile)Fly Evaluation.).

     La séquence dièse-deux-points (‘#:’) définie un “mot-clef” Scheme
     (*note (guile)Keywords::), et ‘#:configure-flags’ est un mot-clef
     utilisé pour passer un argument au système de construction (*note
     (guile)Coding With Keywords::).

   • Le champ ‘inputs’ spécifie les entrées du processus de construction
     — c.-à-d. les dépendances à la construction ou à l’exécution du
     paquet. Ici, nous ajoutons en entrée une référence à la variable
     ‘gawk’ ; ‘gawk’ est lui-même lié à un objet ‘<package>’.

     Remarquez que GCC, Coreutils, Bash et les autres outils essentiels
     n’ont pas besoin d’être spécifiés en tant qu’entrées ici. À la
     place, le ‘gnu-build-system’ est en mesure de s’assurer qu’ils sont
     présents (*note Systèmes de construction::).

     Cependant, toutes les autres dépendances doivent être spécifiées
     dans le champ ‘inputs’. Toute dépendance qui ne serait pas
     spécifiée ici sera simplement indisponible pour le processus de
     construction, ce qui peut mener à un échec de la construction.

   *Note référence de package::, pour une description complète des
champs possibles.

     Pour aller plus loin : Vous vous sentez intimidé·e par le langage
     Scheme ou vous êtes curieux·se de le découvrir ? Le livre de
     recettes a une petite section pour démarrer qui résume une partie
     de ce qui a été montré au-dessus et explique les bases. *Note
     (guix-cookbook.fr)Cours accéléré du langage Scheme::, pour plus
     d’information.

   Lorsqu’une définition de paquet est en place, le paquet peut enfin
être construit avec l’outil en ligne de commande ‘guix build’ (*note
Invoquer guix build::), pour résoudre les échecs de construction que
vous pourriez rencontrer (*note Débogage des échecs de construction::).
Vous pouvez aisément revenir à la définition du paquet avec la commande
‘guix edit’ (*note Invoquer guix edit::). *Note Consignes
d'empaquetage::, pour plus d’informations sur la manière de tester des
définitions de paquets et *note Invoquer guix lint::, pour des
informations sur la manière de vérifier que la définition respecte les
conventions de style. Enfin, *note Canaux:: pour des informations sur la
manière d’étendre la distribution en ajoutant vos propres définitions de
paquets dans un « canal ».

   Finalement, la mise à jour de la définition du paquet à une nouvelle
version amont peut en partie s’automatiser avec la commande ‘guix
refresh’ (*note Invoquer guix refresh::).

   Sous le capot, une dérivation qui correspond à un objet ‘<package>’
est d’abord calculé par la procédure ‘package-derivation’. Cette
dérivation est stockée dans un fichier ‘.drv’ dans ‘/gnu/store’. Les
actions de construction qu’il prescrit peuvent ensuite être réalisées
par la procédure ‘build-derivation’ (*note Le dépôt::).

 -- Procédure Scheme : package-derivation STORE PACKAGE [SYSTEM]
     Renvoie l’objet ‘<derivation>’ du PAQUET pour le SYSTÈME (*note
     Dérivations::).

     PAQUET doit être un objet ‘<package>’ valide et SYSTÈME une chaîne
     indiquant le type de système cible — p. ex. ‘"x86_64-linux"’ pour
     un système GNU x86_64 basé sur Linux. DÉPÔT doit être une connexion
     au démon, qui opère sur les dépôt (*note Le dépôt::).

De manière identique, il est possible de calculer une dérivation qui
effectue une compilation croisée d’un paquet pour un autre système :

 -- Procédure Scheme : package-cross-derivation STORE PAQUET CIBLE
          [SYSTÈME] renvoie l'objet ‘<derivation>’
     du PAQUET construit depuis SYSTÈME pour CIBLE.

     CIBLE doit être un triplet GNU valide indiquant le matériel cible
     et le système d’exploitation, comme ‘"aarch64-linux-gnu"’ (*note
     (autoconf)Specifying Target Triplets::).

   Une fois qu’on a une définition de paquet, on peut facilement définir
des _variantes_ du paquet. *Note Définition de variantes de paquets::,
pour plus d’informations.

* Menu:

* référence de package::   Le type de donnée des paquets.
* référence de origin::    Le type de données d’origine.


File: guix.fr.info,  Node: référence de package,  Next: référence de origin,  Up: Définition des paquets

9.2.1 Référence de ‘package’
----------------------------

Cette section résume toutes les options disponibles dans les
déclarations ‘package’ (*note Définition des paquets::).

 -- Type de données : package
     C’est le type de donnée représentant une recette de paquets.

     ‘name’
          Le nom du paquet, comme une chaîne de caractères.

     ‘version’
          La version du paquet, comme une chaine de caractères. *Note
          Numéros de version::, pour un guide.

     ‘source’
          Un objet qui indique comment le code source du paquet devrait
          être récupéré. La plupart du temps, c’est un objet ‘origin’
          qui indique un fichier récupéré depuis internet (*note
          référence de origin::). Il peut aussi s’agir de tout autre
          objet « simili-fichier » comme un ‘local-file’ qui indique un
          fichier du système de fichier local (*note ‘local-file’:
          G-Expressions.).

     ‘build-system’
          Le système de construction qui devrait être utilisé pour
          construire le paquet (*note Systèmes de construction::).

     ‘arguments’ (par défaut : ‘'()’)
          Les arguments à passer au système de construction (*note
          Systèmes de construction::). C’est une liste qui contient
          typiquement une séquence de paires de clefs-valeurs, comme
          dans cet exemple :

               (package
                 (name "exemple")
                 ;; plusieurs champs omis
                 (arguments
                   (list #:tests? #f                     ;passer les tests
                         #:make-flags #~'("VERBOSE=1")   ;passer les arguments à « make »
                         #:configure-flags #~'("--enable-frobbing"))))

          L’ensemble exact des mots-clés pris en charge dépend du
          système de construction (*note Systèmes de construction::),
          mais vous trouverez qu’ils prennent presque tous en compte
          ‘#:configure-flags’, ‘#:make-flags’, ‘#:tests?’ et ‘#:phases’.
          Le mot-clé ‘#:phases’ en particulier vous permet de modifier
          l’ensemble des phases de construction pour votre paquet (*note
          Phases de construction::).

     ‘inputs’ (par défaut : ‘'()’)
     ‘native-inputs’ (par défaut : ‘'()’)
     ‘propagated-inputs’ (par défaut : ‘'()’)
          Ces champs listent les dépendances du paquet. Chacune de ces
          listes est soit un paquet, une origine ou un autre « objet
          simili-fichier » (*note G-Expressions::) ; pour spécifier la
          sortie de cet objet simili-fichier à utiliser, passez une
          liste à deux éléments où le second élément est la sortie
          (*note Des paquets avec plusieurs résultats::, pour plus
          d’informations sur les sorties des paquets). Par exemple, la
          liste suivante spécifie trois entrées :

               (list libffi libunistring
                     `(,glib "bin"))      ;la sortie « bin » de GLib

          Dans l’exemple au-dessus, on utilise la sortie ‘"out"’ de
          ‘libffi’ et de ‘libunistring’.

               Notes de compatibilité : Jusqu’à la version 1.3.0, les
               listes d’entrées étaient des listes de tuples, où chaque
               tuple a une étiquette pour une entrée (une chaîne de
               caractères) comme premier élément, un paquet, une origine
               ou une dérivation comme deuxième élément et
               éventuellement le nom d’une sortie à utiliser qui est
               ‘"out"’ par défaut. Par exemple, la liste ci-dessous est
               équivalente à celle au-dessus, mais utilise “l’ancien
               style d’entrées” :

                    ;; Ancien style d'entrées (obsolète)
                    `(("libffi" ,libffi)
                      ("libunistring" ,libunistring)
                      ("glib:bin" ,glib "bin"))  ;la sortie "bin" de Glib

               Ce style est maintenant obsolète ; il est toujours pris
               en charge mais la prise en charge sera supprimée dans une
               future version. Vous ne devriez pas l’utiliser pour de
               nouvelles définitions de paquets. *Note Invoquer guix
               style::, pour apprendre à migrer vers le nouveau style.

          La distinction entre ‘native-inputs’ et ‘inputs’ est
          nécessaire lorsqu’on considère la compilation croisée. Lors
          d’une compilation croisée, les dépendances listées dans
          ‘inputs’ sont construites pour l’architecture _cible_ ;
          inversement, les dépendances listées dans ‘native-inputs’ sont
          construites pour l’architecture de la machine de
          _construction_.

          ‘native-inputs’ est typiquement utilisé pour lister les outils
          requis à la construction mais pas à l’exécution, comme
          Autoconf, Automake, pkg-config, Gettext ou Bison. ‘guix lint’
          peut rapporter des erreurs de ce type (*note Invoquer guix
          lint::).

          Enfin, ‘propagated-inputs’ est similaire à ‘inputs’, mais les
          paquets spécifiés seront automatiquement installés sur les
          profils (*note le rôle des profils dans Guix:
          Fonctionnalités.) à côté du paquet auquel ils appartiennent
          (*note ‘guix package’: package-cmd-propagated-inputs, pour
          savoir comment ‘guix package’ traite les entrées propagées).

          Par exemple, cela est nécessaire lors de l’empaquetage d’une
          bibliothèque C/C++ qui a besoin des en-têtes d’une autre
          bibliothèque pour se compiler, ou lorsqu’un fichier pkg-config
          fait référence à un autre via son champ ‘Requires’.

          Un autre exemple où le ‘propagated-inputs’ est utile, c’est
          pour les langues qui ne disposent pas de la possibilité
          d’enregistrer le chemin de recherche à l’exécution comme le
          ‘RUNPATH’ des fichiers ELF ; cela inclut Guile, Python, Perl,
          et plus encore. Lors de l’empaquetage de bibliothèques écrites
          dans ces langages, assurez-vous qu’elles peuvent trouver le
          code de bibliothèque dont elles dépendent au moment de
          l’exécution en listant les dépendances d’exécution dans
          ‘propagated-inputs’ plutôt que ‘inputs’.

     ‘outputs’ (par défaut : ‘'("out")’)
          La liste des noms de sorties du paquet. *Note Des paquets avec
          plusieurs résultats::, pour des exemples typiques
          d’utilisation de sorties supplémentaires.

     ‘native-search-paths’ (par défaut : ‘'()’)
     ‘search-paths’ (par défaut : ‘'()’)
          Une liste d’objets ‘search-path-specification’ décrivant les
          variables d’environnement de recherche de chemins que ce
          paquet prend en compte. *Note Chemins de recherche::, pour
          plus de détails sur les spécifications de chemins de
          recherche.

          Comme pour les entrées, la distinction entre
          ‘native-search-paths’ et ‘search-paths’ n’est importante que
          pour la compilation croisée. Lors d’une compilation croisée,
          ‘native-search-paths’ ne s’applique qu’aux entrées natives
          alors que ‘search-paths’ ne s’applique qu’aux entrées hôtes.

          Les paquets comme les compilateurs croisées font attention aux
          entrées de la cible — par exemple notre compilateur GCC croisé
          (modifié) a ‘CROSS_C_INCLUDE_PATH’ dans ‘search-paths’, ce qui
          lui permet de trouver les fichiers ‘.h’ du système cible et
          _pas_ ceux des entrées natives. Pour la plupart des paquets
          cependant, seul ‘native-search-paths’ a du sens.

     ‘replacement’ (par défaut : ‘#f’)
          Ce champ doit être soit ‘#f’ soit un objet de paquet qui sera
          utilisé comme “remplaçant” de ce paquet. *Note grafts: Mises à
          jour de sécurité, pour plus de détails.

     ‘synopsis’
          Une description sur une ligne du paquet.

     ‘description’
          Une description plus détaillée du paquet, en tant que chaine
          au format Texinfo.

     ‘license’
          La licence du paquet ; une valeur tirée de ‘(guix licenses)’
          ou une liste de ces valeurs.

     ‘home-page’
          L’URL de la page d’accueil du paquet, en tant que chaîne de
          caractères.

     ‘supported-systems’ (par défaut : ‘%supported-systems’)
          La liste des systèmes supportés par le paquet, comme des
          chaînes de caractères de la forme ‘architecture-noyau’, par
          exemple ‘"x86_64-linux"’.

     ‘location’ (par défaut : emplacement de la source de la forme ‘package’)
          L’emplacement de la source du paquet. C’est utile de le
          remplacer lorsqu’on hérite d’un autre paquet, auquel cas ce
          champ n’est pas automatiquement corrigé.

 -- Syntaxe Scheme : this-package
     Lorsque vous l’utilisez dans la _portée lexicale_ du champ d’une
     définition de paquet, cet identifiant est résolu comme étant le
     paquet définit.

     L’exemple ci-dessous montre l’ajout d’un paquet comme entrée native
     de lui-même pour la compilation croisée :

          (package
            (name "guile")
            ;; ...

            ;; Lors de la compilation croisée, Guile par exemple dépend
            ;; d'une version native de lui-même. On l'ajoute ici.
            (native-inputs (if (%current-target-system)
                               (list this-package)
                               '())))

     C’est une erreur que de se référer à ‘this-package’ en dehors de la
     définition d’un paquet.

   Les procédures auxiliaires suivantes vous aideront à utiliser les
entrées des paquets.

 -- Procédure Scheme : lookup-package-input PACKAGE NAME
 -- Procédure Scheme : lookup-package-native-input PACKAGE NAME
 -- Procédure Scheme : lookup-package-propagated-input PACKAGE NAME
 -- Procédure Scheme : lookup-package-direct-input PACKAGE NAME
     Cherche NAME dans les entrées de PACKAGE (ou les entrées natives,
     propagées ou directes). Renvoie l’entrée si elle la trouve, et ‘#f’
     sinon.

     NAME est le nom d’un paquet de dépendance. Voici comment vous
     pouvez l’utiliser :

          (use-modules (guix packages) (gnu packages base))

          (lookup-package-direct-input coreutils "gmp")
          ⇒ #<package gmp@6.2.1 ...>

     Dans cet exemple, on obtient le paquet ‘gmp’ qui fait partie des
     entrées directes de ‘coreutils’.

   Parfois vous voudrez obtenir la liste des entrées requises pour
_développer_ un paquet — toutes les entrées visibles quand le paquet est
compilé. C’est ce que la procédure ‘package-development-inputs’ renvoie.

 -- Procédure Scheme : package-development-inputs PACKAGE [SYSTEM]
          [#:target #f]
     Renvoie la liste des entrées requises par PACKAGE pour le
     développement sur SYSTEM. Lorsque TARGET est vrai, les entrées
     renvoyées sont celles requises pour la compilation croisée de
     PACKAGE de SYSTEM vers TARGET, où TARGET est un triplet comme
     ‘"aarch64-linux-gnu"’.

     Remarquez que le résultat inclus à la fois les entrées explicites
     et implicites — les entrées ajoutées automatiquement par le système
     de construction (*note Systèmes de construction::). Prenons le
     paquet ‘hello’ pour illustrer :

          (use-modules (gnu packages base) (guix packages))

          hello
          ⇒ #<package hello@2.10 gnu/packages/base.scm:79 7f585d4f6790>

          (package-direct-inputs hello)
          ⇒ ()

          (package-development-inputs hello)
          ⇒ (("source" ...) ("tar" #<package tar@1.32 ...>) ...)

     Dans cet exemple, ‘package-direct-inputs’ renvoie la liste vide,
     parce que ‘hello’ n’a pas de dépendance explicite. À l’inverse,
     ‘package-development-inputs’ inclut les entrées implicites ajoutées
     par ‘gnu-build-system’ qui sont requises pour construire ‘hello’ :
     tar, gzip, GCC, libc, Bash et d’autres. Pour les visualiser, ‘guix
     graph hello’ montrerait les entrées explicites, alors que ‘guix
     graph -t bag hello’ inclurait les entrées implicites (*note
     Invoquer guix graph::).

   Comme les paquets sont des objets Scheme réguliers qui capturent un
graphe de dépendance complet et les procédures de construction
associées, il est souvent utile d’écrire des procédures qui prennent un
paquet et renvoient une version modifiée de celui-ci en fonction de
certains paramètres. En voici quelques exemples.

 -- Procédure Scheme : package-with-c-toolchain PACKAGE TOOLCHAIN
     Renvoie une variante de PACKAGE qui utilise TOOLCHAIN au lieu de la
     chaîne d’outils GNU C/C++ par défaut. TOOLCHAIN doit être une liste
     d’entrées (tuples label/package) fournissant une fonctionnalité
     équivalente, comme le paquet ‘gcc-toolchain’.

     L’exemple ci-dessous renvoie une variante du paquet ‘hello’
     construit avec GCC 10.x et le reste de la chaîne d’outils GNU
     (Binutils et la bibliothèque C GNU) au lieu de la chaîne d’outils
     par défaut :

          (let ((toolchain (specification->package "gcc-toolchain@10")))
            (package-with-c-toolchain hello `(("toolchain" ,toolchain))))

     La chaîne d’outils de construction fait partie des “entrées
     implicites” des paquets— elle n’est généralement pas listée comme
     faisant partie des différents champs "entrées" et est à la place
     récupérée par le système de construction. Par conséquent, cette
     procédure fonctionne en modifiant le système de compilation de
     PAQUET de sorte qu’il utilise TOOLCHAIN au lieu des valeurs par
     défaut. *note Systèmes de construction::, pour en savoir plus sur
     les systèmes de construction.


File: guix.fr.info,  Node: référence de origin,  Prev: référence de package,  Up: Définition des paquets

9.2.2 Référence de ‘origin’
---------------------------

Cette section documente “origins”. Une déclaration ‘origin’ spécifie les
données qui doivent être "produites" – téléchargées, généralement – et
dont le contenu est connu à l’avance. Les origines sont principalement
utilisées pour représenter le code source des paquets (*note Définition
des paquets::). Pour cette raison, le formulaire ‘origin’ permet de
déclarer des correctifs à appliquer au code source original ainsi que
des bribes de code pour le modifier.

 -- Type de données : origin
     C’est le type de donnée qui représente l’origine d’un code source.

     ‘uri’
          Un objet contenant l’URI de la source. Le type d’objet dépend
          de la ‘method’ (voir plus bas). Par exemple, avec la méthode
          URL-FETCH de ‘(guix download)’, les valeurs valide d’‘uri’
          sont : une URL représentée par une chaîne de caractères, ou
          une liste de chaînes de caractères.

     ‘method’
          Une procédure monadique qui gère l’URI donné. La procédure
          doit accepter au moins trois arguments : la valeur du champ
          ‘uri’ et l’algorithme de hachage et la valeur de hachage
          spécifiée par le champ ‘hash’. Elle doit renvoyer un élément
          du dépôt ou une dérivation dans la monade du dépôt (*note La
          monade du dépôt::) ; la plupart des méthodes renvoient une
          dérivation à sortie fixe (*note Dérivations::).

          Les méthodes couramment utilisées comprennent ‘url-fetch’, qui
          récupère les données à partir d’une URL, et ‘git-fetch’, qui
          récupère les données à partir d’un dépôt Git (voir
          ci-dessous).

     ‘sha256’
          Un bytevector contenant le hachage SHA-256 de la source. Cela
          équivaut à fournir un ‘content-hash’ Objet SHA256 dans le
          champ ‘hash’ décrit ci-dessous.

     ‘hash’
          L’objet ‘content-hash’ de la source–voir ci-dessous pour
          savoir comment utiliser ‘content-hash’.

          Vous pouvez obtenir cette information avec ‘guix download’
          (*note Invoquer guix download::) ou ‘guix hash’ (*note
          Invoquer guix hash::).

     ‘file-name’ (par défaut : ‘#f’)
          Le nom de fichier à utiliser pour sauvegarder le fichier.
          Lorsqu’elle est à ‘#f’, une valeur par défaut raisonnable est
          utilisée dans la plupart des cas. Dans le cas où la source est
          récupérée depuis une URL, le nom de fichier est celui de
          l’URL. Pour les sources récupérées depuis un outil de contrôle
          de version, il est recommandé de fournir un nom de fichier
          explicitement parce que le nom par défaut n’est pas très
          descriptif.

     ‘patches’ (par défaut : ‘'()’)
          Une liste de noms de fichiers, d’origines ou d’objets
          simili-fichiers (*note file-like objects: G-Expressions.) qui
          pointent vers des correctifs à appliquer sur la source.

          Cette liste de correctifs doit être inconditionnelle. En
          particulier, elle ne peut pas dépendre des valeurs de
          ‘%current-system’ ou ‘%current-target-system’.

     ‘snippet’ (par défaut : ‘#f’)
          Une G-expression (*note G-Expressions::) ou une S-expression
          qui sera lancée dans le répertoire des sources. C’est une
          manière pratique de modifier la source, parfois plus qu’un
          correctif.

     ‘patch-flags’ (par défaut : ‘'("-p1")’)
          Une liste de drapeaux à passer à la commande ‘patch’.

     ‘patch-inputs’ (par défaut : ‘#f’)
          Paquets d’entrées ou dérivations pour le processus de
          correction. Lorsqu’elle est à ‘#f’, l’ensemble d’entrées
          habituellement nécessaire pour appliquer des correctifs est
          fournit, comme GNU Patch.

     ‘modules’ (par défaut : ‘'()’)
          Une liste de modules Guile qui devraient être chargés pendant
          le processus de correction et pendant que le lancement du code
          du champ ‘snippet’.

     ‘patch-guile’ (par défaut : ‘#f’)
          Le paquet Guile à utiliser dans le processus de correction.
          Lorsqu’elle est à ‘#f’, une valeur par défaut raisonnable est
          utilisée.

 -- Data Type : content-hash VALUE [ALGORITHM]
     Construire un objet de hash de contenu pour l’ALGORITHME donné, et
     avec VALEUR comme valeur de hachage. Lorsque ALGORITHME est omis,
     on suppose qu’il s’agit de ‘sha256’.

     VALUE peut être une chaîne littérale, auquel cas elle est décodée
     en base32, ou il peut s’agir d’un bytevecteur.

     Les options suivantes sont équivalentes :

          (content-hash "05zxkyz9bv3j9h0xyid1rhvh3klhsmrpkf3bcs6frvlgyr2gwilj")
          (content-hash "05zxkyz9bv3j9h0xyid1rhvh3klhsmrpkf3bcs6frvlgyr2gwilj"
                        sha256)
          (content-hash (base32
                         "05zxkyz9bv3j9h0xyid1rhvh3klhsmrpkf3bcs6frvlgyr2gwilj"))
          (content-hash (base64 "kkb+RPaP7uyMZmu4eXPVkM4BN8yhRd8BTHLslb6f/Rc=")
                        sha256)

     Techniquement, le ‘content-hash’ est actuellement mis en œuvre sous
     forme de macro. Il effectue des contrôles de bon sens au moment de
     l’expansion de la macro, lorsque cela est possible, en s’assurant
     par exemple que VALEUR a la bonne taille pour ALGORITHME.

   Comme nous l’avons vu plus haut, la manière dont les données
auxquelles une origine se réfère exactement sont récupérées est
déterminée par son champ ‘method’. Le module ‘(guix download)’ fournit
la méthode la plus courante, ‘url-fetch’, décrite ci-dessous.

 -- Procédure Scheme : url-fetch URL HASH-ALGO HASH [name] [#:executable
          ? #f] Renvoie une dérivation à sortie fixe qui récupère
     les données de URL (une chaîne de caractères, ou une liste de
     chaînes de caractères désignant des URLs alternatives), qui est
     censée avoir un hash HASH de type HASH-ALGO (un symbole). Par
     défaut, le nom du fichier est le nom de base de l’URL ; en option,
     NOM peut spécifier un nom de fichier différent. Lorsque EXECUTABLE?
     est vrai, rendez le fichier téléchargé exécutable.

     Lorsque l’une des URL commence par ‘mirror://’, sa partie hôte est
     alors interprétée comme le nom d’un schéma de miroir, tiré de
     ‘%mirror-file’.

     Alternativement, lorsque l’URL commence par ‘file://’, renvoie le
     nom du fichier correspondant dans le dépôt.

   De même, le module ‘(guix git-download)’ définit la méthode d’origine
‘git-download’, qui récupère les données d’un dépôt de contrôle de
version Git, et le type de données ‘git-reference’ pour décrire le dépôt
et la révision à récupérer.

 -- Procédure Scheme : git-fetch REF HASH-ALGO HASH
     Renvoie une dérivation à sortie fixe qui va chercher REF, un objet
     ‘<git-reference>’. La sortie est censée avoir un hash récursif HASH
     de type HASH-ALGO (un symbole). Utilisez NAME comme nom de fichier,
     ou un nom générique si ‘#f’.

 -- Type de données : git-reference
     Ce type de données représente une référence Git pour le ‘git-fetch’
     à récupérer.

     ‘url’
          L’URL du dépôt Git à cloner.

     ‘commit’
          Cette chaîne indique soit le commit à récupérer (une chaîne
          hexadécimale), soit le tag à récupérer. Vous pouvez aussi
          utiliser une chaîne de commit « courte » ou un identifiant
          dans le style de ‘git describe’ comme ‘v1.0.1-10-g58d7909c97’.

     ‘recursive?’ (par défaut : ‘#f’)
          Ce booléen indique s’il faut aller chercher récursivement les
          sous-modules de Git.

     L’exemple ci-dessous indique la balise ‘v2.10’ du dépôt GNU Hello :

          (git-reference
            (url "https://git.savannah.gnu.org/git/hello.git")
            (commit "v2.10"))

     C’est équivalent à la référence ci-dessous, qui nomme explicitement
     le commit :

          (git-reference
            (url "https://git.savannah.gnu.org/git/hello.git")
            (commit "dc7dc56a00e48fe6f231a58f6537139fe2908fb9"))

   Pour les dépôts Mercurial, le module ‘(guix hg-download)’ définit la
méthode d’origine ‘hg-download’ et le type de données ‘hg-reference’
pour la prise en charge du système de contrôle de version Mercurial.

 -- Procédure Scheme : hg-fetch REF HASH-ALGO HASH [name]
     Renvoie une dérivation à sortie fixe qui va chercher REF, un objet
     ‘<hg-reference>’. La sortie est censée avoir un hash récursif HASH
     de type HASH-ALGO (un symbole). Utilisez NAME comme nom de fichier,
     ou un nom générique si ‘#false’.


File: guix.fr.info,  Node: Définition de variantes de paquets,  Next: Écrire un manifeste,  Prev: Définition des paquets,  Up: Interface de programmation

9.3 Définition de variantes de paquets
======================================

L’une des choses intéressantes avec Guix est qu’à partir d’une
définition, on peut facilement _dériver_ des variantes du paquet — pour
une version en amont différente, avec des dépendances différentes, des
options de compilation différentes, etc. Certains de ces paquets
personnalisés peuvent être définis directement par la ligne de commande
(*note Options de transformation de paquets::). Cette section décrit
comment définir des variantes de paquets avec du code. Cela est utile
dans les « manifestes » (*note Écrire un manifeste::) et dans votre
propre collection de paquets (*note Écrire de nouveaux de canaux::),
entre autres choses !

   Comme nous en avons parlé plus tôt, les paquets sont des objets de
première classe dans le langage Scheme. Le module ‘(guix packages)’
fournit la construction ‘package’ pour définir de nouveaux objets de
paquets (*note référence de package::). La manière la plus simple de
définir la variante d’un paquet est d’utiliser le mot-clé ‘inherit’ avec
‘package’. Cela vous permet d’hériter la définition d’un paquet tout en
redéfinissant les champs que vous voulez.

   Par exemple, étant donné la variable ‘hello’, qui contient la
définition d’une version récente de GNU Hello, voici comment définir une
variante pour la version 2.2 (publiée en 2006, c’est vintage !) :

     (use-modules (gnu packages base))    ;pour 'hello'

     (define hello-2.2
       (package
         (inherit hello)
         (version "2.2")
         (source (origin
                   (method url-fetch)
                   (uri (string-append "mirror://gnu/hello/hello-" version
                                       ".tar.gz"))
                   (sha256
                    (base32
                     "0lappv4slgb5spyqbh6yl5r013zv72yqg2pcl30mginf3wdqd8k9"))))))

   L’exemple ci-dessus correspond à ce que l’option de transformation
des paquets ‘--with-source’ fait. En substance, ‘hello-2.2’ préserve
tous les champs de ‘hello’, sauf ‘version’ et ‘source’, qu’il remplace.
Remarquez que la variable ‘hello’ originale est toujours là, dans le
module ‘(gnu packages base)’, et n’est pas modifiée. Lorsque vous
définissez un paquet personnalisé comme ceci, vous _ajoutez_ en fait une
nouvelle définition de paquet ; la version originale est toujours
disponible.

   Vous pouvez aussi bien définir des variantes avec un ensemble de
dépendances différent du paquet d’origine. Par exemple, le paquet ‘gdb’
par défaut dépend de ‘guile’, mais comme c’est une dépendance
facultative, vous pouvez définir une variante qu supprime cette
dépendance de cette manière :

     (use-modules (gnu packages gdb))   ; pour « gdb »

     (define gdb-sans-guile
       (package
         (inherit gdb)
         (inputs (modify-inputs (package-inputs gdb)
                   (delete "guile")))))

   La forme ‘modify-inputs’ ci-dessus supprime le paquet ‘"guile"’ du
champ ‘inputs’ de ‘gdb’. La macro ‘modify-inputs’ est une macro
auxiliaire qui peut être utile si vous voulez supprimer, ajouter et
remplacer des paquets en entrée.

 -- Syntaxe Scheme : modify-inputs INPUTS CLAUSES
     Modifie les entrées de paquet spécifiées, telles que renvoyées par
     ‘package-inputs’ & co., suivant les clauses données. Chaque clause
     doit avoir l’une des formes suivantes :

     ‘(delete NOM...)’
          Supprime des entrées les paquets avec les NOMs donnés (chaines
          de caractères).

     ‘(prepend PAQUET...)’
          Ajoute les PAQUETS au début de la liste des entrées.

     ‘(append PAQUET...)’
          Ajoute les PAQUETs à la fin de la liste des entrées.

     L’exemple suivant supprime les entrées GMP et ACL de Coreutils et
     ajoute libcap au début de la liste des entrées :

          (modify-inputs (package-inputs coreutils)
            (delete "gmp" "acl")
            (prepend libcap))

     L’exemple suivant remplace le paquet ‘guile’ des entrées de
     ‘guile-redis’ avec ‘guile-2.2’ :

          (modify-inputs (package-inputs guile-redis)
            (replace "guile" guile-2.2))

     Le dernier type de clause est ‘append’, pour ajouter des entrées à
     la fin de la liste.

   Dans certains cas, vous pouvez trouver cela utile d’écrire des
fonctions (« procédures », pour Scheme) qui renvoie un paquet en
fonction de certains paramètres. Par exemple, considérez la bibliothèque
‘luasocket’ pour le langage de programmation lua. Nous voulons créer des
paquets ‘luasocket’ pour les versions majeures de Lua. Une manière de
faire est de définir une procédure qui prend un paquet Lua et renvoie un
paquet ‘luasocket’ qui en dépend :

     (define (make-lua-socket name lua)
       ;; Renvoie un paquet luasocket construit avec LUA.
       (package
         (name name)
         (version "3.0")
         ;; plusieurs champs ont été omis
         (inputs (list lua))
         (synopsis "Socket library for Lua")))

     (define-public lua5.1-socket
       (make-lua-socket "lua5.1-socket" lua-5.1))

     (define-public lua5.2-socket
       (make-lua-socket "lua5.2-socket" lua-5.2))

   ici nous avons défini les paquets ‘lua5.1-socket’ et ‘lua5.2-socket’
en appelant ‘make-lua-socket’ avec différents arguments. *Note
(guile)Procedures::, pour plus d’informations sur les procédures. Avoir
des définitions publiques au premier niveau pour ces deux paquets
signifie qu’ils sont disponibles depuis la ligne de commande (*note
Modules de paquets::).

   Ce sont des variantes simples de paquets. Par simplicité, le module
‘(guix transformations)’ fournit une interface de haut niveau qui
correspond directement aux options de transformations de paquets plus
sophistiquées (*note Options de transformation de paquets::) :

 -- Procédure Scheme : options->transformation OPTS
     Renvoie une procédure qui, lorsqu’on lui passe un objet à
     construire (un paquet, une dérivation, etc), applique les
     transformations spécifiées par OPTS et renvoie les objets qui en
     résultent. OPTS doit être une liste de pairs de symboles et de
     chaine comme dans :

          ((with-branch . "guile-gcrypt=master")
           (without-tests . "libgcrypt"))

     Chaque nom de symbole nomme une transformation et la chaine
     correspondante est un argument pour cette transformation.

   Par exemple, un manifeste équivalent à cette commande :

     guix build guix \
       --with-branch=guile-gcrypt=master \
       --with-debug-info=zlib

... ressemblerait à ceci :

     (use-modules (guix transformations))

     (define transform
       ;; La procédure de transformation des paquets.
       (options->transformation
        '((with-branch . "guile-gcrypt=master")
          (with-debug-info . "zlib"))))

     (packages->manifest
      (list (transform (specification->package "guix"))))

   La procédure ‘options->transformation’ est pratique, mais elle n’est
peut-être pas aussi flexible que vous pourriez le souhaiter. Comment
est-elle implémentée ? Le lecteur attentif aura sans doute remarqué que
la plupart des options de transformation des paquets va plus loin que
les changements superficiels montrés dans les premiers exemples de cette
sections : ils font de la “réécriture d’entrées”, où le graphe de
dépendance d’un paquet est réécrit en remplaçant des entrées spécifiques
par d’autres.

   La procédure ‘package-input-rewriting’ de ‘(guix packages)’
implémente la réécriture du graphe de dépendance, pour remplacer des
paquets dans le graphe.

 -- Procédure Scheme : package-input-rewriting REPLACEMENTS
          [NOM-RÉÉCRIT] [#:deep ? #t] Renvoie une procédure qui,
          lorsqu'elle est
     passée à un paquet, remplace ses dépendances directes et
     indirectes, y compris les entrées implicites lorsque DEEP? est
     vrai, selon REPLACEMENTS. REPLACEMENTS est une liste de paires de
     paquets ; le premier élément de chaque paire est le paquet à
     remplacer, et le second est le remplacement.

     De manière facultative, NOM-RÉÉCRIT est une procédure à un argument
     qui prend le nom d’un paquet et renvoie son nouveau nom après
     l’avoir réécrit.

Regardez cet exemple :

     (define libressl-instead-of-openssl
       ;; Cette procédure remplace OPENSSL par LIBRESSL,
       ;; récursivement.
       (package-input-rewriting `((,openssl . ,libressl))))

     (define git-with-libressl
       (libressl-instead-of-openssl git))

Ici nous définissons d’abord une procédure de réécriture qui remplace
OPENSSL par LIBRESSL. Ensuite nous l’utilisons pour définir une
“variante” du paquet GIT qui utilise LIBRESSL plutôt que OPENSSL. cela
est exactement ce que l’option en ligne de commande ‘--with-input’ fait
(*note ‘--with-input’: Options de transformation de paquets.).

   La variante suivante de ‘package-input-rewriting’ peut repérer les
paquets à remplacer par nom à la place de leur identité.

 -- Procédure Scheme : package-input-rewriting/spec
          REMPLACEMENTS[#:deep? #t]
     Renvoie une procédure qui, étant donné un paquet, applique les
     REMPLACEMENTS donnés à tout le graphe du paquet, y compris les
     entrées implicites, à moins que DEEP? ne soit faux. REPLACEMENTS
     est une liste de paires spécifications/procédures ; chaque
     spécification est une spécification de paquet telle que ‘"gcc"’ ou
     ‘"guile@2"’, et chaque procédure prend un paquet correspondant et
     renvoie un remplacement pour ce paquet.

   L’exemple ci-dessus pourrait être réécrit de cette manière :

     (define libressl-instead-of-openssl
       ;; Remplace tous les paquets nommés « openssl » par LibreSSL.
       (package-input-rewriting/spec `(("openssl" . ,(const libressl)))))

   Le différence clef est que, cette fois-ci, les paquets correspondent
à la spécification et non à l’identité. En d’autres termes, tout paquet
dans le graphe qui est appelé ‘openssl’ sera remplacé.

   Une procédure plus générique pour réécrire un graphe de dépendance
d’un paquet est ‘package-mapping’ : elle supporte n’importe quel
changement dans les nœuds du graphe.

 -- Procédure Scheme : package-mapping PROC [CUT?] [#:deep? #f]
     Renvoie une procédure qui, pour un paquet donné, applique PROC à
     tous les paquets dont il dépend et renvoie le paquet résultant. La
     procédure arrête la récursion lorsque CUT? renvoie true pour un
     paquet donné. Lorsque DEEP? est vrai, PROC est également appliqué
     aux entrées implicites.


File: guix.fr.info,  Node: Écrire un manifeste,  Next: Systèmes de construction,  Prev: Définition de variantes de paquets,  Up: Interface de programmation

9.4 Écrire un manifeste
=======================

Les commandes ‘guix’ vous permettent de spécifier des listes de paquets
sur la ligne de commande. C’est pratique, mais en même temps que la
ligne de commande devient plus longue et moins triviales, il devient
plus pratique d’avoir la liste des paquets dans ce que nous appelons un
“manifeste”. Un manifeste est une sorte de « nomenclature » qui définie
un ensemble de paquets. Habituellement, vous trouverez un bout de code
qui construit le manifeste, vous l’enregistrerez dans un fichier, disons
‘manifest.scm’ puis passerez ce fichier à l’option ‘−m’ (ou
‘--manifest’) que de nombreuses commandes ‘guix’ prennent en charge. Par
exemple, voici ce à quoi un manifeste pour un ensemble de paquets simple
peut ressembler :

     ;; Manifeste pour trois paquets.
     (specifications->manifest '("gcc-toolchain" "make" "git"))

   Une fois que vous avez le manifeste, vous pouvez le passer, par
exemple, à ‘guix package’ pour installer uniquement ces trois paquets
dans votre profil (*note l’option ‘-m’ de ‘guix package’:
profile-manifest.) :

     guix package -m manifest.scm

... ou vous pouvez le passer à ‘guix shell’ (*note l’option ‘-m’ de
‘guix shell’: shell-manifest.) pour créer un environnement temporaire :

     guix shell -m manifest.scm

... ou vous pouvez le passer à ‘guix pack’ de la même manière (*note
l’option ‘-m’ de ‘guix pack’: pack-manifest.). Vous pouvez garder un
manifeste sous contrôle de version, le partager avec d’autres personnes
pour qu’elles puissent facilement l’installer, etc.

   Mais comment écrire votre premier manifeste ? Pour commencer, vous
voudrez peut-être écrire un manifeste qui reflète ce que vous avez déjà
dans un profil. Plutôt que de commencer par une feuille blanche, ‘guix
package’ peut générer un manifeste pour vous (*note ‘guix package
--export-manifest’: export-manifest.) :

     # Écrit dans « manifest.scm » un manifeste correspondant au profil
     # par défaut, ~/.guix-profile.
     guix package --export-manifest > manifest.scm

   Ou vous voudrez peut-être « traduire » des arguments de la ligne de
commande en un manifeste. Dans ce cas, ‘guix shell’ peut aider (*note
‘guix shell --export-manifest’: shell-export-manifest.) :

     # Écrit un manifeste pour les paquets spécifiés sur la ligne de commande.
     guix shell --export-manifest gcc-toolchain make git > manifest.scm

   Dans les deux cas, l’option ‘--export-manifest’ essaye de générer un
manifeste fidèle ; en particulier, il prend en compte les options de
transformation des paquets (*note Options de transformation de
paquets::).

     Remarque : Les manifestes sont _symboliques_ : ils font référence
     aux paquets des canaux _actuellement utilisés_ (*note Canaux::).
     Dans l’exemple ci-dessus, ‘gcc-toolchain’ peut se référer à la
     version 11 aujourd’hui, mais pourra se référer à la version 13 dans
     deux ans.

     Si vous voulez « épingler » votre environnement logiciel à une
     version et une variante spécifique d’un paquet, vous devez donner
     des informations supplémentaires : la liste des révisions des
     canaux utilisés, renvoyée par ‘guix describe’. *Note Répliquer
     Guix::, pour plus de détails.

   Une fois que vous avez votre premier manifeste, vous voudrez
peut-être le personnaliser. Comme votre manifeste est du code, vous avez
maintenant accès à toutes les interfaces de programmation de Guix !

   Supposons que vous souhaitiez avoir un manifeste pour déployer une
variante personnalisée de GDB, le débogueur de GNU, qui ne dépend pas de
Guile, avec un autre paquet. En complétant l’exemple vu dans la section
précédente (*note Définition de variantes de paquets::), vous pouvez
écrire un manifeste de ce type :

     (use-modules (guix packages)
                  (gnu packages gdb)               ;pour « gdb »
                  (gnu packages version-control))  ;pour « git »

     ;; Définie une variante de GDB qui ne dépend pas de Guile.
     (define gdb-sans-guile
       (package
         (inherit gdb)
         (inputs (modify-inputs (package-inputs gdb)
                   (delete "guile")))))

     ;; Renvoie un manifeste contenant ce paquet plus Git.
     (packages->manifest (list gdb-sans-guile git))

   Remarquez que dans cet exemple, le manifeste se réfère directement
aux variables ‘gdb’ et ‘git’, qui sont liées à un objet ‘package’ (*note
référence de package::), au lieu d’appeler ‘specifications->manifest’
pour rechercher les paquets par leur nom comme nous l’avons fait
précédemment. La forme ‘use-modules’ au début nous permet d’accéder à
l’interface centrale des paquets (*note Définition des paquets::) et aux
modules qui définissent ‘gdb’ et ‘git’ (*note Modules de paquets::).
Nous combinons tout cela harmonieusement — les possibilités sont
infinies, débridez votre créativité !

   Le type de données pour les manifestes et les procédures auxiliaires
sont définis dans le module ‘(guix profiles)’, qui est automatiquement
disponible pour le code passé à ‘-m’. Voici la documentation de
référence.

 -- Type de données : manifest
     Type de données représentant un manifeste.

     Il a actuellement un seul champ :

     ‘entries’
          Ce doit être une liste d’enregistrements ‘manifest-entry’ —
          voir plus bas.

 -- Type de données : manifest-entry
     Type de donnée représentant une entrée d’un manifeste. Une entrée
     de manifeste contient les métadonnées nécessaires : un nom et une
     chaîne de version, l’objet (généralement un paquet) pour cette
     entrée, la sortie souhaitée (*note Des paquets avec plusieurs
     résultats::) et un certain nombre d’autres informations
     facultatives décrites plus bas.

     La plupart du temps, vous n’aurez pas à construire une entrée de
     manifeste directement ; au lieu de cela, vous passerez un paquet à
     ‘package->manifest-entry’, décrit plus bas. Dans certains cas rares
     cependant, vous pourriez être amené à créer des entrées de
     manifeste pour des objets qui ne sont pas des paquets, comme dans
     cet exemple :

          ;; Construit manuellement une entrée de manifeste pour un objet qui n'est pas un paquet.
          (let ((hello (program-file "hello" #~(display "Hi!"))))
            (manifest-entry
              (name "toto")
              (version "42")
              (item
               (computed-file "hello-directory"
                               #~(let ((bin (string-append #$output "/bin")))
                                   (mkdir #$output) (mkdir bin)
                                    (symlink #$hello
                                             (string-append bin "/hello")))))))

     Les champs disponibles sont les suivants :

     ‘name’
     ‘version’
          Nom et chaine de version pour cette entrée.

     ‘item’
          Un paquet ou n’importe quel objet simili-fichier (*note objets
          de type fichier: G-Expressions.).

     ‘output’ (par défaut : ‘"out"’)
          Sortie de ‘item’ à utiliser, dans le cas où ‘item’ a plusieurs
          sorties (*note Des paquets avec plusieurs résultats::).

     ‘dependencies’ (par défaut : ‘'()’)
          Liste des entrées de manifeste desquelles dépend cette entrée.
          Lorsqu’un profil est construit, les dépendances sont ajoutées
          au profil.

          Généralement, les entrées propagées d’un paquet (*note
          ‘propagated-inputs’: référence de package.) ont une entrée de
          manifeste correspondante parmi les dépendances de l’entrée du
          paquet.

     ‘search-paths’ (par défaut : ‘'()’)
          La liste des spécifications de chemins de recherche que cette
          entrée prend en compte (*note Chemins de recherche::).

     ‘properties’ (par défaut : ‘'()’)
          Une liste de pairs de symboles et de valeurs. Lorsqu’un profil
          est construit, ces propriétés sont sérialisées.

          Cela peut être utilisé pour intégrer des métadonnées
          supplémentaires — p. ex. les transformations appliquées à un
          paquet (*note Options de transformation de paquets::).

     ‘parent’ (par défaut : ‘(delay #f)’)
          Une promesse pointant vers l’entrée de manifeste « parente ».

          cela est utilisé comme une indication pour fournir du contexte
          si une erreur liée à une entrée de manifeste provenant du
          champ ‘dependencies’ doit être rapportée.

 -- Procédure Scheme : concatenate-manifests LST
     Concatène les manifestes listés dans LST et renvoie le manifeste
     qui en résulte.

 -- Procédure Scheme : package->manifest-entry PAQUET [SORTIE]
          [#:properties]
     Renvoie une entrée de manifeste pour la SORTIE du paquet PAQUET, où
     SORTIE vaut ‘"out"’ par défaut, et avec les propriétés PROPERTIES
     données. Par défaut PROPERTIES est la liste vide ou, si des
     transformations de paquets sont appliquées à PAQUET, une liste
     d’association représentant ces transformations, utilisable en tant
     qu’argument à ‘options->transformation’ (*note
     ‘options->transformation’: Définition de variantes de paquets.).

     Le bout de code ci-dessous construit un manifeste avec une entrée
     pour la sortie par défaut et la sortie ‘send-email’ du paquet ‘git’
     :

          (use-modules (gnu packages version-control))

          (manifest (list (package->manifest-entry git)
                          (package->manifest-entry git "send-email")))

 -- Procédure Scheme : packages->manifest PAQUETS
     Renvoie une liste d’entrées de manifestes, un paquet élément listé
     dans PAQUETS. Les éléments de PAQUETS peuvent être soit des objets
     paquets soit des tuples paquet / chaine dénotant une sortie
     particulière d’un paquet.

     Avec cette procédure, le manifeste ci-dessus peut être réécrit de
     manière plus concise :

          (use-modules (gnu packages version-control))

          (packages->manifest (list git `(,git "send-email")))

 -- Procédure Scheme : package->development-manifest PAQUET [SYSTÈME]
          [#:target]
     Renvoie un manifeste pour les “entrées de développement” de PAQUET
     pour SYSTÈME, éventuellement pour la compilation croisée vers la
     cible TARGET. Les entrées de développement comprennent à la fois
     les entrées explicites et les entrées implicites de PAQUET.

     Comme l’option ‘-D’ de ‘guix shell’ (*note ‘guix shell -D’:
     shell-development-option.), le manifeste qui en résulte décrit
     l’environnement dans lequel on peut développer le PAQUET. Par
     exemple, si vous voulez configurer un environnement de
     développement pour Inkscape, avec Git pour le contrôle de version,
     vous pouvez décrire cette « nomenclature » avec le manifeste
     suivant :

          (use-modules (gnu packages inkscape)          ;pour « inkscape »
                       (gnu packages version-control))  ;pour « git »

          (concatenate-manifests
           (list (package->development-manifest inkscape)
                 (packages->manifest (list git))))

     Dans cet exemple, le manifeste de développement qui renvoie
     ‘package->development-manifest’ inclus le compilateur (GCC), les
     nombreuses bibliothèques qui portent le projet (Boost, GLib, GTK,
     etc) et quelques outils de développement supplémentaires — ce sont
     les dépendances listées par ‘guix show inkscape’.

   Enfin, le module ‘(gnu packages)’ fournit des fonctions pour
construire des manifestes. En particulier, il vous permet de rechercher
des paquets par leur nom — voir ci-dessous.

 -- Procédure Scheme : specifications->manifest SPECS
     Étant données les SPECS, une liste de spécifications comme
     ‘"emacs@25.2"’ ou ‘"guile:debug"’, renvoie un manifeste. Les
     spécifications ont le même format que celui attendu par les outils
     en ligne de commande comme ‘guix install’ et ‘guix package’ (*note
     Invoquer guix package::).

     Par exemple, elle vous permet de réécrire le manifeste avec Git que
     nous avons vu plus haut comme ceci :

          (specifications->manifest '("git" "git:send-email"))

     Remarque que nous n’avons pas à nous soucier de ‘use-modules’,
     d’importer le bon ensemble de modules et de se référer aux bonnes
     variables. À la place, nous nous référons directement aux paquets
     de la même manière que sur la ligne de commande, ce qui peut
     souvent être plus pratique.


File: guix.fr.info,  Node: Systèmes de construction,  Next: Phases de construction,  Prev: Écrire un manifeste,  Up: Interface de programmation

9.5 Systèmes de construction
============================

Chaque définition de paquet définie un “système de construction” et des
arguments pour ce système de construction (*note Définition des
paquets::). Ce champ ‘build-system’ représente la procédure de
construction du paquet, ainsi que des dépendances implicites pour cette
procédure de construction.

   Les systèmes de construction sont des objets ‘<build-system>’.
L’interface pour les créer et les manipuler est fournie par le module
‘(guix build-system)’ et les systèmes de construction eux-mêmes sont
exportés par des modules spécifiques.

   Sous le capot, les systèmes de construction compilent d’abord des
objets paquets en “sacs”. Un “sac” est comme un paquet, mais avec moins
de décoration — en d’autres mots, un sac est une représentation à
bas-niveau d’un paquet, qui inclus toutes les entrées de ce paquet, dont
certaines ont été implicitement ajoutées par le système de construction.
Cette représentation intermédiaire est ensuite compilée en une
dérivation (*note Dérivations::). Le ‘package-with-c-toolchain’ est un
exemple d’une manière de modifier les entrées implicites que le système
de construction d’un paquet récupère (*note ‘package-with-c-toolchain’:
référence de package.).

   Les systèmes de construction acceptent une liste d’“arguments”
facultatifs. Dans les définitions de paquets, ils sont passés via le
champ ‘arguments’ (*note Définition des paquets::). Ce sont typiquement
des arguments par mot-clef (*note keyword arguments in Guile:
(guile)Optional Arguments.). La valeur de ces arguments est
habituellement évaluée dans la “strate de construction” — c.-à-d. par un
processus Guile lancé par le démon (*note Dérivations::).

   Le système de construction principal est le ‘gnu-build-system’ qui
implémente les procédures de construction standard pour les paquets GNU
et de nombreux autres. Il est fournit par le module ‘(guix build-system
gnu)’.

 -- Variable Scheme : gnu-build-system
     ‘gnu-build-system’ représente le système de construction GNU et ses
     variantes (*note configuration and makefile conventions:
     (standards)Configuration.).

     En résumé, les paquets qui l’utilisent sont configurés, construits
     et installés avec la séquence ‘./configure && make && make check &&
     make install’ habituelle. En pratique, des étapes supplémentaires
     sont souvent requises. Toutes ces étapes sont séparées dans des
     “phases” différentes, *Note Phases de construction:: pour plus
     d’informations sur les phases de construction et comment les
     personnaliser.

     En plus, ce système de construction s’assure que l’environnement «
     standard » pour les paquets GNU est disponible. Cela inclus des
     outils comme GCC, libc, Coreutils, Bash, Make, Diffutils, grep et
     sed (voir le module ‘(guix build-system gnu)’ pour une liste
     complète). Nous les appelons les “entrées implicites” d’un paquet
     parce que la définition du paquet ne les mentionne pas.

     Ce système de construction prend en charge un certain nombre de
     mot-clés, qui peuvent être passés via le champ ‘arguments’ d’un
     paquet. Voici certains des paramètres principaux :

     ‘#:phases’
          Cet argument spécifie le code du côté de la construction qui
          s’évalue en une liste d’association des phases de
          construction. *Note Phases de construction::, pour plus
          d’informations.

     ‘#:configure-flags’
          C’est une liste de drapeaux (chaînes) passés au script
          ‘configure’. *Note Définition des paquets::, pour un exemple.

     ‘#:make-flags’
          Cette liste de chaînes contient les drapeaux passés en
          argument aux invocation de ‘make’ dans les phases ‘build’,
          ‘check’ et ‘install’.

     ‘#:out-of-source?’
          Ce booléen, ‘#f’ par défaut, indique s’il faut lancer les
          constructions dans un répertoire séparé de l’arborescence des
          sources.

          Lorsque la valeur est vraie, la phase ‘configure’ crée un
          répertoire de construction séparé, se déplace dedans et lance
          le script ‘configure’ à partir de celui-ci. C’est utile pour
          les paquets qui en ont besoin, comme ‘glibc’.

     ‘#:tests?’
          Ce booléen, ‘#t’ par défaut, indique si la phase ‘check’ doit
          lancer la suite de tests du paquet.

     ‘#:test-target’
          Cette chaîne, ‘"check"’ par défaut, donne le nom de la cible
          du makefile à utiliser dans la phase ‘check’.

     ‘#:parallel-build?’
     ‘#:parallel-tests?’
          Ces booléens spécifient s’il faut construire, respectivement
          lancer la suite de tests, en parallèle, avec le drapeau ‘-j’
          de ‘make’. Lorsque la valeur est vraie, ‘make’ reçoit ‘-jN’,
          où N est le nombre spécifié dans l’option ‘--cores’ de
          ‘guix-daemon’ ou celle de la commande du client ‘guix’ (*note
          ‘--cores’: Options de construction communes.).

     ‘#:validate-runpath?’
          Ce booléen, ‘#t’ par défaut, détermine s’il faut « valider »
          le ‘RUNPATH’ des binaires ELF (les bibliothèques partagées
          ‘.so’ et les exécutables) installés précédemment par la phase
          ‘install’. *Note la phase ‘validate-runpath’:
          phase-validate-runpath, pour plus de détails.

     ‘#:substitutable?’
          Ce booléen, ‘#t’ par défaut, indique si les sorties du paquet
          peuvent être substituées — c.-à-d. si les utilisateur·rices
          peuvent obtenir des substituts au lieu de les construire
          localement (*note Substituts::).

     ‘#:allowed-references’
     ‘#:disallowed-references’
          Lorsque la valeur est vraie, ces arguments doivent être une
          liste de dépendance qui ne doivent pas apparaître dans les
          dépendances des résultats de la construction. Si, à la fin de
          la construction, certaines de ces références sont retenues, le
          processus échoue.

          C’est utile pour s’assurer qu’un paquet ne garde pas une
          référence par erreur à ses entrées de construction, sis cela
          augmente par exemple la taille de sa clôture (*note Invoquer
          guix size::).

     La plupart des autres systèmes de construction prennent en charge
     ces mot-clés.

   D’autres objets ‘<build-system>’ sont définis pour supporter d’autres
conventions et outils utilisés par les paquets de logiciels libres. Ils
héritent de la plupart de ‘gnu-build-system’ et diffèrent surtout dans
l’ensemble des entrées implicites ajoutées au processus de construction
et dans la liste des phases exécutées. Certains de ces systèmes de
construction sont listés ci-dessous.

 -- Variable Scheme : ant-build-system
     Cette variable est exportée par ‘(guix build-system ant)’. Elle
     implémente la procédure de construction pour les paquets Java qui
     peuvent être construits avec l’outil de construction Ant
     (https://ant.apache.org/).

     Elle ajoute à la fois ‘ant’ et the “kit de développement Java”
     (JDK) fournit par le paquet ‘icedtea’ à l’ensemble des entrées. Des
     paquets différents peuvent être spécifiés avec les paramètres
     ‘#:ant’ et ‘#:jdk’ respectivement.

     Lorsque le paquet d’origine ne fournit pas de fichier de
     construction Ant acceptable, le paramètre ‘#:jar-name’ peut être
     utilisé pour générer un fichier de construction Ant ‘build.xml’
     minimal, avec des tâches pour construire l’archive jar spécifiée.
     Dans ce cas, le paramètre ‘#:source-dir’ peut être utilisé pour
     spécifier le sous-répertoire des sources, par défaut « src ».

     Le paramètre ‘#:main-class’ peut être utilisé avec le fichier de
     construction minimal pour spécifier la classe principale du jar.
     Cela rend le fichier jar exécutable. Le paramètre ‘#:test-include’
     peut être utilisé pour spécifier la liste des tests junits à
     lancer. Il vaut par défaut ‘(list "**/*Test.java")’. Le paramètre
     ‘#:test-exclude’ peut être utilisé pour désactiver certains tests.
     Sa valeur par défaut est ‘(list "**/Abstract*.java")’, parce que
     les classes abstraites ne peuvent pas être utilisées comme des
     tests.

     Le paramètre ‘#:build-target’ peut être utilisé pour spécifier la
     tâche Ant qui devrait être lancée pendant la phase ‘build’. Par
     défaut la tâche « jar » sera lancée.

 -- Variable Scheme : android-ndk-build-system
     Cette variable est exportée par ‘(guix build-system android-ndk)’.
     Elle implémente une procédure de construction pour les paquets du
     NDK Android (native development kit) avec des processus de
     construction spécifiques à Guix.

     Le système de compilation suppose que les paquets installent leurs
     fichiers d’interface publique (en-tête) dans le sous-répertoire
     ‘include’ de la sortie ‘out’ et leurs bibliothèques dans le
     sous-répertoire ‘lib’ de la sortie ‘out’.

     Il est aussi supposé que l’union de toutes les dépendances d’un
     paquet n’a pas de fichiers en conflit.

     Pour l’instant, la compilation croisée n’est pas supportées — donc
     pour l’instant les bibliothèques et les fichiers d’en-têtes sont
     supposés être des outils de l’hôte.

 -- Variable Scheme : asdf-build-system/source
 -- Variable Scheme : asdf-build-system/sbcl
 -- Variable Scheme : asdf-build-system/ecl

     Ces variables, exportées par ‘(guix build-system asdf)’,
     implémentent les procédures de constructions pour les paquets en
     Common Lisp qui utilisent « ASDF »
     (https://common-lisp.net/project/asdf/). ASDF est un dispositif de
     définition de systèmes pour les programmes et les bibliothèques en
     Common Lisp.

     Le système ‘asdf-build-system/source’ installe les paquets au
     format source qui peuvent être chargés avec n’importe quelle
     implémentation de common lisp, via ASDF. Les autres, comme
     ‘asdf-build-system/sbcl’, installent des binaires au format qu’un
     implémentation particulière comprend. Ces systèmes de constructions
     peuvent aussi être utilisés pour produire des programmes
     exécutables ou des images lisp qui contiennent un ensemble de
     paquets pré-chargés.

     Le système de construction utilise des conventions de nommage. Pour
     les paquets binaires, le nom du paquet devrait être préfixé par
     l’implémentation lisp, comme ‘sbcl-’ pour ‘asdf-build-system/sbcl’.

     En plus, le paquet source correspondant devrait étiquetté avec la
     même convention que les paquets python (voir *note Modules
     Python::), avec le préfixe ‘cl-’.

     Pour créer des programmes exécutables et des images, les procédures
     côté construction ‘build-program’ et ‘build-image’ peuvent être
     utilisées. Elles devraient être appelées dans une phase de
     construction après la phase ‘create-asdf-configuration’ pour que le
     système qui vient d’être construit puisse être utilisé dans l’image
     créée. ‘build-program’ requiert une liste d’expressions Common Lisp
     dans l’argument ‘#:entry-program’.

     Par défaut, tous les fichiers ‘.asd’ présents dans les sources sont
     lus pour trouver les définitions du système. Le paramètre
     ‘#:asd-file’ peut être utilisé pour préciser la liste des fichiers
     ‘.asd’ à lire. En outre, si le paquet définit un système pour ses
     tests dans un fichier séparé, il sera chargé avant l’exécution des
     tests s’il est spécifié par le paramètre ‘#:test-asd-file’. S’il
     n’est pas défini, les fichiers ‘<system>-tests.asd’,
     ‘<system>-test.asd’, ‘tests.asd’ et ‘test.asd’ seront essayés s’ils
     existent.

     Si pour quelque raison que ce soit le paquet doit être nommé d’une
     manière différente de ce que la convention de nommage suggère, ou
     si plusieurs systèmes doivent être compilés, le paramètre
     ‘#:asd-systems’ peut être utilisé pour spécifier la liste des noms
     de systèmes.

 -- Variable Scheme : cargo-build-system
     Cette variable est exportée par ‘(guix build-system cargo)’. Elle
     supporte les construction de paquets avec Cargo, le système de
     construction du langage de programmation Rust
     (https://www.rust-lang.org).

     Cela ajoute ‘rustc’ et ‘cargo’ à l’ensemble des entrées. Un autre
     paquet Rust peut être spécifié avec le paramètre ‘#:rust’.

     Les dépendances régulières de cargo doivent être ajoutées à la
     définition du paquet comme avec les autres paquets ; celles qui ne
     sont requises qu’à la construction dans « native-inputs », les
     autres dans « inputs ». Si vous devez ajouter des crates sources
     alors vous devez les ajouter via le paramètre ‘#:cargo-inputs’ sous
     la forme d’une liste de paires de noms et de spécifications, où la
     spécification peut être un paquet ou une définition de source.
     Notez que la spécification doit évaluer un chemin vers une arhive
     gzippée qui inclut un fichier ‘Cargo.toml’ à sa racine, sinon elle
     sera ignorée. De même, les dépendances de développement de cargo
     doivent être ajoutées à la définition du paquet via le paramètre
     ‘#:cargo-development-inputs’.

     Dans sa phase ‘configure’, ce système de construction mettra à
     disposition de cargo toutes les entrées sources spécifiées dans les
     paramètres ‘#:cargo-inputs’ et ‘#:cargo-development-inputs’. Il
     supprimera également un fichier ‘Cargo.lock’ inclus, qui sera
     recréé par ‘cargo’ pendant la phase ‘build’. La phase ‘package’
     lancera ‘cargo package’ pour créer un crate source réutilisable
     plus tard. La phase ‘install’ installe les binaires définis par le
     crate. À moins de définir ‘install-source? #f’ elle installera
     aussi un crate source et les sources décompressées pour faciliter
     le travail avec les paquets rust.

 -- Variable Scheme : chicken-build-system
     Cette variable est exportée par ‘(guix build-system chicken)’. Elle
     construit des modules CHICKEN Scheme (https://call-cc.org/), aussi
     appelés « eggs » ou « extensions ». CHICKEN génère du code source
     C, qui est ensuite compilé par un compilateur C, dans ce cas GCC.

     Ce système de construction ajoute ‘chicken’ aux entrées du paquet,
     en plus des paquets de ‘gnu-build-system’.

     Le système de construction ne peut pas (encore) déterminer le nom
     de l’egg automatiquement, donc comme avec le ‘go-build-system’ et
     son ‘#:import-path’, vous devriez définir ‘#:egg-name’ dans le
     champ ‘arguments’ du paquet.

     Par exemple, si vous créez un paquet pour l’egg ‘srfi-1’ :

          (arguments '(#:egg-name "srfi-1"))

     Les dépendances des egg doivent être définies dans
     ‘propagated-inputs’, pas ‘inputs’ parce que CHICKEN n’inclut pas de
     références absolues dans les eggs compilés. Les dépendances des
     tests doivent aller dans ‘native-inputs’, comme d’habitude.

 -- Variable Scheme : copy-build-system
     Cette variable est exportée par ‘(guix build-system copy)’. Il
     prend en charge la construction de paquets simples qui ne
     nécessitent pas beaucoup de compilation, la plupart du temps juste
     le déplacement de fichiers.

     Cela ajoute une grande partie des paquets ‘gnu-build-system’ à
     l’ensemble des entrées. De ce fait, le ‘copy-build-system’ n’a pas
     besoin de tout le code passe-partout souvent nécessaire pour le
     ‘trivial-build-system’.

     Pour simplifier davantage le processus d’installation des fichiers,
     un argument ‘#:install-plan’ est exposé pour permettre au packager
     de spécifier quels fichiers vont où. Le plan d’installation est une
     liste de ‘(SOURCE CIBLE [FILTRES])’. Les FILTRES sont facultatifs.

        • Lorsque SOURCE correspond à un fichier ou à un répertoire sans
          barre oblique, installez-le sur CIBLE.
             • Si TARGET a une barre oblique, installez le nom de base
               SOURCE sous TARGET.
             • Sinon, installez SOURCE comme CIBLE.

        • Lorsque SOURCE est un répertoire avec une barre oblique, ou
          lorsque des FILTRES sont utilisés, la barre oblique de TARGET
          est implicite avec la même signification que ci-dessus.
             • Sans FILTRES, installez le SOURCE complet _contenu_ à
               CIBLE.
             • Avec FILTRES parmi ‘#:include’, ‘#:include-regexp’,
               ‘#:exclude’, ‘#:exclude-regexp’, seuls les fichiers
               sélectionnés sont installés en fonction des filtres.
               Chaque filtre est spécifié par une liste de chaînes de
               caractères.
                  • Avec ‘#:include’, installez tous les fichiers dont
                    le suffixe de chemin correspond au moins un des
                    éléments dans la liste donnée.
                  • Avec ‘#:include-regexp’, installez tous les fichiers
                    que le les sous-chemins correspondent à au moins une
                    des expressions régulières de la liste donnée.
                  • Les filtres ‘#:exclude’ et ‘#:exclude-regexp’ sont
                    le complément de leur homologue pour l’inclusion.
                    Sans les drapeaux ‘#:include’, installez tous les
                    fichiers sauf ceux qui correspondent aux filtres
                    d’exclusion. Si les inclusions et les exclusions
                    sont toutes deux spécifiées, les exclusions sont
                    faites en complément des inclusions.
          Dans tous les cas, les chemins relatifs à SOURCE sont
          préservés dans CIBLE.

     Exemples :

        • ‘("toto/titi" "share/mon-app/")’ : Installer ‘titi’ sur
          ‘share/mon-app/titi’.
        • ‘("toto/titi" "share/mon-app/tata")’ : Installer ‘titi’ sur
          ‘share/mon-app/tata’.
        • ‘("toto/" "share/mon-app")’ : Installez le contenu de ‘toto’
          dans ‘share/mon-app’, par exemple, installe ‘toto/sub/file’
          dans ‘share/mon-app/sub/file’.
        • ‘("toto/" "share/mon-app" #:include ("sub/file"))’ : Installe
          seulement ‘toto/sub/file’ vers ‘share/mon-app/sub/file’.
        • ‘("toto/sub" "share/mon-app" #:include ("file"))’ : Installe
          ‘toto/sub/file’ vers ‘share/mon-app/file’.

 -- Variable Scheme : clojure-build-system
     Cette variable est exportée par ‘(guix build-system clojure)’. Elle
     implémente une procédure de construction des paquets simple qui
     utilise le bon vieux ‘compile’ de Clojure. La compilation croisée
     n’est pas encore supportée.

     Elle ajoute ‘clojure’, ‘icedtea’ et ‘zip’ à l’ensemble des entrées.
     Des paquets différents peuvent être spécifiés avec les paramètres
     ‘#:clojure’, ‘#:jdk’ et ‘#:zip’.

     Une liste de répertoires sources, de répertoires de tests et de
     noms de jar peuvent être spécifiés avec les paramètres
     ‘#:source-dirs’, ‘#:test-dirs’ et ‘#:jar-names’. Le répertoire de
     construction est la classe principale peuvent être spécifiés avec
     les paramètres ‘#:compile-dir’ et ‘#:main-class’. Les autres
     paramètres sont documentés plus bas.

     Ce système de construction est une extension de ‘ant-build-system’,
     mais avec les phases suivantes modifiées :

     ‘build’
          Cette phase appelle ‘compile’ en Clojure pour compiler les
          fichiers sources et lance ‘jar’ pour créer les fichiers jar à
          partir des fichiers sources et des fichiers compilés en
          suivant la liste d’inclusion et d’exclusion spécifiées dans
          ‘#:aot-include’ et ‘#:aot-exclude’. La liste d’exclusion a la
          priorité sur la liste d’inclusion. Ces listes consistent en
          des symboles représentant des bibliothèque Clojure ou le mot
          clef spécial ‘#:all’, représentant toutes les bibliothèques
          Clojure trouvées dans les répertoires des sources. Le
          paramètre ‘#:omit-source?’ décide si les sources devraient
          être incluses dans les fichiers jar.

     ‘check’
          Cette phase lance les tests en suivant les liste d’inclusion
          et d’exclusion spécifiées dans ‘#:test-include’ et
          ‘#:test-exclude’. Leur signification est analogue à celle de
          ‘#:aot-include’ et ‘#:aot-exclude’, sauf que le mot-clef
          spécial ‘#:all’ signifie maintenant toutes les bibliothèques
          Clojure trouvées dans les répertoires de tests. Le paramètre
          ‘#:tests?’ décide si les tests devraient être lancés.

     ‘install’
          Cette phase installe tous les fichiers jar précédemment
          construits.

     En dehors de cela, le système de construction contient aussi la
     phase suivante :

     ‘install-doc’
          Cette phase installe tous les fichiers dans le répertoire de
          plus haut niveau dont le nom correspond à ‘%doc-regex’. On
          peut spécifier une regex différente avec le paramètre
          ‘#:doc-regex’. Tous les fichiers (récursivement) dans les
          répertoires de documentations spécifiés dans ‘#:doc-dirs’ sont
          aussi installés.

 -- Variable Scheme : cmake-build-system
     Cette variable est exportée par ‘(guix build-system cmake)’. Elle
     implémente la procédure de construction des paquets qui utilisent
     l’outil de construction CMake (https://www.cmake.org).

     Elle ajoute automatiquement le paquet ‘cmake’ à l’ensemble des
     entrées. Le paquet utilisé peut être spécifié par le paramètre
     ‘#:cmake’.

     Le paramètre ‘#:configure-flags’ est pris comme une liste de
     drapeaux à passer à la commande ‘cmake’. Le paramètre
     ‘#:build-type’ spécifie en termes abstrait les drapeaux passés au
     compilateur ; sa valeur par défaut est ‘"RelWithDebInfo"’ (ce qui
     veut dire « mode public avec les informations de débogage » en plus
     court), ce qui signifie en gros que le code sera compilé avec ‘-O2
     -g’ comme pour les paquets autoconf par défaut.

 -- Variable Scheme : dune-build-system
     Cette variable est exportée par ‘(guix build-system dune)’. Elle
     prend en charge la construction des paquets qui utilisent Dune
     (https://dune.build/), un outil de construction pour le langage de
     programmation OCaml. Elle est implémentée comme une extension de
     ‘ocaml-build-system’ décrit plus bas. En tant que tel, les
     paramètres ‘#:ocaml’ et ‘#:findlib’ peuvent être passés à ce
     système de construction.

     Elle ajoute automatiquement le paquet ‘dune’ à l’ensemble des
     entrées. Le paquet utilisé peut être spécifié par le paramètre
     ‘#:dune’.

     Il n’y a pas de phase ‘configure’ parce que les paquets dune n’ont
     habituellement pas besoin d’être configurés. Le paramètre
     ‘#:build-flags’ est interprété comme une liste de drapeaux pour la
     commande ‘dune’ pendant la construction.

     Le paramètre ‘#:jbuild?’ peut être passé pour utiliser la commande
     ‘jbuild’ à la place de la commande ‘dune’ plus récente pour la
     construction d’un paquet. Sa valeur par défaut est ‘#f’.

     Le paramètre ‘#:package’ peut être passé pour spécifié un nom de
     paquet, ce qui est utile lorsqu’un paquet contient plusieurs
     paquets et que vous voulez n’en construire qu’un. C’est équivalent
     à passer l’argument ‘-p’ à ‘dune’.

 -- Variable Scheme : elm-build-system
     Cette variable est exportée par ‘(guix build-system elm)’. Elle
     implémente une procédure de construction pour les paquets Elm
     (https://elm-lang.org) qui ressemble à ‘elm install’.

     Le système de construction ajoute un paquet qui contient le
     compilateur Elm à l’ensemble des entrées. Le paquet de compilateur
     par défaut (actuellement ‘elm-sans-reactor’) peut être remplacé
     avec l’argument ‘#:elm’. En plus, les paquets Elm requis par le
     système de construction lui-même sont ajoutés en tant qu’entrées
     implicites s’ils ne sont pas déjà présents : pour supprimer ce
     comportement, utilisez l’argument ‘#:implicit-elm-package-inputs?’
     qui est surtout utile pour l’armorçage.

     Les ‘"dependencies"’ et ‘"test-dependencies"’ du fichier ‘elm.json’
     d’un paquet Elm correspondent à ‘propagated-inputs’ et ‘inputs’,
     respectivement.

     Elm a besoin d’une structure particulière pour les noms des paquets
     : *note Paquets elm:: pour plus de détails, en particulier sur les
     outils fournis par ‘(guix build-system elm)’.

     Il y a actuellement quelques limites notables à ‘elm-build-system’
     :

        • Le système de construction se concentre sur les “paquets” au
          sens d’Elm : les “projets” Elm qui déclarent ‘{ "type":
          "package"}’ dans leur fichier ‘elm.json’. Utiliser
          ‘elm-build-system’ pour construire des “applications” Elm (qui
          déclarent ‘{ "type": "application" }’ est possible, mais
          nécessite des modifications ad-hoc des phases de construction.
          Par exemple, voir les définitions de l’application d’exemple
          ‘elm-todomvc’ et du paquet ‘elm’ lui-même (parce que
          l’interface de la commande ‘elm reactor’ est une application
          Elm).

        • Elm permet la coexistence simultané de plusieurs versions d’un
          paquet dans ‘ELM_HOME’, mais cela ne fonctionne pas encore
          bien avec ‘elm-build-system’. Cette limite affecte
          principalement les applications Elm, parce qu’elles spécifient
          les versions exactes de leurs dépendances, alors que les
          paquets Elm spécifient des intervalles de versions prises en
          charge. Pour contourner le problème, les applications
          d’exemple mentionnées plus haut utilisent la procédure
          ‘patch-application-dependencies’ fournie par ‘(guix build
          elm-build-system)’ pour réécrire leur fichier ‘elm.json’ pour
          qu’ils se réfèrent aux versions effectivement présentes dans
          l’environnement de construction. Autrement, les
          transformations des paquets Guix (*note Définition de
          variantes de paquets::) peuvent aussi réécrire tout le graphe
          de dépendance d’une application.

        • Nous ne pouvons pas encore lancer les tests des projets Elm
          parce que ni ‘elm-test-rs’
          (https://github.com/mpizenberg/elm-test-rs) ni l’exécuteur
          ‘elm-test’ (https://github.com/rtfeldman/node-test-runner)
          basé sur Node.js ne sont empaquetés dans Guix.

 -- Variable Scheme : go-build-system
     Cette variable est exportée par ‘(guix build-system go)’. Elle
     implémente la procédure pour les paquets Go utilisant les
     mécanismes de construction Go
     (https://golang.org/cmd/go/#hdr-Compile_packages_and_dependencies)
     standard.

     L’utilisateur doit fournir une valeur à la clef ‘#:import-path’ et,
     dans certains cas, ‘#:unpack-path’. Le chemin d’import
     (https://golang.org/doc/code.html#ImportPaths) correspond au chemin
     dans le système de fichiers attendu par le script de construction
     du paquet et les paquets qui s’y réfèrent et fournit une manière
     unique de se référer à un paquet Go. Il est typiquement basé sur
     une combinaison de l’URI du code source du paquet et d’une
     structure hiérarchique du système de fichier. Dans certains cas,
     vous devrez extraire le code source du paquet dans une structure de
     répertoires différente que celle indiquée par le chemin d’import et
     ‘#:unpack-path’ devrait être utilisé dans ces cas-là.

     Les paquets qui fournissent des bibliothèques Go devraient
     installer leur code source dans la sortie du paquet. La clef
     ‘#:install-source?’, qui vaut ‘#t’ par défaut, contrôle
     l’installation du code source. Elle peut être mise à ‘#f’ pour les
     paquets qui ne fournissent que des fichiers exécutables.

     Vous pouvez effectuer une compilation croisée des paquets et si
     vous voulez une architecture ou un système d’exploitation
     spécifique alors vous pouvez utiliser les mot-clés ‘#:goarch’ et
     ‘#:goos’ pour forcer le paquet à être construit pour l’architecture
     et le système d’exploitation donnés. Vous trouverez les
     combinaisons connues pour Go dans leur documentation
     ("https://golang.org/doc/install/source#environment").

 -- Variable Scheme : glib-or-gtk-build-system
     Cette variable est exportée par ‘(guix build-system glib-or-gtk)’.
     Elle est conçue pour être utilisée par des paquets qui utilisent
     GLib ou GTK+.

     Ce système de construction ajoute les deux phases suivantes à
     celles définies par ‘gnu-build-system’ :

     ‘glib-or-gtk-wrap’
          La phase ‘glib-or-gtk-wrap’ garantit que les programmes dans
          ‘bin/’ sont capables de trouver les « schémas » GLib et GTK+
          modules
          (https://developer.gnome.org/gtk3/stable/gtk-running.html).
          Cela est réalisé en enveloppant les programmes dans des
          scripts de lancement qui définissent de manière appropriée les
          variables d’environnement ‘XDG_DATA_DIRS’ et ‘GTK_PATH’.

          Il est possible d’exclure des sorties spécifiques de ce
          processus d’enveloppage en listant leur nom dans le paramètre
          ‘#:glib-or-gtk-wrap-excluded-outputs’. C’est utile lorsqu’une
          sortie est connue pour ne pas contenir de binaires GLib ou
          GTK+, et où l’enveloppe ajouterait une dépendance inutile vers
          GLib et GTK+.

     ‘glib-or-gtk-compile-schemas’
          La phase ‘glib-or-gtk-compile-schemas’ s’assure que tous les
          schémas GSettings
          (https://developer.gnome.org/gio/stable/glib-compile-schemas.html)
          de GLib sont compilés. La compilation est effectuée par le
          programme ‘glib-compile-schemas’. Il est fournit par le paquet
          ‘glib:bin’ qui est automatiquement importé par le système de
          construction. Le paquet ‘glib’ qui fournit
          ‘glib-compile-schemas’ peut être spécifié avec le paramètre
          ‘#:glib’.

     Ces deux phases sont exécutées après la phase ‘install’.

 -- Variable Scheme : guile-build-system
     Ce système de construction sert aux paquets Guile qui consistent
     exclusivement en code Scheme et qui sont si simple qu’ils n’ont
     même pas un makefile, sans parler d’un script ‘configure’. Il
     compile le code Scheme en utilisant ‘guild compile’ (*note
     (guile)Compilation::) et installe les fichiers ‘.scm’ et ‘.go’ aux
     bons emplacements. Il installe aussi la documentation.

     Ce système de construction supporte la compilation croisée en
     utilisant l’option ‘--target’ de ‘guild compile’.

     Les paquets construits avec ‘guile-build-system’ doivent fournir un
     paquet Guile dans leur champ ‘native-inputs’.

 -- Variable Scheme : julia-build-system
     Cette variable est exportée par ‘(guix build-system julia)’. Elle
     implémente la procédure de compilation utilisée par les paquets
     julia (https://julialang.org/), qui est globalement similaire à
     l’exécution de ‘julia -e 'using Pkg ; Pkg.add(package)'’ dans un
     environnement où ‘JULIA_LOAD_PATH’ contient les chemins de toutes
     les entrées des paquets Julia. Les tests sont effectués en appelant
     ‘/test/runtests.jl’.

     Le nom et l’uuid du paquet Julia est lu dans le fichier
     ‘Project.toml’. Ces valeurs peuvent être remplacées en passant
     l’argument ‘#:julia-package-name’ (le nom doit être correctement
     capitalisé) ou ‘#:julia-package-uuid’.

     Les paquets Julia gèrent généralement leurs dépendances binaires
     via ‘JLLWrappers.jl’, un paquet Julia qui crée un module (nommé
     d’après la bibliothèque enveloppée suivie de ‘_jll.jl’.

     Pour ajouter le chemin vers les binaires ‘_jll.jl’, vous devez
     corriger les fichiers dans ‘src/wrappers/’, en remplaçant l’appel à
     la macro ‘JLLWrappers.@generate_wrapper_header’, en ajoutant un
     second argument contenant le chemin du binaire dans le dépôt.

     Par exemple, dans le paquets Julia MbedTLS, on ajoute un phase de
     construction (*note Phases de construction::) pour insérer le nom
     de fichier absolu du paquet enveloppé MbedTLS :

          (add-after 'unpack 'override-binary-path
            (lambda* (#:key inputs #:allow-other-keys)
              (for-each (lambda (wrapper)
                          (substitute* wrapper
                            (("generate_wrapper_header.*")
                             (string-append
                              "generate_wrapper_header(\"MbedTLS\", \""
                              (assoc-ref inputs "mbedtls-apache") "\")\n"))))
                        ;; Il y a un fichier Julia pour chaque plateforme, on les remplace tous.
                        (find-files "src/wrappers/" "\\.jl$"))))

     Certains paquets plus anciens qui n’utilisent pas encore
     ‘Project.toml’ nécessiteront aussi la création de ce fichier. Cela
     s’effectue en interne si les arguments ‘#:julia-package-name’ et
     ‘#:julia-package-uuid’ sont fournis.

 -- Variable Scheme : maven-build-system
     Cette variable est exportée par ‘(guix build-system maven)’. Elle
     implémente une procédure de construction pour les paquets Maven
     (https://maven.apache.org). Maven est un outil de gestion des
     dépendances et du cycle de vie pour Java. Un·e utilisateur·rice de
     Maven spécifie les dépendances et les plugins dans un fichier
     ‘pom.xml’ que Maven lit. Lorsque Maven n’a pas l’une des
     dépendances ou l’un des plugins dans son dépôt, il les télécharge
     et les utilise pour construire le paquet.

     Le système de construction de maven garantit que maven n’essaiera
     pas de télécharger une dépendance en s’exécutant en mode hors
     ligne. Maven échouera si une dépendance est manquante. Avant de
     lancer Maven, le fichier ‘pom.xml’ (et sous-projets) sont modifiés
     pour spécifier la version des dépendances et des plugins qui
     correspondent aux versions disponibles dans l’environnement de
     construction de guix. Les dépendances et plugins doivent être
     installés dans le faux dépôt maven à ‘lib/m2’, et sont liés par un
     lien symbolique à un dépôt approprié avant que maven ne soit lancé.
     Maven a pour instruction d’utiliser ce dépôt pour la construction
     et y installe les artefacts construits. Les fichiers modifiés sont
     copiés dans le répertoire ‘lib/m2’ de la sortie du paquet.

     Vous pouvez spécifier un fichier ‘pom.xml’ avec l’argument
     ‘#:pom-file’, ou bien laisser le système de construction utiliser
     le fichier par défaut ‘pom.xml’ dans les sources.

     Dans le cas où vous avez besoin de spécifier manuellement une
     version de dépendances, vous pouvez utiliser l’argument
     ‘#:local-packages’. Il prend une liste d’association dont la clé
     est le groupId du paquet et sa valeur est une liste d’association
     où la clé est l’artefactId du paquet et sa valeur est la version
     que vous souhaitez remplacer dans le fichier ‘pom.xml’.

     Certains paquets utilisent des dépendances ou des plugins qui ne
     sont pas utiles au moment de l’exécution ou de la compilation dans
     Guix. Vous pouvez modifier le fichier ‘pom.xml’ pour les supprimer
     en utilisant l’argument ‘#:exclude’. Sa valeur est une liste
     d’association où la clé est le groupId du plugin ou de la
     dépendance que vous voulez supprimer, et la valeur est une liste
     d’artifactId que vous voulez supprimer.

     Vous pouvez remplacer les paquets ‘jdk’ et ‘maven’ par défaut avec
     l’argument correspondant, ‘#:jdk’ et ‘#:maven’.

     L’argument ‘#:maven-plugins’ est une liste de plugins maven
     utilisés pendant la construction, avec le même format que le champ
     ‘inputs’ de la déclaration du paquet. Sa valeur par défaut est
     ‘(default-maven-plugins)’ qui est également exportée.

 -- Variable Scheme : minetest-mod-build-system
     Cette variable est exportée par ‘(guix build-system minetest)’.
     Elle implémente une procédure de construction pour les mods de
     Minetest (https://runwww.minetest.net) qui consiste à copier du
     code Lua, des images et d’autres ressources aux emplacements où
     Minetest recherche des mods. Le système de construction minimise
     aussi les images PNG et vérifie que Minetest peut charger le mod
     sans erreur.

 -- Variable Scheme : minify-build-system
     Cette variable est exportée par ‘(guix build-system minify)’. Elle
     implémente une procédure de minification pour des paquets
     JavaScript simples.

     Elle ajoute ‘uglify-js’ à l’ensemble des entrées et l’utilise pour
     compresser tous les fichiers JavaScript du répertoire ‘src’. Un
     minifieur différent peut être spécifié avec le paramètre
     ‘#:uglify-js’ mais il est attendu que ce paquet écrive le code
     minifié sur la sortie standard.

     Lorsque les fichiers JavaScript d’entrée ne sont pas situés dans le
     répertoire ‘src’, le paramètre ‘#:javascript-files’ peut être
     utilisé pour spécifier une liste de noms de fichiers à donner au
     minifieur.

 -- Variable Scheme : ocaml-build-system
     Cette variable est exportée par ‘(guix build-system ocaml)’. Elle
     implémente une procédure de construction pour les paquets OCaml
     (https://ocaml.org) qui consiste à choisir le bon ensemble de
     commande à lancer pour chaque paquet. Les paquets OCaml peuvent
     demander des commandes diverses pour être construit. Ce système de
     construction en essaye certaines.

     Lorsqu’un fichier ‘setup.ml’ est présent dans le répertoire de plus
     haut niveau, elle lancera ‘ocaml setup.ml -configure’, ‘ocaml
     setup.ml -build’ et ‘ocaml setup.ml -install’. Le système de
     construction supposera que ces fichiers ont été générés par OASIS
     (http://oasis.forge.ocamlcore.org/) et prendra soin d’initialiser
     le préfixe et d’activer les tests s’ils ne sont pas désactivés.
     Vous pouvez passer des drapeaux de configuration et de construction
     avec ‘#:configure-flags’ et ‘#:build-flags’. La clef ‘#:test-flags’
     peut être passée pour changer l’ensemble des drapeaux utilisés pour
     activer les tests. La clef ‘#:use-make?’ peut être utilisée pour
     outrepasser ce système dans les phases de construction et
     d’installation.

     Lorsque le paquet a un fichier ‘configure’, il est supposé qu’il
     s’agit d’un script configure écrit à la main qui demande un format
     différent de celui de ‘gnu-build-system’. Vous pouvez ajouter plus
     de drapeaux avec la clef ‘#:configure-flags’.

     Lorsque le paquet a un fichier ‘Makefile’ (ou ‘#:use-make?’ vaut
     ‘#t’), il sera utilisé et plus de drapeaux peuvent être passés à la
     construction et l’installation avec la clef ‘#:make-flags’.

     Enfin, certains paquets n’ont pas ces fichiers mais utilisent un
     emplacement plus ou moins standard pour leur système de
     construction. Dans ce cas, le système de construction lancera
     ‘ocaml pkg/pkg.ml’ ou ‘pkg/build.ml’ et prendra soin de fournir le
     chemin du module findlib requis. Des drapeaux supplémentaires
     peuvent être passés via la clef ‘#:bulid-flags’. L’installation se
     fait avec ‘opam-installer’. Dans ce cas, le paquet ‘opam’ doit être
     ajouté au champ ‘native-inputs’ de la définition du paquet.

     Remarquez que la plupart des paquets OCaml supposent qu’ils seront
     installés dans le même répertoire qu’OCaml, ce qui n’est pas ce que
     nous voulons faire dans Guix. En particulier, ils installeront
     leurs fichiers ‘.so’ dans leur propre répertoire de module, ce qui
     est normalement correct puisqu’il s’agit du répertoire du
     compilateur OCaml. Dans Guix en revanche, ces bibliothèques ne
     peuvent pas y être trouvées et on utilise ‘CAML_LD_LIBRARY_PATH’ à
     la place. Cette variable pointe vers ‘lib/ocaml/site-lib/stubslibs’
     et c’est là où les bibliothèques ‘.so’ devraient être installées.

 -- Variable Scheme : python-build-system
     Cette variable est exportée par ‘(guix build-system python)’. Elle
     implémente la procédure de construction plus ou moins standard
     utilisée pour les paquets Python, qui consiste à lancer ‘python
     setup.py build’ puis ‘python setup.py install
     --prefix=/gnu/store/...’.

     Pour les paquets qui installent des programmes autonomes Python
     dans ‘bin/’, elle prend soin d’envelopper ces binaires pour que
     leur variable d’environnement ‘GUIX_PYTHONPATH’ pointe vers toutes
     les bibliothèques Python dont ils dépendent.

     Le paquet Python utilisé pour effectuer la construction peut être
     spécifié avec le paramètre ‘#:python’. C’est une manière utile de
     forcer un paquet à être construit avec une version particulière de
     l’interpréteur python, ce qui peut être nécessaire si le paquet
     n’est compatible qu’avec une version de l’interpréteur.

     Par défaut, guix appelle ‘setup.py’ sous le contrôle de
     ‘setuptools’, tout comme ‘pip’ le fait. Certains paquets ne sont
     pas compatibles avec setuptools (et pip), vous pouvez donc le
     désactiver en réglant le paramètre ‘#:use-setuptools?’ sur ‘#f’.

     Si la sortie ‘"python"’ est disponible, le paquet y est installé au
     lieu de la sortie ‘"out"’ par défaut. C’est utile pour les paquets
     qui incluent un paquet Python seulement comme partie du logiciel,
     et donc qu’il faut combiner les phases de ‘python-build-system’
     avec celles d’un autre système de construction. Les liaisons Python
     sont un cas courant.

 -- Variable Scheme : pyproject-build-system
     C’est une variable exportée par ‘guix build-system pyproject’. Elle
     est basée sur PYTHON-BUILD-SYSTEM et ajoute la prise en charge de
     ‘pyproject.toml’ et PEP 517 (https://peps.python.org/pep-0517/).
     Elle prend aussi en charge plusieurs moteurs de construction et
     cadriciels de test.

     L’API est un peu différente de celle de PYTHON-BUILD-SYSTEM :
        • ‘#:use-setuptools?’ et ‘#:test-target’ sont supprimés.
        • ‘#:build-backend’ est ajouté. Sa valeur par défaut est
          ‘#false’ et le système essaiera de deviner le moteur approprié
          en fonction de ‘pyproject.toml’.
        • ‘#:test-backend’ est ajouté. Sa valeur par défaut est ‘#false’
          et le système essaiera de deviner un moteur de test approprié
          en fonction de ce qui est disponible dans les entrées du
          paquet.
        • ‘#:test-flags’ est ajouté. La valeur par défaut est ‘'()’. Ces
          drapeaux sont passés en argument à la commande de test.
          Remarquez que les drapeaux pour la sortie verbeuse sont
          toujours activés pour les moteurs pris en charge.

     Il est considéré comme « expérimental » dans le sens où les détails
     d’implémentation ne sont pas encore figés, mais nous vous
     encourageons à l’essayer pour les nouveaux projets Python (même
     ceux qui utilisent ‘setup.py’). L’API pourrait changer mais les
     changements provoquant des problèmes dans le canal Guix seront
     gérés.

     Ce système de construction finira par être obsolète et fusionné
     dans PYTHON-BUILD-SYSTEM, sans doute au courant de l’année 2024.

 -- Variable Scheme : perl-build-system
     Cette variable est exportée par ‘(guix build-system perl)’. Elle
     implémente la procédure de construction standard des paquets Perl,
     qui consiste soit à lancer ‘perl Build.PL --prefix=/gnu/store/...’,
     suivi de ‘Build’ et ‘Build install’ ; ou à lancer ‘perl Makefile.PL
     PREFIX=/gnu/store/...’, suivi de ‘make’ et ‘make install’, en
     fonction de la présence de ‘Build.PL’ ou ‘Makefile.PL’ dans la
     distribution du paquet. Le premier a la préférence si ‘Build.PL’ et
     ‘Makefile.PL’ existent tous deux dans la distribution du paquet.
     Cette préférence peut être inversée en spécifiant ‘#t’ pour le
     paramètre ‘#:make-maker?’.

     L’invocation initiale de ‘perl Makefile.PL’ ou ‘perl Build.PL’
     passe les drapeaux spécifiés par le paramètre ‘#:make-maker-flags’
     ou ‘#:module-build-flags’, respectivement.

     Le paquet Perl utilisé peut être spécifié avec ‘#:perl’.

 -- Variable Scheme : renpy-build-system
     Cette variable est exportée par ‘(guix build-system renpy)’. Elle
     implémente la procédure de construction plus ou moins standard
     utilisée pour les jeux Ren’py, qui consiste à charger ‘#:game’ une
     fois, et donc à créer le bytecode pour le jeu.

     Elle crée aussi un script enveloppe dans ‘bin/’ et une entrée de
     bureau dans ‘share/applications’, tous deux pouvant être utilisés
     pour lancer le jeu.

     Le paquet Ren’py utilisé peut être spécifié avec ‘#:renpy’. Les
     jeux peuvent aussi être installé dans des sorties différentes de «
     out » avec ‘#:output’.

 -- Variable Scheme : qt-build-system
     Cette variable est exportée par ‘(guix build-system qt)’. Elle est
     destinée à être employée avec des applications utilisant Qt ou KDE.

     Ce système de construction ajoute les deux phases suivantes à
     celles définies par ‘gnu-build-system’ :

     ‘check-setup’
          La phase ‘check-setup’ prépare l’environnement pour
          l’exécution des contrôles tels qu’ils sont couramment utilisés
          par les programmes de test Qt. Pour l’instant, elle ne définit
          que quelques variables d’environnement :
          ‘QT_QPA_PLATFORM=offscreen’, ‘DBUS_FATAL_WARNINGS=0’ et
          ‘CTEST_OUTPUT_ON_FAILURE=1’.

          Cette phase est ajoutée avant la phase ‘check’. C’est une
          phase distincte pour faciliter l’ajustement si nécessaire.

     ‘qt-wrap’
          La phase ‘qt-wrap’ recherche les chemins des plugins Qt5, les
          chemins QML et certains XDG dans les entrées et sorties. Si un
          chemin est trouvé, tous les programmes des répertoires ‘bin/’,
          ‘sbin/’, ‘libexec/’ et ‘lib/libexec/’ de la sortie sont
          enveloppés dans des scripts définissant les variables
          d’environnement nécessaires.

          Il est possible d’exclure des sorties de paquets spécifiques
          de ce processus d’emballage en listant leurs noms dans le
          paramètre ‘#:qt-wrap-excluded-outputs’. Ceci est utile
          lorsqu’une sortie est connue pour ne pas contenir de binaires
          Qt, et où le wrapping ajouterait gratuitement une dépendance
          de cette sortie à Qt, KDE, ou autre.

          Cette phase est exécutée après la phase ‘install’.

 -- Variable Scheme : r-build-system
     Cette variable est exportée par ‘(guix build-system r)’. Elle
     implémente la procédure de compilation utilisée par les paquets R
     (https://r-project.org), qui consiste en substance à exécuter ‘R
     CMD INSTALL --library=/gnu/store/...’ dans un environnement où
     ‘R_LIBS_SITE’ contient les chemins de toutes les entrées des
     paquets R. Les tests sont exécutés après l’installation en
     utilisant la fonction R ‘tools::testInstalledPackage’.

 -- Variable Scheme : rakudo-build-system
     Cette variable est exportée par ‘(guix build-system rakudo)’. Elle
     implémente la procédure de construction utilisée par Rakudo
     (https://rakudo.org/) pour les paquets Perl6 (https://perl6.org/).
     Elle installe le paquet dans
     ‘/gnu/store/.../NOM-VERSION/share/perl6’ et installe les binaires,
     les fichiers de bibliothèques et les ressources, et enveloppe les
     fichiers dans le répertoire ‘bin/’. Les tests peuvent être passés
     en indiquant ‘#f’ au paramètre ‘tests?’.

     Le paquet rakudo utilisé peut être spécifié avec ‘rakudo’. Le
     paquet perl6-tap-harness utilisé pour les tests peut être spécifié
     avec ‘#:prove6’ ou supprimé en passant ‘#f’ au paramètre
     ‘with-prove6?’. Le paquet perl6-zef utilisé pour les tests et
     l’installation peut être spécifié avec ‘#:ef’ ou supprimé en
     passant ‘#f’ au paramètre ‘with-zef?’.

 -- Variable Scheme : rebar-build-system
     Cette variable est exportée par ‘(guix build-system rebar)’. Elle
     implémente une procédure de construction pour rebar3
     (https://rebar3.org), un système de construction pour les
     programmes écrits en Erlang.

     Elle ajoute à la fois ‘rebar3’ et ‘erlang’ à l’ensemble des
     entrées. Des paquets différents peuvent être spécifiés avec les
     paramètres ‘#:rebar’ et ‘#:erlang’, respectivement.

     Ce système de construction est basé sur GNU-BUILD-SYSTEM, mais avec
     les phases suivantes modifiées :

     ‘unpack’
          Cette phase, après avoir déballé les sources comme le fait le
          ‘gnu-build-system’, vérifie qu’un fichier ‘contents.tar.gz’
          existe au plus haut niveau des sources. Si ce fichier existe,
          il sera aussi déballé. Cela facilite la gestion des paquets
          hébergés sur <https://hex.pm/>, le dépôt des paquets Erlang et
          Elixir.

     ‘bootstrap’
     ‘configure’
          Il n’y a ni phase ‘bootstrap’ ni ‘configure’ parce que les
          paquets erlang n’ont pas besoin d’être configurés.

     ‘build’
          Cette phase lance ‘rebar3 compile’ avec les drapeaux listés
          dans ‘#:rebar-flags’.

     ‘check’
          À moins que ‘#:tests? #f’ ne soit passé, cette phase lance
          ‘rebar3 eunit’, ou une cible spécifiée avec ‘#:test-target’,
          avec les drapeaux listés dans ‘#:rebar-flags’,

     ‘install’
          Cela installe les fichiers créés dans le profil default, ou un
          autre profil spécifié avec ‘#:install-profile’.

 -- Variable Scheme : texlive-build-system
     Cette variable est exportée par ‘(guix build-system texlive)’. Elle
     est utilisée pour construire des paquets TeX en mode batch avec le
     moteur spécifié. Le système de construction initialise la variable
     ‘TEXINPUTS’ pour trouver tous les fichiers source TeX dans ses
     entrées.

     Par défaut, elle lance ‘luatex’ sur tous les fichiers qui se
     terminent par ‘ins’. Un moteur et un format différent peuvent être
     spécifiés avec l’argument ‘#:tex-format’. Plusieurs cibles de
     constructions peuvent être indiquées avec l’argument
     ‘#:build-targets’ qui attend une liste de noms de fichiers. Le
     système de construction ajoute uniquement ‘texlive-bin’ et
     ‘texlive-latex-base’ (de ‘(gnu packages tex)’ à la liste des
     entrées. Les deux peuvent être remplacés avec les arguments
     ‘#:texlive-bin’ et ‘#:texlive-latex-base’, respectivement.

     Le paramètre ‘#:tex-directory’ dit au système de construction où
     installer les fichiers construit dans l’arbre texmf.

 -- Variable Scheme : ruby-build-system
     Cette variable est exportée par ‘(guix build-system ruby)’. Elle
     implémenter la procédure de construction RubyGems utilisée par les
     paquets Ruby qui consiste à lancer ‘gem build’ suivi de ‘gem
     install’.

     Le champ ‘source’ d’un paquet qui utilise ce système de
     construction référence le plus souvent une archive gem, puisque
     c’est le format utilisé par les personnes qui développent en Ruby
     quand elles publient leur logiciel. Le système de construction
     décompresse l’archive gem, éventuellement en corrigeant les
     sources, lance la suite de tests, recompresse la gemme et
     l’installe. En plus, des répertoires et des archives peuvent être
     référencés pour permettre de construire des gemmes qui n’ont pas
     été publiées depuis Git ou une archive de sources traditionnelle.

     Le paquet Ruby utilisé peut être spécifié avec le paramètre
     ‘#:ruby’. Une liste de drapeaux supplémentaires à passer à la
     commande ‘gem’ peut être spécifiée avec le paramètre ‘#:gem-flags’.

 -- Variable Scheme : waf-build-system
     Cette variable est exportée par ‘(guix build-system waf)’. Elle
     implémente une procédure de construction autour du script ‘waf’.
     Les phases usuelles — ‘configure’, ‘build’ et ‘install’ — sont
     implémentée en passant leur nom en argument au script ‘waf’.

     Le script ‘waf’ est exécuté par l’interpréteur Python. Le paquet
     Python utilisé pour lancer le script peut être spécifié avec le
     paramètre ‘#:python’.

 -- Variable Scheme : scons-build-system
     Cette variable est exportée par ‘(guix build-system scons)’. Elle
     implémente la procédure de construction utilisée par l’outil de
     construction SCons. Ce système de construction lance ‘scons’ pour
     construire le paquet, ‘scons test’ pour lancer les tests puis
     ‘scons install’ pour installer le paquet.

     Des drapeaux supplémentaires à passer à ‘scons’ peuvent être
     spécifiés avec le paramètre ‘#:scons-flags’. Les cibles de
     construction et d’installation par défaut peuvent être remplacées
     respectivement par les paramètres ‘#:build-targets’ et
     ‘#:install-targets’. La version de Python utilisée pour exécuter
     SCons peut être spécifiée en sélectionnant le paquet SCons
     approprié avec le paramètre ‘#:scons’.

 -- Variable Scheme : haskell-build-system
     Cette variable est exportée par ‘(guix build-system haskell)’. Elle
     implémente la procédure de construction Cabal utilisée par les
     paquets Haskell, qui consiste à lancer ‘runhaskell Setup.hs
     configure --prefix=/gnu/store/...’ et ‘runhaskell Setup.hs build’.
     Plutôt que d’installer le paquets en lançant ‘runhaskell Setup.hs
     install’, pour éviter d’essayer d’enregistrer les bibliothèques
     dans le répertoire du dépôt en lecture-seule du compilateur, le
     système de construction utilise ‘runhaskell Setup.hs copy’, suivi
     de ‘runhaskell Setup.hs register’. En plus, le système de
     construction génère la documentation du paquet en lançant
     ‘runhaskell Setup.hs haddock’, à moins que ‘#:haddock? #f’ ne soit
     passé. Des paramètres facultatifs pour Haddock peuvent être passés
     à l’aide du paramètre ‘#:haddock-flags’. Si le fichier ‘Setup.hs’
     n’est pas trouvé, le système de construction cherchera ‘Setup.lhs’
     à la place.

     Le compilateur Haskell utilisé peut être spécifié avec le paramètre
     ‘#:haskell’ qui a pour valeur par défaut ‘ghc’.

 -- Variable Scheme : dub-build-system
     Cette variable est exportée par ‘(guix build-system dub)’. Elle
     implémente la procédure de construction Dub utilisée par les
     paquets D qui consiste à lancer ‘dub build’ et ‘dub run’.
     L’installation est effectuée en copiant les fichiers manuellement.

     Le compilateur D utilisé peut être spécifié avec le paramètre
     ‘#:ldc’ qui vaut par défaut ‘ldc’.

 -- Variable Scheme : emacs-build-system
     Cette variable est exportée par ‘(guix build-system emacs)’. Elle
     implémente une procédure d’installation similaire au système de
     gestion de paquet d’Emacs lui-même (*note (emacs)Packages::).

     Cela crée d’abord le fichier ‘package-autoloads.el’, puis compile
     tous les fichiers Emacs Lisp en bytecode. Contrairement au système
     de gestion de paquets d’Emacs, les fichiers de documentation info
     sont déplacés dans le répertoire standard et le fichier ‘dir’ est
     supprimé. Les fichiers du paquet Elisp sont directement installés
     sous ‘share/emacs/site-lisp’.

 -- Variable Scheme : font-build-system
     Cette variable est exportée par ‘(guix build-system font)’. Elle
     implémente une procédure d’installation pour les paquets de polices
     où des fichiers de polices TrueType, OpenType, etc. sont fournis en
     amont et n’ont qu’à être copiés à leur emplacement final. Elle
     copie les fichiers de polices à l’emplacement standard dans le
     répertoire de sortie.

 -- Variable Scheme : meson-build-system
     Cette variable est exportée par ‘(guix build-system meson)’. Elle
     implémente la procédure de construction des paquets qui utilisent
     Meson (https://mesonbuild.com) comme système de construction.

     Elle ajoute à la fois Meson et Ninja (https://ninja-build.org/) à
     l’ensemble des entrées, et ils peuvent être modifiés avec les
     paramètres ‘#:meson’ et ‘#:ninja’ si requis.

     Ce système de construction est une extension de ‘gnu-build-system’,
     mais avec les phases suivantes modifiées pour Meson :

     ‘configure’
          La phase lance ‘meson’ avec les drapeaux spécifiés dans
          ‘#:configure-flags’. Le drapeau ‘--buildtype’ est toujours
          défini à ‘debugoptimized’ à moins qu’autre chose ne soit
          spécifié dans ‘#:build-type’.

     ‘build’
          La phase lance ‘ninja’ pour construire le paquet en parallèle
          par défaut, mais cela peut être changé avec
          ‘#:parallel-build?’.

     ‘check’
          La phase lance ‘meson test’ avec un ensemble d’options de base
          qui ne peuvent pas être modifiées. Cette base d’options peut
          être étendue avec l’argument ‘#:test-options’, par exemple
          pour choisir ou passer une suite de test spécifique.

     ‘install’
          La phase lance ‘ninja install’ et ne peut pas être changée.

     En dehors de cela, le système de construction ajoute aussi la phase
     suivante :

     ‘fix-runpath’
          Cette phase s’assure que tous les binaire peuvent trouver les
          bibliothèques dont ils ont besoin. Elle cherche les
          bibliothèques requises dans les sous-répertoires du paquet en
          construction et les ajoute au ‘RUNPATH’ là où c’est
          nécessaire. Elle supprime aussi les références aux
          bibliothèques laissées là par la phase de construction par
          ‘meson’ comme les dépendances des tests, qui ne sont pas
          vraiment requises pour le programme.

     ‘glib-or-gtk-wrap’
          Cette phase est la phase fournie par
          ‘glib-or-gtk-build-system’ et n’est pas activée par défaut.
          Elle peut l’être avec ‘#:glib-or-gtk?’.

     ‘glib-or-gtk-compile-schemas’
          Cette phase est la phase fournie par
          ‘glib-or-gtk-build-system’ et n’est pas activée par défaut.
          Elle peut l’être avec ‘#:glib-or-gtk?’.

 -- Variable Scheme : linux-module-build-system
     ‘linux-module-build-system’ permet de construire des modules du
     noyau Linux.

     Ce système de construction est une extension de GNU-BUILD-SYSTEM,
     mais avec les phases suivantes modifiées :

     ‘configure’
          Cette phase configure l’environnement pour que le Makefile du
          noyau Linux puisse être utilisé pour construire le module du
          noyau externe.

     ‘build’
          Cette phase utilise le Makefile du noyau Linux pour construire
          le module du noyau externe.

     ‘install’
          Cette phase utilise le Makefile du noyau Linux pour installer
          le module du noyau externe.

     Il est possible et utile de spécifier le noyau Linux à utiliser
     pour construire le module (sous la forme ‘arguments’ d’un paquet
     utilisant le ‘linux-module-build-system’, utilisez la clé ‘#:linux’
     pour le spécifier).

 -- Variable Scheme : node-build-system
     Cette variable est exportée par ‘(guix build-system node)’. Elle
     implémente la procédure de compilation utilisée par Node.js
     (https://nodejs.org), qui implémente une approximation de la
     commande ‘npm install’, suivie d’une commande ‘npm test’.

     Le paquet Node.js utilisé pour interpréter les commandes ‘npm’ peut
     être spécifié avec le paramètre ‘#:node’ dont la valeur par défaut
     est ‘node’.

   Enfin, pour les paquets qui n’ont pas besoin de choses sophistiquées,
un système de construction « trivial » est disponible. Il est trivial
dans le sens où il ne fournit en gros aucun support : il n’apporte pas
de dépendance implicite, et n’a pas de notion de phase de construction.

 -- Variable Scheme : trivial-build-system
     Cette variable est exportée par ‘(guix build-system trivial)’.

     Ce système de construction requiert un argument ‘#:builder’. Cet
     argument doit être une expression Scheme qui construit la sortie du
     paquet — comme avec ‘build-expression->derivation’ (*note
     ‘build-expression->derivation’: Dérivations.).

 -- Variable Scheme : channel-build-system
     Cette variable est exportée par ‘(guix build-system channel)’.

     Ce système de construction est surtout conçu pour usage interne.
     Pour utiliser ce système de construction, un paquet doit avoir une
     spécification de canal dans son champ ‘source’ (*note Canaux::);
     autrement, sa source doit être un nom de répertoire, auquel cas un
     argument ‘#:commit’ supplémentaire doit être fournit pour spécifier
     le commit à construire (une chaine hexadécimale).

     Le paquet qui en résulte est une instance de Guix d’un canal donné,
     comme ‘guix-time-machine’ le construirait.


File: guix.fr.info,  Node: Phases de construction,  Next: Utilitaires de construction,  Prev: Systèmes de construction,  Up: Interface de programmation

9.6 Phases de construction
==========================

Presque tous les systèmes de construction de paquets mettent en œuvre
une notion de “phase de construction” : une séquence d’actions que le
système de construction exécute, lorsque vous construisez le paquet,
conduisant aux sous-produits installés dans le dépôt. Une exception
notable est le ‘trivial-build-system’ (*note Systèmes de construction::)
minimaliste.

   Comme nous l’avons dit dans la section précédente, ces systèmes de
construction fournissent une liste de phases standards. Pour
‘gnu-build-system’, les phases de construction principales sont les
suivantes :

‘set-paths’
     Défini les variables d’environnement de chemins de recherche pour
     tous les paquets d’entrée, dont ‘PATH’ (*note Chemins de
     recherche::).

‘unpack’
     Décompresse l’archive des sources et se déplace dans l’arborescence
     des sources fraîchement extraites. Si la source est en fait un
     répertoire, le copie dans l’arborescence de construction et entre
     dans ce répertoire.

‘patch-source-shebangs’
     Corrige les shebangs (‘#!’) rencontrés dans les fichiers pour
     qu’ils se réfèrent aux bons noms de fichiers. Par exemple, elle
     change ‘#!/bin/sh’ en ‘#!/gnu/store/...-bash-4.3/bin/sh’.

‘configure’
     Lance le script ‘configure’ avec un certain nombre d’options par
     défaut, comme ‘--prefix=/gnu/store/...’, ainsi que les options
     spécifiées par l’argument ‘#:configure-flags’.

‘build’
     Lance ‘make’ avec la liste des drapeaux spécifiés avec
     ‘#:make-flags’. Si l’argument ‘#:parallel-build?’ est vrai (par
     défaut), construit avec ‘make -j’.

‘check’
     Lance ‘make check’, ou une autre cible spécifiée par
     ‘#:test-target’, à moins que ‘#:tests? #f’ ne soit passé. Si
     l’argument ‘#:parallel-tests?’ est vrai (par défaut), lance ‘make
     check -j’.

‘install’
     Lance ‘make install’ avec les drapeaux listés dans ‘#:make-flags’.

‘patch-shebangs’
     Corrige les shebangs des fichiers exécutables installés.

‘strip’
     Nettoie les symboles de débogage dans les fichiers ELF (à moins que
     ‘#:strip-binaries?’ ne soit faux), les copie dans la sortie ‘debug’
     lorsqu’elle est disponible (*note Installer les fichiers de
     débogage::).

‘validate-runpath’
     Valide le ‘RUNPATH’ des binaires ELF, à moins que
     ‘#:validate-runpath?’ ne soit faux (*note Systèmes de
     construction::).

     Cette étape de validation s’assure que toutes les bibliothèques
     partagées par les binaires ELF, qui sont listées dans des entrées
     ‘DT_NEEDED’ de leur segment ‘PT_DYNAMIC’ apparaissent dans l’entrée
     ‘DT_RUNPATH’ de ce même binaire. En d’autres termes, elle s’assure
     que lancer ou utiliser ces binaires ne renvoie pas l’erreur «
     fichier introuvable » à l’exécution. *Note ‘-rpath’: (ld)Options,
     pour plus d’informations sur le ‘RUNPATH’.

   Les autres systèmes de construction ont des phases similaires, avec
quelques variations. Par exemple, ‘cmake-build-system’ a des phases de
même nom, mais sa phase ‘configure’ exécute ‘cmake’ au lieu de
‘./configure’. D’autres, tels que ‘python-build-system’, ont une liste
de phases standard totalement différente. Tout ce code s’exécute “côté
construction” : il est évalué lorsque vous construisez réellement le
paquet, dans un processus de construction dédié engendré par le démon de
construction (*note Invoquer guix-daemon::).

   Les phases de construction sont représentées sous forme de listes
d’associations ou « alists » (*note Listes d’association:
(guile)Association Lists.) où chaque clé est un symbole pour le nom de
la phase et la valeur associée est une procédure qui accepte un nombre
arbitraire d’arguments. Par convention, ces procédures reçoivent des
informations sur la construction sous la forme de “paramètres nommés”,
qu’elles peuvent utiliser ou ignorer.

   Par exemple, voici comment ‘(guix build gnu-build-system)’ définit
‘%standard-phases’, la variable contenant sa liste de phases de
construction(1) :

     ;; Les phases de construction de « gnu-build-system ».

     (define* (unpack #:key source #:allow-other-keys)
       ;; Extrait l'archive des sources.
       (invoke "tar" "xvf" source))

     (define* (configure #:key outputs #:allow-other-keys)
       ;; Exécute le script « configure ». Installe la sortie « out ».
       (let ((out (assoc-ref outputs "out")))
         (invoke "./configure"
                 (string-append "--prefix=" out))))

     (define* (build #:allow-other-keys)
       ;; Compile.
       (invoke "make"))

     (define* (check #:key (test-target "check") (tests? #true)
                     #:allow-other-keys)
       ;; Lance la suite de tests.
       (if tests?
           (invoke "make" test-target)
           (display "test suite not run\n")))

     (define* (install #:allow-other-keys)
       ;; Installe les fichiers sous le préfixe spécifié à « configure ».
       (invoke "make" "install"))

     (define %standard-phases
       ;; La liste des phases standard (un certain nombre d'entre elles sont omises
       ;; par souci de concision).  Chaque élément est une paire symbole/procédure.
       (list (cons 'unpack unpack)
             (cons 'configure configure)
             (cons 'build build)
             (cons 'check check)
             (cons 'install install)))

   Cela montre comment ‘%standard-phases’ est défini comme une liste de
paires symbole/procédure (*note (guile)Pairs::). La première paire
associe le symbole ‘unpack’ — un nom — à la procédure ‘unpack’ ; la
deuxième paire définit la phase ‘configure’ de manière similaire, et
ainsi de suite. Lors de la construction d’un paquet qui utilise
‘gnu-build-system’ avec sa liste de phases par défaut, ces phases sont
exécutées de manière séquentielle. Vous pouvez voir le nom de chaque
phase commencée et terminée dans le journal de construction des paquets
que vous construisez.

   Examinons maintenant les procédures elles-mêmes. Chacune est définie
par ‘define*’ : ‘#:key’ énumère les paramètres nommés que la procédure
accepte, éventuellement avec une valeur par défaut, et
‘#:allow-other-keys’ précise que les autres paramètres nommés sont
ignorés (*note (guile)Optional Arguments::).

   La procédure ‘unpack’ prend en compte le paramètre ‘source’, que le
système de compilation utilise pour passer le nom de fichier de
l’archive source (ou le répertoire cloné d’un système de contrôle de
version), et elle ignore les autres paramètres. La phase ‘configure’ ne
s’intéresse qu’au paramètre ‘outputs’, une liste d’association des noms
des sorties du paquet avec le nom de leur fichier du dépôt (*note Des
paquets avec plusieurs résultats::). Elle extrait le nom de fichier de
‘out’, la sortie par défaut, et le transmet à ‘./configure’ comme
préfixe d’installation, ce qui signifie que ‘make install’ copiera tous
les fichiers vers ce répertoire (*note configuration and makefile
conventions: (standards)Configuration.). ‘build’ et ‘install’ ignorent
tous leurs arguments. ‘check’ prend en compte l’argument ‘test-target’,
qui spécifie le nom de la cible du Makefile pour exécuter les tests ; il
imprime un message et saute les tests lorsque ‘tests?’ est faux.

   La liste des phases utilisées pour un paquet particulier peut être
modifiée avec le paramètre ‘#:phases’ du système de construction. La
modification de l’ensemble des phases de construction se résume à la
création d’une nouvelle liste de phases basée sur la liste
‘%standard-phases’ décrite ci-dessus. On peut faire cela à l’aide des
procédures standards qui manipulent des listes d’associations telles que
‘alist-delete’ (*note (guile)SRFI-1 Association Lists::) ; cependant, il
est plus pratique de le faire avec ‘modify-phases’ (*note
‘modify-phases’: Utilitaires de construction.).

   Voici un exemple de définition de paquet qui supprime la phase
‘configure’ de ‘%standard-phases’ et insère une nouvelle phase avant la
phase ‘build’, appelée ‘set-prefix-in-makefile’ :

     (define-public exemple
       (package
         (name "exemple")
         ;; les autres champs sont omis
         (build-system gnu-build-system)
         (arguments
          '(#:phases (modify-phases %standard-phases
                       (delete 'configure)
                       (add-before 'build 'set-prefix-in-makefile
                         (lambda* (#:key outputs #:allow-other-keys)
                           ;; Modifie le Makefile pour que sa variable
                           ;; 'PREFIX' pointe vers « out ».
                           (let ((out (assoc-ref outputs "out")))
                             (substitute* "Makefile"
                               (("PREFIX =.*")
                                (string-append "PREFIX = "
                                               out "\n")))))))))))

   La nouvelle phase insérée est écrite comme une procédure anonyme,
introduite avec ‘lambda*’ ; elle prend en compte le paramètre ‘outputs’
que nous avons vu auparavant. *Note Utilitaires de construction::, pour
en savoir plus sur les procédures auxiliaires utilisées par cette phase,
et pour d’autres exemples de ‘modify-phases’.

   Gardez à l’esprit que le code des phases de construction est évalué à
la construction effective des paquets. Cela explique pourquoi toute
l’expression ‘modify-phases’ ci-dessus est citée (elle vient après ‘'’
ou apostrophe) : elle est “mise de côté” pour une exécution ultérieure.
*Note G-Expressions::, pour une explication de la mise en place du code
et des “strates de code” concernées.

   ---------- Footnotes ----------

   (1) Nous présentons une vue simplifiée de ces phases de construction,
mais jetez un oeil à ‘(guix build gnu-build-system)’ pour voir tous les
détails !


File: guix.fr.info,  Node: Utilitaires de construction,  Next: Chemins de recherche,  Prev: Phases de construction,  Up: Interface de programmation

9.7 Utilitaires de construction
===============================

Dès que vous commencerez à écrire des définitions de paquets non
triviales (*note Définition des paquets::) ou d’autres actions de
compilation (*note G-Expressions::), vous commencerez probablement à
chercher des fonctions auxiliaires pour les actions « de type shell » —
créer des répertoires, copier et supprimer des fichiers de manière
récursive, manipuler les phases de compilation, etc. Le module ‘(guix
build utils)’ fournit de telles procédures utilitaires.

   La plupart des systèmes de construction chargent ‘(guix build utils)’
(*note Systèmes de construction::). Ainsi, lorsque vous écrivez des
phases de construction personnalisées pour vos définitions de paquets,
vous pouvez généralement supposer que ces procédures sont disponibles.

   Lorsque vous écrivez des G-expressions, vous pouvez importer ‘(guix
build utils)’ « côté construction » en utilisant ‘with-imported-modules’
et ensuite le rendre disponible avec la forme ‘use-modules’ (*note
(guile)Using Guile Modules::) :

     (with-imported-modules '((guix build utils))  ;on l'importe
       (computed-file "empty-tree"
                      #~(begin
                          ;; On le rend disponible.
                          (use-modules (guix build utils))

                          ;; On utilise sa procédure « mkdir-p » sans souci.
                          (mkdir-p (string-append #$output "/a/b/c")))))

   Le reste de cette section est la référence pour la plupart des
procédures auxiliaires fournies par ‘(guix build utils)’.

9.7.1 Traitement des noms de fichiers du dépôt
----------------------------------------------

Cette section documente les procédures de traitement des noms de fichier
du dépôt.

 -- Procédure Scheme : %store-directory
     Renvoie le nom de répertoire du dépôt.

 -- Procédure Scheme : store-file-name? FICHIER
     Renvoie vrai si FICHIER est dans le dépôt.

 -- Procédure Scheme : strip-store-file-name FICHIER
     Enlevez le ‘/gnu/store’ et le hash de FICHIER, un nom de fichier du
     dépôt. Le résultat est généralement une chaîne ‘"PAQUET-VERSION"’.

 -- Procédure Scheme : package-name->name+version NOM
     Si l’on passe NOM, un nom de paquet comme ‘"toto-0.9.1b"’, on
     obtient deux valeurs : ‘"toto"’ et ‘"0.9.1b"’. Lorsque la partie
     version est indisponible, NOM et ‘#f’ sont renvoyés. Le premier
     trait d’union suivi d’un chiffre est considéré comme introduisant
     la partie version.

9.7.2 Types de fichier
----------------------

Les procédures ci-dessous portent sur les fichiers et les types de
fichiers.

 -- Procédure Scheme : directory-exists? DIR
     Renvoie ‘#t’ si DIR existe et est un répertoire.

 -- Procédure Scheme : executable-file? FICHIER
     Renvoie ‘#t’ si FICHIER existe et est exécutable.

 -- Procédure Scheme : symbolic-link? FICHIER
     Renvoie ‘#t’ si FICHIER est un lien symbolique (un « symlink »).

 -- Procédure Scheme : elf-file? FICHIER
 -- Procédure Scheme : ar-file? FICHIER
 -- Procédure Scheme : gzip-file? FICHIER
     Renvoie ‘#t’ si FICHIER est, respectivement, un fichier ELF, une
     archive ‘ar’ (telle qu’une bibliothèque statique ‘.a’), ou un
     fichier gzip.

 -- Procédure Scheme : reset-gzip-timestamp FICHIER [#:keep-mtime? #t]
     Si FICHIER est un fichier gzip, réinitialise son horodatage intégré
     (comme avec ‘gzip --no-name’) et renvoie vrai. Sinon, renvoie ‘#f’.
     Lorsque KEEP-MTIME? est vrai, conserve la date de modification de
     FICHIER.

9.7.3 Manipulation de fichiers
------------------------------

Les procédures et macros suivantes permettent de créer, modifier et
supprimer des fichiers. Elles offrent des fonctionnalités comparables à
celles des utilitaires shell courants tels que ‘mkdir -p’, ‘cp -r’, ‘rm
-r’ et ‘sed’. Elles complètent l’interface de système de fichiers
étendue, mais de bas niveau, de Guile (*note (guile)POSIX::).

 -- Syntaxe Scheme : with-directory-excursion RÉPERTOIRE CORPS...
     Exécute CORPS avec RÉPERTOIRE comme répertoire actuel du processus.

     En gros, cette macro change le répertoire actuel en RÉPERTOIRE
     avant d’évaluer CORPS, en utilisant ‘chdir’. (*note
     (guile)Processus::). Elle revient au répertoire initial à la sortie
     de la portée dynamique de CORPS, qu’il s’agisse d’un retour de
     procédure normal ou d’une sortie non locale telle qu’une exception.

 -- Procédure Scheme : mkdir-p DIR
     Crée le répertoire DIR et tous ses ancètres.

 -- Procédure Scheme : install-file FICHIER RÉPERTOIRE
     Crée RÉPERTOIRE s’il n’existe pas et y copie FICHIER sous le même
     nom.

 -- Procédure Scheme : make-file-writable FICHIER
     Rend FICHIER inscriptible pour son propriétaire.

 -- Procédure Scheme : copy-recursively SOURCE DESTINATION [#:log
          (current-output-port)] [#:follow-symlinks ? #f] [#:copy-file
          copy-file] [#:keep-mtime? #f] [#:keep-permissions? #t]
     Copie le répertoire SOURCE dans DESTINATION. Suit les liens
     symboliques si FOLLOW-SYMLINKS? est vrai ; sinon, les conserve.
     Appelle COPY-FILE pour copier les fichiers normaux. Lorsque
     KEEP-MTIME? est vrai, conserve les heures de modification des
     fichiers de SOURCE pour ceux de DESTINATION. Si KEEP-PERMISSIONS?
     est vrai, préserve les permissions des fichiers. Affiche une sortie
     verbeuse sur le port LOG.

 -- Procédure Scheme : delete-file-recursively DIR [#:follow-mounts? #f]
     Efface récursivement DIR, comme ‘rm -rf’, sans suivre les liens
     symboliques. Ne suit pas non plus les points de montage, à moins
     que FOLLOW-MOUNTS? ne soit vrai. Rapporte mais ignore les erreurs.

 -- Syntaxe Scheme : substitute* FICHIER ((REGEXP MATCH-VAR...) BODY...)
          ...
     Remplace REGEXP dans FICHIER par la chaîne renvoyée par BODY. BODY
     est évalué avec chaque MATCH-VAR lié à la sous-expression de regexp
     positionnelle correspondante. Par exemple :

          (substitute* file
            (("hello")
             "good morning\n")
            (("toto([a-z]+)titi(.*)$" all letters end)
             (string-append "tata" letters end)))

     Ici, chaque fois qu’une ligne de FICHIER contient ‘hello’, elle est
     remplacée par ‘good morning’. Chaque fois qu’une ligne de FICHIER
     correspond à la deuxième regexp, ‘all’ est lié à la correspondance
     complète, ‘letters’ est lié à la première sous-expression, et ‘end’
     est lié à la dernière.

     Lorsque l’une des MATCH-VAR est ‘_’, aucune variable n’est liée à
     la sous-chaîne de correspondance associée.

     Autrement, FICHIER peut être une liste de noms de fichier, auquel
     cas ils sont tous sujets aux substitutions.

     Faites attention à l’utilisation du ‘$’ pour faire correspondre la
     fin d’une ligne ; à lui seul, il ne correspondra pas à la fin d’une
     nouvelle ligne.

9.7.4 Recherche de fichiers
---------------------------

Cette section documente les procédures pour chercher et filtrer des
fichiers.

 -- Procédure Scheme : file-name-predicate REGEXP
     Renvoie un prédicat qui devient vrai lorsqu’on lui passe un nom de
     fichier dont le nom de base correspond à REGEXP.

 -- Procédure Scheme : find-files DIR [PRED] [#:stat lstat]
          [#:directories ? #f] [#:fail-on-error ? #f]
     Renvoie la liste des fichiers triés lexicographiquement sous DIR
     pour lesquels PRED renvoie « vrai ». Deux arguments sont passés à
     PRED : le nom absolu du fichier et son tampon stat ; le prédicat
     par défaut renvoie toujours « vrai ». PRED peut également être une
     expression régulière, auquel cas elle est équivalente à
     ‘(file-name-predicate PRED)’. STAT est utilisé pour obtenir des
     informations sur les fichiers ; l’utilisation de ‘lstat’ signifie
     que les liens symboliques ne sont pas suivis. Si DIRECTORIES? est
     vrai, alors les répertoires seront également inclus. Si
     FAIL-ON-ERROR? est vrai, il lance une exception en cas d’erreur.

   Voici quelques exemples où nous supposons que le répertoire actuel
est la racine de l’arborescence des sources de Guix :

     ;; Liste tous les fichiers normaux dans le répertoire actuel.
     (find-files ".")
     ⇒ ("./.dir-locals.el" "./.gitignore" ...)

     ;; Liste tous les fichiers .scm sous gnu/services.
     (find-files "gnu/services" "\\.scm$")
     ⇒ ("gnu/services/admin.scm" "gnu/services/audio.scm" ...)

     ;; Liste les fichiers ar dans le répertoire actuel.
     (find-files "." (lambda (file stat) (ar-file? file)))
     ⇒ ("./libformat.a" "./libstore.a" ...)

 -- Procédure Scheme : which PROGRAMME
     Renvoie le nom complet du fichier pour PROGRAMME tel qu’il se
     trouve dans ‘$PATH’, ou ‘#f’ si PROGRAMME n’a pas pu être trouvé.

 -- Procédure Scheme : search-input-file ENTRÉES NOM
 -- Procédure Scheme : search-input-directory ENTRÉES NOM
     Renvoie le nom de fichier complet de NOM trouvé dans ENTRÉES ;
     ‘search-input-file’ recherche les fichiers normaux et
     ‘search-input-directory’ recherche les dossiers. Si NOM n’est pas
     trouvé, une exception est levée.

     Ici, ENTRÉES doit être une liste d’association comme les variables
     ‘inputs’ et ‘native-inputs’ disponibles dans les phases de
     construction (*note Phases de construction::).

   Voici un exemple (simplifié) d’utilisation de ‘search-input-file’
dans une phase de construction du paquet ‘wireguard-tools’ :

     (add-after 'install 'wrap-wg-quick
       (lambda* (#:key inputs outputs #:allow-other-keys)
         (let ((coreutils (string-append (assoc-ref inputs "coreutils")
                                         "/bin")))
           (wrap-program (search-input-file outputs "bin/wg-quick")
             #:sh (search-input-file inputs "bin/bash")
             `("PATH" ":" prefix ,(list coreutils))))))

9.7.5 Invocation de programme
-----------------------------

Vous trouverez des procédures pratiques pour invoquer des processus dans
ce module, en particulier des enveloppes pratiques autour de ‘system*’
de Guile (*note ‘system*’: (guile)Processes.).

 -- Procédure Scheme : invoke PROGRAMME ARGS...
     Invoque le PROGRAMME avec les ARGS donnés. Lève une exception
     ‘&invoke-error’ si le code de retour n’est pas zéro ; sinon renvoie
     ‘#t’.

     L’avantage par rapport à ‘system*’ c’est que vous n’avez pas besoin
     de vérifier la valeur de sortie. Cela réduit le code dans les
     petits scripts comme par exemple dans les phases de construction
     des paquets.

 -- Procédure Scheme : invoke-error? C
     Renvoie vrai si C est une condition ‘&invoke-error’.

 -- Procédure Scheme : invoke-error-program C
 -- Procédure Scheme : invoke-error-arguments C
 -- Procédure Scheme : invoke-error-exit-status C
 -- Procédure Scheme : invoke-error-term-signal C
 -- Procédure Scheme : invoke-error-stop-signal C
     Accède aux champs de C, une condition ‘&invoke-error’.

 -- Procédure Scheme : report-invoke-error C [PORT]
     Rapporte C, une condition ‘&invoke-error’, sur PORT (par défaut le
     port d’erreur actuel), dans un format humainement lisible.

     L’utilisation habituelle ressemblerait à ceci :

          (use-modules (srfi srfi-34) ;pour « guard »
                       (guix build utils))

          (guard (c ((invoke-error? c)
                     (report-invoke-error c)))
            (invoke "date" "--option-imaginaire"))

          ⊣ command "date" "--option-imaginaire" failed with status 1

 -- Procédure Scheme : invoke/quiet PROGRAMME ARGS...
     Invoque PROGRAMME avec ARGS et capture la sortie standard et
     l’erreur standard de PROGRAMME. Si PROGRAMME termine sans erreur,
     n’affiche rien et renvoie la valeur non spécifiée ; sinon, lève une
     condition d’erreur ‘&message’ qui inclut le code de statut et la
     sortie de PROGRAMME.

     Voici un exemple :

          (use-modules (srfi srfi-34) ;pour « guard »
                       (srfi srfi-35) ;pour « message-condition? »
                       (guix build utils))

          (guard (c ((message-condition? c)
                     (display (condition-message c))))
            (invoke/quiet "date")  ; tout va bien
            (invoke/quiet "date" "--imaginary-option"))

          ⊣ 'date --imaginary-option' exited with status 1; output follows:

              date : option non reconnue '--imaginary-option'
            Saisissez « date --help » pour plus d'informations.

9.7.6 Phases de construction
----------------------------

Le ‘(guix build utils)’ contient également des outils permettant de
manipuler les phases de construction telles qu’elles sont utilisées par
les systèmes de construction (*note Systèmes de construction::). Les
phases de construction sont représentées sous forme de listes
d’associations ou « alists » (*note (guile)Association Lists::) où
chaque clé est un symbole désignant la phase et où la valeur associée
est une procédure (*note Phases de construction::).

   Le noyau Guile et le module ‘(srfi srfi-1)’ fournissent tous deux des
outils pour manipuler les alignements. Le module ‘(guix build utils)’
complète ces outils avec des outils écrits en tenant compte des phases
de construction.

 -- Syntaxe Scheme : modify-phases PHASES CLAUSE...
     Modifie PHASES séquentiellement selon chaque CLAUSE, qui peut avoir
     l’une des formes suivantes :

          (delete OLD-PHASE-NAME)
          (replace OLD-PHASE-NAME NEW-PHASE)
          (add-before OLD-PHASE-NAME NEW-PHASE-NAME NEW-PHASE)
          (add-after OLD-PHASE-NAME NEW-PHASE-NAME NEW-PHASE)

     Où chaque PHASE-NAME ci-dessus est une expression s’évaluant en un
     symbole, et NEW-PHASE une expression évaluant à une procédure.

   L’exemple ci-dessous est tiré de la définition du paquet ‘grep’. Il
ajoute une phase à exécuter après la phase ‘install’, appelée
‘fix-egrep-and-fgrep’. Cette phase est une procédure (‘lambda*’ pour les
procédures anonymes) qui prend un paramètre nommé ‘#:outputs’ et ignore
les paramètres nommés supplémentaires (*note (guile)Optional
Arguments::, pour en savoir plus sur ‘lambda*’ et les arguments
optionnels et nommés). La phase utilise ‘substitute*’ pour modifier les
scripts ‘egrep’ et ‘fgrep’ installés afin qu’ils se réfèrent à ‘grep’
par son nom de fichier absolu :

     (modify-phases %standard-phases
       (add-after 'install 'fix-egrep-and-fgrep
         ;; Corrige « egrep » et « fgrep » pour exécuter « grep » via son
         ;; nom de fichier absolu au lieu de le chercher dans $PATH.
         (lambda* (#:key outputs #:allow-other-keys)
           (let* ((out (assoc-ref outputs "out"))
                  (bin (string-append out "/bin")))
             (substitute* (list (string-append bin "/egrep")
                                (string-append bin "/fgrep"))
               (("^exec grep")
                (string-append "exec " bin "/grep")))))))

   Dans l’exemple ci-dessous, les phases sont modifiées de deux façons :
la phase standard ‘configure’ est supprimée, vraisemblablement parce que
le paquet n’a pas de script ‘configure’ ou quelque chose de similaire,
et la phase par défaut ‘install’ est remplacée par une phase qui copie
manuellement les fichiers exécutables à installer :

     (modify-phases %standard-phases
       (delete 'configure)      ;pas de script « configure »
       (replace 'install
         (lambda* (#:key outputs #:allow-other-keys)
           ;; Le Makefile du paquet ne fournit pas de règle « install »
           ;; alors on le fait nous-mêmes.
           (let ((bin (string-append (assoc-ref outputs "out")
                                     "/bin")))
             (install-file "footswitch" bin)
             (install-file "scythe" bin)))))

9.7.7 Enveloppes
----------------

Il est courant qu’une commande ait besoin que certaines variables
d’environnement soient initialisées pour fonctionner correctement,
souvent des chemins de recherche (*note Chemins de recherche::). Sans
cela, la commande peut échouer à trouver les fichiers et les autres
commandes dont elle a besoin, ou elle pourrait trouver la « mauvaise »
dépendance — en dépendant de l’environnement sur lequel elle tourne.
Voici quelques exemples :

   • un script shell qui suppose que toutes les commandes qu’il utilise
     sont dans ‘PATH’ ;

   • un programme Guile qui suppose que tous ses modules sont dans
     ‘GUILE_LOAD_PATH’ et ‘GUILE_LOAD_COMPILED_PATH’ ;

   • une application Qt qui s’attend à trouver certains greffons dans
     ‘QT_PLUGIN_PATH’.

   Pour l’auteur ou l’autrice d’un paquet, le but est de s’assurer que
les commandes fonctionnent toujours pareil plutôt que de dépendre de
paramètres externes. Une manière d’y arriver est d’“envelopper” les
commandes dans un petit script qui défini ces variables d’environnement,
ce qui assure que ces dépendances à l’exécution seront trouvées.
L’enveloppe serait utilisée pour initialiser ‘PATH’, ‘GUILE_LOAD_PATH’
ou ‘QT_PLUGIN_PATH’ dans les exemple ci-dessus.

   Pour faciliter cette tâche, le module ‘(guix build utils)’ fournit
quelques fonctions auxiliaires pour envelopper des commandes.

 -- Procédure Scheme : wrap-program PROGRAMME [#:sh SH] [#:rest
          VARIABLES]
     Crée une enveloppe pour PROGRAMME. VARIABLES doit ressembler à ceci
     :

          '(VARIABLE DÉLIMITEUR POSITION LISTE-DE-RÉPERTOIRES)

     où DÉLIMITEUR est facultatif. ‘:’ sera utilisé si DÉLIMITEUR n’est
     pas fourni.

     Par exemple, cet appel :

          (wrap-program "toto"
                        '("PATH" ":" = ("/gnu/.../titi/bin"))
                        '("CERT_PATH" suffix ("/gnu/.../tata/certs"
                                              "/qux/certs")))

     copiera ‘toto’ dans ‘.toto-real’ et créera le fichier ‘toto’ avec
     le contenu suivant :

          #!emplacement/de/bin/bash
          export PATH="/gnu/.../titi/bin"
          export CERT_PATH="$CERT_PATH${CERT_PATH:+:}/gnu/.../tata/certs:/qux/certs"
          exec -a $0 emplacement/de/.foo-real "$@"

     Si PROGRAMME a déjà été enveloppé par ‘wrap-program’, l’enveloppe
     est agrandie avec les définitions de VARIABLES. Sinon, SH sera
     utilisé comme interpréteur.

 -- Procédure Scheme : wrap-script PROGRAMME [#:guile GUILE] [#:rest
          VARIABLES]
     Enveloppe le script PROGRAMME pour que VARIABLES soient définie
     avant. Le format de VARIABLES est le même que pour la procédure
     ‘wrap-program’. Cette procédure est différente de ‘wrap-program’
     car elle ne crée pas de script shell séparé. Au lieu de cela,
     PROGRAM est modifié directement en ajoutant un script Guile au
     début, qui est interprété comme un commentaire par le langage de
     script.

     Les commentaires à l’encodage spécifique pris en charge par Python
     sont recréés sur la seconde ligne.

     Remarquez que cette procédure ne peut être utilisée qu’une seule
     fois par fichier car les scripts Guile ne sont pas pris en charge.


File: guix.fr.info,  Node: Chemins de recherche,  Next: Le dépôt,  Prev: Utilitaires de construction,  Up: Interface de programmation

9.8 Chemins de recherche
========================

De nombreux programmes et bibliothèques cherchent leurs données d’entrée
dans un “chemin de recherch”, une liste de répertoire : les shells comme
Bash cherchent des exécutables dans le chemin de recherche des
commandes, un compilateur C cherche des fichiers ‘.h’ dans son chemin de
recherche d’en-têtes, l’interpréteur Python cheche des fichiers ‘.py’
dans son chemin de recherche, le correcteur orthographique a un chemin
de recherche pour les dictionnaires, et cætera.

   Les chemins de recherche peuvent habituellement être définis ou
remplacés par des variables d’environnement (*note (libc)Environment
Variables::). Par exemple, les chemins de recherches mentionnés
ci-dessus peuvent être modifiés en définissant les variables
d’environnement ‘PATH’, ‘C_INCLUDE_PATH’, ‘PYTHONPATH’ (ou
‘GUIX_PYTHONPATH’) et ‘DICPATH’ — vous savez, toutes ces variables comme
PATH que vous devez paramétrer correctement sous peine de voir les
choses « non trouvée ».

   Vous aurez peut-être remarqué en utilisant la ligne de commande, Guix
« sait » quelles variables d’environnement de chemin de recherche
doivent être définies et comment. Quand vous installez des paquets dans
votre profil par défaut, le fichier ‘~/.guix-profile/etc/profile’ est
créé, et vous pouvez le « sourcer » à partir du shell pour initialiser
ces variables. De même, si vous demandez à ‘guix shell’ de créer un
environnement contenant Python et NumPy, une bibliothèque Python, et que
vous passez l’option ‘--search-paths’, il vous parlera de ‘PATH’ et
‘GUIX_PYTHONPATH’ (*note Invoquer guix shell::) :

     $ guix shell python python-numpy --pure --search-paths
     export PATH="/gnu/store/...-profile/bin"
     export GUIX_PYTHONPATH="/gnu/store/...-profile/lib/python3.9/site-packages"

   Si vous omettez ‘--search-paths’, il défini ces variables
d’environnement directement, si bien que Python peut immédiatement
trouver NumPy :

     $ guix shell python python-numpy -- python3
     Python 3.9.6 (default, Jan  1 1970, 00:00:01)
     [GCC 10.3.0] on linux
     Type "help", "copyright", "credits" or "license" for more information.
     >>> import numpy
     >>> numpy.version.version
     '1.20.3'

   Pour que cela fonctionne, la définition du paquet ‘python’ _déclare_
le chemin de recherche qui l’intéresse et sa variable d’environnement
associée, ‘GUIX_PYTHONPATH’. Cela ressemble à ceci :

     (package
       (name "python")
       (version "3.9.9")
       ;; quelques champs omis...
       (native-search-paths
        (list (search-path-specification
               (variable "GUIX_PYTHONPATH")
               (files (list "lib/python/3.9/site-packages"))))))

   Ce qui ce champ ‘native-search-paths’ signifie que lorsque le paquet
‘python’ est utilisé, la variable d’environnement ‘GUIX_PYTHONPATH’ doit
être définie et inclure tous les sous-répertoires
‘lib/python/3.9/site-packages’ rencontrés dans son environnement.
(‘native-’ signifie que, dans un environnement de compilation croisée,
seules les entrées natives seront ajoutées au chemin de recherche ;
*note ‘search-paths’: référence de package.) Dans l’exemple NumPy
ci-dessus, le profil où ‘python’ apparait contient exactement un de ces
sous-répertoires, et ‘GUIX_PYTHONPATH’ est initialisé à cette valeur.
Lorsqu’il y a plusieurs ‘lib/python/3.9/site-packages’ — c’est le cas
dans l’environnement de construction des paquets — ils sont ajoutés à
‘GUIX_PYTHONPATH’, séparés par des deux-points (‘:’).

     Remarque : Remarquez que ‘GUIX_PYTHONPATH’ est spécifié dans la
     définition du paquet ‘python’, et _pas_ dans celle de
     ‘python-numpy’. C’est parce que cette variable d’environnement «
     appartient » à Python, pas à NumPy : Python lit effectivement la
     valeur de cette variable et la prend en compte.

     Corollaire : si vous créez un profil qui ne contient pas ‘python’,
     ‘GUIX_PYTHONPATH’ ne sera _pas_ défini, même s’il contient des
     paquets qui fournissent des fichiers ‘.py’ :

          $ guix shell python-numpy --search-paths --pure
          export PATH="/gnu/store/...-profile/bin"

     Cela a plus de sens si on considère ce profil individuellement
     : aucun logiciel de ce profil ne lirait ‘GUIX_PYTHONPATH’.

   Bien sûr, il y a de nombreuses variations sur ce thème : certains
paquets prennent en compte plus d’un chemin de recherche, certains
utiliser d’autres séparateurs que le deux-points, certains accumulent
plusieurs répertoires dans leur chemin de recherche, etc. Un exemple
plus complexe est le chemin de recherche de libxml2 : la valeur de la
variable d’environnement ‘XML_CATALOG_FILES’ utilise des espaces pour
séparer ses composants, elle doit contenir une liste de fichiers
‘catalog.xml’ (pas des répertoires), qui doivent se trouver dans des
sous-répertoires ‘xml’ — rien de moins. La spécification du chemin de
recherche ressemble à ceci :

     (package
       (name "libxml2")
       ;; certains champs sont omis
       (native-search-paths
        (list (search-path-specification
               (variable "XML_CATALOG_FILES")
               (separator " ")
               (files '("xml"))
               (file-pattern "^catalog\\.xml$")
               (file-type 'regular)))))

   Ne vous inquiétez pas, les spécifications de chemins de recherche ne
sont généralement pas aussi complexes.

   Le module ‘(guix search-paths)’ défini le type de donnée des
spécifications de chemins de recherche et un certain nombre de
procédures auxiliaires. Vous trouverez ci-dessous la référence des
spécifications de chemins de recherche.

 -- Type de données : search-path-specification
     Le type de données représentant les spécifications de chemins de
     recherche.

     ‘variable’
          le nom de la variable d’environnement pour ce chemin de
          recherche (une chaine).

     ‘files’
          La liste des sous-répertoires (des chaines) qui devraient être
          ajoutés au chemin de recherche.

     ‘separator’ (par défaut : ‘":"’)
          La chaine utilisée pour séparer les composants du chemin de
          recherche.

          Un cas spécial, quand ‘separator’ vaut ‘#f’, signifie qu’il
          n’y a « qu’un composant au chemin de recherche » — en d’autres
          termes, le chemin de recherche ne peut contenir plus d’un
          élément. C’est utile dans certains cas, comme la variable
          ‘SSL_CERT_DIR’ (prise en compte par OpenSSL, cURL, et quelques
          autres paquets) ou la variable ‘ASPELL_DICT_DIR’ (prise en
          compte par le correcteur orthographique GNU Aspell), toutes
          deux devant pointer vers un unique répertoire.

     ‘file-type’ (par défaut : ‘'directory’)
          Le type de fichier qui doit être trouvé — ‘'directory’ ou
          ‘'regular’, même si cela peut aussi être n’importe quel
          symbole renvoyé par ‘stat:type’ (*note ‘stat’: (guile)File
          System.).

          Dans l’exemple libxml2 plus haut, on cherche des fichiers
          normaux ; dans l’exemple Python, on cherche des répertoires.

     ‘file-pattern’ (par défaut : ‘#f’)
          Cela doit être soit ‘#f’, soit une expression régulière qui
          spécifie les fichiers à trouver _à l’intérieur_ des
          sous-répertoires spécifiés par le champ ‘files’.

          De nouveau, l’exemple libxml2 montre une situation où cela est
          nécessaire.

   Certains chemins de recherche ne sont pas liés à une seul paquet,
mais à plusieurs. Pour réduire la duplication, certains sont prédéfinis
dans ‘(guix search-paths)’.

 -- Variable Scheme : $SSL_CERT_DIR
 -- Variable Scheme : $SSL_CERT_FILE
     Ces deux chemins de recherche indiquent où trouver les certificats
     X.509 (*note Certificats X.509::).

   Ces chemins de recherche prédéfinis peuvent être utilisés comme dans
l’exemple suivant :

     (package
       (name "curl")
       ;; certains champs sont omis ...
       (native-search-paths (list $SSL_CERT_DIR $SSL_CERT_FILE)))

   Comment transformer des spécifications de chemins de recherche d’un
côté en et un tas de répertoire de l’autre en un ensemble de définitions
de variables d’environnement ? C’est le travail de
‘evaluate-search-paths’.

 -- Procédure Scheme : evaluate-search-paths SEARCH-PATHS DIRECTORIES
          [GETENV]
     Évalue SEARCH-PATHS, une liste de spécifications de chemins de
     recherche, par rapport à DIRECTORIES, une liste de noms de
     répertoires, et renvoie une liste de paires de spécification /
     valeur. Utilise GETENV pour déterminer les paramètres actuel et
     rapporter seulement les paramètres qui ne sont pas déjà en place.

   Le module ‘(guix profiles)’ fournit une procédure auxiliaire de
haut-niveau, ‘load-profile’, qui met en place les variables
d’environnement d’un profil.


File: guix.fr.info,  Node: Le dépôt,  Next: Dérivations,  Prev: Chemins de recherche,  Up: Interface de programmation

9.9 Le dépôt
============

Conceptuellement, le “dépôt” est l’endroit où les dérivations qui ont
bien été construites sont stockées — par défaut, ‘/gnu/store’. Les
sous-répertoires dans le dépôt s’appellent des “éléments du dépôt” ou
parfois des “chemins du dépôt”. Le dépôt a une base de données associée
qui contient des informations comme les chemins du dépôt auxquels se
réfèrent chaque chemin du dépôt et la liste des éléments du dépôt
_valides_ — les résultats d’une construction réussie. Cette base de
données se trouve dans ‘LOCALSTATEDIR/guix/db’ où LOCALSTATEDIR est le
répertoire d’états spécifié via ‘--localstatedir’ à la configuration,
typiquement ‘/var’.

   C’est _toujours_ le démon qui accède au dépôt pour le compte de ses
clients (*note Invoquer guix-daemon::). Pour manipuler le dépôt, les
clients se connectent au démon par un socket Unix-domain, envoient une
requête dessus et lisent le résultat — ce sont des appels de procédures
distantes, ou RPC.

     Remarque : Les utilisateurs ne doivent _jamais_ modifier les
     fichiers dans ‘/gnu/store’ directement. Cela entraînerait des
     incohérences et casserait l’hypothèse d’immutabilité du modèle
     fonctionnel de Guix (*note Introduction::).

     *Note ‘guix gc --verify’: Invoquer guix gc, pour des informations
     sur la manière de vérifier l’intégrité du dépôt et d’essayer de
     réparer des modifications accidentelles.

   Le module ‘(guix store)’ fournit des procédures pour se connecter au
démon et pour effectuer des RPCs. Elles sont décrites plus bas. Par
défaut, ‘open-connection’, et donc toutes les commandes ‘guix’ se
connectent au démon local ou à l’URI spécifiée par la variable
d’environnement ‘GUIX_DAEMON_SOCKET’.

 -- Variable d'environnement : GUIX_DAEMON_SOCKET
     Lorsqu’elle est initialisée, la valeur de cette variable devrait
     être un nom de fichier ou une URI qui désigne l’extrémité du démon.
     Lorsque c’est un nom de fichier, il dénote un socket Unix-domain où
     se connecter. En plus des noms de fichiers, les schémas d’URI
     supportés sont :

     ‘file’
     ‘unix’
          Pour les sockets Unix-domain.
          ‘file:///var/guix/daemon-socket/socket’ est équivalent à
          ‘/var/guix/daemon-socket/socket’.

     ‘guix’
          Ces URI dénotent des connexions par TCP/IP, sans chiffrement
          ni authentification de l’hôte distant. L’URI doit spécifier le
          nom d’hôte et éventuellement un numéro de port (par défaut
          44146) :

               guix://master.guix.example.org:1234

          Ce paramétrage est adapté aux réseaux locaux, comme dans le
          cas de grappes de serveurs, où seuls des noms de confiance
          peuvent se connecter au démon de construction sur
          ‘master.guix.example.org’.

          L’option ‘--listen’ de ‘guix-daemon’ peut être utilisé pour
          lui dire d’écouter les connexions TCP (*note ‘--listen’:
          Invoquer guix-daemon.).

     ‘ssh’
          Ces URI vous permettent de vous connecter à un démon distant
          via SSH. Cette fonctionnalité nécessite Guile-SSH (*note
          Prérequis::) et un binaire ‘guile’ fonctionnel dans ‘PATH’ sur
          la machine de destination. Elle prend en charge
          l’authentification par clé publique et GSSAPI. Une URL typique
          pourrait ressembler à ceci :

               ssh://charlie@guix.example.org:22

          Comme pour ‘guix copy’, les fichiers de configuration du
          client OpenSSH sont pris en compte (*note Invoquer guix
          copy::).

     Des schémas d’URI supplémentaires pourraient être supportés dans le
     futur.

          Remarque : La capacité de se connecter à un démon de
          construction distant est considéré comme expérimental à la
          version 1.4.0rc2. Contactez-nous pour partager vos problèmes
          ou des suggestions que vous pourriez avoir (*note
          Contribuer::).

 -- Procédure Scheme : open-connection [URI] [#:reserve-space? #t]
     Se connecte au démon à travers le socket Unix-domain à URI (une
     chaîne de caractères). Lorsque RESERVE-SPACE? est vrai, cela
     demande de réserver un peu de place supplémentaire sur le système
     de fichiers pour que le ramasse-miette puisse opérer au cas où le
     disque serait plein. Renvoie un objet serveur.

     FILE prend par défaut la valeur ‘%default-socket-path’, qui est
     l’emplacement normal compte tenu des options qui ont été passées à
     ‘configure’.

 -- Procédure Scheme : close-connection SERVER
     Ferme la connexion au SERVEUR.

 -- Variable Scheme : current-build-output-port
     Cette variable est liée à un paramètre SRFI-39, qui se réfère au
     port où les journaux de construction et d’erreur envoyés par le
     démon devraient être écrits.

   Les procédures qui font des RPC prennent toutes un objet serveur
comme premier argument.

 -- Procédure Scheme : valid-path? SERVER PATH
     Renvoie ‘#t’ lorsque PATH désigne un élément valide du dépôt et
     ‘#f’ sinon (un élément invalide peut exister sur le disque mais
     être toujours invalide, par exemple parce qu’il est le résultat
     d’une construction avortée ou échouée).

     Une condition ‘&store-protocol-error’ est levée si PATH n’est pas
     préfixée par le répertoire du dépôt (‘/gnu/store’).

 -- Procédure Scheme : add-text-to-store SERVER NAME TEXT [REFERENCES]
     Ajoute TEXT dans le fichier NAME dans le dépôt et renvoie son
     chemin. REFERENCES est la liste des chemins du dépôt référencés par
     le chemin du dépôt qui en résulte.

 -- Procédure Scheme : build-derivations STORE DERIVATIONS
     [MODE] Construit DERIVATIONS, une liste d’objets ‘<derivation>’, de
     noms de fichiers ‘.drv’, ou de paires dérivation/sortie, en
     utilisant le MODE—‘(build-mode normal)’ spécifié par défaut.

   Remarque que le module ‘(guix monads)’ fournit une monade ainsi que
des version monadiques des procédures précédentes, avec le but de rendre
plus facile de travailler avec le code qui accède au dépôt (*note La
monade du dépôt::).

   Cette section est actuellement incomplète.


File: guix.fr.info,  Node: Dérivations,  Next: La monade du dépôt,  Prev: Le dépôt,  Up: Interface de programmation

9.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 sorties de la dérivation — les dérivations produisent au moins
     un fichier ou répertoire dans le dépôt, mais peuvent en produire
     plus.

   • Les entrées des dérivations - c’est-à-dire leurs dépendances de
     temps de construction - qui peuvent être d’autres dérivations ou
     des fichiers simples dans le dépôt (patchs, scripts de
     construction, etc.).

   • Le type de système ciblé par la dérivation — p.ex. ‘x86_64-linux’.

   • Le nom de fichier d’un script de construction dans le dépôt avec
     les arguments à lui passer.

   • Une liste de variables d’environnement à définir.

   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 (*note 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’ (*note 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 Scheme : 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 (*note Réglages du déchargement du démon::).
     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 (*note
     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, *note
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 Scheme : 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 => ...>


File: guix.fr.info,  Node: La monade du dépôt,  Next: G-Expressions,  Prev: Dérivations,  Up: Interface de programmation

9.11 La monade du dépôt
=======================

Les procédures qui travaillent sur le dépôt décrites dans les sections
précédentes prennent toutes une connexion ouverte au démon de
construction comme premier argument. Bien que le modèle sous-jacent soit
fonctionnel, elles ont soit des effets de bord, soit dépendent de l’état
actuel du dépôt.

   Le premier point est embêtant : on doit se balader avec la connexion
au démon dans toutes ces fonctions, ce qui rend impossible le fait de
composer des fonctions qui ne prennent pas ce paramètre avec des
fonctions qui le prennent. Le deuxième point est problématique : comme
les opérations sur le dépôt ont des effets de bord ou dépendent d’états
externes, elles doivent être enchaînés correctement.

   C’est là que le module ‘(guix monads)’ arrive à la rescousse. Ce
module fournit un cadre pour travailler avec des “monads”, en
particulier une monade très utile pour notre usage, la “monade du
dépôt”. Les monades sont des constructions qui permettent deux choses :
associer un « contexte » avec une valeur (dans notre cas, le contexte
est le dépôt) et construire une séquence de calculs (ici les calculs
comprennent des accès au dépôt). Les valeurs dans une monade — les
valeurs qui contiennent ce contexte supplémentaire — sont appelées des
“valeurs monadiques” ; les procédures qui renvoient ce genre de valeur
sont appelées des “procédures monadiques”.

   Considérez cette procédure « normale » :

     (define (sh-symlink store)
       ;; Renvoie une dérivation qui crée un lien symbolique vers l'exécutable « bash ».
       (let* ((drv (package-derivation store bash))
              (out (derivation->output-path drv))
              (sh  (string-append out "/bin/bash")))
         (build-expression->derivation store "sh"
                                       `(symlink ,sh %output))))

   En utilisant ‘(guix monads)’ et ‘(guix gexp)’, on peut la réécrire en
une fonction monadique :

     (define (sh-symlink)
       ;; Pareil, mais renvoie une valeur monadique.
       (mlet %store-monad ((drv (package->derivation bash)))
         (gexp->derivation "sh"
                           #~(symlink (string-append #$drv "/bin/bash")
                                      #$output))))

   Il y a plusieurs choses à remarquer avec cette deuxième version : le
paramètre ‘store’ est maintenant implicitement « enfilé » dans les
appels aux procédures monadiques ‘package->derivation’ et
‘gexp->derivation’, et la valeur monadique renvoyée par
‘package->derivation’ est “liée” avec ‘mlet’ plutôt qu’avec un simple
‘let’.

   Il se trouve que l’appel à ‘package->derivation’ peut même être omis
puisqu’il aura lieu implicitement, comme nous le verrons plus tard
(*note G-Expressions::) :

     (define (sh-symlink)
       (gexp->derivation "sh"
                         #~(symlink (string-append #$bash "/bin/bash")
                                    #$output)))

   L’appel à la procédure monadique ‘sh-symlink’ n’a aucun effet. Comme
on pourrait le dire, « on sort d’une monade comme de la monarchie : en
l’exécutant »(1). Donc, pour sortir de la monade et obtenir l’effet
escompté, on doit utiliser ‘run-with-store’ :

     (run-with-store (open-connection) (sh-symlink))
     ⇒ /gnu/store/...-sh-symlink

   Remarquez que le module ‘(guix monad-repl)’ étend la console Guile
avec de nouvelles « commandes » pour rendre plus facile la manipulation
de procédures monadiques : ‘run-in-store’ et ‘enter-store-monad’ (*note
Utiliser Guix de manière interactive::). La première est utilisée pour «
lancer » une seule valeur monadique à travers le dépôt :

     scheme@(guile-user)> ,run-in-store (package->derivation hello)
     $1 = #<derivation /gnu/store/...-hello-2.9.drv => ...>

   La deuxième entre dans une console récursive, où toutes les valeurs
de retour sont automatiquement lancées à travers le dépôt :

     scheme@(guile-user)> ,enter-store-monad
     store-monad@(guile-user) [1]> (package->derivation hello)
     $2 = #<derivation /gnu/store/...-hello-2.9.drv => ...>
     store-monad@(guile-user) [1]> (text-file "toto" "Hello!")
     $3 = "/gnu/store/...-toto"
     store-monad@(guile-user) [1]> ,q
     scheme@(guile-user)>

Remarquez qu’on ne peut pas renvoyer de valeur non monadique dans la
console ‘store-monad’.

   D’autres méta-commandes sont disponibles sur la REPL, comme ‘,build’
pour construire un objet simili-fichier (*note Utiliser Guix de manière
interactive::).

   Les formes syntaxiques principales pour utiliser des monades en
général sont disponibles dans le module ‘(guix monads)’ et sont décrites
ci-dessous.

 -- Syntaxe Scheme : with-monad MONAD BODY ...
     Évalue n’importe quelle forme ‘>>=’ ou ‘return’ dans BODY comme une
     MONAD.

 -- Syntaxe Scheme : return VAL
     Renvoie une valeur monadique qui encapsule VAL.

 -- Syntaxe Scheme : >>= MVAL MPROC ...
     “Lie” une valeur monadique MVAL, en passant son « contenu » aux
     procédures monadiques MPROC...(2). Il peut y avoir une ou plusieurs
     ‘mproc’, comme dans cet exemple :

          (run-with-state
              (with-monad %state-monad
                (>>= (return 1)
                     (lambda (x) (return (+ 1 x)))
                     (lambda (x) (return (* 2 x)))))
            'some-state)

          ⇒ 4
          ⇒ some-state

 -- Syntaxe Scheme : mlet MONAD ((VAR MVAL) ...) BODY ...
 -- Syntaxe Scheme : mlet* MONAD ((VAR MVAL) ...) BODY ...
     Lie les variables VAR aux valeurs monadiques MVAL dans BODY, une
     séquence d’expressions. Comme avec l’opérateur de liaison, on peut
     réfléchir comme si on « ouvrait » la valeur non-monadique «
     contenue » dans MVAL et comme si on faisait en sorte que VAR se
     réfère à cette valeur pure, non-monadique, dans la portée de BODY.
     La forme (VAR -> VAL) lie VAR à la valeur « normale » VAL, comme
     ‘let’. L’opération de liaison a lieu en séquence de la gauche vers
     la droite. La dernière expression de BODY doit être une expression
     monadique et son résultat deviendra le résultat de ‘mlet’ ou
     ‘mlet*’ lorsque lancé dans la MONAD.

     ‘mlet*’ est à ‘mlet’ ce que ‘let*’ est à ‘let’ (*note (guile)Local
     Bindings::).

 -- Système Scheme : mbegin MONAD MEXP ...
     Lie MEXP et les expressions monadiques suivantes en séquence, et
     renvoie le résultat de la dernière expression. Chaque expression
     dans la séquence doit être une expression monadique.

     Cette procédure est similaire à ‘mlet’, sauf que les valeurs de
     retour des expressions monadiques sont ignorées. Dans ce sens, elle
     est analogue à ‘begin’, mais appliqué à des expressions monadiques.

 -- Système Scheme : mwhen CONDITION MEXP0 MEXP* ...
     Lorsque la CONDITION est vraie, évalue la séquence des expressions
     monadiques MEXP0..MEXP* comme dans un ‘mbegin’. Lorsque la
     CONDITION est fausse, renvoie ‘*unspecified*’ dans la monade
     actuelle. Chaque expression dans la séquence doit être une
     expression monadique.

 -- Système Scheme : munless CONDITION MEXP0 MEXP* ...
     Lorsque la CONDITION est fausse, évalue la séquence des expressions
     monadiques MEXP0..MEXP* comme dans un ‘mbegin’. Lorsque la
     CONDITION est vraie, renvoie ‘*unspecified*’ dans la monade
     actuelle. Chaque expression dans la séquence doit être une
     expression monadique.

   Le module ‘(guix monads)’ fournit la “monade d’état” qui permet à une
valeur supplémentaire — l’état — d’être enfilée à travers les appels de
procédures.

 -- Variable Scheme : %state-monad
     La monade d’état. les procédure dans la monade d’état peuvent
     accéder et modifier l’état qui est enfilé.

     Considérez l’exemple ci-dessous. La procédure ‘square’ renvoie une
     valeur dans la monade d’état. Elle renvoie le carré de son
     argument, mais incrémente aussi la valeur actuelle de l’état :

          (define (square x)
            (mlet %state-monad ((count (current-state)))
              (mbegin %state-monad
                (set-current-state (+ 1 count))
                (return (* x x)))))

          (run-with-state (sequence %state-monad (map square (iota 3))) 0)
          ⇒ (0 1 4)
          ⇒ 3

     Lorsque c’est « lancé » à travers ‘%state-monad’, nous obtenons
     cette valeur d’état supplémentaire, qui est le nombre d’appels au
     ‘square’.

 -- Procédure monadique : current-state
     Renvoie l’état actuel dans une valeur monadique.

 -- Procédure monadique : set-current-state VALUE
     Initialise l’état actuel à VALUE et renvoie l’état précédent dans
     une valeur monadique.

 -- Procédure monadique : state-push VALUE
     Pousse VALUE sur l’état actuel, qui est supposé être une liste, et
     renvoie l’état précédent dans une valeur monadique.

 -- Procédure monadique : state-pop
     Récupère (pop) une valeur dans l’état actuel et la renvoie comme
     une valeur monadique. L’état est supposé être une liste.

 -- Procédure Scheme : run-with-state MVAL [STATE]
     Lance la valeur monadique MVAL avec STATE comme valeur initiale.
     Renvoie deux valeurs : la valeur du résultat et l’état du résultat.

   L’interface principale avec la monade du dépôt, fournit par le module
‘(guix store)’, est la suivante.

 -- Variable Scheme : %store-monad
     La monade du dépôt — un alias pour ‘%state-monad’.

     Les valeurs dans la monade du dépôt encapsulent les accès vers le
     dépôt. Lorsque son effet est nécessaire, une valeur de la monade du
     dépôt doit être « évaluée » en la passant à la procédure
     ‘run-with-store’ (voir ci-dessous).

 -- Procédure Scheme : run-with-store STORE MVAL [#:guile-for-build]
          [#:system (%current-system)]
     Lance MVAL, une valeur monadique dans la monade du dépôt, dans
     STORE, une connexion ouvert au dépôt.

 -- Procédure monadique : text-file NAME TEXT [REFERENCES]
     Renvoie une valeur monadique correspondant au nom de fichier dans
     le dépôt du fichier contenant TEXT, une chaîne de caractères.
     REFERENCES est une liste d’éléments du dépôt auxquels le fichier
     texte en résultat se réfère ; c’est la liste vide par défaut.

 -- Procédure monadique : binary-file NAME DATA [REFERENCES]
     Renvoie une valeur monadique correspondant au nom de fichier absolu
     dans le dépôt du fichier contenant DATA, un vecteur d’octets.
     REFERENCES est une liste d’éléments du dépôt auxquels le fichier
     binaire en résultat se réfère ; c’est la liste vide par défaut.

 -- Procédure monadique : interned-file FILE [NAME] [#:recursive? #t]
          [#:select? (const #t)]
     Renvoie le nom de FILE une fois ajouté au dépôt. Utilise NAME comme
     nom dans le dépôt ou le nom de fichier de FILE si NAME est omis.

     Lorsque RECURSIVE? est vraie, le contenu de FILE est ajouté
     récursivement ; si FILE désigne un fichier simple et que RECURSIVE?
     est vrai, son contenu est ajouté et ses bits de permissions sont
     préservés.

     Lorsque RECURSIVE? est vraie, appelle ‘(SELECT? FILE STAT)’ pour
     chaque répertoire où FILE est le nom de fichier absolu de l’entrée
     et STAT est le résultat de ‘lstat’ ; à l’exception des entrées pour
     lesquelles SELECT? ne renvoie pas vrai.

     L’exemple ci-dessous ajoute un fichier au dépôt, sous deux noms
     différents :

          (run-with-store (open-connection)
            (mlet %store-monad ((a (interned-file "README"))
                                (b (interned-file "README" "LEGU-MIN")))
              (return (list a b))))

          ⇒ ("/gnu/store/rwm...-README" "/gnu/store/44i...-LEGU-MIN")

   Le module ‘(guix packages)’ exporte les procédures monadiques liées
aux paquets suivantes :

 -- Procédure monadique : package-file PACKAGE [FILE] [#:system
          (%current-system)] [#:target #f] [#:output "out"]
     Renvoie une valeur monadique qui contient le nom de fichier absolu
     de FILE dans le répertoire OUTPUT de PACKAGE. Lorsque FILE est
     omis, renvoie le nom du répertoire OUTPUT de PACKAGE. Lorsque
     TARGET est vrai, l’utilise comme un triplet de cible pour la
     compilation croisée.

     Notez que cette procédure ne permet _pas_ de construire PACKAGE.
     Ainsi, le résultat peut ou non désigner un fichier existant. Nous
     vous recommandons de ne pas utiliser cette procédure si vous ne
     savez pas ce que vous faites.

 -- Procédure monadique : package->derivation PACKAGE [SYSTEM]
 -- Procédure monadique : package->cross-derivation PACKAGE TARGET
          [SYSTEM]
     Version monadique de ‘package-derivation’ et
     ‘package-cross-derivation’ (*note Définition des paquets::).

   ---------- Footnotes ----------

   (1) NdT : il y a là un jeu de mot en anglais qui se base sur un
double sens de « run », qui peut se traduire par « exécuter » dans ce
contexte.

   (2) Cette opération est souvent appelée « bind », mais ce nom dénote
une procédure qui n’a rien à voir en Guile. Ainsi, nous empruntons ce
symbole quelque peu cryptique au langage Haskell


File: guix.fr.info,  Node: G-Expressions,  Next: Invoquer guix repl,  Prev: La monade du dépôt,  Up: Interface de programmation

9.12 G-Expressions
==================

On a donc des « dérivations » qui représentent une séquence d’actions de
construction à effectuer pour produire un élément du dépôt (*note
Dérivations::). Ces actions de construction sont effectuées lorsqu’on
demande au démon de construire effectivement les dérivations ; elles
sont lancées par le démon dans un conteneur (*note Invoquer
guix-daemon::).

   Ça ne devrait pas vous surprendre, mais nous aimons écrire ces
actions de construction en Scheme. Lorsqu’on fait ça, on fini avec deux
“strates” de code Scheme(1) : le « code hôte » — le code qui définit les
paquets, parle au démon, etc. — et le « code côté construction » — le
code qui effectue effectivement les actions de construction, comme créer
des répertoires, invoquer ‘make’, etc. (*note Phases de construction::).

   Pour décrire une dérivation et ses actions de construction, on a
typiquement besoin d’intégrer le code de construction dans le code hôte.
Ça revient à manipuler le code de construction comme de la donnée, et
l’homoiconicité de Scheme — le code a une représentation directe en tant
que donnée — est très utile pour cela. Mais on a besoin de plus que le
mécanisme de ‘quasiquote’ en Scheme pour construire des expressions de
construction.

   Le module ‘(guix gexp)’ implémente les “G-expressions”, une forme de
S-expression adaptée aux expressions de construction. Les G-expression,
ou “gexps”, consistent en gros en trois formes syntaxiques : ‘gexp’,
‘ungexp’ et ‘ungexp-splicing’ (ou plus simplement : ‘#~’, ‘#$’ et
‘#$@’), qui sont comparable à ‘quasiquote’, ‘unquote’ et
‘unquote-splicing’ respectivement (*note ‘quasiquote’: (guile)Expression
Syntax.). Cependant il y a des différences majeures :

   • Les Gexps sont conçues pour être écrites dans un fichier et être
     lancées ou manipulées par d’autres processus.

   • Lorsqu’un objet de haut-niveau comme un paquet ou une dérivation
     est unquotée dans une gexp, le résultat est comme si le nom de
     fichier de son résultat avait été introduit.

   • Les gexps transportent des informations sur les paquets ou les
     dérivations auxquels elles se réfèrent, et ces dépendances sont
     automatiquement ajoutées comme des entrées du processus de
     construction qui les utilise.

   Ce mécanisme n’est pas limité aux paquets et aux objets de dérivation
: Des “compilateurs” capables d’ « abaisser » d’autres objets de haut
niveau vers des dérivations ou des fichiers dans le dépôt peuvent être
définis, de sorte que ces objets peuvent également être insérés dans des
gexps. Par exemple, un type utile d’objets de haut niveau pouvant être
insérés dans un gexp est celui des « objets de type fichier », qui
permettent d’ajouter facilement des fichiers au dépôt et d’y faire
référence dans des dérivations et autres (voir ‘local-file’ et
‘plain-file’ ci-dessous).

   Pour illustrer cette idée, voici un exemple de gexp :

     (define build-exp
       #~(begin
           (mkdir #$output)
           (chdir #$output)
           (symlink (string-append #$coreutils "/bin/ls")
                    "list-files")))

   Cette gexp peut être passée à ‘gexp->derivation’ ; on obtient une
dérivation qui construit un répertoire contenant exactement un lien
symbolique à ‘/gnu/store/...-coreutils-8.22/bin/ls’ :

     (gexp->derivation "the-thing" build-exp)

   Comme on pourrait s’y attendre, la chaîne
‘"/gnu/store/...-coreutils-8.22"’ est substituée à la place de la
référence au paquet COREUTILS dans le code de construction final, et
COREUTILS est automatiquement devenu une entrée de la dérivation. De
même, ‘#$output’ (équivalent à ‘(ungexp output)’) est remplacé par une
chaîne de caractères contenant le nom du répertoire de la sortie de la
dérivation.

   Dans le contexte d’une compilation croisée, il est utile de
distinguer entre des références à la construction _native_ d’un paquet —
qui peut être lancé par l’hôte — et des références à la construction
croisée d’un paquet. Pour cela, ‘#+’ joue le même rôle que ‘#$’, mais
référence une construction native d’un paquet :

     (gexp->derivation "vi"
        #~(begin
            (mkdir #$output)
            (mkdir (string-append #$output "/bin"))
            (system* (string-append #+coreutils "/bin/ln")
                     "-s"
                     (string-append #$emacs "/bin/emacs")
                     (string-append #$output "/bin/vi")))
        #:target "aarch64-linux-gnu")

Dans l’exemple ci-dessus, la construction native de COREUTILS est
utilisée, pour que ‘ln’ puisse effectivement être lancé sur l’hôte ;
mais ensuite la construction croisée d’EMACS est utilisée.

   Une autre fonctionnalité, ce sont les “modules importés” : parfois
vous voudriez pouvoir utiliser certains modules Guile de «
l’environnement hôte » dans la gexp, donc ces modules devraient être
importés dans « l’environnement de construction ». La forme
‘with-imported-modules’ vous permet d’exprimer ça :

     (let ((build (with-imported-modules '((guix build utils))
                    #~(begin
                        (use-modules (guix build utils))
                        (mkdir-p (string-append #$output "/bin"))))))
       (gexp->derivation "empty-dir"
                         #~(begin
                             #$build
                             (display "success!\n")
                             #t)))

Dans cet exemple, le module ‘(guix build utils)’ est automatiquement
récupéré dans l’environnement de construction isolé de notre gexp, pour
que ‘(use-modules (guix build utils))’ fonctionne comme on s’y
attendrait.

   Typiquement, vous voudriez que la _closure_ complète du module soit
importé — c.-à-d. le module lui-même et tous les modules dont il dépend
— plutôt que seulement le module ; sinon, une tentative de chargement du
module échouera à cause des modules dépendants manquants. La procédure
‘source-module-closure’ calcule la closure d’un module en cherchant dans
ses en-têtes sources, ce qui est pratique dans ce cas :

     (use-modules (guix modules))   ;pour 'source-module-closure'

     (with-imported-modules (source-module-closure
                              '((guix build utils)
                                (gnu build image)))
       (gexp->derivation "something-with-vms"
                         #~(begin
                             (use-modules (guix build utils)
                                          (gnu build image))
                             ...)))

   Dans la même idée, parfois vous pouvez souhaiter importer non
seulement des modules en Scheme pur, mais aussi des « extensions » comme
des liaisons Guile de bibliothèques C ou d’autres paquet « complets ».
Disons que vous voulez utiliser le paquet ‘guile-json’ du côté de la
construction, voici comme procéder :

     (use-modules (gnu packages guile))  ;pour 'guile-json'

     (with-extensions (list guile-json)
       (gexp->derivation "something-with-json"
                         #~(begin
                             (use-modules (json))
                             ...)))

   La forme syntaxique pour construire des gexps est résumée ci-dessous.

 -- Syntaxe Scheme : #~EXP
 -- Syntaxe Scheme : (gexp EXP)
     Renvoie une G-expression contenant EXP. EXP peut contenir une ou
     plusieurs de ces formes :

     ‘#$OBJ’
     ‘(ungexp OBJ)’
          Introduit une référence à OBJ. OBJ peut être d’un des types
          supportés, par exemple un paquet ou une dérivation, auquel cas
          la forme ‘ungexp’ est remplacée par le nom de fichier de sa
          sortie — p. ex. ‘"/gnu/store/...-coreutils-8.22’.

          Si BOJ est une liste, elle est traversée et les références aux
          objets supportés sont substitués de manière similaire.

          Si OBJ est une autre gexp, son contenu est inséré et ses
          dépendances sont ajoutées à celle de la gexp qui l’entoure.

          Si OBJ est un autre type d’objet, il est inséré tel quel.

     ‘#$OBJ:OUTPUT’
     ‘(ungexp OBJ OUTPUT)’
          Cette forme est similaire à la précédente, mais se réfère
          explicitement à la sortie OUTPUT de l’objet OBJ — c’est utile
          lorsque OBJ produit plusieurs sorties (*note Des paquets avec
          plusieurs résultats::).

     ‘#+OBJ’
     ‘#+OBJ:output’
     ‘(ungexp-native OBJ)’
     ‘(ungexp-native OBJ OUTPUT)’
          Comme ‘ungexp’, mais produit une référence à la construction
          _native_ de OBJ lorsqu’elle est utilisée dans une compilation
          croisée.

     ‘#$output[:OUTPUT]’
     ‘(ungexp output [OUTPUT])’
          Insère une référence à la sortie OUTPUT de la dérivation, ou à
          la sortie principale lorsque OUTPUT est omis.

          Cela ne fait du sens que pour les gexps passées à
          ‘gexp->derivation’.

     ‘#$@LST’
     ‘(ungexp-splicing LST)’
          Comme au dessus, mais recolle (splice) le contenu de LST dans
          la liste qui la contient.

     ‘#+@LST’
     ‘(ungexp-native-splicing LST)’
          Comme au dessus, mais se réfère à la construction native des
          objets listés dans LST.

     Les G-expressions créées par ‘gexp’ ou ‘#~’ sont des objets
     d’exécution du type ‘gexp?’ (voir ci-dessous).

 -- Syntaxe Scheme : with-imported-modules MODULES BODY...
     Marque les gexps définies dans BODY... comme requérant MODULES dans
     leur environnement d’exécution.

     Chaque élément dans MODULE peut être le nom d’un module, comme
     ‘(guix build utils)’ ou le nom d’un module suivi d’une flèche,
     suivie d’un objet simili-fichier :

          `((guix build utils)
            (guix gcrypt)
            ((guix config) => ,(scheme-file "config.scm"
                                            #~(define-module ...))))

     Dans l’exemple au dessus, les deux premiers modules sont récupérés
     dans le chemin de recherche, et le dernier est créé à partir d’un
     objet simili-fichier.

     Cette forme a une portée _lexicale_ : elle a un effet sur les gexp
     directement définies dans BODY..., mais pas sur celles définies
     dans des procédures appelées par BODY....

 -- Syntaxe Scheme : with-extensions EXTENSIONS BODY...
     Marque les gexps définies dans BODY... comme requérant EXTENSIONS
     dans leur environnement de construction et d’exécution. EXTENSIONS
     est typiquement une liste d’objets paquets comme définis dans le
     module ‘(gnu packages guile)’.

     Concrètement, les paquets listés dans EXTENSIONS sont ajoutés au
     chemin de chargement lors de la compilation des modules importés
     dans BODY... ; ils sont aussi ajoutés au chemin de chargement de la
     gexp renvoyée par BODY....

 -- Procédure Scheme : gexp? OBJ
     Renvoie ‘#t’ si OBJ est une G-expression.

   Les G-expressions sont conçues pour être écrites sur le disque, soit
en tant que code pour construire une dérivation, soit en tant que
fichier normal dans le dépôt. Les procédures monadiques suivantes vous
permettent de faire cela (*note La monade du dépôt::, pour plus
d’information sur les monads).

 -- Procédure monadique : gexp->derivation NAME EXP [#:system
          (%current-system)] [#:target #f] [#:graft ? #t] [#:hash #f]
          [#:hash-algo #f] [#:recursive ? #f] [#:env-vars '()]
          [#:modules '()] [#:module-path ‘%load-path’]
          [#:effective-version "2. 2"] [#:references-graphs #f]
          [#:allowed-references #f] [#:disallowed-references #f]
          [#:leaked-env-vars #f] [#:script-name (string-append NAME
          "-builder")] [#:deprecation-warnings #f] [#:local-build ? #f]
          [#:substituable ? #t] [#:properties '()] [#:guile-for-build
          #f]
     Renvoie une dérivation NAME qui exécute EXP (un gexp) avec
     GUILE-FOR-BUILD (une dérivation) sur SYSTEM ; EXP est stocké dans
     un fichier appelé SCRIPT-NAME. Lorsque TARGET est vrai, il est
     utilisé comme le triplet cible de compilation croisée pour les
     paquets auxquels EXP fait référence.

     MODULES est devenu obsolète en faveur de ‘with-imported-modules’.
     Sa signification est de rendre MODULES disponibles dans le contexte
     d’évaluation de EXP ; MODULES est une liste de noms de modules
     Guile qui sont cherchés dans MODULE-PATH pour les copier dans le
     dépôt, les compiler et les rendre disponibles dans le chemin de
     chargement pendant l’exécution de EXP — p. ex. ‘((guix build utils)
     (guix build gnu-build-system))’.

     EFFECTIVE-VERSION détermine la chaîne à utiliser lors d’ajout
     d’extensions de EXP (voir ‘with-extensions’) au chemin de recherche
     — p. ex. ‘"2.2"’.

     GRAFT? détermine si les paquets référencés par EXP devraient être
     greffés si possible.

     Lorsque REFERENCES-GRAPHS est vrai, il doit s’agir d’une liste de
     tuples de la forme suivante :

          (FILE-NAME PACKAGE)
          (FILE-NAME PACKAGE OUTPUT)
          (FILE-NAME DERIVATION)
          (FILE-NAME DERIVATION OUTPUT)
          (FILE-NAME STORE-ITEM)

     La partie droite des éléments de REFERENCES-GRAPHS est
     automatiquement transformée en une entrée du processus de
     construction EXP. Dans l’environnement de construction, chaque
     FILE-NAME contient le graphe des références de l’élément
     correspondant, dans un format texte simple.

     ALLOWED-REFERENCES doit soit être ‘#f’, soit une liste de noms de
     sorties ou de paquets. Dans ce dernier cas, la liste dénote les
     éléments du dépôt auxquels le résultat a le droit de faire
     référence. Toute référence à un autre élément du dépôt conduira à
     une erreur à la construction. Comme pour DISALLOWED-REFERENCES, qui
     peut lister des éléments qui ne doivent pas être référencés par les
     sorties.

     DEPRECATION-WARNINGS détermine s’il faut afficher les avertissement
     d’obsolescence à la compilation de modules. Il peut valoir ‘#f’,
     ‘t’ ou ‘'detailed’.

     Les autres arguments sont les mêmes que pour ‘derivation’ (*note
     Dérivations::).

   Les procédures ‘local-file’, ‘plain-file’, ‘computed-file’,
‘program-file’ et ‘scheme-file’ ci-dessous renvoient des “objets
simili-fichiers”. C’est-à-dire, lorsqu’ils sont unquotés dans une
G-expression, ces objets donnent un fichier dans le dépôt. Considérez
cette G-expression :

     #~(system* #$(file-append glibc "/sbin/nscd") "-f"
                #$(local-file "/tmp/my-nscd.conf"))

   Ici, l’effet est « d’internaliser » ‘/tmp/my-nscd.conf’ en le copiant
dans le dépôt. Une fois étendu, par exemple via ‘gexp->derivation’, la
G-expression se réfère à cette copie dans ‘/gnu/store’ ; ainsi, modifier
ou supprimer le fichier dans ‘/tmp’ n’a aucun effet sur ce que fait la
G-expression. ‘plain-file’ peut être utilisé de la même manière ; elle
est seulement différente par le fait que le contenu du fichier est passé
directement par une chaîne de caractères.

 -- Procédure Scheme : local-file FILE [NAME] [#:recursive ? #f]
          [#:select ? (const #t)]
     Renvoie un objet représentant le fichier local FILE à ajouter au
     magasin ; cet objet peut être utilisé dans un gexp. Si FILE est une
     chaîne littérale désignant un nom de fichier relatif, il est
     recherché par rapport au fichier source où il apparaît ; si FILE
     n’est pas une chaîne littérale, il est recherché par rapport au
     répertoire de travail courant au moment de l’exécution. FILE sera
     ajouté au dépôt sous NAME–par défaut le nom de base de FILE.

     Lorsque RECURSIVE? est vraie, le contenu de FILE est ajouté
     récursivement ; si FILE désigne un fichier simple et que RECURSIVE?
     est vrai, son contenu est ajouté et ses bits de permissions sont
     préservés.

     Lorsque RECURSIVE? est vraie, appelle ‘(SELECT? FILE STAT)’ pour
     chaque répertoire où FILE est le nom de fichier absolu de l’entrée
     et STAT est le résultat de ‘lstat’ ; à l’exception des entrées pour
     lesquelles SELECT? ne renvoie pas vrai.

     C’est la version déclarative de la procédure monadique
     ‘interned-file’ (*note ‘interned-file’: La monade du dépôt.).

 -- Procédure Scheme : plain-file NAME CONTENT
     Renvoie un objet représentant un fichier texte nommé NAME avec pour
     contenu CONTENT (une chaîne de caractères ou un vecteur d’octets) à
     ajouter un dépôt.

     C’est la version déclarative de ‘text-file’.

 -- Procédure Scheme : computed-file NAME GEXP [#:local-build ? #t]
          [#:options '()]
     Renvoie un objet représentant l’élément du dépôt NAME, un fichier
     ou un répertoire calculé par GEXP. Lorsque LOCAL-BUILD? est vrai
     (par défaut), la dérivation est construite localement. OPTIONS est
     une liste d’arguments supplémentaires à passer à
     ‘gexp->derivation’.

     C’est la version déclarative de ‘gexp->derivation’.

 -- Procédure monadique : gexp->script NAME EXP [#:guile
          (default-guile)] [#:module-path %load-path] [#:system
          (%current-system)] [#:target #f]
     Renvoie un script exécutable NAME qui exécute EXP en utilisant
     GUILE, avec les modules importés de EXP dans son chemin de
     recherche. Recherchez les modules de EXP dans MODULE-PATH.

     L’exemple ci-dessous construit un script qui invoque simplement la
     commande ‘ls’ :

          (use-modules (guix gexp) (gnu packages base))

          (gexp->script "list-files"
                        #~(execl #$(file-append coreutils "/bin/ls")
                                 "ls"))

     Lorsqu’elle est « lancée » à travers le dépôt (*note
     ‘run-with-store’: La monade du dépôt.), on obtient une dérivation
     qui produit une fichier exécutable ‘/gnu/store/...-list-files’ qui
     ressemble à :

          #!/gnu/store/...-guile-2.0.11/bin/guile -ds
          !#
          (execl "/gnu/store/...-coreutils-8.22"/bin/ls" "ls")

 -- Procédure Scheme : program-file NAME EXP [#:guile #f] [#:module-path
          %load-path]
     Renvoie un objet représentant un élément du dépôt NAME qui lance
     GEXP. GUILE est le paquet Guile à utiliser pour exécuter le script.
     Les modules importés par GEXP sont recherchés dans MODULE-PATH.

     C’est la version déclarative de ‘gexp->script’.

 -- Procédure monadique : gexp->file NAME EXP [#:set-load-path? #t]
          [#:module-path %load-path] [#:splice? #f] [#:guile
          (default-guile)]
     Renvoie une dérivation qui construit un fichier NAME contenant EXP.
     Lorsque SPLICE? est vrai, EXP est considéré comme une liste
     d’expressions qui seront splicée dans le fichier qui en résulte.

     Lorsque SET-LOAD-PATH? est vrai, émet du code dans le fichier de
     résultat pour initialiser ‘%load-path’ et ‘%load-compiled-path’
     pour prendre en compte les modules importés de EXP. Les modules de
     EXP sont trouvés dans MODULE-PATH.

     Le fichier qui en résulte retient les références à toutes les
     dépendances de EXP ou un sous-ensemble.

 -- Procédure Scheme : scheme-file NAME GEXP [#:splice? #f]
          [#:set-load-path? #t]
     Renvoie un objet représentant le fichier Scheme NAME qui contient
     EXP.

     C’est la version déclarative de ‘gexp->file’.

 -- Procédure monadique : text-file* NAME TEXT ...
     Renvoie une valeur monadique qui construit un ficher texte
     contenant TEXT. TEXT peut lister, en plus de chaînes de caractères,
     des objet de n’importe quel type qui peut être utilisé dans une
     gexp : des paquets, des dérivations, des fichiers objet locaux,
     etc. Le fichier du dépôt qui en résulte en retient toutes les
     références.

     Cette variante devrait être préférée à ‘text-file’ lorsque vous
     souhaitez créer des fichiers qui référencent le dépôt. Cela est le
     cas typiquement lorsque vous construisez un fichier de
     configuration qui contient des noms de fichiers du dépôt, comme
     ceci :

          (define (profile.sh)
            ;; Renvoie le nom d'un script shell dans le dépôt qui initialise
            ;; la variable d'environnement « PATH ».
            (text-file* "profile.sh"
                        "export PATH=" coreutils "/bin:"
                        grep "/bin:" sed "/bin\n"))

     Dans cet exemple, le fichier ‘/gnu/store/...-profile.sh’ qui en
     résulte référence COREUTILS, GREP et SED, ce qui les empêche d’être
     glanés tant que le script est accessible.

 -- Procédure Scheme : mixed-text-file NAME TEXT ...
     Renvoie un objet représentant le fichier du dépôt NAME contenant
     TEXT. TEXT est une séquence de chaînes de caractères et de fichiers
     simili-objets, comme dans :

          (mixed-text-file "profile"
                           "export PATH=" coreutils "/bin:" grep "/bin")

     C’est la version déclarative de ‘text-file*’.

 -- Procédure Scheme : file-union NAME FILES
     Renvoie un ‘<computed-file>’ qui construit un répertoire qui
     contient tous les fichiers de FILES. Chaque élément de FILES doit
     être une paire où le premier élément est le nom de fichier à
     utiliser dans le nouveau répertoire et le second élément est une
     gexp dénotant le fichier cible. Voici un exemple :

          (file-union "etc"
                      `(("hosts" ,(plain-file "hosts"
                                              "127.0.0.1 localhost"))
                        ("bashrc" ,(plain-file "bashrc"
                                               "alias ls='ls --color=auto'"))))

     Cela crée un répertoire ‘etc’ contenant ces deux fichiers.

 -- Procédure Scheme : directory-union NAME THINGS
     Renvoie un répertoire qui est l’union de THINGS, où THINGS est une
     liste d’objets simili-fichiers qui dénotent des répertoires. Par
     exemple :

          (directory-union "guile+emacs" (list guile emacs))

     crée un répertoire qui est l’union des paquets ‘guile’ et ‘emacs’.

 -- Procédure Scheme : file-append OBJ SUFFIX ...
     Renvoie un objet simili-fichier qui correspond à la concaténation
     de OBJ et SUFFIX où OBJ est un objet abaissable et chaque SUFFIX
     est une chaîne de caractères.

     Par exemple, considérez cette gexp :

          (gexp->script "run-uname"
                        #~(system* #$(file-append coreutils
                                                  "/bin/uname")))

     On peut obtenir le même effet avec :

          (gexp->script "run-uname"
                        #~(system* (string-append #$coreutils
                                                  "/bin/uname")))

     Il y a une différence cependant : dans le cas ‘file-append’, le
     script qui en résulte contient le nom de fichier absolu comme une
     chaîne de caractère alors que dans le deuxième cas, le script
     contient une expression ‘(string-append ...)’ pour construire le
     nom de fichier _à l’exécution_.

 -- Syntaxe Scheme : let-system SYSTEM BODY...
 -- Syntaxe Scheme : let-system (SYSTEM TARGET) BODY...
     Lier SYSTEM au système actuellement visé—par exemple,
     ‘"x86_64-linux"’—dans BODY.

     Dans le second cas, lier également TARGET à la cible de compilation
     croisée actuelle–un triplet GNU tel que ‘"arm-linux-gnueabihf"’—ou
     ‘#f’ si nous ne faisons pas de compilation croisée.

     ‘let-system’ est utile occasionellement dans le cas où l’objet
     raccordé au gexp dépend de la cible sur le système cible, comme
     dans cet exemple :

          #~(system*
             #+(let-system system
                 (cond ((string-prefix? "armhf-" system)
                        (file-append qemu "/bin/qemu-system-arm"))
                       ((string-prefix? "x86_64-" system)
                        (file-append qemu "/bin/qemu-system-x86_64"))
                       (else
                        (error "dunno!"))))
             "-net" "user" #$image)

 -- Syntaxe Scheme : with-parameters ((PARAMETER VALUE) ...) EXP
     Cette macro est similaire à la forme ‘parameterize’ pour les
     “paramètres” liés dynamiquement (*note (guile)Parameters::). La
     principale différence est qu’il prend effet lorsque l’objet de type
     fichier renvoyé par EXP est abaissé à un élément de dérivation ou
     de stockage.

     Une utilisation typique de ‘with-parameters’ consiste à forcer le
     système en vigueur pour un objet donné :

          (with-parameters ((%current-system "i686-linux"))
            coreutils)

     L’exemple ci-dessus renvoie un objet qui correspond à la version
     i686 de Coreutils, quelle que soit la valeur actuelle de
     ‘%current-système’.

   Bien sûr, en plus de gexps inclues dans le code « hôte », certains
modules contiennent des outils de construction. Pour savoir facilement
qu’ils sont à utiliser dans la strate de construction, ces modules sont
gardés dans l’espace de nom ‘(guix build ...)’.

   En interne, les objets de haut-niveau sont “abaissés”, avec leur
compilateur, soit en des dérivations, soit en des objets du dépôt. Par
exemple, abaisser un paquet crée une dérivation, et abaisser un
‘plain-file’ crée un élément du dépôt. Cela est effectué par la
procédure monadique ‘lower-object’.

 -- Procédure monadique : lower-object OBJ [SYSTEM] [#:target #f]
     Renvoie comme valeur dans ‘%store-monad’ la dérivation ou l’élément
     de dépôt correspondant à OBJ pour SYSTEM, en effectuant une
     compilation croisée pour TARGET si TARGET est vrai. OBJ doit être
     un objet auquel est associé un compilateur gexp, tel qu’un
     ‘<package>’.

 -- Procédure : gexp->approximate-sexp GEXP
     Il peut parfois être utile de convertir une G-expression en
     S-expression. Par exemple, certains outils d’analyse statique de
     style (dits « linters », *note Invoquer guix lint::) vérifient les
     phases de compilation des paquets pour détecter des problèmes
     potentiels. Cette conversion peut être réalisée avec cette
     procédure. Toutefois, certaines informations peuvent être perdues
     au cours de l’opération. Plus spécifiquement, les objets
     abaissables seront remplacés silencieusement par un objet
     arbitraire – pour l’instant la liste ‘(*approximate*)’, mais cela
     pourrait changer.

   ---------- Footnotes ----------

   (1) Le terme de “strate” dans ce contexte a été inventé par Manuel
Serrano et ses collègues dans le contexte de leurs travaux sur Hop. Oleg
Kiselyov, qui a écrit des essais perspicaces ainsi que du code sur le
sujet (http://okmij.org/ftp/meta-programming/#meta-scheme), utilise le
terme de « mise en scène » pour ce genre de génération de code.


File: guix.fr.info,  Node: Invoquer guix repl,  Next: Utiliser Guix de manière interactive,  Prev: G-Expressions,  Up: Interface de programmation

9.13 Invoquer ‘guix repl’
=========================

La commande ‘guix repl’ facilite la programmation de Guix dans Guile en
lançant une boucle Guile “read-eval-print”. (REPL) pour la programmation
interactive (*note (guile)Using Guile Interactively::), ou en exécutant
des scripts Guile (*note guile: (GNU Guile Reference Manual)Running
Guile Scripts.). Par rapport au simple lancement de la commande ‘guile’,
‘guix repl’ garantit que tous les modules Guix et toutes ses dépendances
sont disponibles dans le chemin de recherche.

   La syntaxe générale est :

     guix repl OPTION FICHIER ARGS]

   Lorsqu’un argument FILE est fourni, FILE est exécuté comme un script
Guile :

     guix repl mon-script.scm

   Pour passer des arguments au script, utilisez ‘--’ pour éviter qu’ils
ne soient interprétés comme des arguments pour ‘guix repl’ lui-même :

     guix repl -- mon-script.scm --input=toto.txt

   Pour rendre exécutable un script directement depuis le shell, en
utilisant l’exécutable guix qui se trouve dans le chemin de recherche
utilisateur·rice, ajoutez les deux lignes suivantes en haut du script :

     #!/usr/bin/env -S guix repl --
     !#

   En l’absence d’un argument de nom de fichier, une REPL guile est
lancé, ce qui permet de l’utiliser de manière interactive (*note
Utiliser Guix de manière interactive::) :

     $ guix repl
     scheme@(guile-user)> ,use (gnu packages base)
     scheme@(guile-user)> coreutils
     $1 = #<package coreutils@8.29 gnu/packages/base.scm:327 3e28300>

   En plus, ‘guix repl’ implémente un protocole REPL simple lisible par
une machine à utiliser avec ‘(guix inferior)’, un dispositif pour
interagir avec des “inférieurs”, des processus séparés qui font tourner
une version potentiellement différente de Guix.

   Les options disponibles sont les suivantes :

‘--type=TYPE’
‘-t TYPE’
     Démarrer un REPL du TYPE donné, qui peut être l’un de ces types :

     ‘guile’
          C’est la valeur par défaut. Elle démarre un REPL Guile
          standard fonctionnel.
     ‘machine’
          Démarre un REPL qui utilise le protocole lisible par machine.
          C’est le protocole que parle le module ‘(guix inferior)’.

‘--listen=EXTRÉMITÉ’
     Par défaut, ‘guix repl’ lit depuis l’entrée standard et écrit sur
     la sortie standard. Lorsque cette option est passée, il écoutera
     plutôt les connexions sur ENDPOINT. Voici un exemple d’options
     valides :

     ‘--listen=tcp:37146’
          Accepte les connexions sur localhost, sur le port 31.

     ‘--listen=unix:/tmp/socket’
          Accepte les connexions sur le socket Unix-domain
          ‘/tmp/socket’.

‘--load-path=RÉPERTOIRE’
‘-L RÉPERTOIRE’
     Ajoute RÉPERTOIRE au début du chemin de recherche de module de
     paquets (*note Modules de paquets::).

     Cela permet à des utilisateurs de définir leur propres paquets et
     les rendre disponibles au script ou au REPL.

‘-q’
     Inhiber le chargement du fichier ‘~/.guile’. Par défaut, ce fichier
     de configuration est chargé lors de la création d’un fichier
     ‘guile’. REPL.


File: guix.fr.info,  Node: Utiliser Guix de manière interactive,  Prev: Invoquer guix repl,  Up: Interface de programmation

9.14 Utiliser Guix de manière interactive
=========================================

La commande ‘guix repl’ vous donne accès à une
“boucle-lecture-évalutation-affichage” (BLÉA ou REPL en anglais)
chaleureuse et amicale (*note Invoquer guix repl::). Si vous commencez
la programmation avec Guix — pour définir vos propres paquets, écrire
des manifestes, définir des services pour le système Guix ou Guix Home,
etc — vous la trouverez sans doute pratique pour jouer avec vos idées
sur la REPL.

   Si vous utilisez Emacs, le moyen le plus pratique pour cela est
d’utiliser Geiser (*note La configuration parfaite::), mais vous n’avez
pas besoin d’utiliser Emacs pour profiter de la REPL. Lorsque vous
utilisez ‘guix repl’ ou ‘guile’ dans un terminal, nous vous recommandons
d’utiliser Readline pour la complétion et Colorized pour avoir une
sortie colorée. Pour cela, vous pouvez lancer :

     guix install guile guile-readline guile-colorized

… puis créer un fichier ‘.guile’ dans votre répertoire personnel,
contenant ceci :

     (use-modules (ice-9 readline) (ice-9 colorized))

     (activate-readline)
     (activate-colorized)

   La REPL vous permet d’évaluer du code SCheme ; vous tapez une
expression Scheme sur l’invite, et la REPL affiche ce en quoi elle
s’évalue :

     $ guix repl
     scheme@(guix-user)> (+ 2 3)
     $1 = 5
     scheme@(guix-user)> (string-append "a" "b")
     $2 = "ab"

   Ça devient plus intéressant quand vous commencez à jouer avec Guix
sur la REPL. La première chose à faire est « d’importer » le module
‘(guix)’, qui vous donne accès à la partie principale de l’interface de
programmation, et peut-être à un ensemble de modules Guix utiles. Vous
pouvez taper ‘(use-modules (guix))’, ce qui est du code Scheme valide
pour importer un module (*note (guile)Using Guile Modules::), mais la
REPL fournit la “commande” ‘use’ comme raccourci (*note (guile)REPL
Commands::) :

     scheme@(guix-user)> ,use (guix)
     scheme@(guix-user)> ,use (gnu packages base)

   Remarquez que les commandes de la REPL sont introduites par une
virgule. Une commande REPL comme ‘use’ n’est pas du code Scheme valide,
elle est interprétée de manière spéciale par la REPL.

   Guix étend la REPL Guile avec des commandes supplémentaires pour
votre confort. Parmi celles-ci, la commande ‘build’ est pratique : elle
s’assure que l’objet simili-fichier donné est construit, en le
construisant si nécessaire, et renvoie le nom de fichier de sa sortie.
Dans l’exemple ci-dessous, nous construisons les paquets ‘coreutils’ et
‘grep’, ainsi qu’un « fichiers calculé » (*note ‘computed-file’:
G-Expressions.), et nous utilisons la procédure ‘scandir’ pour lister
les fichiers du répertoire ‘/bin’ de Grep :

     scheme@(guix-user)> ,build coreutils
     $1 = "/gnu/store/...-coreutils-8.32-debug"
     $2 = "/gnu/store/...-coreutils-8.32"
     scheme@(guix-user)> ,build grep
     $3 = "/gnu/store/...-grep-3.6"
     scheme@(guix-user)> ,build (computed-file "x" #~(mkdir #$output))
     construction de /gnu/store/...-x.drv...
     $4 = "/gnu/store/...-x"
     scheme@(guix-user)> ,use(ice-9 ftw)
     scheme@(guix-user)> (scandir (string-append $3 "/bin"))
     $5 = ("." ".." "egrep" "fgrep" "grep")

   À plus bas niveau, une commande utile est ‘lower’ : elle prend un
objet simili-fichier et l’« abaisse » en une dérivation (*note
Dérivations::) ou un fichier du dépôt :

     scheme@(guix-user)> ,lower grep
     $6 = #<derivation /gnu/store/...-grep-3.6.drv => /gnu/store/...-grep-3.6 7f0e639115f0>
     scheme@(guix-user)> ,lower (plain-file "x" "Hello!")
     $7 = "/gnu/store/...-x"

   La liste complète des commandes de la REPL se trouvent en tapant
‘,help guix’ et est donnée ci-dessous pour référence.

 -- commande REPL : build OBJET
     Abaisse OBJET et le construit s’il n’est pas déjà construit, et
     renvoie le nom de fichier de ses sorties.

 -- commande REPL : lower OBJET
     Abaisse OBJET en une dérivation ou un nom de fichier du dépôt et le
     renvoie.

 -- commande REPL : verbosity NIVEAU
     Change la verbosité des construction à NIVEAU.

     C’est similaire à l’option en ligne de commande ‘--verbosity’
     (*note Options de construction communes::) : le niveau 0 signifie
     le silence total, le niveau 1 montre les événements de construction
     et les niveaux plus élevés affichent les journaux de construction.

 -- commande REPL : run-in-store EXP
     Lance EXP, une expression monadique dans la monade du dépôt. *Note
     La monade du dépôt::, pour plus d’information.

 -- command REPL : enter-store-monad
     Entre dans une nouvelle REPL pour évaluer des expressions
     monadiques (*note La monade du dépôt::). Vous pouvez quitter la
     REPL « interne » en tapant ‘,q’.


File: guix.fr.info,  Node: Utilitaires,  Next: Architectures externes,  Prev: Interface de programmation,  Up: Top

10 Utilitaires
**************

Cette section décrit les utilitaires en ligne de commande de Guix.
certains sont surtout faits pour les personnes qui écrivent de nouvelles
définitions de paquets tandis que d’autres sont plus utiles pour une
utilisation générale. Ils complètent l’interface de programmation Scheme
de Guix d’une manière pratique.

* Menu:

* Invoquer guix build::      Construire des paquets depuis la ligne de
                               commande.
* Invoquer guix edit::       Modifier les définitions de paquets.
* Invoquer guix download::   Télécharger un fichier et afficher son hash.
* Invoquer guix hash::       Calculer le hash cryptographique d’un fichier.
* Invoquer guix import::     Importer des définitions de paquets.
* Invoquer guix refresh::    Mettre à jour les définitions de paquets.
* Invoquer guix style::      Modifier le style des définitions de paquets.
* Invoquer guix lint::       Trouver des erreurs dans les définitions de
                               paquets.
* Invoquer guix size::       Profiler l’utilisation du disque.
* Invoquer guix graph::      Visualiser le graphe des paquets.
* Invoquer guix publish::    Partager des substituts.
* Invoquer guix challenge::  Défier les serveurs de substituts.
* Invoquer guix copy::       Copier vers et depuis un dépôt distant.
* Invoquer guix container::  Isolation de processus.
* Invoquer guix weather::    Mesurer la disponibilité des substituts.
* Invoquer guix processes::  Lister les processus clients.


File: guix.fr.info,  Node: Invoquer guix build,  Next: Invoquer guix edit,  Up: Utilitaires

10.1 Invoquer ‘guix build’
==========================

La commande ‘guix build’ construit des paquets ou des dérivations et
leurs dépendances et affiche les chemins du dépôt qui en résulte.
Remarquez qu’elle ne modifie pas le profil de l’utilisateur — c’est le
travail de la commande ‘guix package’ (*note Invoquer guix package::).
Ainsi, elle est surtout utile pour les personnes qui développent la
distribution.

   La syntaxe générale est :

     guix build OPTIONS PACKAGE-OR-DERIVATION...

   Par exemple, la commande suivante construit la dernière version
d’Emacs et de Guile, affiche leur journaux de construction et enfin
affiche les répertoires des résultats :

     guix build emacs guile

   De même, la commande suivante construit tous les paquets disponibles
:

     guix build --quiet --keep-going \
       $(guix package -A | awk '{ print $1 "@" $2 }')

   PACKAGE-OR-DERIVATION peut être soit le nom d’un paquet trouvé dans
la distribution logicielle comme ‘coreutils’, soit ‘coreutils@8.20’,
soit une dérivation comme ‘/gnu/store/...-coreutils-8.19.drv’. Dans le
premier cas, la commande cherchera un paquet avec le nom correspondant
(et éventuellement la version) dans les modules de la distribution GNU
(*note Modules de paquets::).

   Autrement, l’option ‘--expression’ peut être utilisée pour spécifier
une expression Scheme qui s’évalue en un paquet ; c’est utile lorsqu’il
est nécessaire de faire la distinction entre plusieurs paquets ou
variantes de paquets portant le même nom.

   Il peut y avoir aucune, une ou plusieurs OPTIONS. Les options
disponibles sont décrites dans les sous-sections ci-dessous.

* Menu:

* Options de construction communes::  Options de construction pour la
                                        plupart des commandes.
* Options de transformation de paquets::  Créer des variantes de paquets.
* Options de construction supplémentaires::  Options spécifiques à «
                                                guix build ».
* Débogage des échecs de construction::  L’empaquetage dans la vraie vie.


File: guix.fr.info,  Node: Options de construction communes,  Next: Options de transformation de paquets,  Up: Invoquer guix build

10.1.1 Options de construction communes
---------------------------------------

Un certain nombre d’options qui contrôlent le processus de construction
sont communes avec ‘guix build’ et les autres commandes qui peuvent
générer des constructions, comme ‘guix package’ ou ‘guix archive’. Voici
ces options :

‘--load-path=RÉPERTOIRE’
‘-L RÉPERTOIRE’
     Ajoute RÉPERTOIRE au début du chemin de recherche de module de
     paquets (*note Modules de paquets::).

     Cela permet à des utilisateurs de définir leur propres paquets et
     les rendre disponibles aux outils en ligne de commande.

‘--keep-failed’
‘-K’
     Garde l’arborescence de construction des constructions en échec.
     Ainsi, si une construction échoue, son arborescence de construction
     est préservée dans ‘/tmp’, dans un répertoire dont le nom est
     affiché à la fin du journal de construction. Cela est utile pour
     déboguer des échecs de construction. *Note Débogage des échecs de
     construction::, pour des astuces sur la manière de déboguer des
     problèmes de construction.

     Cette option implique ‘--no-offload’, et elle n’a pas d’effet quand
     elle est connectée à un démon distant avec une ‘guix://’ URI (*note
     the ‘GUIX_DAEMON_SOCKET’ variable: Le dépôt.).

‘--keep-going’
‘-k’
     Continue lorsque certaines dérivations échouent ; ne s’arrête que
     lorsque toutes les constructions ont soit réussies, soit échouées.

     Le comportement par défaut est de s’arrêter dès qu’une des
     dérivations spécifiées échoue.

‘--dry-run’
‘-n’
     Ne pas construire les dérivations.

‘--fallback’
     Lorsque la substitution d’un binaire pré-compilé échoue, construit
     les paquets localement à la place (*note Échec de substitution::).

‘--substitute-urls=URLS’
     Considère URLS comme une liste d’URL de sources de substituts
     séparés par des espaces, et remplace la liste par défaut d’URL de
     ‘guix-daemon’ (*note ‘guix-daemon’ URLs: daemon-substitute-urls.).

     Cela signifie que les substituts peuvent être téléchargés depuis
     URLS, tant qu’ils sont signés par une clef autorisée par
     l’administrateur système (*note Substituts::).

     Lorsque URLS est la chaîne vide, cela a pour effet de désactiver la
     substitution.

‘--no-substitutes’
     Ne pas utiliser de substitut pour les résultats de la construction.
     C’est-à-dire, toujours construire localement plutôt que de
     permettre le téléchargement de binaires pré-construits (*note
     Substituts::).

‘--no-grafts’
     Ne par « greffer » les paquets. En pratique, cela signifie que les
     mises à jour des paquets disponibles comme des greffes ne sont pas
     appliquées. *Note Mises à jour de sécurité::, pour plus
     d’information sur les greffes.

‘--rounds=N’
     Construit chaque dérivation N fois d’affilé, et renvoie une erreur
     si les constructions consécutives ne sont pas identiques bit-à-bit.

     Cela est une manière utile pour détecter des processus de
     construction non déterministes. Les processus de construction non
     déterministes sont problématiques car ils rendent pratiquement
     impossible la _vérification_ par les utilisateurs de l’authenticité
     de binaires tiers. *Note Invoquer guix challenge::, pour plus
     d’informations.

     Lorsqu’utilisé avec ‘--keep-failed’, la sortie différente est
     gardée dans le dépôt sous ‘/gnu/store/...-check’. Cela rend plus
     facile l’étude des différences entre les deux résultats.

‘--no-offload’
     N’essaye pas de décharger les constructions vers d’autres machines
     (*note Réglages du déchargement du démon::). C’est-à-dire que tout
     sera construit localement au lieu de décharger les constructions à
     une machine distante.

‘--max-silent-time=SECONDES’
     Lorsque le processus de construction ou de substitution restent
     silencieux pendant plus de SECONDES, le terminer et rapporter une
     erreur de construction.

     Par défaut, le paramètre du démon est pris en compte (*note
     ‘--max-silent-time’: Invoquer guix-daemon.).

‘--timeout=SECONDES’
     De même, lorsque le processus de construction ou de substitution
     dure plus de SECONDES, le terminer et rapporter une erreur de
     construction.

     Par défaut, le paramètre du démon est pris en compte (*note
     ‘--timeout’: Invoquer guix-daemon.).

‘-v [NIVEAU]’
‘--verbosity=NIVEAU’
     Utiliser le NIVEAU de verbosité, en tant qu’entier. 0 signifie
     qu’aucune sortie n’est produite, 1 signifie une sortie silencieuse
     ; 2 est similaire à 1 mais affiche aussi les URL des
     téléchargements ; 3 montre tous les journaux de construction sur la
     sortie d’erreur standard.

‘--cores=N’
‘-c N’
     Permet d’utiliser jusqu’à N cœurs du CPU pour la construction. La
     valeur spéciale ‘0’ signifie autant de cœurs que possible.

‘--max-jobs=N’
‘-M N’
     Permettre au maximum à N de construire des jobs en parallèle. *Note
     ‘--max-jobs’: Invoquer guix-daemon, pour plus de détails sur cette
     option et l’option équivalente ‘guix-daemon’.

‘--debug=NIVEAU’
     Produire une sortie de débogage qui provient du démon de
     construction. NIVEAU doit être un entier entre 0 et 5 ; plus grand
     est ce nombre, plus verbeuse sera la sortie. Indiquer un niveau de
     4 ou plus peut être utile pour déboguer des problèmes
     d’installation avec le démon de construction.

   Sous le capot, ‘guix build’ est surtout une interface à la procédure
‘package-derivation’ du module ‘(guix packages)’, et à la procédure
‘build-derivations’ du module ‘(guix derivations)’.

   En plus des options passées explicitement par la ligne de commande,
‘guix build’ et les autres commandes ‘guix’ qui peuvent effectuer des
constructions prennent en compte la variable d’environnement
‘GUIX_BUILD_OPTIONS’.

 -- Variable d'environnement : GUIX_BUILD_OPTIONS
     Les utilisateurs peuvent définir cette variable à une liste
     d’options de la ligne de commande qui seront automatiquement
     utilisées par ‘guix build’ et les autres commandes ‘guix’ qui
     peuvent effectuer des constructions, comme dans l’exemple suivant :

          $ export GUIX_BUILD_OPTIONS="--no-substitutes -c 2 -L /toto/titi"

     Ces options sont analysées indépendamment, et le résultat est
     ajouté aux options de la ligne de commande analysées.


File: guix.fr.info,  Node: Options de transformation de paquets,  Next: Options de construction supplémentaires,  Prev: Options de construction communes,  Up: Invoquer guix build

10.1.2 Options de transformation de paquets
-------------------------------------------

Un autre ensemble d’options de la ligne de commande supportés par ‘guix
build’ et aussi ‘guix package’ sont les “options de transformation de
paquets”. Ce sont des options qui rendent possible la définition de
“variantes de paquets” — par exemple, des paquets construit à partir de
sources différentes. C’est une manière simple de créer des paquets
personnalisés à la volée sans avoir à taper les définitions de variantes
de paquets (*note Définition des paquets::).

   Les options de transformation des paquets sont préservées dans les
mises à jour : ‘guix upgrade’ tente d’appliquer aux paquets mis à jour
les options de transformation initialement utilisées lors de la création
du profil.

   Les options disponibles sont énumérées ci-dessous. La plupart des
commandes les prennent en charge, ainsi qu’une option ‘--help-transform’
qui liste toutes les options disponibles et un synopsis (ces options ne
sont pas affichées dans la sortie ‘--help’ par souci de concision).

‘--tune[=CPU]’
     Utilise les versions des paquets marqués comme « réglables »
     optimisées pour CPU. Lorsque CPU est ‘native’, ou s’il est omis,
     règle pour le CPU sur lequel la commande ‘guix’ est lancée.

     Les noms de CPU valides sont ceux reconnus par le compilateur
     sous-jacent, par défaut la collection de compilateurs de GNU (GCC).
     Sur les processurs x86_64, cela comprend les noms des CPU comme
     ‘nehalem’, ‘haswell’ et ‘skylake’ (*note ‘-march’: (gcc)x86
     Options.).

     Au fur et à mesure de la sortie de nouvelles générations de CPU, de
     nouvelles instructions sont ajoutées à l’ensemble d’instruction
     standard de l’architecture (ISA), en particulier des instructions
     pour le calcul parallèle instruction-unique/données-multiples
     (SIMD). Par exemple, alors que les CPU Core2 et Skylake
     implémentent tous deux l’ISA x86_64, seul ce dernier prend en
     charge les instructions SIMD AVX2.

     Le principal bénéfice attendu de ‘--tune’ est que les programmes
     peuvent utiliser ces fonctionnalités SIMD _et_ qu’ils n’ont pas
     déjà un mécanisme pour choisir le bon code optimisé à l’exécution.
     Les paquets qui possèdent la propriété ‘tunable?’ sont considérés
     comme des “paquets réglables” par l’option ‘--tune’ ; une
     définition de paquet avec la bonne propriété ressemble à ceci :

          (package
            (name "hello-simd")
            ;; ...

            ;; Ce paquet peut bénéficier des extensions SIMD donc
            ;; on le marque « réglable ».
            (properties '((tunable? . #t))))

     Les autres paquets ne sont pas considérés comme réglables. Cela
     permet à Guix d’utiliser des binaires génériques dans le cas où le
     réglage pour un CPU particulier ne donnera probablement aucun
     avantage.

     Les paquets réglés sont construits avec ‘-march=CPU’ ; sous le
     capot, l’option ‘-march’ est passée à l’enveloppe par une enveloppe
     du compilateur. Comme la machine de construction peut ne pas être
     capable de lancer du code pour la micro-architecture CPU cible, la
     suite de tests n’est pas lancée lors de la construction d’un paquet
     réglé.

     Pour réduire les reconstructions au minimum, les paquets réglés
     sont _greffés_ sur les paquets qui en dépendent (*note grafts:
     Mises à jour de sécurité.). Ainsi, utiliser ‘--no-grafts’ annule
     l’effet de ‘--tune’.

     Nous appelons cette technique le “multi-versionement des paquets” :
     on peut construire plusieurs variantes d’un paquet réglable, une
     pour chaque variante de CPU. C’est la contrepartie à gros grain du
     “multi-versionement fonctionnel” implémenté par la chaine d’outils
     de GNU (*note (gcc)Function Multiversioning::).

‘--with-source=SOURCE’
‘--with-source=PAQUET=SOURCE’
‘--with-source=PAQUET@VERSION=SOURCE’
     Utilise SOURCE comme la source de PAQUET, et VERSION comme son
     numéro de version. SOURCE doit être un nom de fichier ou une URL,
     comme pour ‘guix download’ (*note Invoquer guix download::).

     Lorsque PAQUET est omis, la commande utilisera le nom de paquet
     spécifié par la base de SOURCE — p. ex. si SOURCE est
     ‘/src/guix-2.0.10.tar.gz’, le paquet correspondant est ‘guile’.

     De même, lorsque VERSION est omis, la chaîne de version est inférée
     à partir de SOURCE ; dans l’exemple précédent, il s’agit de
     ‘2.0.10’.

     Cette option permet aux utilisateurs d’essayer des version des
     paquets différentes de celles fournies par la distribution.
     L’exemple ci-dessous télécharge ‘ed-1.7.tar.g’ depuis un miroir GNU
     et l’utilise comme source pour le paquet ‘ed’ :

          guix build ed --with-source=mirror://gnu/ed/ed-1.4.tar.gz

     En tant que développeur·euse, ‘--with-source’ permet de tester
     facilement des version bêta, et même de vérifier leur impact sur
     les paquets qui en dépendent :

          guix build elogind --with-source=.../shepherd-0.9.0rc1.tar.gz

     ... ou pour construire un dépôt de gestion de version dans un
     environnement vierge :

          $ git clone git://git.sv.gnu.org/guix.git
          $ guix build guix --with-source=guix@1.0=./guix

‘--with-input=PAQUET=REMPLAÇANT’
     Remplace la dépendance sur PAQUET par une dépendance à REMPLAÇANT.
     PAQUET doit être un nom de paquet et REMPLAÇANT doit être une
     spécification de paquet comme ‘guile’ ou ‘guile@1.8’.

     Par exemple, la commande suivante construit Guix, mais remplace sa
     dépendance à la version stable actuelle de Guile par une dépendance
     à une ancienne version de Guile, ‘guile@2.0’ :

          guix build --with-input=guile=guile@2.0 guix

     C’est un remplacement récursif profond. Donc dans cet exemple, à la
     fois ‘guix’ et ses dépendances ‘guile-json’ (qui dépend aussi de
     ‘guile’) sont reconstruits avec ‘guile@2.0’.

     Cette option est implémentée avec la procédure Scheme
     ‘package-input-rewriting’ (*note ‘package-input-rewriting’:
     Définition des paquets.).

‘--with-graft=PAQUET=REMPLAÇANT’
     Cette option est similaire à ‘--with-input’ mais avec une
     différence importante : plutôt que de reconstruire la chaîne de
     dépendance complète, REMPLAÇANT est construit puis “greffé” sur les
     binaires qui référençaient initialement PAQUET. *Note Mises à jour
     de sécurité::, pour plus d’information sur les greffes.

     Par exemple, la commande ci-dessous greffe la version 3.5.4 de
     GnuTLS sur Wget et toutes ses dépendances, en remplaçant les
     références à la version actuelle de GnuTLS à laquelle ils se
     réfèrent actuellement :

          guix build --with-graft=gnutls=gnutls@3.5.4 wget

     Cela a l’avantage d’être bien plus rapide que de tout reconstruire.
     Mais il y a un piège : cela ne fonctionne que si PAQUET et
     REMPLAÇANT sont strictement compatibles — par exemple, s’ils
     fournissent une bibliothèque, l’interface binaire applicative (ABI)
     de ces bibliothèques doivent être compatibles. Si REMPLAÇANT est
     incompatible avec PAQUET, alors le paquet qui en résulte peut
     devenir inutilisable. À utiliser avec précaution !

‘--with-debug-info=PAQUET’
     Construire PAQUET de manière à préserver ses informations de
     débogage et les greffer sur les paquets qui en dépendent. Cela est
     utile si PAQUET ne fournit pas déjà les informations de débogage
     sous forme de sortie ‘debug’ (*note Installer les fichiers de
     débogage::).

     Par exemple, supposons que vous subissiez un plantage de Inkscape
     et que vous vouliez voir ce qui se passe dans GLib, une
     bibliothèque au fond du graphe de dépendance d’Inkscape. GLib n’a
     pas de sortie ‘debug’, donc le débogage est difficile.
     Heureusement, vous reconstruisez la GLib avec les informations de
     débogage et vous l’installez dans Inkscape :

          guix install inkscape --with-debug-info=glib

     Seule GLib doit être recompilée, ce qui prend un temps raisonnable.
     *Note Installer les fichiers de débogage::, pour plus
     d’informations.

          Remarque : Sous le capot, cette option fonctionne en passant
          par le ‘#:strip-binaries ? #f’ au système de construction du
          paquet qui nous intéresse (*note Systèmes de construction::).
          La plupart des systèmes de compilation supportent cette
          option, mais certains ne le font pas. Dans ce cas, une erreur
          se produit.

          De même, si un paquet C/C++ est construit sans ‘-g’ (ce qui
          est rarement le cas), les informations de débogage resteront
          indisponibles même si ‘#:strip-binaries?’ est faux.

‘--with-c-toolchain=PACKAGE=TOOLCHAIN’
     Cette option modifie la compilation de PACKAGE et de tout ce qui en
     dépend afin qu’ils soient construits avec TOOLCHAIN au lieu de la
     chaîne d’outils GNU par défaut pour C/C++.

     Regardez cet exemple :

          guix build octave-cli \
            --with-c-toolchain=fftw=gcc-toolchain@10 \
            --with-c-toolchain=fftwf=gcc-toolchain@10

     La commande ci-dessus construit une variante des paquets ‘fftw’ et
     ‘fftwf’ en utilisant la version 10 de ‘gcc-toolchain’ au lieu de la
     chaîne d’outils par défaut, puis construit une variante de
     l’interface en ligne de commande GNU Octave en les utilisant.
     GNU Octave lui-même est également construit avec
     ‘gcc-toolchain@10’.

     Cet autre exemple construit la bibliothèque Hardware Locality
     (‘hwloc’) et ses dépendances jusqu’à ‘intel-mpi-benchmarks’ avec le
     compilateur Clang C :

          guix build --with-c-toolchain=hwloc=clang-toolchain \
                     intel-mpi-benchmarks

          Remarque : Il peut y avoir des incompatibilités d’interface
          binaire d’application (ABI) entre les chaînes d’outils. Cela
          est particulièrement vrai pour la bibliothèque standard C++ et
          les bibliothèques de support d’exécution telles que celle
          d’OpenMP. En reconstruisant toutes les dépendances avec la
          même chaîne d’outils, ‘--with-c-toolchain’ minimise les
          risques d’incompatibilité mais ne peut pas les éliminer
          entièrement. Choisissez PACKAGE judicieusement.

‘--with-git-url=PAQUET=URL’
     Construire PAQUET depuis le dernier commit de la branche ‘master’
     du dépôt sur URL. Les sous-modules Git du dépôt sont récupérés,
     récursivement.

     Par exemple, la commande suivante construit la bibliothèque Python
     NumPy avec le dernier commit de la branche master de Python
     lui-même :

          guix build python-numpy \
            --with-git-url=python=https://github.com/python/cpython

     Cette option peut aussi être combinée avec ‘--with-branch’ ou
     ‘--with-commit’ (voir plus bas).

     Évidemment, comme cela utilise le dernier commit d’une branche
     donnée, le résultat d’une telle commande varie avec le temps.
     Néanmoins c’est une manière pratique pour reconstruire des piles
     logicielles entières avec le dernier commit d’un ou plusieurs
     paquets. C’est particulièrement pratique dans le contexte d’une
     intégration continue.

     Les clones sont gardés dans un cache dans ‘~/.cache/guix/checkouts’
     pour accélérer les accès consécutifs au même dépôt. Vous pourriez
     vouloir le nettoyer de temps en temps pour récupérer de l’espace
     disque.

‘--with-branch=PAQUET=BRANCHE’
     Construire PAQUET à partir du dernier commit de la BRANCHE. Si le
     champ ‘source’ de PAQUET est une origine avec la méthode
     ‘git-fetch’ (*note référence de origin::) ou un objet
     ‘git-checkout’, l’URL du dépôt est récupérée à partir de cette
     ‘source’. Sinon, vous devez utiliser ‘--with-git-url’ pour
     spécifier l’URL du dépôt Git.

     Par exemple, la commande suivante construit ‘guile-sqlite3’ à
     partir du dernier commit de sa branche ‘master’, puis construit
     ‘guix’ (qui en dépend) et ‘cuirass’ (qui dépend de ‘guix’) avec
     cette construction spécifique de ‘guile-sqlite3’ :

          guix build --with-branch=guile-sqlite3=master cuirass

‘--with-commit=PAQUET=COMMIT’
     Cela est similaire à ‘--with-branch’, sauf qu’elle construite à
     partir de COMMIT au lieu du sommet d’une branche. COMMIT doit être
     un identifiant SHA1 de commit Git valide, un tag ou un identifiant
     dans le style de ‘git describe’ comme ‘1.0-3-gabc123’.

‘--with-patch=PAQUET=FICHIER’
     Ajoute FICHIER à la liste des correctifs appliqués à PAQUET, où
     PAQUET est une spécification comme ‘python@3.8’ ou ‘glibc’. FICHIER
     doit contenir un correctif ; il est appliqué avec les drapeaux
     spécifiés dans l’‘origin’ de PAQUET (*note référence de origin::),
     qui par défaut inclus ‘-p1’ *note (diffutils)patch Directories::).

     Par exemple, la commande ci-dessous reconstruit Coreutils avec la
     bibliothèque C de GNU (glibc) corrigée avec le correctif donné :

          guix build coreutils --with-patch=glibc=./glibc-frob.patch

     Dans cet exemple, glibc lui-meme ainsi que tout ce qui mène à
     Coreutils dans le graphe des dépendances est reconstruit.

‘--with-latest=PAQUET’
     Alors vous aimez les toutes dernières technologies ? Cette option
     est faite pour vous ! Elle remplace les occurence de PAQUET dans le
     graphe des dépendances avec sa toute dernière version en amont,
     telle que rapportée par ‘guix refresh’ (*note Invoquer guix
     refresh::).

     Elle fait cela en déterminant la dernière version publiée en amont
     (si possible), en la téléchargeant et en l’authentifiant _si_ elle
     propose une signature OpenPGP.

     Par exemple, la commande ci-dessous construit Guix avec la dernière
     version de Guile-JSON :

          guix build guix --with-latest=guile-json

     Il y a des limites. Déjà, dans les cas où l’outil ne peut pas ou ne
     sait pas comment authentifier le code source, vous risquez de
     charger du code malveillant ; un avertissement est émis dans ce
     cas. Ensuite, cette option change simplement la source utilisée
     dans les définitions existantes des paquets, ce qui n’est pas
     toujours suffisant : il peut y avoir des dépendances
     supplémentaires qui doivent être ajoutées, des correctifs à
     appliquer, et plus généralement tout le travail d’assurance qualité
     que les développeurs de Guix font habituellement sera absent.

     On vous aura prévenu ! Dans tous les autres cas, c’est une méthode
     pour rester à la hauteur qui a du punch ! Nous vous encourageons à
     soumettre des correctifs pour les définitions des paquets quand
     vous aurez testé une mise à jour (*note Contribuer::).

‘--without-tests=PAQUET’
     Construire PAQUET sans lancer la suite de tests. Cela peut être
     utile dans les situations où vous voulez éviter la longue série de
     tests d’un paquet intermédiaire, ou si une suite de tests de paquet
     échoue dans un mode non déterministe. Il doit être utilisé avec
     précaution car l’exécution de la suite de tests est un bon moyen de
     s’assurer qu’un paquet fonctionne comme prévu.

     L’arrêt des tests conduit à un autre élément du dépôt. Par
     conséquent, lorsque vous utilisez cette option, tout ce qui dépend
     de PAQUET doit être reconstruit, comme dans cet exemple :

          guix install --without-tests=python python-notebook

     La commande ci-dessus installe ‘python-notebook’ par dessus
     ‘python’, construit sans exécuter sa suite de tests. Pour ce faire,
     elle reconstruit également tout ce qui dépend de ‘python’, y
     compris ‘python-notebook’ lui-même.

     En interne, ‘--without-tests’ repose sur le changement de l’option
     ‘#:tests?’ de la phase ‘check’ d’un paquet (*note Systèmes de
     construction::). Notez que certains paquets utilisent une phase
     ‘check’ personnalisée qui ne respecte pas le paramètre ‘#:tests?
     #f’. Par conséquent, ‘--without-tests’ n’a aucun effet sur ces
     paquets.

   Vous vous demandez comme faire la même chose dans du code Scheme, par
exemple dans votre manifeste, ou comme écrire votre propre
transformation de paquets ? *Note Définition de variantes de paquets::,
pour un aperçu des interfaces de programmation disponibles.


File: guix.fr.info,  Node: Options de construction supplémentaires,  Next: Débogage des échecs de construction,  Prev: Options de transformation de paquets,  Up: Invoquer guix build

10.1.3 Options de construction supplémentaires
----------------------------------------------

Les options de la ligne de commande ci-dessous sont spécifiques à ‘guix
build’.

‘--quiet’
‘-q’
     Construire silencieusement, sans afficher les journaux de
     construction ; c’est équivalent à ‘--verbosity=0’. À la fin, le
     journal de construction est gardé dans ‘/var’ (ou similaire) et on
     peut toujours l’y trouver avec l’option ‘--log-file’.

‘--file=FICHIER’
‘-f FICHIER’
     Construit le paquet, la dérivation ou l’objet simili-fichier en
     lequel le code dans FILE s’évalue (*note file-like objects:
     G-Expressions.).

     Par exemple, FILE peut contenir une définition de paquet comme ceci
     (*note Définition des paquets::) :

          (use-modules (guix)
                       (guix build-system gnu)
                       (guix licenses))

          (package
            (name "hello")
            (version "2.10")
            (source (origin
                      (method url-fetch)
                      (uri (string-append "mirror://gnu/hello/hello-" version
                                          ".tar.gz"))
                      (sha256
                       (base32
                        "0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i"))))
            (build-system gnu-build-system)
            (synopsis "Hello, GNU world: An example GNU package")
            (description "Guess what GNU Hello prints!")
            (home-page "http://www.gnu.org/software/hello/")
            (license gpl3+))

     FILE peut également contenir une représentation JSON d’une ou
     plusieurs définitions de paquets. L’exécution de ‘guix build -f’
     sur ‘hello.json’ avec le contenu suivant entraînerait la
     construction des paquets ‘myhello’ et ‘greeter’ :

          [
            {
              "name": "myhello",
              "version": "2.10",
              "source": "mirror://gnu/hello/hello-2.10.tar.gz",
              "build-system": "gnu",
              "arguments": {
                "tests?": false
              }
              "home-page": "https://www.gnu.org/software/hello/",
              "synopsis": "Hello, GNU world: An example GNU package",
              "description": "GNU Hello prints a greeting.",
              "license": "GPL-3.0+",
              "native-inputs": ["gettext"]
            },
            {
              "name": "greeter",
              "version": "1.0",
              "source": "https://example.com/greeter-1.0.tar.gz",
              "build-system": "gnu",
              "arguments": {
                "test-target": "foo",
                "parallel-build?": false,
              },
              "home-page": "https://example.com/",
              "synopsis": "Greeter using GNU Hello",
              "description": "This is a wrapper around GNU Hello.",
              "license": "GPL-3.0+",
              "inputs": ["myhello", "hello"]
            }
          ]

‘--manifest=MANIFEST’
‘-m MANIFEST’
     Construire tous les paquets listés dans un MANIFEST donné (*note
     ‘--manifest’: profile-manifest.).

‘--expression=EXPR’
‘-e EXPR’
     Construit le paquet ou la dérivation en lequel EXPR s’évalue.

     Par exemple, EXPR peut être ‘(@ (gnu packages guile) guile-1.8)’,
     qui désigne sans ambiguïté cette variante spécifique de la version
     1.8 de Guile.

     Autrement, EXP peut être une G-expression, auquel cas elle est
     utilisée comme un programme de construction passé à
     ‘gexp->derivation’ (*note G-Expressions::).

     Enfin, EXPR peut se référer à une procédure monadique à au moins un
     argument (*note La monade du dépôt::). La procédure doit renvoyer
     une dérivation comme une valeur monadique, qui est ensuite lancée à
     travers ‘run-with-store’.

‘--source’
‘-S’
     Construit les dérivation source des paquets, plutôt que des paquets
     eux-mêmes.

     Par exemple, ‘guix build -S gcc’ renvoie quelque chose comme
     ‘/gnu/store/...-gcc-4.7.2.tar.bz2’, qui est l’archive des sources
     de GCC.

     L’archive des sources renvoyée est le résultat de l’application des
     correctifs et des extraits de code éventuels spécifiés dans le
     champ ‘origin’ du paquet (*note Définition des paquets::).

     Comme avec les autres dérivations, le résultat de la construction
     des sources peut être vérifié avec l’option ‘--check’ (*note
     vérification de la construction::). C’est utile pour valider que
     les source (éventuellement déjà construites ou substituées, donc en
     cache) correspondent au hash déclaré.

     Notez que ‘guix build -S’ compile seulement les sources des paquets
     spécifiés. Les sources de dépendances statiquement liées ne sont
     pas incluses et sont en elles-mêmes insuffisantes pour reproduire
     les paquets.

‘--sources’
     Récupère et renvoie la source de PACKAGE-OR-DERIVATION et toute ses
     dépendances, récursivement. C’est pratique pour obtenir une copie
     locale de tous les codes sources requis pour construire PACKAGES,
     ce qui vous permet de les construire plus tard même sans accès au
     réseau. C’est une extension de l’option ‘--source’ et elle peut
     accepter l’un des arguments facultatifs suivants :

     ‘package’
          Cette valeur fait que l’option ‘--sources’ se comporte comme
          l’option ‘--source’.

     ‘all’
          Construit les dérivations des sources de tous les paquets,
          dont les sources qui pourraient être listées dans ‘inputs’.
          C’est la valeur par défaut.

               $ guix build --sources tzdata
               The following derivations will be built:
                  /gnu/store/...-tzdata2015b.tar.gz.drv
                  /gnu/store/...-tzcode2015b.tar.gz.drv

     ‘transitive’
          Construire les dérivations des sources de tous les paquets,
          ainsi que toutes celles des entrées transitives des paquets.
          On peut par exemple utiliser cette option pour précharger les
          sources des paquets pour les construire plus tard hors ligne.

               $ guix build --sources=transitive tzdata
               The following derivations will be built:
                  /gnu/store/...-tzcode2015b.tar.gz.drv
                  /gnu/store/...-findutils-4.4.2.tar.xz.drv
                  /gnu/store/...-grep-2.21.tar.xz.drv
                  /gnu/store/...-coreutils-8.23.tar.xz.drv
                  /gnu/store/...-make-4.1.tar.xz.drv
                  /gnu/store/...-bash-4.3.tar.xz.drv
               ...

‘--system=SYSTÈME’
‘-s SYSTÈME’
     Essayer de construire pour SYSTEM — p. ex. ‘i686-linux’ — au lieu
     du type de système de l’hôte. La commande ‘guix build’ vous permet
     de répéter cette option plusieurs fois, auquel cas elle construit
     pour tous les systèmes spécifiés ; les autres commandes ignorent
     les options ‘-s’ supplémentaires.

          Remarque : Le drapeau ‘--system’ est utilisé pour une
          compilation _native_ et ne doit pas être confondu avec une
          compilation croisée. Voir ‘--target’ ci-dessous pour des
          informations sur la compilation croisée.

     Un exemple d’utilisation de ceci sur les systèmes Linux, qui peut
     émuler différentes personnalités. Par exemple, passer
     ‘--system=i686-linux’ sur un système ‘x86_64-linux’ ou
     ‘--system=armhf-linux’ sur un système ‘aarch64-linux’ vous permet
     de construire des paquets dans un environnement 32-bit complet.

          Remarque : La possibilité de construire pour un système
          ‘armhf-linux’ est activé sans condition sur les machines
          ‘aarch64-linux’, bien que certaines puces aarch64 n’en soient
          pas capables, comme les ThunderX.

     De même, lorsque l’émulation transparente avec QEMU et
     ‘binfnmt_misc’ est activée (*note ‘qemu-binfmt-service-type’:
     Services de virtualisation.), vous pouvez construire pour n’importe
     quel système pour lequel un gestionnaire QEMU ‘binfmt_misc’ est
     installé.

     Les constructions pour un autre système que celui de la machine que
     vous utilisez peuvent aussi être déchargées à une machine distante
     de la bonne architecture. *Note Réglages du déchargement du
     démon::, pour plus d’information sur le déchargement.

‘--target=TRIPLET’
     Effectuer une compilation croisée pour TRIPLET qui doit être un
     triplet GNU valide, comme ‘"aarch64-linux-gnu"’ (*note GNU
     configuration triplets: (autoconf)Specifying Target Triplets.).

‘--list-systems’
     Liste tous les systèmes pris en charge, qui peuvent être passés en
     argument à ‘--system’.

‘--list-targets’
     Liste toutes les cibles prises en charge, qui peuvent être passées
     en argument à ‘--target’.

‘--check’
     Reconstruit les PACKAGE-OR-DERIVATION, qui sont déjà disponibles
     dans le dépôt et lève une erreur si les résultats des constructions
     ne sont pas identiques bit-à-bit.

     Ce mécanisme vous permet de vérifier si les substituts précédemment
     installés sont authentiques (*note Substituts::) ou si le résultat
     de la construction d’un paquet est déterministe. *Note Invoquer
     guix challenge:: pour plus d’informations et pour les outils.

     Lorsqu’utilisé avec ‘--keep-failed’, la sortie différente est
     gardée dans le dépôt sous ‘/gnu/store/...-check’. Cela rend plus
     facile l’étude des différences entre les deux résultats.

‘--repair’
     Essaye de réparer les éléments du dépôt spécifiés, s’ils sont
     corrompus, en les téléchargeant ou en les construisant à nouveau.

     Cette opération n’est pas atomique et donc restreinte à
     l’utilisateur ‘root’.

‘--derivations’
‘-d’
     Renvoie les chemins de dérivation, et non les chemins de sortie,
     des paquets donnés.

‘--root=FICHIER’
‘-r FICHIER’
     Fait de FICHIER un lien symbolique vers le résultat, et
     l’enregistre en tant que racine du ramasse-miettes.

     En conséquence, les résultats de cette invocation de ‘guix build’
     sont protégés du ramasse-miettes jusqu’à ce que FICHIER soit
     supprimé. Lorsque cette option est omise, les constructions sont
     susceptibles d’être glanées.

‘--log-file’
     Renvoie les noms des journaux de construction ou les URL des
     PACKAGE-OR-DERIVATION donnés ou lève une erreur si les journaux de
     construction sont absents.

     Cela fonctionne indépendamment de la manière dont les paquets ou
     les dérivations sont spécifiées. Par exemple, les invocations
     suivantes sont équivalentes :

          guix build --log-file $(guix build -d guile)
          guix build --log-file $(guix build guile)
          guix build --log-file guile
          guix build --log-file -e '(@ (gnu packages guile) guile-2.0)'

     Si un journal n’est pas disponible localement, à moins que
     ‘--no-substitutes’ ne soit passé, la commande cherche un journal
     correspondant sur l’un des serveurs de substituts (tels que
     spécifiés avec ‘--substitute-urls’).

     Donc par exemple, imaginons que vous souhaitiez voir le journal de
     construction de GDB sur ‘aarch64’, mais que vous n’avez qu’une
     machine ‘x86_64’ :

          $ guix build --log-file gdb -s aarch64-linux
          https://ci.guix.gnu.org/log/...-gdb-7.10

     Vous pouvez accéder librement à une vaste bibliothèque de journaux
     de construction !

