build2-community/build2-package

Was macht build2-package?

ROOT auflösen

Sei HERE das Verzeichnis, das diese SKILL.md enthält (absoluter Pfad aus dem Systemkontext).

ROOT ist der build2-Skillbaum. Verwende den ersten Kandidaten, unter dem guides/packaging-guide-summary.md existiert:

1. HERE/../build2 (Geschwister-Layout: dieses Verzeichnis neben einem build2-Skill, einschließlich einer Kopie in ein skills-Verzeichnis auf Benutzerebene)
2. HERE/../.. (verschachteltes Layout: dieses Verzeichnis unter dem build2-Skills skills/-Unterverzeichnis)

Wenn keines existiert, brich ab.

Alle späteren read_file-Pfade sind ${ROOT}/....

Diese Datei ist die Vorgehensweise. Die Paketierungsanleitungen unter ${ROOT}/guides/ und ${ROOT}/HOWTO/ sind die maßgeblichen Quellen dafür, wie jeder Schritt ausgeführt wird. Erfinde kein Layout, keinen bdep new-Aufruf, keinen Branchnamen und keine Veröffentlichungssequenz.

Externe Aktionen erfordern explizite Zustimmung

Dieses Skill erstellt ein echtes, öffentlich sichtbares Paket und veröffentlicht es schließlich. Nichts, das außerhalb deines eigenen lokalen Arbeitsbaums sichtbar wird, geschiet automatisch. Das umfasst: Erstellen eines Repositorys auf GitHub, jegliches git push (eines Branches oder eines Tags), Übertragen oder Umbenennen eines Repositorys auf GitHub, Öffnen oder Mergen eines Pull-Requests, Ausführen von bdep ci und Ausführen von bdep publish.

Das Ausführen von /build2-package (oder /build2 package) ist keine Zustimmung zu einer dieser Aktionen, und auch das Erreichen eines Gates, bei dem eine davon stattfindet, ist es nicht. Bevor du eine dieser Aktionen zum ersten Mal in diesem Durchlauf ausführst, halte an, teile genau mit, was gleich passieren wird (den Befehl und was er extern sichtbar macht), und warte auf die explizite Zustimmung des Benutzers für diese spezifische Aktion. Die Zustimmung zu einer solchen Aktion überträgt sich nicht auf eine spätere; frage jedes Mal erneut. Standardannahme: Keine dieser Aktionen findet statt, es sei denn, der Benutzer bittet ausdrücklich um diesen Schritt.

Alles andere, lokale Commits, Brancherstellung, Dateibearbeitung, lokale Builds und Tests, Klonen oder schreibgeschütztes Abrufen, geschieht ohne Nachfrage.

Harte Regeln

Diese sind nicht optional. Ein Verstoß gegen eine einzige Regel bedeutet einen fehlgeschlagenen Durchlauf.

