Hinzufügen neuer Projekte zu WrapDB

Wie es funktioniert

Neue Wraps müssen als ein Arbeitsunterprojekt in das wrapdb Repository eingereicht werden.

Es gibt zwei Arten von Wraps auf WrapDB - reguläre Wraps und Wraps mit Meson Build Definition Patches.

Wraps mit Meson Build Definition Patches funktionieren ähnlich wie bei Debian: Wir nehmen das unveränderte Upstream-Quellpaket und fügen ein neues Build-System als Patch hinzu. Diese Build-Systeme werden als Unterverzeichnis von subprojects/packagefiles/ gespeichert. Sie enthalten nur Build-Definitionsdateien. Man kann sie auch als eine Überlagerung der Upstream-Quelle betrachten.

Wraps ohne Meson Build Definition Patches enthalten nur die Wrap-Metadaten, die beschreiben, wie das Projekt abgerufen werden kann.

Immer wenn eine neue Version in das wrapdb eingecheckt wird, wird ein neuer Tag mit einer inkrementierten Versionsnummer generiert und eine neue Version zur wrapdb API-Liste hinzugefügt. Alle alten Versionen bleiben unverändert. Neue Commits erfolgen immer über GitHub Merge Requests und müssen von jemand anderem als dem Einreicher überprüft werden.

Beachten Sie, dass Ihr Git-Repository mit dem Wrap nicht das Unterverzeichnis der Quellversion enthalten darf. Dieses wird automatisch vom Dienst hinzugefügt. Sie dürfen auch keinen Quellcode aus dem Original-Tarball in das Wrap-Repository einchecken.

Auswahl des Wrap-Namens

Gewrappte Unterprojekte werden ähnlich wie externe Abhängigkeiten verwendet. Daher sollten sie den gleichen Namen wie die Upstream-Projekte haben.

HINWEIS: Wrap-Namen müssen vollständig mit diesem Regex übereinstimmen: [a-z0-9._]+.

Wenn das Projekt eine pkg-config-Datei bereitstellt, sollte der Wrap-Name derselbe sein wie der pkg-config-Name. Normalerweise ist dies der Name des Projekts, wie z. B. libpng. Manchmal ist er jedoch leicht unterschiedlich. Als Beispiel ist der von libogg gewählte pkg-config-Name ogg anstelle von libogg, was der Grund dafür ist, dass der Wrap einfach ogg heißt.

Wenn keine pkg-config-Datei vorhanden ist, sollte der Name verwendet werden, den das Projekt verwendet/bewirbt, nur in Kleinbuchstaben (Catch2 -> catch2).

Wenn der Projektname zu generisch oder mehrdeutig ist (z. B. benchmark), sollten Sie das Namensformat organisation-projekt verwenden (z. B. google-benchmark).

Wie man einen neuen Wrap beiträgt

Wenn das Projekt bereits das Meson Build-System verwendet, sollte nur eine Wrap-Datei project.wrap bereitgestellt werden. In anderen Fällen sollte auch ein Meson Build Definition Patch - eine Reihe von meson.build-Dateien - bereitgestellt werden.

Erstellung des Wrap-Inhalts

Neue Release-Branches erfordern eine project.wrap-Datei. Erstellen Sie also eine, falls erforderlich.

${EDITOR} upstream.wrap

Das Dateiformat ist einfach. Sehen Sie sich jedes vorhandene wrapdb-Unterprojekt an, um den Inhalt zu sehen. Die Prüfsumme ist SHA-256 und kann mit dem folgenden Befehl auf den meisten Unix-ähnlichen Betriebssystemen berechnet werden.

sha256sum path/to/libfoo-1.0.0.tar.gz

Unter macOS lautet der Befehl wie folgt.

shasum -a 256 path/to/libfoo-1.0.0.tar.gz

Als nächstes müssen Sie die Einträge hinzufügen, die definieren, welche Abhängigkeiten das aktuelle Projekt bereitstellt. Dies ist wichtig, da es Mesons automatischen Abhängigkeitsauflöser zum Laufen bringt. Dies geschieht durch Hinzufügen eines provide-Eintrags am Ende der Datei upstream.wrap. Am Beispiel der Ogg-Bibliothek würde das so aussehen:

