8.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 (voir Environment Variables dans le manuel de référence de la bibliothèque C de GNU). 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 (voir 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 ; voir search-paths.) 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 :

(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 (voir stat dans le manuel de référence de Guile).

In the XML_CATALOG_FILES example above, we would match regular files; in the Python example, we would match directories.

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.

Again, the XML_CATALOG_FILES example shows a situation where this is needed.

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 :$SGML_CATALOG_FILES

Variable :$XML_CATALOG_FILES

These two search paths indicate where the TR9401 catalog²² or XML catalog files can be found.

Variable :$SSL_CERT_DIR

Variable :$SSL_CERT_FILE

Ces deux chemins de recherche indiquent où trouver les certificats X.509 (voir 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 :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.