Concepts

Builders et artefacts

Construire, valider et injecter automatiquement des artefacts pendant provision.

Un builder est un pack spécialisé, décrit par xbee-pack-builder.yaml. Il produit une arborescence de fichiers qu’un autre pack reçoit automatiquement pendant son provision, sans intégrer le builder lui-même à l’image finale.

Le pack consommateur déclare uniquement le builder :

# xbee-pack.yaml
builder:
  origin: ./frontend-builder

provision:
  - shell: frontend --version

Il ne faut déclarer aucune action copy pour installer son résultat : Xbee ajoute cette action à la forme canonique du provision.

Le manifeste builder déclare obligatoirement une action build. Les fichiers placés sous {{ .xbee.out }} constituent l’artefact :

# frontend-builder/xbee-pack-builder.yaml
schema-version: "1.0"
require: ubuntu:24.04

provision:
  - folder: "{{ .xbee.out }}/usr/local/bin"

build:
  - shell: npm ci && npm run build
  - shell: cp dist/frontend "{{ .xbee.out }}/usr/local/bin/frontend"

Xbee crée automatiquement {{ .xbee.src }} et {{ .xbee.out }}, puis ajoute au builder une action d’export de {{ .xbee.out }}. Le résultat est archivé sous le nom <hash-builder>.tar.

Injection pendant provision

Avant de provisionner le pack consommateur, Xbee résout et construit si nécessaire tous ses builders. Il enrichit ensuite automatiquement provision.actions avec une action conceptuellement équivalente à :

copy:
  from: "{{ .xbee.builders }}/<hash-builder>.tar"
  todir: /
  unpack: true
order:
  phase: first

Cette action interne décompresse l’archive à la racine de la cible avant les actions ordinaires de provisioning. Par exemple :

{{ .xbee.out }}/usr/local/bin/frontend
                    ↓
          /usr/local/bin/frontend

Le contenu de {{ .xbee.out }} doit donc reproduire l’arborescence finale attendue. deploy n’intervient pas dans l’installation d’un artefact builder.

Résolution et intégrité

Pour chaque couple système/builder, Xbee cherche successivement un artefact local valide, un artefact dans le cache distant, puis construit le builder localement. Un manifeste associé enregistre notamment la taille, le nombre de fichiers et le SHA-256 ; un artefact corrompu n’est pas accepté.

Les artefacts locaux vivent sous cache-exports/ dans le répertoire interne Xbee (~/.xbee par défaut).

Les builders sont résolus récursivement : ceux d’un pack système, des dépendances et des sous-dépendances sont également construits et injectés dans le provision du pack qui les déclare.

Inspection

Depuis un pack ou un environnement :

xbee builder list
xbee builder graph
xbee builder graph --json
xbee builder inspect <sélecteur>
xbee builder build <sélecteur>

list donne une vue tabulaire, graph affiche les relations avec les packs consommateurs et inspect détaille le cache et l’intégrité d’un builder.

Cache local et distant

xbee builder clean <sélecteur>
xbee builder clean --all
xbee builder push <sélecteur>
xbee builder pull <sélecteur>
xbee builder remote inspect <sélecteur>
xbee builder remote clean <sélecteur>

Les commandes qui acceptent un sélecteur acceptent aussi généralement --all. Les suppressions demandent confirmation, sauf avec --force.

Pendant xbee pack, les options suivantes contrôlent la résolution :