[provide]
ogg = ogg_dep

Der Teil ogg auf der linken Seite bezieht sich auf den Abhängigkeitsnamen, der derselbe sein sollte wie sein Pkg-Config-Name. ogg_dep auf der rechten Seite bezieht sich auf die Variable in den Build-Definitionen, die die Abhängigkeit bereitstellt. Am häufigsten enthält sie das Ergebnis eines declare_dependency-Aufrufs. Wenn eine Variable dieses Namens nicht definiert ist, wird Meson mit einem harten Fehler beendet. Weitere Details finden Sie in dem Haupt-Wrap-Handbuch.

Jetzt können Sie die Build-Dateien erstellen, falls das Upstream-Projekt keine enthält, und an ihnen arbeiten, bis das Projekt korrekt kompiliert wird. Denken Sie daran, dass alle Dateien im Verzeichnis subprojects/packagefiles/<projektname> abgelegt werden.

${EDITOR} meson.build meson.options

Um die lokal hinzugefügten Build-Dateien auf das Upstream-Release-Tarball anzuwenden, muss der Abschnitt wrap-file eine Eigenschaft patch_directory enthalten, die das Unterverzeichnis in subprojects/packagefiles/ mit den Build-Dateien darin benennt, da dies zentral für die Funktionsweise von wrapdb ist. Es wird vom wrapdb meson.build verwendet, und wenn eine Version erstellt wird, werden die Dateien aus diesem Verzeichnis in ein Archiv umgewandelt und eine patch_url wird zur Wrap-Datei hinzugefügt.

Wenn Sie mit den Ergebnissen zufrieden sind, fügen Sie die Build-Dateien zu Git hinzu, aktualisieren Sie releases.json wie in README.md beschrieben und pushen Sie das Ergebnis nach GitHub.

<verify that your project builds and runs>
git add releases.json subprojects/project.wrap subprojects/packagefiles/project/
git commit -a -m 'Add wrap files for libfoo-1.0.0'
git push -u origin libfoo

Erstellen Sie nun einen Pull Request auf GitHub.

Wenn die Packaging-Überprüfung Änderungen erfordert, verwenden Sie das Argument --amend für commit, damit Ihr Branch nur einen Commit enthält.

${EDITOR} meson.build
git commit -u --amend
git push --force

Änderungen an der Originalquelle

Der Sinn eines Wraps ist es, das Upstream-Projekt mit so wenigen Änderungen wie möglich bereitzustellen. Die meisten Projekte sollten nicht mehr als ein paar Meson-Definitionsdateien enthalten. Manchmal kann es notwendig sein, eine Template-Header-Datei oder etwas Ähnliches hinzuzufügen. Diese sollten auf ein Minimum beschränkt werden.

Es sollte insbesondere darauf hingewiesen werden, dass keine Patches an der Funktionalität vorgenommen werden dürfen. Alle solchen Änderungen müssen an das Upstream übermittelt werden. Sie können auch Ihr eigenes Git-Repository mit den Änderungen hosten, wenn Sie möchten. Das Wrap-System unterstützt native Git-Unterprojekte.

Bestehen der automatischen Validierung

Jeder eingereichte Wrap durchläuft eine automatisierte Korrekturprüfung, und deren Bestehen ist eine Voraussetzung für das Mergen. Daher wird dringend empfohlen, die Validierungsprüfungen selbst durchzuführen, damit Sie Probleme schneller beheben können.

Sie können den Wrap selbst mit den folgenden Befehlen testen.

meson subprojects purge --confirm
meson setup builddir/ -Dwraps=<project-name>

Der erste Befehl dient dazu, sicherzustellen, dass der Wrap korrekt aus den neuesten Paketdateien abgerufen wird. Der zweite Befehl konfiguriert Meson und wählt eine Reihe von Unterprojekten aus, die aktiviert werden sollen.

Das GitHub-Projekt enthält eine automatische CI beim Pushen, um das Projekt auszuführen und die Metadaten auf offensichtliche Fehler zu überprüfen. Dies kann von Ihrer Fork aus überprüft werden, bevor ein PR eingereicht wird.