build2-community/build2-package

Que fait build2-package ?

Résoudre ROOT

Soit HERE le répertoire qui contient ce SKILL.md (chemin absolu depuis le contexte système).

ROOT est l'arbre de compétences build2. Utilisez le premier candidat dont guides/packaging-guide-summary.md existe :

1. HERE/../build2 (disposition en voisin : ce répertoire à côté d'une compétence build2, y compris une copie dans un répertoire de compétences au niveau utilisateur)
2. HERE/../.. (disposition imbriquée : ce répertoire sous le sous-répertoire skills/ de la compétence build2)

Si aucun n'existe, arrêtez.

Tous les chemins read_file ultérieurs sont ${ROOT}/....

Ce fichier est la procédure. Les guides de packaging sous ${ROOT}/guides/ et ${ROOT}/HOWTO/ sont la source de vérité pour chaque étape. N'inventez pas de disposition, d'invocation bdep new, de nom de branche ou de séquence de publication.

Les actions externes nécessitent une approbation explicite

Cette compétence crée un paquet réel et publiquement visible et le publie éventuellement. Rien de ce qui devient visible en dehors de votre propre arbre de travail local ne se produit automatiquement. Cela couvre : la création d'un dépôt sur GitHub, tout git push (une branche ou une étiquette), le transfert ou le renommage d'un dépôt sur GitHub, l'ouverture ou la fusion d'une pull request, l'exécution de bdep ci, et l'exécution de bdep publish.

Exécuter /build2-package (ou /build2 package) n'est pas une approbation pour l'une de ces actions, et atteindre la porte où l'une d'elles se produit non plus. Avant d'effectuer l'une d'elles pour la première fois dans cette session, arrêtez, décrivez exactement ce qui va se passer (la commande et ce qu'elle rend visible à l'extérieur), et attendez le feu vert explicite de l'utilisateur pour cette action spécifique. L'approbation pour une action ne s'applique pas à une autre, demandez à nouveau à chaque fois. Par défaut : aucune de ces actions ne se produit à moins que l'utilisateur ne le demande explicitement pour cette étape.

Tout le reste, les commits locaux, la création de branches, l'édition de fichiers, les builds et tests locaux, le clonage ou le fetch en lecture seule, se déroule sans demander.

Règles strictes

Elles ne sont pas optionnelles. En violer une seule entraîne un échec de la session.

1. N'écrivez jamais de buildfiles à partir de zéro. Commencez toujours par bdep new. N'utilisez pas ${ROOT}/scripts/new-package.sh pour ce workflow.
2. Ne touchez jamais à main après le premier commit bdep new --type empty,third-party jusqu'à la fusion fast-forward de review au moment de la publication.
3. Ne regroupez (vendorisez) jamais les dépendances. Déregroupez-les en depends.
4. Ne mettez jamais de cibles lib{} / exe{} principales dans le buildfile racine.
5. Ne faites jamais d'une bibliothèque un header-only si l'amont fournit un mode compilé.
6. Ne sautez jamais la recette de distribution source (b dist, puis configure, update, test, clean dans l'archive décompressée). Un bdep ci vert ne suffit pas.
7. Ne descendez jamais les lignes générées depends: * build2 / depends: * bpkg.
8. Ne devinez jamais une étiquette amont, une licence ou un schéma d'inclusion d'en-tête public. Si ce n'est pas dans l'arbre ou dans une page récupérée, arrêtez et demandez.
9. Un commit git par étape de packaging logique (ou un groupe étroitement lié). Un commit dont l'arbre est exactement une invocation bdep new utilise cette ligne de commande comme message de commit, rien d'autre. Un commit qui crée une paire de superposition .orig/.patch pour un fichier amont utilise Patch <filename>: <reason> (corps <details> facultatif pour un patch non trivial) comme message, voir packaging-guide-antipatterns.md.
10. Ne fusionnez pas review dans main, n'exécutez pas bdep release, et n'exécutez pas bdep publish tant que les tests locaux, les tests de cas installé, les tests de distribution et le CI ne sont pas verts.
11. Chaque lien symbolique de répertoire (pas un lien symbolique de fichier simple) nécessite une entrée symlink=dir correspondante dans le <pkg>/.gitattributes de ce paquet (un nouveau fichier, bdep new --package n'en génère pas), dans le même commit qui ajoute le lien symbolique. Vérifiez avec find <pkg>/ -type l -exec test -d {} \; -print et recoupez chaque résultat avec <pkg>/.gitattributes. git n'enregistre pas le type de lien symbolique et recrée toujours un lien symbolique de fichier lors du checkout, donc ignorer cela casse le paquet sur un checkout Windows.
12. Ne laissez jamais de commentaire ou de note README qui raconte le processus de packaging lui-même, une approche antérieure qui n'a pas fonctionné, ou un incident en cours de route. Les commentaires et README reflètent uniquement l'état final (voir packaging-guide-antipatterns.md, "Ne laissez pas de commentaires ou de notes de type journal").
13. Ne créez jamais de dépôt, ne poussez, ne transférez ou ne renommez jamais un dépôt sur GitHub, n'ouvrez ou ne fusionnez jamais une pull request, n'exécutez jamais bdep ci, ou n'exécutez jamais bdep publish sans l'approbation explicite de l'utilisateur pour cette action spécifique, donnée à ce moment (voir "Les actions externes nécessitent une approbation explicite" ci-dessus). Par défaut, aucune de ces actions ne se produit.

Lectures obligatoires (cette session, avant toute écriture)

Lisez ces fichiers en intégralité avec read_file avant de créer un dépôt, d'éditer un buildfile ou de publier. Ne les parcourez pas superficiellement.

1. ${ROOT}/guides/packaging-guide-summary.md
2. ${ROOT}/guides/packaging-guide-testing.md
3. ${ROOT}/guides/packaging-guide-antipatterns.md
4. ${ROOT}/HOWTO/package-naming.md

Ensuite, chargez à la demande à partir de la carte à la fin de ce fichier. Ne remplacez jamais la mémoire par un guide que ce fichier nomme.

Revérifiez avec les documents de checklist au fur et à mesure

Un cycle de packaging complet (Portes A-K, ou une session new-version/revision) peut s'étendre sur bien plus de sessions qu'une seule fenêtre de contexte ne peut en contenir. Les sessions précédentes, y compris les lectures obligatoires ci-dessus, peuvent déjà être résumées au moment où vous atteignez une porte ultérieure. Avoir lu un guide une fois au début ne signifie pas que ses règles sont toujours en contexte, ne vous fiez pas à la mémoire de la conversation pour elles.

Rouvrez et revérifiez l'état actuel de l'arbre par rapport à ces documents de type checklist au moins une fois par porte, et à nouveau juste avant la Porte K (moment de la publication) :

• ${ROOT}/guides/packaging-guide-antipatterns.md : ce qu'il ne faut pas faire (buildfiles écrits à la main, correction de l'amont dans le paquet, disposition amont modifiée, header-only malgré un mode compilé, dépendances regroupées, cibles principales dans le buildfile racine, une révision trop large, une mauvaise inclusion d'en-tête, un patch ad hoc, des commentaires ou notes de type journal).
• ${ROOT}/guides/packaging-guide-review.md : la même checklist qu'un relecteur cppget.org applique. Auto-vérifiez l'arbre par rapport à elle avant la publication plutôt que de le découvrir pendant la relecture réelle.
• ${ROOT}/HOWTO/third-party-private-headers.md : les en-têtes privés ne doivent pas atteindre l'arbre d'installation.
• ${ROOT}/HOWTO/buildfile-compile-options.md : quelles options de compilation/édition de liens sont locales par rapport à exportées.
• ${ROOT}/HOWTO/package-naming.md : les décisions de nommage prises à la Porte E, un renommage découvert tardivement est coûteux.
• ${ROOT}/guides/packaging-guide-summary.md Étape 5 : chaque lien symbolique de répertoire dans chaque paquet a une entrée symlink=dir dans le <pkg>/.gitattributes de ce paquet (Règle stricte 11).

Si l'arbre ne correspond plus à l'un de ces éléments, corrigez-le avant de passer à la porte suivante plutôt que de reporter la dérive.

Arguments

$ARGUMENTS est le texte d'invocation après /build2-package (ou après /build2 package). Analysez-le dans l'ordre. La première règle correspondante l'emporte.

Premier jeton	Mode
vide / omis	new si le répertoire de travail n'est pas déjà un dépôt de packaging, sinon continue
new	cycle de packaging initial
new-version	nouvelle version amont après la première publication
revision	révision de packaging (X.Y.Z+R)
continue	reprendre le cycle en cours dans le répertoire de travail
autre chose	si cela ressemble à une URL git ou owner/repo, traiter comme new avec cet amont. Sinon, demander.

Jetons restants : <upstream-url> facultatif et <tag-or-version> facultatif. Si l'un manque et est requis pour le mode, demandez. Ne les inventez pas.

Signalez le mode choisi à l'utilisateur avant la première écriture.

Mode : continue

Inspectez le répertoire de travail (et son historique git) et reprenez à la première porte incomplète dans le mode correspondant ci-dessous. Les preuves l'emportent sur le résumé de la conversation.

Preuve	Reprendre à
Pas de .git, ou pas de premier commit bdep new --type empty,third-party	new depuis le début
Le premier commit existe, pas de branche review	créer review et continuer new
Sur review, pas de sous-module upstream/	ajouter l'amont
upstream/ présent, pas de répertoire de paquet / pas de bdep new --package	structure du paquet
Échafaudage du paquet présent, tests ou CI non verts	tests
Tests verts, review non fusionnée dans main	fusion au moment de la publication
Sur main après fusion, pas d'étiquette vX.Y.Z	release puis publish
Déjà publié, l'utilisateur a demandé un nouvel amont	new-version
Déjà publié, l'utilisateur a demandé une correction de packaging	revision

Si le dépôt est sur main avec des commits de packaging qui auraient dû être sur review, arrêtez. C'est une erreur de processus. Ne réécrivez pas l'historique publié. Demandez à l'utilisateur comment récupérer.

Mode : new (cycle initial)

Suivez la checklist dans ${ROOT}/guides/packaging-guide-summary.md et les étapes 8-10 dans ${ROOT}/guides/packaging-guide-testing.md. Les portes numérotées ci-dessous sont celles qui ne doivent pas être sautées ou réordonnées.

Porte A : travail existant

Recherchez dans les quatre, dans cet ordre, et signalez les résultats :

1. https://cppget.org/?advanced-search
2. https://queue.cppget.org
3. https://github.com/build2-packaging
4. https://github.com/build2-packaging/WISHLIST

Si un dépôt ou un paquet publié existe déjà, arrêtez et demandez s'il faut rejoindre ce travail (continue / new-version / revision) plutôt que de commencer un doublon.

Porte B : dépôt vide et premier commit

Arrêtez et obtenez une approbation explicite avant les actions externes de cette porte : créer le dépôt GitHub et pousser le commit initial vers celui-ci. Faites d'abord l'échafaudage local (bdep new, git add, git commit) si cela aide à montrer ce qui va être poussé, mais ne créez pas le dépôt distant et n'exécutez pas git push tant que l'utilisateur n'a pas donné son feu vert.

Créez un dépôt git public vide dans l'espace de travail personnel de l'utilisateur. Description : build2 package for <name>. Clonez avec SSH. Pas de README, pas de licence, pas de fichiers générés par GitHub.

bdep new --type empty,third-party
git add .
git commit -m "bdep new --type empty,third-party"
git push -u origin main

Vérifiez avant de continuer :

• git rev-list --max-parents=0 HEAD est ce commit.
• git show --stat --format=%s HEAD le message est exactement bdep new --type empty,third-party.
• L'arbre ne contient que des fichiers générés par cette commande.

Si un fichier supplémentaire ou une édition manuelle se trouve dans ce commit, réinitialisez et refaites. Le processus de relecture en dépend.

Porte C : branche review

git checkout -b review

Restez sur review pour chaque commit ultérieur de ce cycle. Ne faites pas git checkout main. Ne fusionnez pas. Ne publiez pas.

Porte D : sous-module amont

git submodule add https://github.com/<upstream>/<repo>.git upstream

Utilisez https:// uniquement. Checkoutez le commit de release (étiquette). Commitez : Add upstream submodule, <tag>.

Porte E : noms et disposition

Relisez ${ROOT}/HOWTO/package-naming.md si nécessaire. Décidez et écrivez les décisions avant de générer le paquet :

• Nom du dépôt Git : casse amont, pas de préfixe build2-, pas de suffixe -package.
• project: et project = : minuscules sauf si la casse mixte est l'identifiant amont (Qt est l'exception documentée).
• name: du paquet : préfixe lib pour les bibliothèques sauf si Debian et l'amont rendent un conflit d'exécutable impossible.
• Séparez la bibliothèque de l'exécutable en paquets distincts.
• Schéma d'inclusion d'en-tête public (préfixe de sous-répertoire vs préfixe de nom de fichier).
• include/ / src/ combinés vs séparés.

Restez aussi proche que possible de la disposition amont.

Porte F : pré-remplissage puis bdep new --package

Créez le répertoire du paquet. Liez symboliquement uniquement les fichiers méta amont qui existent (README.md, LICENSE / équivalent, NEWS / CHANGES / ChangeLog). Commitez cela seul. Ensuite :

bdep new --package --lang ... --type lib,...,third-party <name>

Itérez en supprimant et réexécutant, pas en éditant à la main l'échafaudage, jusqu'à ce que la disposition corresponde. La sous-option third-party est requise. Commitez avec la ligne de commande exacte comme message.

Si le nom de base du changelog n'est pas un nom reconnu, définissez changes-file: à la main plus tard. Voir ${ROOT}/HOWTO/package-changes-file.md.

Porte G : version, manifeste, dépendances

• La version reste X.Y.Z-a.0.z jusqu'à bdep release --no-open.
• summary : moins de 70 caractères, pas de termes vagues, pas de point final.
• -tests / -examples / -benchmarks associés : copiez le résumé principal et ajoutez (tests) (ou le type correspondant). Ne le réécrivez pas. Voir ${ROOT}/HOWTO/tests-extra-dependencies.md.
• license: est SPDX (ou other:). Voir ${ROOT}/guides/packaging-license.md.
• Décommentez la prérequise pkg.cppget.org. Utilisez la section la moins stable qui contient encore chaque dépendance. Ne laissez pas queue.cppget.org dans un repositories.manifest de longue durée.
• bdep sync -a après les modifications de depends.
• Les en-têtes d'interface dans les en-têtes publics de cette bibliothèque vont dans intf_libs. Tout le reste va dans impl_libs.

Porte H : remplir la source et les buildfiles

Remplissez l'arbre du paquet avec la source amont avant de toucher aux buildfiles : liez d'abord symboliquement les fichiers d'en-tête/source individuels, et liez symboliquement un sous-répertoire entier seulement lorsque cela économise de nombreux liens symboliques individuels (nécessite la disposition buildfile-in-prefix, voir packaging-guide-antipatterns.md). Suivez l'exemple travaillé dans ${ROOT}/guides/packaging-guide-summary.md Étape 5.

Obligatoire : pour chaque lien symbolique de répertoire ajouté, ajoutez une entrée symlink=dir correspondante dans le <pkg>/.gitattributes de ce paquet (créez le fichier s'il n'existe pas encore) dans le même commit. Vérifiez avec find <pkg>/ -type l -exec test -d {} \; -print et recoupez chaque résultat. C'est la règle stricte 11, l'ignorer casse le paquet sur un checkout Windows. Commitez les liens symboliques (et .gitattributes) avant d'ajuster les buildfiles, pour faciliter le rollback.

Ensuite, ajustez uniquement les fichiers générés. Préservez la structure générée et les commentaires.

Chargez à la demande :

• en-têtes / en-têtes privés : ${ROOT}/HOWTO/third-party-private-headers.md
• SONAME / nom de sortie : ${ROOT}/HOWTO/buildfile-output-name.md
• options de compilation : ${ROOT}/HOWTO/buildfile-compile-options.md
• configuration lua : ${ROOT}/HOWTO/buildfile-config-lua.md
• scripts de test : ${ROOT}/guides/packaging-guide-testing.md
• tout guide de cette liste qui existe et est pertinent.

Porte I : version manifeste dans les en-têtes

Vérifiez les en-têtes publics pour une version codée en dur (#define VERSION ... ou similaire. Si elles en ont, créez un script de version manifeste (.build2/), ne modifiez pas l'en-tête amont. Voir ${ROOT}/HOWTO/manifest-version-header.md.

Porte J : test local, test de distribution, CI

1. b configure (TBD) dans la hiérarchie du paquet.
2. b test (sur chaque paquet).
3. Tests de cas installé (b install, voir packaging-guide-testing.md).
4. Distribution source (b dist, puis décompressez, configure, update, test, clean).
5. git push -u origin review (APPROBATION EXTERNE REQUISE).
6. Passez en revue et fusionnez une pull request vers le dépôt original (ou votre fork pour l'instant).
7. bdep ci (APPROBATION EXTERNE REQUISE).

Ne passez pas à la porte suivante tant que toutes ces étapes ne sont pas vertes.

Porte K : publication

Approbation explicite de l'utilisateur requise pour créer un tag, pousser un tag, et exécuter bdep publish.

1. Fusion de review dans main : git checkout main && git merge --ff-only review. (Aucun commit de fusion).
2. git push origin main (APPROBATION EXTERNE REQUISE).
3. bdep release --no-open --tag.
4. git push --tags (APPROBATION EXTERNE REQUISE).
5. bdep publish (APPROBATION EXTERNE REQUISE).

Après la publication, revenez à review et recommencez pour toute porte ultérieure :

git checkout review

Mode : new-version (nouvelle version amont après la première publication)

...

Mode : revision (révision de packaging X.Y.Z+R)

...

Carte des guides

(Liste des guides référencés avec des chemins et des descriptions - à charger à la demande)