Référence deps.edn

Aperçu

Le fichier deps.edn est un fichier de données spécifiant toutes les informations nécessaires à la construction du classpath d'un projet, notamment les dépendances, les chemins d'accès et les informations sur les dépôts de dépendances externes. Le format de fichier deps.edn est utilisé par la bibliothèque tools.deps et l'interface de ligne de commande Clojure (CLI).

Si vous développez un outil souhaitant exploiter deps.edn, créez des alias (:aliases) bien définis et organisés en espaces de noms pour communiquer la configuration de l'outil, plutôt que d'ajouter de nouvelles balises arbitraires ailleurs dans les données deps.edn ; ces dernières risquent de ne pas être conservées ou transmises lors du traitement. Les outils peuvent accéder aux données d'alias via la base lors de l'exécution, ou par programmation via tools.deps.

Index des attributs de deps.edn :

:paths

Les chemins spécifient les répertoires du projet à inclure dans le classpath, y compris les répertoires source et ressources.

Les chemins sont déclarés dans une clé de premier niveau :paths et constituent une collection de chemins sous forme de chaînes de caractères ou d'alias. Les alias font référence à une collection de chemins définis dans un alias (ce qui permet leur réutilisation).

Les chemins doivent être des sous-répertoires relatifs à la racine du projet, tels que «src» ou «resources». Les chemins absolus sont pris en charge, mais ne doivent être utilisés que dans des cas exceptionnels. Les chemins situés en dehors de la racine du projet généreront un avertissement ; ils sont obsolètes et pourront être supprimés ultérieurement.

Le cas échéant, les alias doivent faire référence à un vecteur de chemin dans les données d'alias.

Les chemins sont toujours inclus au début du classpath, dans l'ordre indiqué dans la collection :paths étendue.

:deps

Les dépendances sont déclarées dans le fichier `deps.edn` avec une clé de premier niveau `:deps` qui associe une bibliothèque à une coordonnée.

Le nom de la bibliothèque est un symbole qualifié. Les symboles non qualifiés sont traités comme `nom/nom`, mais cet usage est obsolète. Les coordonnées (et, dans une certaine mesure, les noms de bibliothèques) sont spécifiques aux types de coordonnées définis ci-dessous.

Les dépendances sont étendues à partir de cet ensemble de dépendances de premier niveau pour inclure toutes les dépendances transitives. Généralement, la version la plus récente est sélectionnée (sauf autres contraintes ; voir la documentation). Les dépendances sont placées dans le classpath après les chemins d'accès, triées par : a) profondeur depuis la racine et b) ordre alphabétique des dépendances à une profondeur donnée. Cet ordre est stable.

Exemples :

Dépendances Maven

Le collecteur Maven utilise le qualificateur `mvn` pour récupérer les artefacts de bibliothèque depuis les dépôts Maven, le gestionnaire de dépôts standard de l'écosystème Java. Les bibliothèques sont téléchargées sous forme de fichiers `.jar` et stockées dans le cache du dépôt local Maven (situé par défaut dans `~/.m2/repository`, ou redéfini avec `:mvn/local-repo`). D'autres outils JVM peuvent également utiliser ce cache.

Les bibliothèques Maven sont localisées dans les dépôts Maven grâce à leurs « coordonnées Maven », généralement le `groupId`, l'`artifactId` et la version (parfois abrégée en `GAV`). Dans `deps.edn`, le nom de la bibliothèque est analysé comme `groupId/artifactId` et la version est extraite de `:mvn/version`. Certains artefacts Maven possèdent également un « classificateur », une variante de l'artefact. Dans le collecteur Maven, les classificateurs sont ajoutés à la fin du nom de la bibliothèque, séparés par un `$`, au format suivant : `groupId/artifactId$classificateur`.

Actuellement, seuls les fichiers JAR sont pris en charge. La prise en charge d'autres types d'artefacts (notamment les fichiers POM de nomenclature) pourra être ajoutée ultérieurement.

Notez que les dépôts Maven déclarés dans les dépendances ou les dépendances transitives sont ignorés. Tous les dépôts nécessaires à l'ensemble des dépendances doivent être déclarés dans le fichier deps.edn du projet à l'aide de :mvn-repos.

:mvn/version

Obligatoire pour toutes les dépendances Maven, spécifie la version sous forme de chaîne de caractères.

Exemples :

• "1.2.3"
• "1.2.3-SNAPSHOT"

Dépendances Git

Le gestionnaire de dépendances Git permet l'utilisation directe des bibliothèques sources hébergées dans des dépôts Git. Par défaut, les bibliothèques Git sont téléchargées dans le répertoire ~/.gitlibs. L'arborescence de travail est extraite et mise en cache pour chaque SHA inclus comme dépendance.

