Wie Sie Ihre Software auf Copr, der Benutzer-Paketquelle von Fedora, veröffentlichen

Christopher Engelhard, Jean-Baptiste Holcroft, Otto Urpelainen Version unspecified Last review: 2022-02-05
Dies ist eine kurze Anleitung zur automatisierten Erstellung und Pflege eines Copr-Repositorys für Ihre Software. Grundkenntnisse in Git und der Erstellung von RPM-Paketen werden vorausgesetzt.

In diesem Leitfaden werden wir

  • ein RPM-Paket für ein Programm erstellen

  • eine Copr-Paketquelle erstellen und das Programm darin veröffentlichen

  • die automatische Verwaltung von Programmversionen, Paket-Releases und Paketänderungsprotokollen einrichten

  • das automatische Bauen neuer Paketversionen einrichten

Ziel ist es, Ihnen zu ermöglichen, Ihre Software in Copr auf dem neuesten Stand zu halten, ohne jemals mit etwas anderem als dem Git-Repository Ihrer Software interagieren zu müssen.

Eine ähnliche Automatisierung lässt sich auch beim Paketieren fremder Programme einrichten, also beim Kompilieren aus einem heruntergeladenen Quellcode-Archiv. Die notwendigen Änderungen werden am Ende des Tutorials beschrieben.

Voraussetzungen

Folgendes wird benötigt:

  1. Der Quellcode unseres Programms, der sich in einem öffentlich zugänglichen Git-Repository befindet. Dieses Tutorial verwendet das einfache Beispielprogramm „hellocopr“, um den Prozess zu veranschaulichen. Das Programm und alle in dieser Anleitung erwähnten Dateien finden Sie im Git-Repository des Projekts. Es handelt sich um ein sehr einfaches (und überflüssiges) Python-Programm mit einem setuptools-Installer:

    $ ls
doc  LICENSE  README.md  requirements.txt  setup.py  src

$ ls src/hellocopr
colors.py  hellocopr.py  __init__.py

  2. Ein Fedora(FAS)-Konto, um Repositories auf Copr erstellen zu können. Das Demo-Repository dieses Tutorials finden Sie hier.

  3. Das auf Ihrem System installierte Dienstprogramm tito. Tito bietet zahlreiche Möglichkeiten zur Automatisierung der Paketerstellung, von denen wir die meisten hier nicht benötigen. Weitere Informationen finden Sie in dessen Dokumentation.

  4. Eine spec-Datei für unser Programm. Weitere Informationen zur Erstellung einer solchen Datei finden Sie im Paketbau-Tutorial 2: GNU Hello oder passen Sie die mit Anmerkungen versehene Beispiel-Spec-Datei an.

Sie können diesem Tutorial folgen, indem Sie das Repository klonen oder forken und den Tag initial auschecken. Dadurch befindet sich das Repository im Zustand kurz vor dem nächsten Schritt. Der Commit-Verlauf des Repositorys entspricht den Schritten in diesem Tutorial.

Schritt 1: Das Paket mit tito erstellen

Kopieren Sie die Spec-Datei in das Basisverzeichnis des Projekts. Vor dem Fortfahren sollten einige Änderungen vorgenommen werden:

  1. Die Werte von Version: und Release: sind irrelevant, da diese von Tito verwaltet werden. Es ist sinnvoll, sie auf Version: 0.0.0 und Release: 0%{?dist} zu setzen, um zu kennzeichnen, dass dieses Paket noch nicht erstellt wurde.

  2. Tito kümmert sich auch um die Erstellung des Quellcode-Tarballs aus dem Git-Repository. Ändern Sie daher die URL Source0: in den Dateinamen %{name}-%{version}.tar.gz und fügen Sie einen Kommentar hinzu, der den Benutzern erklärt, wie sie den Tarball erhalten.

  3. Das Änderungsprotokoll (Changelog) kann leer bleiben.

    $ cat hellocopr.spec
...
Version: 0.0.0
Release: 0%{?dist}
...
# Sources can be obtained by
# git clone https://pagure.io/copr-tito-quickdoc
# cd copr-tito-quickdoc
# tito build --tgz
Source0: %{name}-%{version}.tar.gz
...
%changelog

