Aller au contenu

Concept : Les Manifestes Modulaires de Paquets

Navigation : Documentation > Manifestes
Spécification technique détaillée : 05. Spécification des Manifestes Modulaires
Spécification des hooks : 06. Scripts Normalisés et Contexte

Sommaire

  1. Philosophie du Format Modulaire
  2. Structure d'un Dossier de Paquet
  3. Détail des Fichiers de Déclaration
  4. 3.1 package.toml : Métadonnées générales
  5. 3.2 targets.toml : Plateformes, URLs et Binaires
  6. 3.3 verification.toml : Commandes sanitaires obligatoires
  7. 3.4 shortcuts.toml : Raccourcis GUI (Optionnel)
  8. Hooks de Cycle de Vie (.nu)
  9. Contrôles de Sécurité & Validations CI
  10. Liens et Références Associées

1. Philosophie du Format Modulaire

Contrairement aux gestionnaires qui regroupent toutes les informations dans un seul fichier monolithique JSON complexe (ex: Scoop) ou un script impératif (ex: Homebrew Ruby), Érable découpe chaque paquet en fichiers déclaratifs TOML spécialisés situés dans un sous-dossier parts/.

Avantages :

  • Lisibilité immédiate : Un mainteneur ou contributeur peut inspecter ou modifier les URLs d'une plateforme sans toucher aux métadonnées générales.
  • Merge Requests sans conflits : Les bots de mise à jour automatique mettent à jour uniquement targets.toml ou package.toml sans risque d'écraser des configurations spécifiques.
  • Parsing O(1) léger : Le moteur Érable ne charge en mémoire que les parties dont il a besoin.

2. Structure d'un Dossier de Paquet

Chaque paquet est hébergé dans le répertoire shardé d'un bucket : packages/<lettre>/<nom-du-paquet>/ :

packages/r/ripgrep/
├── parts/
│   ├── package.toml        # Métadonnées, licence, version
│   ├── targets.toml        # URLs, sommes SHA-256 et binaires par OS
│   ├── verification.toml   # Sanity checks obligatoires (check_version, check_help)
│   ├── autoupdate.toml     # (Recommandé) Surveillance automatisée des releases
│   └── shortcuts.toml      # (Optionnel) Raccourcis menu / bureau (GUI)
├── pre_install.nu          # (Optionnel) Hook exécuté avant le téléchargement/l'extraction
├── post_install.nu         # (Optionnel) Hook exécuté après l'extraction et trampolines
├── pre_uninstall.nu        # (Optionnel) Hook exécuté avant la suppression des fichiers
└── post_uninstall.nu       # (Optionnel) Hook exécuté après le nettoyage et la purge

3. Détail des Fichiers de Déclaration

3.1 package.toml : Métadonnées générales

Définit l'identité du logiciel, sa version courante et sa catégorisation :

name = "ripgrep"
version = "14.1.0"
description = "Outil de recherche récursive ultra-rapide basé sur des expressions régulières"
homepage = "https://github.com/BurntSushi/ripgrep"
license = "MIT"
categories = ["cli", "developer-tools", "search"]
tags = ["regex", "grep", "rust", "fast"]

3.2 targets.toml : Plateformes, URLs et Binaires

Mappe chaque architecture prise en charge avec son URL de téléchargement, son empreinte SHA-256 et la définition des trampolines à créer :

[targets.x86_64-windows]
url = "https://github.com/BurntSushi/ripgrep/releases/download/14.1.0/ripgrep-14.1.0-x86_64-pc-windows-msvc.zip"
sha256 = "eb39d6ec36e651e44f849ffb19f0ffbe0c14f6b5b5c90b6e159aa4b7f8c1f930"
archive_type = "zip"

[[targets.x86_64-windows.binaries]]
source = "ripgrep-14.1.0-x86_64-pc-windows-msvc/rg.exe"
alias = "rg"

[targets.x86_64-linux]
url = "https://github.com/BurntSushi/ripgrep/releases/download/14.1.0/ripgrep-14.1.0-x86_64-unknown-linux-musl.tar.gz"
sha256 = "b7a0d4c82c65a4c9b3191f6305a2e5d95e09f582c0fa642a8b3ff5fa1c8d5c41"
archive_type = "tar.gz"

[[targets.x86_64-linux.binaries]]
source = "ripgrep-14.1.0-x86_64-unknown-linux-musl/rg"
alias = "rg"

[targets.aarch64-macos]
url = "https://github.com/BurntSushi/ripgrep/releases/download/14.1.0/ripgrep-14.1.0-aarch64-apple-darwin.tar.gz"
sha256 = "a5e98b7f8b725c50c05943b17c76899b823e20ec4227f272a819b5bfb7d9c661"
archive_type = "tar.gz"

[[targets.aarch64-macos.binaries]]
source = "ripgrep-14.1.0-aarch64-apple-darwin/rg"
alias = "rg"

3.3 verification.toml : Commandes sanitaires obligatoires

Définit les sanity checks minimaux exécutés sur chaque OS cible pour certifier l'installation : 

[verification]
check_version = { command = "rg --version", expected_regex = 'ripgrep 14\.1\.0' }
check_help = { command = "rg --help", expected_contains = "USAGE:" }

3.4 shortcuts.toml : Raccourcis GUI (Optionnel)

Utilisé pour les applications graphiques (Bucket gui) :

[[shortcuts]]
target = "vlc.exe"
name = "VLC Media Player"
category = "AudioVideo"
icon = "vlc.ico"

4. Hooks de Cycle de Vie (.nu)

Certains logiciels nécessitent des étapes personnalisées sécurisées lors du cycle de vie :

  • pre_install.nu : Exécuté avant le téléchargement et l'extraction de l'archive.
  • post_install.nu : Exécuté immédiatement après l'extraction et le déploiement des trampolines.
  • pre_uninstall.nu : Exécuté avant la suppression des fichiers du paquet et des shims.
  • post_uninstall.nu : Exécuté immédiatement après la suppression et le nettoyage complet.

Les scripts doivent obligatoirement respecter la signature def main [ctx: record] et se conformer à la politique stricte Zero Egress (aucun accès réseau curl, wget, ni accès aux répertoires sensibles .ssh, .env, tokens) : 

# post_install.nu
def main [ctx: record] {
    print $"Configuration post-installation pour ($ctx.package)..."
    # Accès sécurisé aux chemins : $ctx.paths.install, $ctx.version, etc.
}

5. Contrôles de Sécurité & Validations CI

Chaque manifeste soumis fait l'objet d'audits automatisés stricts dans le pipeline CI/CD :

  1. Audit Statique Zero Egress (scripts/ci/audit_package_scripts.py) : Rejet bloquant immédiat de tout script .nu utilisant curl, wget, http get/post, ssh, eval, ou tentant d'accéder à des secrets d'environnement ou fichiers système protégés.
  2. Validation syntaxique TOML : Structure conforme aux schémas stricts.
  3. Immutabilité SHA-256 & Anti-Zip Slip : L'empreinte cryptographique est recalculée et validée, avec inspection d'archive interdisant tout contournement de chemin.
  4. Validation du Cycle de Vie sur OS Cibles : Exécution sur machines réelles (Windows, Linux, macOS) avec exécution des sanity checks de verification.toml (check_version, check_help), puis désinstallation et confirmation matérielle de la purge absolue du store et des binaires.
  5. Attestation SLSA 3 & Signature Ed25519 : Traçabilité et signature cryptographique de l'index du bucket.

6. Liens et Références Associées