1. Niemals buildfiles von Grund auf neu schreiben. Beginne immer mit bdep new. Verwende nicht ${ROOT}/scripts/new-package.sh für diesen Workflow.
2. Niemals main nach dem ersten bdep new --type empty,third-party Commit berühren, bis zum Fast-Forward-Merge von review zum Zeitpunkt der Veröffentlichung.
3. Niemals Abhängigkeiten bündeln (vendoren). Entbündele sie als depends.
4. Niemals Haupt-lib{} / exe{}-Ziele in die root buildfile setzen.
5. Niemals eine Bibliothek als header-only erstellen, wenn der Upstream eine kompilierte Version ausliefert.
6. Niemals das Quellverteilungs-Rezept überspringen (b dist, dann configure, update, test, clean im entpackten Archiv). Ein grünes bdep ci ist nicht genug.
7. Niemals die generierten depends: * build2 / depends: * bpkg-Zeilen herabsetzen.
8. Niemals einen Upstream-Tag, eine Lizenz oder ein Include-Schema für öffentliche Header erraten. Wenn es nicht im Baum oder auf einer abgerufenen Seite steht, halte an und frage.
9. Ein Git-Commit pro logischem Paketierungsschritt (oder einer eng verwandten Gruppe). Ein Commit, dessen Baum genau einem bdep new-Aufruf entspricht, verwendet diese Befehlszeile als Commit-Nachricht und nichts anderes. Ein Commit, das ein .orig/.patch-Overlay-Paar für eine Upstream-Datei erstellt, verwendet Patch <Dateiname>: <Grund> (optionaler <details>-Body für einen nicht-trivialen Patch) als seine Nachricht, siehe packaging-guide-antipatterns.md.
10. Merge review nicht in main, führe kein bdep release durch und führe kein bdep publish durch, bis lokale Tests, Tests für installierte Fälle, Verteilungstests und CI grün sind.
11. Jeder Verzeichnis-Level-Symlink (kein einfacher Datei-Symlink) benötigt einen passenden symlink=dir-Eintrag in der <pkg>/.gitattributes-Datei dieses Pakets (eine neue Datei, bdep new --package erzeugt keine), im selben Commit, der den Symlink hinzufügt. Überprüfe mit find <pkg>/ -type l -exec test -d {} \; -print und kreuzprüfe jeden Treffer gegen <pkg>/.gitattributes. git zeichnet den Symlink-Typ nicht auf und erstellt bei einem Checkout immer einen Datei-Symlink neu. Das Überspringen dieses Schritts bricht das Paket bei einem Windows-Checkout.
12. Hinterlasse niemals einen Kommentar oder eine README-Notiz, die den Paketierungsprozess selbst erzählt, einen früheren Ansatz, der nicht funktioniert hat, oder ein Missgeschick auf dem Weg. Kommentare und READMEs spiegeln nur den endgültigen Zustand wider (siehe packaging-guide-antipatterns.md, "Hinterlasse keine tagebuchartigen Kommentare oder Notizen").
13. Erstelle kein Repository, push, übertrage oder benenne kein Repository auf GitHub, öffne oder merge keinen Pull-Request, führe kein bdep ci aus und führe kein bdep publish aus, ohne die explizite Zustimmung des Benutzers für diese spezifische Aktion, die zu diesem Zeitpunkt gegeben wird (siehe "Externe Aktionen erfordern explizite Zustimmung" oben). Die Voreinstellung ist, dass keine dieser Aktionen stattfindet.

Obligatorische Lektüren (dieser Durchlauf, vor jedem Schreibzugriff)

Lies diese Dateien mit read_file vollständig, bevor du ein Repository erstellst, eine buildfile bearbeitest oder veröffentlichst. Nicht überfliegen.

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

Dann bei Bedarf aus der Karte am Ende dieser Datei laden. Ersetze niemals das Gedächtnis für eine Anleitung, die diese Datei nennt.

Während der Arbeit erneut gegen die Checklisten-Dokumente prüfen

Ein vollständiger Paketierungsdurchlauf (Gates A-K oder ein new-version/revision Durchlauf) kann sich über weit mehr Durchläufe erstrecken, als ein einzelner Kontextfenster fasst. Frühere Durchläufe, einschließlich der obligatorischen Lektüren oben, können bereits zusammengefasst worden sein, wenn du ein späteres Gate erreichst. Eine Anleitung einmal zu Beginn gelesen zu haben, bedeutet nicht, dass ihre Regeln noch im Kontext sind; verlasse dich nicht auf das Gesprächsgedächtnis für sie.

Öffne und überprüfe den aktuellen Zustands des Baums erneut anhand dieser Checklisten-ähnlichen Dokumente mindestens einmal pro Gate und noch einmal direkt vor Gate K (Veröffentlichungszeitpunkt):

• ${ROOT}/guides/packaging-guide-antipatterns.md: was nicht zu tun ist (handgeschriebene buildfiles, Fix des Upstreams im Paket, geändertes Upstream-Layout, header-only trotz kompilierter Version, gebündelte Abhängigkeiten, Hauptziele in der root buildfile, eine zu breite Revision, schlechte Header-Einbindung, Ad-hoc- Patching, tagebuchartige Kommentare oder Notizen).
• ${ROOT}/guides/packaging-guide-review.md: dieselbe Checkliste, die ein cppget.org-Reviewer anwendet. Überprüfe den Baum selbst dagegen vor der Veröffentlichung, anstatt es während der tatsächlichen Überprüfung herauszufinden.
• ${ROOT}/HOWTO/third-party-private-headers.md: private Header dürfen nicht in den Installationsbaum gelangen.
• ${ROOT}/HOWTO/buildfile-compile-options.md: welche Compile/Link-Optionen lokal vs. exportiert sind.
• ${ROOT}/HOWTO/package-naming.md: die Namensentscheidungen, die bei Gate E getroffen wurden; eine spät entdeckte Umbenennung ist teuer.
• ${ROOT}/guides/packaging-guide-summary.md Schritt 5: jeder Verzeichnis-Symlink in jedem Paket hat einen symlink=dir-Eintrag in der <pkg>/.gitattributes-Datei dieses Pakets (Harte Regel 11).