Committen Sie die Änderungen.

Als Nächstes initialisieren wir das Projekt für die Verwendung mit Tito.

$ tito init
Creating tito metadata in: ~/copr-tito-quickdoc/.tito
   - created ~/copr-tito-quickdoc/.tito
   - wrote tito.props
   - created ~/copr-tito-quickdoc/.tito/packages
   - wrote ~/copr-tito-quickdoc/.tito/packages/.readme
   - committed to git
Done!

Dies erstellt ein Unterverzeichnis .tito mit einigen Standardkonfigurationen, das vorerst unverändert bleiben kann.

Wir können nun einen Test-Build des Pakets mit tito build durchführen. Normalerweise baut tito von einem Tag aus, das wir noch nicht erstellt haben. Mit dem Schalter --test können wir jedoch stattdessen vom aktuellsten Commit bauen, der in /tmp/tito geschrieben wird:

$ tito build --rpm --test
Creating output directory: /tmp/tito
WARNING: unable to lookup latest package tag, building untagged test project
WARNING: .tito/packages/hellocopr doesn't exist in git, using current directory
Building package [hellocopr-0.0.0-0]
Wrote: /tmp/tito/hellocopr-git-11.7a6919d.tar.gz
...

Successfully built: /tmp/tito/hellocopr-0.0.0-0.git.11.7a6919d.fc32.src.rpm
	- /tmp/tito/noarch/hellocopr-0.0.0-0.git.11.7a6919d.fc32.noarch.rpm

Sobald wir alle eventuell auftretenden Probleme mit dem Paket behoben haben, können wir tito mit tito tag eine Paketversion erstellen lassen. Da wir noch keine Versionsnummer festgelegt haben, müssen wir diese für das erste Tag an tito übergeben:

$ tito tag --use-version 1.0.0

Dadurch wird der Editor geöffnet und ein vorformatierter Changelog-Eintrag angezeigt, der alle Commits seit der letzten Veröffentlichung enthält und nach Bedarf bearbeitet werden kann. Da es bisher keine Commits gab, enthält der Eintrag lediglich „- new package built with tito“. Speichern Sie die Datei, und Tito wird

  1. „Version“ in der Spec-Datei auf 1.0.0 setzen

  2. „Release“ in der Spec-Datei auf 1 setzen

  3. den Änderungsprotokolleintrag zum %changelog-Abschnitt der Spec-Datei hinzufügen

  4. das Ergebnis speichern und mit <Name>-<Version>-<Release> kennzeichnen, z. B. hellocopr-1.0.0-1

    $ tito tag --use-version 1.0.0
Creating output directory: /tmp/tito
Tagging new version of hellocopr: untagged -> 1.0.0-1
Created tag: hellocopr-1.0.0-1
   View: git show HEAD
   Undo: tito tag -u
   Push: git push --follow-tags origin

Mit git push --follow-tags werden die Commits und Tags auf das Remote-Repository übertragen, und wir sind bereit, das Paket auf Copr zu veröffentlichen.

Schritt 2: Veröffentlichung des Pakets in einem Copr-Repository

  1. Gehen Sie zu https://copr.fedorainfracloud.org/ und melden Sie sich an. Klicken Sie anschließend auf New Project, um ein Repository für unser Programm zu erstellen. Im folgenden Eingabefeld:

    1. Unter 1. Project information → Project name geben Sie den gewünschten Namen für Ihr Repository ein. Da dieses nur ein einziges Paket enthält, ist es sinnvoll, Projektname = Paketname zu verwenden, z. B. hellocopr. Diese Einstellung kann später nicht mehr geändert werden.

    2. Unter 2. Build options wählen Sie alle Distributionen aus, für die Sie Repositories erstellen möchten – in der Regel alle Fedora-Versionen und gegebenenfalls auch EPEL-Versionen.

    3. Unter 4. Other Options stellen Sie sicher, dass Follow Fedora branching folgen_ aktiviert ist. Dadurch wird sichergestellt, dass Ihr Repository bei neuen Fedora-Versionen automatisch aktualisiert wird.

  2. Gehen Sie zu Packages → New Package

    1. Unter 1. Provide the source , legen Sie den Paketnamen und die URL Ihres Git-Repositorys fest.

    2. Unter 2. How to build SRPM from the source wählen Sie tito.

    3. Unter 3. Generic package setup aktivieren Sie das Ankreuzfeld Auto-rebuild

  3. Ihr Paket wird in der Paketliste angezeigt. Klicken Sie auf Rebuild, um den Bauprozess zu starten. Auf der folgenden Seite können Sie bei Bedarf die Bauoptionen ändern. Wir verwenden jedoch die Standardeinstellungen, also die Optionen, die wir im vorherigen Schritt festgelegt haben. Klicken Sie auf Submit. Copr erstellt das Paket dann anhand des in Schritt 1 erstellten Tito-Tags.

