Barrel
EN GitHub

Distribuer les applications de l’umbrella

L’umbrella est la source de vérité : vous développez toutes les applications dans un seul arbre pour que les changements entre applications restent atomiques. Ce guide sert quand vous devez remettre une application seule à quelqu’un en dehors de l’umbrella. Il y a trois façons de faire, et vous pouvez les utiliser toutes à la fois : publier sur Hex (un paquet versionné), maintenir un miroir git par application (un dépôt autonome consultable), et consommer une application depuis un autre projet. Lisez ce guide avant de préparer une release ou de brancher une dépendance en aval.

Prérequis

Avant de publier une application :

  • Augmentez son vsn dans apps/<app>/src/<app>.app.src (Hex refuse d’écraser une version publiée), et augmentez au même pas les versions épinglées couplées dans les deps par défaut des applications qui en dépendent (par exemple, augmenter barrel_vectordb signifie mettre à jour l’épinglage {barrel_vectordb, ...} dans barrel).
  • Vérifiez que l’application a un README.md, une LICENSE, un CHANGELOG.md, un bloc ex_doc, et {rebar3_hex, "7.2.0"} dans ses project_plugins (voir la note sur le plugin plus bas).
  • Ne taguez pas l’application. Fusionner le changement de version dans main publie le bundle Barrel (YYYY.MM.N), qui enregistre la version de chaque application ; voir releases.

Ordre de publication

Les applications dépendent les unes des autres : publiez d’abord les feuilles et remontez. Un paquet ne peut être publié qu’une fois que chaque application sœur dont il dépend est déjà sur Hex. L’ordre, avec la version que porte chaque application dans l’arbre :

#ApplicationVersionDépend de
1barrel_crypto1.0.0
2barrel_embed2.5.0
3barrel_docdb1.7.0barrel_crypto
4barrel_rerank1.0.2
5barrel_faiss1.0.1(optionnel ; la bibliothèque C++ FAISS pour le build)
6barrel_vectordb2.5.0barrel_embed, barrel_crypto
7barrel_ngram0.11.1barrel_docdb
8barrel_att_s30.1.1barrel_docdb
9barrel1.10.0barrel_crypto, barrel_docdb, barrel_vectordb, barrel_embed
10barrel_spaces1.2.2barrel, barrel_docdb, barrel_crypto
11barrel_server1.10.0barrel, barrel_spaces, barrel_ngram

