Ubuntu logo

Packaging Guide

2. Allgemeine Übersicht über das debian/ Verzeichnis

Dieser Artikel gibt eine kurze Übersicht über die verschiedenen Dateien im debian/ Verzeichnis, welche für das Paketieren von Ubuntu Paketen wichtig sind. Die wichtigsten Dateien sind changelog, control, copyright und rules. Diese Dateien werden für alle Pakete benötigt. Anhand weiterer Dateien im debian/ Verzeichnis kann das Verhalten der Pakete angepasst und konfiguriert werden. Während einige dieser Dateien in diesem Artikel beschrieben werden, ist er nicht als vollständige Übersicht gedacht.

2.1. Das Änderungsprotokoll

Die Datei ist, wie sich schon am Namen erkennen lässt, eine Liste von Änderungen die in jeder Version gemacht wurden. Sie hat ein spezielles Format aus dem man Paketname, Version, Distribution, Änderungen, Autor und Zeitpunkt herauslesen kann. Falls Sie einen GPG-Schlüssel besitzen (siehe: Erste Schritte), stellen Sie sicher dass Sie den selben Alias und E-Mail Adresse im changelog verwenden wie in Ihrem Schlüssel. Das folgende ist eine changelog Vorlage:

package (version) distribution; urgency=urgency

 * change details
  - more change details
 * even more change details

-- maintainer name <email address>[two spaces]  date

Das Format (besonders das Datumsformat) ist wichtig. Das Datum sollte im RFC 5322 Format sein, sodass es dann durch Eingabe von date -R abgerufen werden kann. Zur Erleichterung kann der Befehl ``dch``genutzt werden, um den Changelog zu editieren. Er wird das Datum automatisch aktualisieren.

Unterpunkte werden durch einen Strich “-” dargestellt, während Hauptpunkte durch einen Stern “*” gekennzeichnet werden.

Falls Sie ein neues Paket ohne Vorlage erstellen, können Sie mit dch --create (dch befindet sich im devscripts Paket) Standard-Daten für debian/changelog anlegen.

Dies ist ein Beispiel für eine changelog Datei des hello Pakets:

hello (2.8-0ubuntu1) trusty; urgency=low

  * New upstream release with lots of bug fixes and feature improvements.

-- Jane Doe <packager@example.com>  Thu, 21 Oct 2013 11:12:00 -0400

Erwähnenswert ist, dass die Version ein -0ubuntu1 Suffix angehängt hat, das die Distributions-Änderung wiederspiegelt. Sie wird benutzt damit das Paketieren in der gleichen Quellversion aktualisiert werden kann (z.B. für Fehlerbehebungen).

Ubuntu und Debian haben leicht unterschiedliche Versionsbezeichnungen um Konflikte mit demselben Quellpaket zu vermeiden. Wenn ein Debian-Paket unter Ubuntu geändert wurde, wird ein ubuntuX (wobei X für die Ubuntu-Revision steht) an das Ende der Debianversion angehängt. Also wenn das Debian-Paket hello 2.6-1 unter Ubuntu geändert wurde, würde die Versionsbezeichnung 2.6-1ubuntu1 sein. Falls ein Paket dieser Anwendung nicht für Debian existiert, dann ist die Debian-Revision 0 (z.B. 2.6-0ubuntu1).

Für weitere Informationen, schauen Sie die changelog section (Section 4.4) des Debian Policy Manual an.

2.2. Die control Datei

Die control Datei enthält Informationen, die der Paketmanager (also z.B. apt-get, synaptic und adept) verwendet, build-spezifische Abhängigkeiten, Betreuerinformationen und vieles andere.

Für das Ubuntupaket hello, sieht die Datei control folgendermaßen aus:

Source: hello
Section: devel
Priority: optional
Maintainer: Ubuntu Developers <ubuntu-devel-discuss@lists.ubuntu.com>
XSBC-Original-Maintainer: Jane Doe <packager@example.com>
Standards-Version: 3.9.5
Build-Depends: debhelper (>= 7)
Vcs-Bzr: lp:ubuntu/hello
Homepage: http://www.gnu.org/software/hello/

Package: hello
Architecture: any
Depends: ${shlibs:Depends}
Description: The classic greeting, and a good example
 The GNU hello program produces a familiar, friendly greeting. It
 allows non-programmers to use a classic computer science tool which
 would otherwise be unavailable to them. Seriously, though: this is
 an example of how to do a Debian package. It is the Debian version of
 the GNU Project's `hello world' program (which is itself an example
 for the GNU Project).

Der erste Absatz beschreibt in dem Feld Build-Depends das Quellpaket inklusive aller benötigten Paketabhängigkeiten, die nötig sind um das Paket aus dem Quellcode zu bauen. Es enthält außerdem einige Metadaten wie den Namen des Verantwortlichen, die Version der Debian-Richtlinien, der Ort der Paketversionkontrolle und die Upstream-Homepage.