Sobald der Bauvorgang abgeschlossen ist, können Sie die Installation des Pakets von Copr testen, indem Sie Ihr Repository aktivieren.

$ sudo dnf copr enable <Benutzername>/hellocopr

$ sudo dnf install hellocopr

Schritt 3: (Re-)Builds des Pakets automatisieren

Als Nächstes möchten wir Copr so einrichten, dass automatisch eine neue Paketversion gebaut wird, sobald wir eine erstellen. Dadurch müssen wir uns nicht mehr anmelden und den Bauvorgang manuell auslösen. Dazu müssen wir lediglich jedes Mal einen Bauvorgang auslösen, wenn wir ein neues Tag in das Repository pushen.

Hierfür ist eine gewisse Konfiguration sowohl Ihres Git-Repositorys als auch des Copr-Projekts erforderlich.

Die Konfiguration finden Sie unter Settings → Integrations. Auf der Seite werden auch die Schritte zur Konfiguration Ihres Git-Repositorys für alle gängigen Git-Forges (Pagure, GitHub, GitLab und Bitbucket) erläutert.

Um dies zu testen, nehmen wir nun einige Änderungen an unserem Programm vor, die sich für die letzte Automatisierungsebene als nützlich erweisen werden, und erstellen eine neue Version unserer Software.

Aktuell ist die Versionsnummer des Beispielprogramms an mehreren Stellen fest codiert. Dies ändern wir, sodass die Versionsnummer aus einer einzigen Datei stammt. Welche Datei das ist, spielt keine Rolle, idealerweise sollte jedoch nur die Versionsvariable darin geändert werden. In diesem Fall verwenden wir die zuvor leere Datei src/hellocopr/__init__.py. Wir nennen diese neue Version „1.0.1“.

Übernehmen Sie die Änderungen und erstellen Sie mit tito eine neue Version.

$ tito tag
Creating output directory: /tmp/tito
Tagging new version of hellocopr: 1.0.0-1 -> 1.0.1-1
Created tag: hellocopr-1.0.1-1
   View: git show HEAD
   Undo: tito tag -u
   Push: git push --follow-tags origin

Beachten Sie, dass tito die Version nun automatisch aktualisiert, wenn die Option --use-version weggelassen wird. Dies geschieht folgendermaßen:

  1. Die letzte Ziffer der Versionsnummer wird um 1 erhöht - 1.0.0 → 1.0.1

  2. Die Versionsnummer wird auf 1 zurückgesetzt, falls dies nicht bereits der Fall ist.

Wenn Sie auf eine andere Version aktualisieren möchten, beispielsweise auf 1.1.0, können Sie dies erneut tun, indem Sie --use-version angeben.

Pushen Sie den resultierenden Commit und Tag. Wenn Sie nun Ihre Projektseite auf Copr überprüfen, werden Sie sehen, dass durch das Pushen eines Tags ein neuer Bauvorgang von hellocopr-1.0.1-1 ausgelöst wurde.

Schritt 4: Lassen Sie tito die Programmversion verwalten

Wenn Sie das Git-Log überprüfen, werden Sie feststellen, dass ich tatsächlich vergessen habe, die Versionsvariable von hellocopr auf 1.0.1 zu aktualisieren. Das darf nicht wieder vorkommen. Da wir unsere Version glücklicherweise aus einer einzigen Quelle beziehen, kann tito diese Datei automatisch anhand einer Vorlage generieren.