Ne publiez que les applications dont la version n’est pas encore sur Hex (curl -s https://hex.pm/api/packages/<app> affiche la dernière), dans cet ordre. barrel_vectordb et barrel_embed gardent leurs lignes 2.x ; les autres applications 1.x s’engagent à ne pas casser leur API sans changement de version majeure.

Publier sur Hex

Chaque application publiable déclare ses applications sœurs comme dépendances Hex dans les {deps, [...]} par défaut de son rebar.config. Ce n’est ni optionnel ni cosmétique : rebar3_hex construit les requirements du paquet à partir du lockfile du profil par défaut, donc une dépendance placée dans un profil hex (ou n’importe quel autre) est retirée du tarball sans avertissement. Le paquet se publie et s’installe alors sans erreur, et le consommateur tombe sur un undef à l’exécution. Ne mettez pas les dépendances sœurs dans un profil hex.

Par exemple apps/barrel_spaces/rebar.config :

{deps, [
    {barrel_crypto, "~> 1.0"},
    {barrel_docdb, "~> 2.0"},
    {barrel, "~> 1.3"}
]}.

Dans l’umbrella, elles se résolvent comme applications locales du projet ; sur Hex, elles se résolvent depuis Hex. Utilisez des épinglages ~> pour qu’une release de correctif d’une application sœur n’impose pas de republier chaque application qui en dépend.

$ cd apps/barrel_embed
$ rebar3 hex publish

Publiez dans l’ordre des dépendances, par exemple les applications d’une release :

$ for app in barrel_ngram barrel barrel_server; do
    (cd apps/$app && rebar3 hex publish --yes)
  done

Le plugin Hex est épinglé à {rebar3_hex, "7.2.0"} dans chaque rebar.config. rebar3_hex 7.3.0 avec hex_core 0.19.0 plante à la publication (un badmatch sur cli_auth_callbacks dans hex_cli_auth:call_callback). 7.2.0 résout hex_core 0.18.0 ; vérifiez avec ls _build/default/plugins après un build, et gardez l’épinglage jusqu’à la sortie d’une version corrigée.

Avant de publier, faites un essai à blanc de chaque tarball avec rebar3 hex build et vérifiez son contenu (en particulier pour les applications NIF barrel_vectordb/barrel_faiss, dont le {files, [...]} du .app.src doit inclure c_src et les scripts de build racine do_cmake.sh / do_faiss.sh).

Vérifier d’abord les dépendances déclarées

rebar3_hex construit les requirements du paquet à partir de rebar.lock, pas de rebar.config. Deux choses retirent une dépendance du tarball sans avertissement :

  • _checkouts/. Une application sœur résolue par un checkout n’entre jamais dans le lock, elle disparaît donc des requirements. Le paquet se publie et s’installe sans erreur, et le consommateur tombe sur un undef à l’exécution.
  • Un apps/<app>/rebar.lock périmé. Il est ignoré par git : c’est donc ce que votre dernier build local a laissé. Une dépendance verrouillée à un niveau transitif ne devient pas un requirement, même quand rebar.config la nomme directement.

La publication est irréversible : une version ne peut pas être refaite. Pour chaque application, dans l’ordre, supprimez donc les deux, reconstruisez et vérifiez :

$ cd apps/<app>
$ rm -rf _checkouts rebar.lock
$ rebar3 compile                     # regenerate rebar.lock from Hex
$ rebar3 hex build                   # siblings resolve from Hex (default deps)
$ cd ../..
$ python3 scripts/check_hex_requirements.py apps/<app>

rebar3 hex build a besoin d’un lockfile : lancez donc d’abord rebar3 compile (supprimer rebar.lock sans le régénérer fait échouer le build avec « No lockfile detected »). Les applications sœurs se résolvent depuis Hex : chaque application sœur dont dépend une application doit donc déjà être publiée (l’ordre de publication ci-dessus le garantit).

Le script compare les requirements du tarball aux deps du rebar.config de l’application et sort avec un code non nul à la moindre omission. Il ne passe qu’une fois que chaque application sœur dont dépend l’application est déjà sur Hex, ce qui correspond exactement à l’ordre de publication ci-dessus.

Notes :

  • La liste {files, [...]} de chaque .app.src contrôle ce qui part dans le tarball. Tenez-la à jour quand vous ajoutez des ressources priv/ ou des includes.
  • Chaque dépendance se résout depuis Hex, y compris livery (0.10.3) et barrel_mcp (4.1.1) pour barrel_server. Hex refuse les dépendances git, gardez donc les choses ainsi : ne réintroduisez pas de dépendance {git, ...} dans une application que vous comptez publier.
  • barrel_faiss fournit une NIF qui demande la bibliothèque C++ FAISS au moment du build. Le paquet ne se construit que là où cette chaîne d’outils est présente.
  • Augmentez le vsn dans .app.src avant de publier ; Hex refuse d’écraser une version publiée.

Maintenir un miroir git par application

Utilisez cette méthode quand vous voulez un dépôt git autonome et consultable pour une application (par exemple pour en dépendre avec une dépendance {git, ...}, ou pour la publier sur sa propre forge). L’umbrella reste la source de vérité et vous poussez vers l’extérieur un historique limité à une application.

git subtree split produit une branche qui ne contient que l’historique de cette application. L’opération est répétable : vous pouvez la relancer à chaque release pour mettre le miroir à jour.

$ git subtree split --prefix=apps/barrel_embed -b export/barrel_embed
$ git push git@code.barrel-db.eu:barrel-db/barrel_embed.git export/barrel_embed:main

git filter-repo fait une extraction propre et ponctuelle, avec l’application réécrite à la racine du dépôt. Il réécrit l’historique : il sert donc à amorcer un nouveau dépôt, pas à synchroniser.

$ git clone . /tmp/barrel_embed && cd /tmp/barrel_embed
$ git filter-repo --subdirectory-filter apps/barrel_embed
$ git remote add origin git@code.barrel-db.eu:barrel-db/barrel_embed.git
$ git push -u origin main

Notes :

  • Préférez subtree split pour les miroirs suivis dans la durée et filter-repo pour l’extraction initiale.
  • Remplacez le dépôt distant d’exemple par votre forge. Les links du paquet dans chaque .app.src pointent vers le dépôt de l’umbrella ; les miroirs par application sont optionnels (l’umbrella est la source de vérité).
  • Pilotez les miroirs depuis le workflow de release du bundle, pour que chaque bundle Barrel (YYYY.MM.N) se propage vers les dépôts autonomes.

Consommer une application ailleurs

Depuis un autre projet, dépendez d’une application distribuée sous la forme qui correspond à la façon dont vous l’avez livrée.

Paquet Hex (après publication) :

{deps, [
    {barrel_embed, "~> 2.5"}
]}.

Miroir git, épinglé sur le bundle Barrel qui contient la version voulue :

{deps, [
    {barrel_embed, {git, "https://code.barrel-db.eu/barrel-db/barrel_embed.git",
                    {tag, "v2026.11.8"}}}
]}.

Checkout local de l’umbrella (le plus rapide pour le co-développement, sans étape de publication) :

{deps, [
    {barrel_embed, {path, "../barrel/apps/barrel_embed"}}
]}.

Si vous voulez au contraire que les applications vivent dans leurs propres dépôts et que l’umbrella les intègre (l’inverse du miroir), utilisez des sous-modules git :

$ git submodule add git@code.barrel-db.eu:barrel-db/barrel_embed.git apps/barrel_embed

Les dépôts par application deviennent alors la source de vérité, et l’umbrella un consommateur qui épingle chaque application à un commit. Cela ramène les changements coordonnés entre plusieurs dépôts : ne l’utilisez que si vous décidez d’inverser le modèle actuel.

Traduit de la page anglaise: /docs/guides/distributing-apps/ (docs/guides/distributing-apps.md) Modifier cette page Voir en Markdown

Haut et bas pour se déplacerEntrée pour ouvrir