Pour spécifier une bibliothèque Git comme dépendance, deux informations sont nécessaires : l'URL du dépôt Git et un SHA spécifique. L'utilisation de références déplaçables, telles que les noms de branches, n'est pas prise en charge.

Les coordonnées Git possèdent les attributs suivants :

L'URL Git doit être fournie ou déduite du nom de la bibliothèque. Si elle est fournie, l'URL `:git/url` est prioritaire. La convention de conversion des bibliothèques en URL est la suivante :

Voici un exemple de fichier deps.edn contenant deux dépendances Git valides : la première avec une URL Git, une étiquette Git et un préfixe SHA déduits, et la seconde avec une URL Git explicite et un SHA complet.

:git/url

L'URL Git (`:git/url`) est déduite du nom de la bibliothèque si le format décrit ci-dessus est utilisé ; sinon, elle doit être fournie.

Les protocoles d'URL Git les plus courants sont HTTPS et SSH. Les dépôts HTTPS sont accessibles anonymement et ne nécessitent aucune information d'authentification supplémentaire. Cette approche est recommandée pour les dépôts publics que vous ne contrôlez pas. Les dépôts SSH peuvent être publics ou privés et utilisent votre identité SSH.

Pour plus d'informations sur la création de clefs et l'utilisation de l'agent SSH pour gérer vos identités SSH, GitHub propose d'excellentes ressources :

• https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent
• https://docs.github.com/en/authentication/connecting-to-github-with-ssh/working-with-ssh-key-passphrases

D'autres protocoles (y compris locaux et de fichiers) devraient fonctionner, mais ils ne sont pas couramment utilisés.

:git/tag

L'attribut `:git/tag` est une clef de coordination optionnelle précisant la sémantique du SHA en spécifiant l'étiquette. Si `:git/tag` est fourni, `:git/sha` peut être un SHA court au lieu d'un SHA complet de 40 caractères.

:git/sha

L'attribut `:git/sha` est une clé de coordonnées obligatoire. Si `:git/tag` est fourni, il peut s'agir du préfixe `sha` (les deux versions doivent correspondre au même commit), sinon il doit s'agir d'un `sha` complet de 40 caractères.

Lors de la sélection d'une version entre les `sha` A et B, lorsque B a A comme ancêtre, c'est B qui sera privilégiée (la version la plus descendante). Si A et B n'ont pas de relation ancêtre/descendant (par exemple, des commits dans des branches parallèles), une erreur se produit et la construction du classpath échoue.

Dépendances locales

Les dépendances locales font référence à un répertoire ou à un fichier JAR sur le disque. L'attribut `:local/root` est obligatoire et peut être absolu ou relatif.

:local/root

Pour un répertoire de projet local, `:local/root` doit être un chemin de répertoire, absolu ou relatif par rapport à l'emplacement du répertoire du projet.

Pour un fichier JAR, `:local/root` doit être un chemin absolu ou relatif vers le fichier JAR. Si le fichier JAR contient un fichier `pom.xml`, celui-ci sera utilisé pour trouver les dépendances transitives.

Attributs de dépôt partagés

:exclusions

L'attribut `:exclusions` prend un vecteur de symboles de bibliothèque à exclure en tant que dépendances transitives de cette dépendance. Cet attribut peut être utilisé sur n'importe quelle dépendance.

:deps/root

L'attribut `:deps/root` indique un chemin relatif vers un répertoire au sein d'une dépendance (deps) basée sur des fichiers, dans lequel rechercher le fichier manifeste. Il est couramment utilisé dans les projets de type monorepo pour spécifier une racine de dépendance dans un répertoire situé sous la racine du dépôt.

:deps/manifest

Lorsqu'un projet Git ou local est inclus, son type est détecté automatiquement à partir des fichiers manifestes `deps.edn` et `pom.xml`. Si les deux existent, `deps.edn` est prioritaire.

L'attribut `:deps/manifest` spécifie le type de manifeste du projet et remplace la détection automatique. Les valeurs courantes sont `:deps` et `:pom`. (D'autres valeurs possibles sont `:mvn` et `:jar`, mais il n'est pas nécessaire de les spécifier.)

:aliases

Les alias permettent de nommer une structure de données, nom pouvant être utilisé soit par l'interface de ligne de commande Clojure elle-même, soit par d'autres utilisateurs de deps.edn. Ils sont définis dans la section :aliases du fichier de configuration.

:extra-deps

:extra-deps est la modification la plus courante ; elle permet d'ajouter des dépendances supplémentaires à l'ensemble de dépendances de base. Sa valeur est une carte des bibliothèques à coordonner :

:override-deps

:override-deps remplace la version de coordonnées choisie par la résolution de version pour imposer une version particulière. La valeur est une carte de bibliothèques à coordonnées :

:default-deps

