# 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 du einen GPG-Schlüssel besitzt (siehe: Erste Schritte), stelle sicher dass du den selben Alias und E-Mail Adresse im `changelog` verwendest wie in deinem 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 Du ein neues Paket ohne Vorlage erstellst, kannst Du 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 Packetieren 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, schau Dir 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, dass in Ubuntu das `Maintainer` Feld eine allgemeine Adresse enthält, weil jeder jedes Paket bearbeiten kann (dies unterscheidet sich von Debian, wo das Bearbeiten einer Person oder einem Team vorbehalten ist). Pakete von Ubuntu sollten allgemein im `Maintainer` Feld die Angabe `Ubuntu Developers <ubuntu-devel-discuss@lists.ubuntu.com>` haben. Wird dieses Feld verändert, sollte diese Angabe im Feld `XSBC-Original-Maintainer` gespeichert werden. Für diesen Zweck gibt es das `update-maintainer` Script aus dem `ubuntu-dev-tools` Paket. Weitere Informationen können Sie unter Debian Maintainer Feld Spezifikation im Ubuntu Wiki nachlesen.

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

Für weitere Information, schau Dir control file section (Chapter 5) des Debian Policy Manual an.

## 2.3. Die Copyright-Datei

Diese Datei gibt sowohl die Urheberrechte der Upstream-Quelle und der Paketierung an. Die Ubuntu und Debian Richtlinien (Abschnitt 12.5) verlangen, dass jedes Paket eine wortwörtliche Kopie seiner Urheber- und Lizenzinformationen in `/usr/share/doc/$(package_name)/copyright` ablegt.

Im allgemeinen findet man Urheberrechtsinformationen in der Datei `COPYING` in dem Quellverzeichnis des Programms. Diese Datei sollte Auskünfte über die Namen der Autoren und der Paketierer, die URL des ursprünglichen Programms, eine Zeile die das Jahr und den Inhaber der Urheberrechtsansprüche, und den Text des Urheberrechts an sich, geben. Eine Beispiel wäre:

    Format: http://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
    Upstream-Name: Hello
    Source: ftp://ftp.example.com/pub/games

    Files: *
    Copyright: Copyright 1998 John Doe <jdoe@example.com>
    License: GPL-2+

    Files: debian/*
    Copyright: Copyright 1998 Jane Doe <packager@example.com>
    License: GPL-2+

    License: GPL-2+
     This program is free software; you can redistribute it
     and/or modify it under the terms of the GNU General Public
     License as published by the Free Software Foundation; either
     version 2 of the License, or (at your option) any later
     version.
     .
     This program is distributed in the hope that it will be
     useful, but WITHOUT ANY WARRANTY; without even the implied
     warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
     PURPOSE.  See the GNU General Public License for more
     details.
     .
     You should have received a copy of the GNU General Public
     License along with this package; if not, write to the Free
     Software Foundation, Inc., 51 Franklin St, Fifth Floor,
     Boston, MA  02110-1301 USA
     .
     On Debian systems, the full text of the GNU General Public
     License version 2 can be found in the file
     `/usr/share/common-licenses/GPL-2'.

Dieses Beispiel befolgt das Machine-readable debian/copyright Format. Fühl Dich ermutigt, dieses Format auch zu verwenden.

## 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  $@

Lass 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, benutze:

    $ 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 mit anderen Optionen ausführen oder komplett andere Befehle stattdessen ausführen. (Zu beachten ist, dass du für die Erstellung debhelper 7.0.50 oder höher verwenden solltest.)

Wirf 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` wir dvon `dh_install` verwendet um Dateien in das Binärpacket zu installieren. Es hat zwei gängige Einsatzmöglichkeiten:

- Um Dateien in dein 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 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.

Siehe `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

Sollten Deine Tarballs in Launchpad sein, so wird `debian/watch` etwas komplizierter (siehe Question 21146 und Bug 231797 für mehr Informationen). In diesem Fall benutze etwas wie:

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

Für weitere Informationen, schaue Dir `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, schau Dir Ubuntu External Health Status an.

### 2.5.3. Die Datei source/format

Diese Datei spezifiziert das Format des Quellpakets. Es sollt 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. Solltest Du Dich 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/`

http://wiki.debian.org/Projects/DebSrc3.0 umfasst zusätzliche Informationen bezüglich dem Umstieg zu dem 3.0 Quellcode-Format.

`man dpkg-source` und source/format section (Section 5.21) aus dem Debian New Maintainers’ Guide haben weitere Details.

## 2.6. Weiterführende Quellen

Ergänzend zu den Debian Grundlagen in jedem obigen Abschnitt sind detailliertere Informationen zu den einzelnen Dateien im Leitfaden für neue Debian-Betreuer zusammengefasst. Kapitel 4, “Benötigte Dateien im Verzeichnis debian” geht auch vertiefend auf die Dateien control, changelog, copyright und rules ein. Kapitel 5, “Andere Dateien im Verzeichnis debian” behandelt alle anderen möglicherweise benötigten Dateien.