Écrire un manifeste (Manuel de référence de GNU Guix)

8.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 quand la ligne de commande devient longue et moins triviale, il est plus pratique d’avoir la liste des paquets dans ce que nous appelons un manifeste. Un manifeste est une sorte de « nomenclature » qui définit un ensemble de paquets. Typiquement, vous écrirez 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 simple ensemble de paquets 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 (voir l’option -m de guix package) :

guix package -m manifest.scm

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

guix shell -m manifest.scm

... ou vous pouvez le passer à guix pack de la même manière (voir l’option -m de guix pack). 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 (voir guix package --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 (voir guix 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 (voir Options de transformation de paquets).

Remarque : Les manifestes sont symboliques : ils font référence aux paquets des canaux actuellement utilisés (voir 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. Voir 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 (voir 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 (voir 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 (voir Définition des paquets) et aux modules qui définissent gdb et git (voir 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 (voir 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 (voir objets de type fichier).

output (par défaut : "out")

Sortie de item à utiliser, dans le cas où item a plusieurs sorties (voir 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 (voir propagated-inputs) 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 (voir 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 (voir 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 :concatenate-manifests lst: Concatène les manifestes listés dans lst et renvoie le manifeste qui en résulte.

Procédure :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 (voir options->transformation).

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 :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 :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 (voir guix shell -D), 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 :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 (voir 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.