:default-deps fournit un ensemble de versions de coordonnées par défaut à utiliser si aucune coordonnée n'est spécifiée. Ces dépendances par défaut peuvent être utilisées dans un ensemble de projets partagés pour servir de système de gestion des dépendances :

:deps / :replace-deps

:deps et :replace-deps sont synonymes et définissent une correspondance de dépendances qui REMPLACE celle du projet :deps. La valeur est une correspondance entre les bibliothèques et les dépendances à coordonner.

:extra-paths

:extra-paths est utilisé pour inclure des chemins sources en plus de vos chemins sources standard, par exemple pour inclure des répertoires de code source de test :

Notez que les chemins externes doivent se trouver dans le répertoire racine du projet (emplacement du fichier deps.edn) ou à un sous-répertoire de celui-ci.

:paths / :replace-paths

:paths et :replace-paths sont synonymes et définissent une collection de chemins de chaînes de caractères pour REPLACE les :paths du projet.

:classpath-overrides

L'option `:classpath-overrides` spécifie un emplacement pour récupérer une dépendance qui remplace le chemin trouvé lors de la résolution des dépendances, par exemple pour remplacer une dépendance par une version de débogage locale. Dans de nombreux cas d'utilisation, on serait tenté d'ajouter un préfixe au classpath pour «override» un autre élément :

:ns-default

L'attribut :ns-default est un symbole d'espace de noms étant utilisé comme espace de noms par défaut pour les attributs fournissant un symbole non qualifié, notamment :exec-fn.

:ns-aliases

L'attribut :ns-aliases est une carte du symbole d'alias au symbole d'espace de noms étant utilisée pour résoudre les symboles qualifiés, notamment :exec-fn.

:exec-fn

Le symbole :exec-fn définit la fonction par défaut à invoquer lors de l'utilisation de l'exécution de fonction -X dans l'interface de ligne de commande Clojure :

Le symbole :exec-fn est résolu selon les règles suivantes :