Beachten Sie bitte, dass wir in Ubuntu das``Maintainer`` Feld auf eine allgemeine Adresse setzen, da jeder jedes Paket ändern kann (dies unterscheidet sich von Debian wo die Veränderung von Paketen auf eine Person oder ein Team beschränkt ist. Pakete in Ubuntu sollten allgemein das Maintainer Feld auf Ubuntu Developers <ubuntu-devel-discuss@lists.ubuntu.com> setzen. Wenn das Maintainer-Feld modifiziert wird, sollte das alte Wert im XSBC-Original-Maintainer Feld gespeichert werden. Dies kann automatisch mit dem update-maintainer Skript im ubuntu-dev-tools Paket erfolgen. Für weitere Informationen schauen Sie Debian Maintainer Field spec im Ubuntu-Wiki an.

Jeder weitere Abschnitte beschreibt ein Binärpaket, welches gebaut wird.

Für weitere Informationen schauen Sie die control file Section (Kapitel 5) des Debian Policy Manual an.

2.4. Die rules Datei

Die letzte Datei, die wir uns anschauen ist rules. Hier geschieht alle Arbeit, um das Paket zu erzeugen. Es ist ein Makefile mit Targets, um die Anwendung zu kompilieren und zu installieren, dann die .deb Datei von den installierten Dateien zu erzeugen. Es enthält auch ein Target um “aufzuräumen”, so dass das Quellpaket wieder auf dem ursprünglichen Stand ist.

Hier ist eine vereinfachte Version der rules Datei, die von dh_make erzeugt wurde (erhältlich im dh-make Paket):

#!/usr/bin/make -f
# -*- makefile -*-

# Uncomment this to turn on verbose mode.
#export DH_VERBOSE=1

%:
       dh  $@

Lassen Sie uns durch diese Datei ein bisschen genauer durchgehen. Sie sorgt dafür, dass jedes Target, welches von debian/rules aufgerufen wird, als Argument an /usr/bin/dh weitergegeben wird, welches selbst wiederum alle nötigen dh_*-Befehle aufrufen wird.

dh durchläuft eine Sequenz von debhelper Kommandos. Die unterstützen Sequenzen korrespondieren mit den Targets einer debian/rules-Datei: “build”, “clean”, “install”, “binary-arch”, “binary-indep” und “binary”. Um zu sehen, welche Kommandos als Teil welchen Targets durchlaufen werden, benutzen Sie:

$ dh binary-arch --no-act

Befehlen in der Sequenz binary-indep wird die Option “-i” mitgegeben um sicherzustellen, dass sie nur mit binär-unabhängigen Paketen funktionieren und Befehlen in der Sequenz binary-arch wird die Option “-a” mitgegeben um sicherzustellen, dass sie nur mit Architektur-unabhängigen Paketen funktionieren.

Jeder debhelper Befehl wird aufgenommen wenn er erfolgreich in debian/package.debhelper.log ausgeführt wird. (Welcher dh_clean löscht.) So kann dh mitteilen welche Befehle bereits für welches Paket ausgeführt wurden und überspringt diejenigen, die nochmals ausgeführt werden sollen.

Jedes Mal wenn dh ausgeführt wird, untersucht es die Logdatei und findet den zuletzt verwendeten Befehl welcher in der gegebenen Sequenz enthalten ist. Es springt danach zum nächsten Befehl in der Sequenz. Die Optionen --until, --before, --after und --remaining können dieses Verhalten beeinflussen.

Falls debian/rules ein Target mit einem Namen wie override_dh_command enthält, dann wird dh, sobald es an dem Befehl in der Sequenz angekommen ist, das Target von dieser Anweisungsdatei verwenden statt den eigentlichen Befehl auszuführen. Das neue Target kann dann den Befehl mit anderen Optionen ausführen oder komplett andere Befehle stattdessen ausführen. (Zu beachten ist, dass Sie für die Erstellung debhelper 7.0.50 oder höher verwenden sollten.)

Werfen Sie einen Blick in /usr/share/doc/debhelper/examples/ und man dh für weitere Beispiele. Außerdem ist der Regelkatalog (Abschnitt 4.9) der Debian-Grundsatzanweisung hilfreich.

2.5. Zusätzliche Dateien

2.5.1. Die Datei install

Die Datei install wird von dh_install verwendet, um Dateien in das Binärpacket zu installieren. Es hat zwei gängige Einsatzmöglichkeiten:

  • Um Dateien in Ihr Paket zu installieren, die nicht vom Upstream-Build-System installiert werden.

  • Aufteilen eines einzelnen großen Quellpaketes in mehrere Binärpakete.

Im ersten Fall sollte die Datei install eine Zeile für jede installierte Datei enthalten, die sowohl das Datei- als auch Installationsverzeichnis festlegt. Zum Beispiel, die folgende install-Datei würde das das Skript foo in das Stammverzeichnis des Quellpakets nach usr/bin und eine Desktop-Datei in das debian-Verzeichnis nach usr/share/applications installieren:

foo usr/bin
debian/bar.desktop usr/share/applications

Wenn ein Quellpaket mehrere Binärpakete produziert, wird dh die Dateien in debian/tmp statt direkt in debian/<package> installieren. Dateien aus debian/tmp können dann in getrennte Binärpakete mithilfe mehrerer $package_name.install-Dateien verschoben werden. Dies wird oft dazu benutzt um große Mengen architekturunabhängiger Daten aus architekturabhängigen Paketen herauszulösen und sie in Architecture: all-Pakete zu integrieren. In diesem Fall werden nur der Name der zu installierenden Dateien (oder Ordner) benötigt und nicht das Installationsverzeichnis. Zum Beispiel könnte foo.install mit ausschließlich architekturabhängigen Dateien so ausschauen:

usr/bin/
usr/lib/foo/*.so

Während foo-common.install mit der architekturunabhängigen Datei so ausschauen könnte:

/usr/share/doc/
/usr/share/icons/
/usr/share/foo/
/usr/share/locale/

Dies würde zwei Binärpakete erzeugen, foo und foo-common. Beide würden ihren eigenen Abschnitt in debian/control benötigen.

Sehen Sie man dh_install und den Abschnitt zur Installationsdatei (Abschnitt 5.11) der Debian-Anleitung für neue Maintainers für zusätzliche Informationen.

2.5.2. Die Datei ‘watch’

Die Datei debian/watch erlaubt uns automatisch mithilfe des Werkzeuges uscan in dem Paket devscripts zu überprüfen, ob neue Upstream-Versionen vorhanden sind. Die erste Zeile der “watch”-Datei muss die Format-Version bezeichnen (3, zum Zeipunkt dieser Textfassung), während die folgenden Zeilen die zu parsenden URLs enthalten. Zum Beispiel:

version=3

http://ftp.gnu.org/gnu/hello/hello-(.*).tar.gz

Der Befehl uscan im Wurzelverzeichnis des Quellcodes wird jetzt die Upstream-Versionsnummer in debian/changelog mit der neusten verfügbaren Upstream-Version vergleichen. Wenn eine neue Upstream-Version gefunden wurde, wird sie automatisch heruntergeladen. Zum Beispiel:

$ uscan
hello: Newer version (2.7) available on remote site:
  http://ftp.gnu.org/gnu/hello/hello-2.7.tar.gz
  (local version is 2.6)
hello: Successfully downloaded updated package hello-2.7.tar.gz
    and symlinked hello_2.7.orig.tar.gz to it

Wenn Ihre Tarballs auf Launchpad leben, ist die debian/watch etwas komplizierter (siehe Frage 21146 und Bug 231797 für die Gründe). Verwenden Sie in diesem Falle etwas wie:

version=3
https://launchpad.net/flufl.enum/+download http://launchpad.net/flufl.enum/.*/flufl.enum-(.+).tar.gz

Für weitere Informationen, schauen Sie man uscan und die watch file section (Section 4.11) im Debian Policy Manual an.

Um eine Liste der Pakete zu sehen, deren watch Datei eine neuere Version Upstream berichtet, schauen Sie sich Ubuntu External Health Status an.

2.5.3. Die Datei source/format

Diese Datei spezifiziert das Format des Quellpakets. Es soll eine einzige Zeile enthalten, die das gewünschte Format beschreibt.

  • 3.0 (native) für native Debian-Pakete (keine Upstreamversion)

  • 3.0 (quilt) für Pakete mit einem separaten Upstream-Tarball

  • 1.0 für Pakete, die explizit das Standard-Format wünschen

Momentan wird das Paket-Quellformat standardmäßig auf 1.0 gesetzt, sollte die Datei nicht existieren. Das kann man jedoch auch explizit in der source/format Datei angeben. Sollten Sie sich dagegen entscheiden, wird lintian eine Warnung wegen der fehlenden Datei ausgeben. Diese Warnung hat lediglich Informationscharakter und kann sicher ignoriert werden.

Entwickler werden ermutigt, das neuere 3.0 Quellformat zu verwenden. Es stellt eine Reihe von Features bereit:

  • Unterstützung für zusätzliche Komprimierungsformate: bzip2, lzma, xz

  • Ünterstützung für mehrere Upstream-Tarballs

  • Nicht nötig den Upsteam-Tarball neu zu packen um das Debian-Verzeichnis zu löschen

  • Debian-spezifische Änderung sind nicht länger in einem einzelnen .diff.gz sondern stattdessen in mehreren Patches kompatibel mit quilt unter debian/patches/

https://wiki.debian.org/Projects/DebSrc3.0 fasst weitere zusätzliche Informationen bezüglich der Umstellung auf die 3.0 Quellpaketformate zusammen.

Siehe man dpkg-source sowie source/format section (Sektion 5.21) des Debian New Maintainers’ Guide für weitere Details.

2.6. Weiterführende Quellen

Zusätzlich zu den Links im Debian Policy Manual in jeder übergeordneten Sektion bietet der Debian New Maintainers’ Guide detailliertere Beschreibungen jeder Datei. Chapter 4, “Required files under the debian directory” beschreibt weiterhin die control, changelog, copyright und rules Dateien. Chapter 5, “Other files under the debian directory” beschreibt zusätzliche Dateien, die verwendet werden können.