Wenn der Baum nicht mehr mit einem dieser Dokumente übereinstimmt, korrigiere es, bevor du zum nächsten Gate übergehst, anstatt die Abweichung weiterzutragen.

Argumente

$ARGUMENTS ist der Aufruftext nach /build2-package (oder nach /build2 package). Analysiere ihn in der Reihenfolge. Die erste passende Regel gewinnt.

Erstes Token	Modus
leer / weggelassen	new, wenn cwd nicht bereits ein Paketierungs-Repo ist, sonst continue
new	anfänglicher Paketierungsdurchlauf
new-version	neue Upstream-Version nach der ersten Veröffentlichung
revision	Paketrevision (X.Y.Z+R)
continue	Fortsetzen des laufenden Durchlaufs in cwd
alles andere	wenn es wie eine Git-URL oder owner/repo aussieht, als new mit diesem Upstream behandeln. Sonst fragen.

Verbleibende Token: optionale <upstream-url> und optionaler <tag-or-version>. Wenn eines fehlt und für den Modus erforderlich ist, frage. Erfinde sie nicht.

Melde den gewählten Modus dem Benutzer vor dem ersten Schreibzugriff.

Modus: continue

Untersuche cwd (und seine Git-Historie) und setze am ersten unvollständigen Gate im passenden Modus unten fort. Beweise sind besser als die Gesprächszusammenfassung.

Beweis	Fortsetzen bei
Kein .git, oder kein erster bdep new --type empty,third-party Commit	new von Anfang an
Erster Commit existiert, kein review-Branch	review erstellen und new fortsetzen
Auf review, kein upstream/ Submodul	Upstream hinzufügen
upstream/ vorhanden, kein Paketverzeichnis / kein bdep new --package	Paketstruktur
Paket-Gerüst vorhanden, Tests oder CI nicht grün	Testen
Tests grün, review nicht in main gemerged	Merge zum Zeitpunkt der Veröffentlichung
Auf main nach Merge, kein vX.Y.Z Tag	Release, dann veröffentlichen
Bereits veröffentlicht, Benutzer hat nach neuem Upstream gefragt	new-version
Bereits veröffentlicht, Benutzer hat nach einem Paketierungsfix gefragt	revision

Wenn das Repo auf main mit Paketierungs-Commits ist, die auf review hätten sein sollen, halte an. Das ist ein Prozessfehler. Überschreibe keine veröffentlichte Historie. Frage den Benutzer, wie er sich erholen möchte.

Modus: new (anfänglicher Durchlauf)

Befolge die Checkliste in ${ROOT}/guides/packaging-guide-summary.md und die Schritte 8-10 in ${ROOT}/guides/packaging-guide-testing.md. Die nummerierten Gates unten dürfen nicht übersprungen oder umgeordnet werden.

Gate A: vorhandene Arbeit

Durchsuche alle vier in dieser Reihenfolge und melde die Treffer:

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

Wenn ein Repository oder ein veröffentlichtes Paket bereits existiert, halte an und frage, ob dieser Arbeit beigetreten werden soll (continue / new-version / revision), anstatt ein Duplikat zu starten.

Gate B: leeres Repository und erster Commit

Halte an und hole dir eine explizite Zustimmung, bevor du externe Aktionen dieses Gates durchführst: Erstellen des GitHub-Repositorys und Pushen des ersten Commits dorthin. Führe zuerst das lokale Gerüst (bdep new, git add, git commit) durch, wenn das hilft zu zeigen, was gleich gepusht wird, aber erstelle das entfernte Repository nicht und führe git push nicht aus, bis der Benutzer grünes Licht gesagt hat.

Erstelle ein leeres öffentliches Git-Repository im persönlichen Arbeitsbereich des Benutzers. Beschreibung: build2 package for <name>. Klone mit SSH. Kein README, keine Lizenz, keine von GitHub generierten Dateien.

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

Überprüfe vor dem Fortfahren:

• git rev-list --max-parents=0 HEAD ist dieser Commit.
• git show --stat --format=%s HEAD Nachricht ist genau bdep new --type empty,third-party.
• Der Baum besteht nur aus Dateien, die von diesem Befehl generiert wurden.

Wenn sich in diesem Commit eine zusätzliche Datei oder eine manuelle Bearbeitung befindet, setze zurück und wiederhole. Der Überprüfungsprozess hängt davon ab.

Gate C: review-Branch

git checkout -b review