• Si la fonction n'est pas qualifiée, utilisez l'espace de noms défini par la clef :ns-default dans la table des arguments (si aucun espace de noms n'est défini, une erreur est levée).
• Si la fonction est qualifiée et que le qualificateur est un alias dans la table des arguments sous :ns-aliases, utilisez cet espace de noms.
• Sinon, utilisez le symbole de fonction pleinement qualifié.

:exec-args

La carte `:exec-args` spécifie les paires clé-valeur fournies lors de l'exécution d'une fonction `:exec-fn` avec les options `-X` ou `-T` dans l'interface de ligne de commande Clojure. Ces paires clé-valeur sont fournies en premier et peuvent donc être remplacées par d'autres paires clé-valeur sur la ligne de commande.

:jvm-opts

Les options :jvm-opts sont une collection d'options JVM sous forme de chaîne de caractères à fournir lors de l'exécution de l'interface de ligne de commande Clojure avec -M, -X, -T ou un repl.

:main-opts

Les options `:main-opts` sont un ensemble de chaînes de caractères permettant de passer un programme lancé avec l'option `-M` dans l'interface de ligne de commande Clojure. Si plusieurs alias sont fusionnés et fournissent des arguments principaux, seuls les arguments du dernier alias sont utilisés (ils ne s'accumulent pas). Des options principales supplémentaires peuvent être spécifiées en ligne de commande après l'option `-M`.

Configuration du fournisseur

Maven

Le fournisseur Maven utilise le résolveur Maven et le système de dépôt Maven pour télécharger les artefacts. Ceci est décrit plus en détail dans la section Dépendances Maven. Certaines options peuvent être configurées dans le fichier deps.edn.

:mvn/local-repo

Par défaut, Maven utilise le répertoire ~/.m2/repository comme cache local des fichiers POM et JAR téléchargés. L'option :mvn/local-repo est un chemin d'accès (sous forme de chaîne de caractères) vers un autre répertoire à utiliser comme cache local pour Maven.

:mvn/repos

Le fournisseur Maven utilise toujours deux dépôts intégrés qui sont toujours vérifiés en premier, dans cet ordre :

Vous pouvez spécifier des dépôts supplémentaires via la clé `:mvn/repos` sous forme de correspondance entre le nom du dépôt et ses attributs supplémentaires, décrits ci-dessous. Les noms de dépôts sont arbitraires. L'attribut `:url` est obligatoire ; les autres sont facultatifs. Les dépôts déclarés dans les fichiers `pom.xml` ou `deps.edn` des dépendances ne sont pas utilisés : tous les dépôts nécessaires doivent être définis dans le fichier `deps.edn` principal utilisé.

:url

L'attribut `:url` est une URL (chaîne de caractères) pointant vers la racine du dépôt.

Les URL `http://` ne sont pas prises en charge par défaut. Consultez la documentation de `clojure_cli` pour plus d'informations sur l'option `CLOJURE_CLI_ALLOW_HTTP_REPO` si nécessaire.

:releases et :snapshots

L'attribut :releases est facultatif, mais peut être utilisé pour remplacer la configuration de dépôt par défaut pour les versions (artefacts non instantanés) :

L'attribut `:snapshots` est identique à l'attribut `:releases`, mais applique une politique de dépôt aux artefacts de type snapshot.

Attributs du dépôt :

• `:enabled` est un booléen (valeur par défaut : `true`). Il est parfois utilisé pour cibler un dépôt uniquement pour les versions publiées ou les snapshots.
• `:update` indique la fréquence de vérification des mises à jour du dépôt. Les valeurs possibles sont : `:daily` (par défaut), `:always`, `:never` ou un intervalle en minutes (entier).
• `:checksum` active la validation de la somme de contrôle. Les valeurs possibles sont : `:warn` (par défaut), `:fail` et `:ignore`.

Voir également la configuration du fournisseur Maven pour une configuration supplémentaire dans l'interface de ligne de commande Clojure.

Git

Voir également la configuration du fournisseur Git pour une configuration supplémentaire dans l'interface de ligne de commande Clojure.

Local

Il n'existe aucune option de configuration pour l'acheteur local.

Définition de l'outil

Les outils en ligne de commande Clojure chargés depuis GitHub ou un répertoire local peuvent fournir une configuration par défaut dans leur fichier deps.edn grâce à la clé :tools/usage. Tous les utilisateurs de l'outil bénéficieront de cette configuration lors de son installation.

:tools/usage

Une table de correspondance des paramètres d'exécution pour un outil basé sur deps.edn pouvant contenir les attributs suivants :

• :exec-args
• :ns-default
• :ns-aliases

Bibliothèque de préparation

:deps/prep-lib

Les bibliothèques sources Clojure peuvent être ajoutées immédiatement au classpath d'un projet les utilisant. Cependant, certaines bibliothèques nécessitent une préparation préalable, par exemple la compilation Java ou le remplacement de fichiers de ressources. L'interface de ligne de commande Clojure (CLI) détecte désormais les projets nécessitant une préparation et empêche leur exécution à partir du code source tant que cette étape n'est pas terminée.

Si votre bibliothèque nécessite une préparation, ajoutez la clé `:deps/prep-lib` à votre fichier `deps.edn`.

:ensure

:ensure est un chemin de répertoire relatif au projet, dont l'existence détermine si la préparation est nécessaire (s'il existe, la préparation a été effectuée).

:alias

:alias est l'alias du mot-clé à invoquer avec -T lors de la préparation.

:fn

:fn est la fonction à invoquer avec -T lors de la préparation

Base d'exécution

La base d'exécution représente l'environnement de dépendances au démarrage de l'environnement d'exécution Clojure. Elle contient des informations sur les dépendances, le classpath et la méthode de création de cette base.

La base d'exécution est accessible depuis Clojure via l'API `clojure.java.basis`. Elle permet d'accéder à la base initiale et à la base actuelle, cette dernière pouvant être modifiée par les fonctions `add-libs` et apparentées.

Index des attributs de la base d'exécution :

:basis-config

L'attribut :basis-config contient les paramètres utilisés lors de la création de la base et devrait suffire à la recréer ultérieurement. Cette propriété est notamment utilisée par sync-deps.

La configuration de base (`:basis-config`) peut avoir les attributs suivants :

:argmap

L'objet `:argmap` de base contient l'argmap fusionnée utilisée pour la résolution des dépendances et le calcul du classpath. Les argmaps peuvent être fournies indirectement via `:aliases` ou directement via la clé `:args` lors de la création de l'objet de base.

Pour une liste complète des arguments des argmaps et leur rôle, consultez la page de référence de l'interface de ligne de commande Clojure.

:libs

La clef `:libs` de base est une carte de toutes les dépendances, directes et transitives, incluses dans le classpath de base. La valeur `:libs` est une carte associant le nom de la bibliothèque (symbole qualifié) à ses coordonnées, complétée par des clés supplémentaires. Bien que la plupart de ces clés soient non normatives, la clef `:paths` est un vecteur important contenant les chemins de fichiers à ajouter au classpath pour cette bibliothèque.

:classpath

La clef `:classpath` est une table de hachage où les clés sont des chemins de classpath (chaînes de caractères) et les valeurs expliquent pourquoi ce chemin est inclus. Le plus souvent, il s'agira soit d'une table de hachage avec la clé `:lib-name` (pour les bibliothèques), soit d'une table de hachage avec la clef `:path-key` pour les chemins de sources.

:classpath-roots

La clef `:classpath-roots` est un vecteur triant le classpath (les chaînes de chemin doivent correspondre aux clefs de `:classpath`). Consultez la section relative à la construction du classpath dans la documentation Clojure CLI pour connaître les règles de tri.