Kopieren Sie zunächst die Versionsquelldatei src/hellocopr/__init__.py nach .tito/templates/__init__.py.template. Öffnen Sie anschließend die Vorlagendatei und ersetzen Sie die Versionszeichenkette durch $version. Es empfiehlt sich außerdem, einen Hinweis hinzuzufügen, dass die Datei von Tito verwaltet wird und nicht manuell bearbeitet werden sollte.

$ cat .tito/templates/__init__.py.template
...
# This file is automatically created from a template by tito. Do not edit it manually.

__version__ = '$version'

Fügen Sie als Nächstes Folgendes zu .tito/tito.props hinzu:

[version_template]
destination_file = src/hellocopr/__init__.py
template_file = .tito/templates/__init__.py.template

Committen Sie die Änderungen. Wenn wir nun eine neue Version taggen, verwendet Tito die Vorlage, ersetzt $version durch die getaggte Version und kopiert die resultierende Datei nach src/hellocopr/__init__.py, bevor die Spec-Datei aktualisiert und die Änderungen gespeichert werden.

Wir können dies testen, indem wir ein neues Release kennzeichnen:

$ tito tag
Creating output directory: /tmp/tito
Tagging new version of hellocopr: 1.0.1-1 -> 1.0.2-1
Created tag: hellocopr-1.0.2-1
   View: git show HEAD
   Undo: tito tag -u
   Push: git push --follow-tags origin

$ cat src/hellocopr/__init__.py
...
# This file is automatically created from a template by tito. Do not edit it manually.

__version__ = '1.0.2'

Wenn Sie das Tag erneut in das Remote-Repository übertragen, löst Copr automatisch erneut eine Neuerstellung aus.

Veröffentlichungsprozedur in Kürze

Ab sofort läuft das Aktualisieren Ihrer Software im Copr-Repository folgendermaßen ab:

  1. Committen Sie alle Änderungen für Ihre neue Version.

  2. Führen Sie einen Test-Bauvorgang mit tito build --test durch

  3. Versehen Sie die Veröffentlichung mit tito tag (fügen Sie gegebenenfalls --use-version hinzu)

  4. Pushen Sie den Tag mit git push --follow-tags in Ihr Git-Repository

und Copr kümmert sich um den Rest.

Paketierung aus Quell-Tarballs

Ein ähnliches Verfahren lässt sich auch anwenden, um die Software anderer Entwickler auf Copr zu verwalten, d.h. um sie aus einem von Upstream heruntergeladenen Tarball zu erstellen.

Dazu müssen folgende Änderungen am oben beschriebenen Verfahren vorgenommen werden:

  1. Laden Sie anstelle der entpackten Quelldateien das Quellcode-Archiv (Tarball), das Sie paketieren möchten, in Ihr Repository herunter und committen Sie es.

  2. Anstatt den Quellcode direkt zu ändern, fügen Sie alle erforderlichen Änderungen in Form von Patch-Dateien hinzu. Listen Sie diese in der Spec-Datei als PatchX: auf.

  3. Setzen Sie in der Spec-Datei Version: wieder auf die aktuelle Programmversion und Source0: wieder auf die URL des Tarballs. Sie können Makros wie %{version} verwenden, um Versionsänderungen automatisch zu übernehmen.

  4. Ändern Sie Titos .tito/tito.props so, dass erstens nicht versucht wird, einen Quellcode-Tarball zu erstellen, und zweitens beim Taggen Release: anstelle von Version: erhöht wird.

    [buildconfig]
builder = tito.builder.NoTgzBuilder
tagger = tito.tagger.ReleaseTagger

  5. Verwenden Sie keine Tito-Vorlagen

Der restliche Ablauf bleibt unverändert. Wenn Sie Änderungen am Paket vornehmen, ohne den Quellcode zu ändern, können Sie einfach mit tito eine neue Version taggen. Wenn Sie den Quellcode-Tarball aktualisieren, müssen Sie vor dem Taggen das Feld Version: aktualisieren und Release: auf 0%{?dist} zurücksetzen.

Die als Tarball angepasste Version des Projekts befindet sich im Zweig foreign-sources des Git-Repositorys.

Want to help? Learn how to contribute to Fedora Docs ›