Bleibe für jeden späteren Commit in diesem Durchlauf auf review. Führe nicht git checkout main aus. Merge nicht. Führe kein Release durch. Veröffentliche nicht.

Gate D: Upstream-Submodul

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

Verwende nur https://. Checke den Release-Commit (Tag) aus. Commit: Add upstream submodule, <tag>.

Gate E: Namen und Layout

Lies ${ROOT}/HOWTO/package-naming.md erneut, falls nötig. Entscheide und schreibe die Entscheidungen auf, bevor du das Paket generierst:

• Git-Repository-Name: Upstream-Schreibweise, kein build2--Präfix, kein -package-Suffix.
• project: und project =: Kleinschreibung, es sei denn, gemischte Schreibweise ist die Upstream-Kennung (Qt ist die dokumentierte Ausnahme).
• Paket name:: lib-Präfix für Bibliotheken, es sei denn, sowohl Debian als auch der Upstream machen einen Executable-Konflikt unmöglich.
• Bibliothek vs. Executable in separate Pakete aufteilen.
• Include-Schema für öffentliche Header (Unterverzeichnis-Präfix vs. Dateiname-Präfix).
• Kombiniertes vs. getrenntes include/ / src/.

Bleibe so nah wie möglich am Upstream-Layout.

Gate F: Vorbereitung und dann bdep new --package

Erstelle das Paketverzeichnis. Symbolverlinke nur die vorhandenen Upstream-Meta-Dateien (README.md, LICENSE / Äquivalent, NEWS / CHANGES / ChangeLog). Committe das allein. Dann:

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

Iteriere, indem du löschst und erneut ausführst, nicht durch manuelle Bearbeitung des Gerüsts, bis das Layout übereinstimmt. Die third-party-Unteroption ist erforderlich. Committe mit der genauen Befehlszeile als Nachricht.

Wenn der Basisname des Changelogs kein erkannter Name ist, setze changes-file: später manuell. Siehe ${ROOT}/HOWTO/package-changes-file.md.

Gate G: Version, Manifest, Abhängigkeiten

• Version bleibt X.Y.Z-a.0.z bis bdep release --no-open.
• summary: unter 70 Zeichen, keine Füllwörter, kein Punkt am Ende.
• Begleitende -tests / -examples / -benchmarks: kopiere die Hauptzusammenfassung und hänge (tests) (oder die entsprechende Art) an. Schreibe sie nicht neu. Siehe ${ROOT}/HOWTO/tests-extra-dependencies.md.
• license: ist SPDX (oder other:). Siehe ${ROOT}/guides/packaging-license.md.
• Kommentiere die pkg.cppget.org-Voraussetzung aus. Verwende den am wenigsten stabilen Abschnitt, der noch jede Abhängigkeit enthält. Lasse queue.cppget.org nicht in einer langlebigen repositories.manifest.
• bdep sync -a nach depends-Bearbeitungen.
• Schnittstellen-Header in dieser Bibliothek öffentlichen Header gehen in intf_libs. Alles andere geht in impl_libs.

Gate H: Quellen und Build-Dateien füllen

Fülle den Paketbaum mit den Upstream-Quellen, bevor du die buildfiles berührst: Symbolverlinke zuerst einzelne Header-/Quelldateien und symbolverlinke ein ganzes Unterverzeichnis nur, wenn das viele einzelne Symlinks spart (erfordert das buildfile-in-prefix-Layout, siehe packaging-guide-antipatterns.md). Befolge das ausgearbeitete Beispiel in ${ROOT}/guides/packaging-guide-summary.md Schritt 5.

Obligatorisch: für jeden gerade hinzugefügten Verzeichnis-Symlink füge einen passenden symlink=dir-Eintrag zur <pkg>/.gitattributes-Datei dieses Pakets hinzu (erstelle die Datei, falls sie noch nicht existiert) im selben Commit. Überprüfe mit find <pkg>/ -type l -exec test -d {} \; -print und kreuzprüfe jeden Treffer. Dies ist Harte Regel 11; das Überspringen bricht das Paket bei einem Windows-Checkout. Committe die Symlinks (und .gitattributes), bevor du buildfiles anpasst, damit ein Rollback einfach ist.

Dann passe nur die generierten Dateien an. Bewahre die generierte Struktur und Kommentare.

Bei Bedarf laden:

• Header / Private Header: ${ROOT}/HOWTO/third-party-private-headers.md
• SONAME / Ausgabename: ${ROOT}/HOWTO/package-soname.md