Kapitel 4. Benötigte Dateien im Verzeichnis `debian`

# Kapitel 4. Benötigte Dateien im Verzeichnis `debian`

Die Überarbeitung dieser Anleitung mit aktualisierten Inhalten und weiteren praktischen Beispielen ist unter Guide for Debian Maintainers verfügbar. Bitte verwenden Sie diese neue Anleitung als primäre Anleitung.

Im Quellverzeichnis des Programms gibt es ein neues Unterverzeichnis, das `debian` heißt. In diesem Verzeichnis sind einige Dateien, die wir ändern müssen, um die Eigenschaften des Pakets anzupassen. Die wichtigsten davon sind `control`, `changelog`, `copyright` und `rules`, die für jedes Paket benötigt werden. [27]

## 4.1. `control`

Diese Datei enthält verschiedene Werte, die dpkg, dselect, apt-get, apt-cache, aptitude und andere Paketverwaltungswerkzeuge verwenden, um das Paket zu verwalten. Sie ist im Debian Policy Manual, Kapitel 5 »Control files and their fields« definiert.

Dies ist die Datei `control`, die dh_make für uns erstellt hat:

     1 Source: gentoo
     2 Section: unknown
     3 Priority: optional
     4 Maintainer: Josip Rodin <joy-mg@debian.org>
     5 Build-Depends: debhelper (>=10)
     6 Standards-Version: 4.0.0
     7 Homepage: <URL der Originalautoren einfügen, falls relevant>
     8
     9 Package: gentoo
    10 Architecture: any
    11 Depends: ${shlibs:Depends}, ${misc:Depends}
    12 Description: < bis zu 60 Zeichen Beschreibung einfügen>
    13  <lange Beschreibung einfügen, mit Leerzeichen eingerückt>

(Die Zeilennummerierung habe ich hinzugefügt.)

Die Zeilen 1-7 sind die Steuerinformationen für das Quellcode-Paket. Zeilen 9-13 sind die Steuerinformationen für das Binärpaket.

Zeile 1 ist der Name des Quellcode-Pakets.

Zeile 2 bestimmt den Bereich (Section) der Distribution, in die das Quellcode-Paket gehört.

Sie haben bestimmt schon gemerkt, dass das Debian-Archiv in mehrere Bereiche aufgeteilt ist: `main` (freie Software), `non-free` (nicht wirklich freie Software) und `contrib` (freie Software, die von non-free-Software abhängt). Jeder davon ist in Abschnitte eingeteilt, die die Pakete in grobe Kategorien sortieren. Dementsprechend gibt es `admin` für Programme für Administratoren, `devel` für Programmierwerkzeuge, `doc` für Dokumentation, `libs` für Programmbibliotheken, `mail` für E-Mail-Leseprogramme und -Daemons, `net` für Netzwerk-Anwendungen und Daemons, `x11` für X11-Programme, die nirgendwo anders unterkommen, und viele mehr. [28]

Ändern Sie den Bereich also in x11 (das Präfix `main/` wird impliziert, also können wir es weglassen).

Zeile 3 beschreibt, wie wichtig es ist, dass der Benutzer das Paket installiert. [29]

- Die Priorität `optional` ist normalerweise für neue Pakete sinnvoll, die nicht mit anderen Paketen der Prioritäten `required`, `important` oder `standard` kollidieren.

Bereich und Priorität werden von Oberflächen wie aptitude benutzt, um Pakete zu sortieren und Standardparameter auszuwählen. Wenn Sie das Paket für Debian hochladen, können die Werte dieser beiden Felder von den Archivbetreuern überschrieben werden. Sie erhalten dann eine Nachricht darüber per E-Mail.

Da es sich um ein Paket mit normaler Priorität handelt und es nichts anderes stört, ändern wir die Priorität auf »`optional`«.

Zeile 4 ist der Name und die E-Mail-Adresse des Betreuers. Sie müssen sicherstellen, dass dieses Feld eine gültige »`To`«-Kopfzeile für eine E-Mail enthält, weil nach dem Hochladen die Fehlerdatenbank diesen Eintrag nutzt, um die Fehler-E-Mails an Sie zuzustellen. Benutzen Sie keine Kommata, kaufmännische Und-Zeichen (&) oder Klammern.

Zeile 5 enthält die Liste der Pakete, die zum Bauen des Pakets benötigt werden, im Feld `Build-Depends`. Sie können hier ebenso das Feld `Build-Depends-Indep` in einer zusätzlichen Zeile benutzen [30]. Einige Pakete wie `gcc` und `make` werden impliziert, weil sie vom Paket `build-essential` benötigt werden. Falls Sie andere Werkzeuge zum Bauen Ihres Pakets brauchen, müssen Sie sie zu diesen Feldern hinzufügen. Mehrere Einträge werden durch Kommata getrennt; mehr über die Syntax dieser Zeilen finden Sie in den Erläuterungen der binären Paketabhängigkeiten.

- Bei allen Paketen, die auf den Befehl dh in der Datei `debian/rules` zugreifen, müssen Sie »`debhelper (>=9)`« in das Feld `Build-Depends` eintragen, um die Debian-Richtlinien für das Ziel `clean` zu erfüllen.

- Quellpakete, die binäre Pakete mit »`Architecture: any`« erstellen, werden vom automatischen Bausystem (»Autobuilder«) neu gebaut. Da während dieser Autobuilder-Prozedur nur die in `Build-Depends` aufgeführten Pakete vor der Ausführung von `debian/rules build` installiert werden (siehe Abschnitt 6.2, „Autobuilder“), muss das Feld `Build-Depends` praktisch alle erforderlichen Pakete auflisten. Das Feld `Build-Depends-Indep` wird daher selten benutzt.

- Quellpakete, die nur binäre Pakete mit »`Architecture: all`« erstellen, können im Feld `Build-Depends-Indep` alle erforderlichen Pakete auflisten, es sei denn, diese sind bereits im Feld `Build-Depends` aufgeführt, um die Debian-Richtlinie für das Ziel `clean` zu erfüllen.

Wenn Sie sich nicht sicher sind, welches von beiden Sie benutzen sollten, verwenden Sie das Feld `Build-Depends`, um auf der sicheren Seite zu sein. [31]

Um herauszufinden, welche Pakete Ihr Paket zum Bauen benötigt, führen Sie diesen Befehl aus:

    $ dpkg-depcheck -d ./configure

Um die genauen Build-Abhängigkeiten für `/usr/bin/foo` manuell herauszufinden, führen Sie

    $ objdump -p /usr/bin/foo | grep NEEDED

aus. Rufen Sie dann für jede aufgelistete Bibliothek (beispielsweise libfoo.so.6) diesen Befehl auf:

    $ dpkg -S libfoo.so.6

Dann nehmen Sie einfach die Entwicklerversion (`-dev`) jedes Pakets als einen `Build-Depends`-Eintrag. Falls Sie dafür ldd benutzen, werden auch indirekt abhängende Bibliotheken aufgelistet, die wiederum zu exzessiven Bauabhängigkeiten führen können.

`Gentoo` benötigt noch `xlibs-dev`, `libgtk1.2-dev` und `libglib1.2-dev`, um gebaut werden zu können, deshalb hängen wir diese direkt hinter `debhelper` an.

Zeile 6 enthält die Version des Debian Policy Manual, dessen Standards dieses Paket entspricht, also die Version, die Sie gelesen haben, während Sie Ihr Paket erstellten.

In Zeile 7 können Sie die URL der Homepage der Originalautoren der Software notieren.

Zeile 9 enthält den Namen des Binärpakets. Üblicherweise ist dies der gleiche Name wie der des Quellpakets, aber das muss nicht immer so sein.

Zeile 10 beschreibt die Architekturen, für die das binäre Paket kompiliert werden kann. Dieser Wert ist normalerweise einer der folgenden, abhängig von der Art des binären Pakets: [32]

- `Architecture: any`

  - Das erstellte Binärpaket ist architekturabhängig, typischerweise in einer kompilierten Sprache.

- `Architecture: all`

  - Das erstellte Binärpaket ist architekturunabhängig, besteht typischerweise aus Text, Bilder oder Skripten in einer interpretierten Sprache.

Wir lassen Zeile 10 unverändert, da das Programm in C geschrieben ist. dpkg-gencontrol(1) wird den geeigneten Architekturwert für jede Maschine, auf der diese Quellen gebaut werden, einfügen.

Falls Ihr Paket unabhängig von der Architektur funktioniert (beispielsweise ein Shell- oder Perl-Skript oder Dokumentation), ändern Sie dies in »`all`« und lesen Sie später unter Abschnitt 4.4, „`rules`“ über die Benutzung der Regel `binary-indep` statt `binary-arch` für den Bau des Pakets.

Zeile 11 zeigt eine der mächtigsten Eigenschaften des Paketsystems von Debian. Pakete können auf verschiedene Arten miteinander in Beziehung stehen. Neben `Depends` (hängt ab von) gibt es noch die Beziehungsfelder `Recommends` (empfiehlt), `Suggests` (schlägt vor), `Pre-Depends` (setzt voraus), `Breaks` (beschädigt), `Conflicts` (kollidiert mit), `Provides` (enthält) und `Replaces` (ersetzt).

Die verschiedenen Paketverwaltungswerkzeuge verhalten sich normalerweise bei der Behandlung dieser Beziehungen gleich; wenn nicht, wird dies erklärt (siehe dpkg(8), dselect(8), apt(8), aptitude(1) usw.).

Es folgt eine vereinfachte Beschreibung der Paketbeziehungen: [33]

- `Depends`

  Das Paket wird erst installiert, wenn die hier aufgelisteten Pakete ebenfalls installiert sind. Benutzen Sie dies, falls ihr Programm ohne ein bestimmtes Paket überhaupt nicht läuft (oder schwere Schäden verursacht).

- `Recommends`

  Benutzen Sie dies für Pakete, die nicht absolut notwendig sind, die aber typischerweise mit Ihrem Programm verwendet werden. Wenn ein Benutzer Ihr Programm installiert, fragen wahrscheinlich alle Oberflächen nach, ob die empfohlenen Pakete auch installiert werden sollen. aptitude und apt-get installieren alle empfohlenen Pakete zusammen mit Ihrem Paket (aber der Benutzer kann diese Voreinstellung deaktivieren). dpkg ignoriert dieses Feld.

- `Suggests`

  Benutzen Sie dies für Pakete, die mit Ihrem Programm gut zusammenarbeiten, aber absolut nicht notwendig sind. Wenn ein Benutzer Ihr Programm installiert, werden sie wahrscheinlich nicht gefragt, ob die vorgeschlagenen Pakete auch installiert werden sollen. aptitude kann so konfiguriert werden, dass es vorgeschlagene Pakete zusammen mit Ihrem Paket installiert, aber dies ist nicht die Voreinstellung. dpkg und apt-get ignorieren dieses Feld.

- `Pre-Depends`

  Dies ist stärker als `Depends`. Das Paket wird erst installiert, wenn die hier aufgelisteten Pakete fertig installiert und richtig konfiguriert sind. Benutzen Sie dies sehr sparsam und nur, nachdem auf der Mailingliste debian-devel@lists.debian.org darüber diskutiert wurde. Lies: Verwenden Sie es überhaupt nicht. :-)

- `Conflicts`

  Das Paket wird erst installiert, wenn alle Pakete, mit denen es kollidiert, entfernt wurden. Benutzen Sie dies, wenn ihr Programm überhaupt nicht läuft oder schwere Probleme verursacht, solange ein bestimmtes Paket installiert ist.

- `Breaks`

  Wenn dieses Paket installiert ist, werden alle aufgeführten Pakete als beschädigt markiert. Normalerweise gibt ein Eintrag unter `Breaks` an, dass er auf Versionen älter als einen bestimmten Wert zutrifft. Die Lösung besteht üblicherweise darin, höherwertige Paketverwaltungswerkzeuge zu verwenden, um ein Upgrade der aufgeführten Pakete durchzuführen.

- `Provides`

  Für einige Paketarten mit mehreren Alternativen wurden virtuelle Namen definiert. Die vollständige Liste dieser virtuellen Pakete finden Sie in der Datei virtual-package-names-list.txt.gz. Benutzen Sie dies, wenn Ihr Paket die Funktionalität eines existierenden virtuellen Pakets bietet.

- `Replaces`

  Benutzen Sie dies, wenn Ihr Paket Dateien eines anderen Pakets überschreibt oder ein anderes Paket vollständig ersetzt (wird zusammen mit `Conflicts` benutzt). Dateien der genannten Pakete werden mit den Dateien aus Ihrem Paket überschrieben.

All diese Felder haben eine einheitliche Syntax. Es ist jeweils eine durch Kommata getrennte Liste der Paketnamen. Diese Paketnamen können auch aus einer Liste von alternativen Paketnamen bestehen, die durch senkrechte Striche »`|`« (»pipe«-Zeichen) getrennt werden.

Die Anwendung der Felder kann auf bestimmte Versionen eines genannten Pakets beschränkt werden. Die Einschränkung jedes einzelnen Pakets wird in Klammern nach seinem Namen aufgeführt und sollte einen Vergleichsoperator aus der folgenden Liste enthalten, gefolgt von einem Versionsnummernwert. Die erlaubten Vergleiche sind `<<`, `<=`, `=`, `>=` und `>>` für strikt niedriger, niedriger oder gleich, genau gleich, höher oder gleich und strikt höher. Ein Beispiel:

    Depends: foo (>= 1.2), libbar1 (= 1.3.4)
    Conflicts: baz
    Recommends: libbaz4 (>> 4.0.7)
    Suggests: quux
    Replaces: quux (<< 5), quux-foo (<= 7.6)

Die letzte Funktionalität, über die Sie Bescheid wissen müssen, ist `${shlibs:Depends}`, `${perl:Depends}`, `${misc:Depends}`, usw.

dh_shlibdeps(1) berechnet die Abhängigkeiten von gemeinsam benutzten Bibliotheken für Binärpakete. Es erstellt eine Liste von ELF-Programmen und gemeinsam benutzten Bibliotheken, die es für jedes Binärpaket gefunden hat. Diese Liste wird zur Ersetzung von `${shlibs:Depends}` verwandt.

dh_perl(1) berechnet Perl-Abhängigkeiten. Es erstellt für jedes Binärpaket eine Liste von Abhängigkeiten von `perl` oder `perlapi`. Diese Liste wird zur Ersetzung von `${perl:Depends}` verwandt.

Einige `debhelper`-Befehle können dazu führen, dass das erstellte Paket von einigen zusätzlichen Paketen abhängt. Alle diese Befehle erstellen eine Liste von benötigten Paketen für jedes Binärpaket. Diese Liste wird zur Ersetzung von `${misc:Depends}` verwandt.

dh_gencontrol(1) erstellt die Datei `DEBIAN/control` für jedes Binärpaket und ersetzt dabei `${shlibs:Depends}`, `${perl:Depends}`, `${misc:Depends}`, usw.

Nach all diesen Erklärungen können wir das Feld `Depends` aber exakt so belassen, wie es jetzt ist und eine weitere Zeile dahinter einfügen, in der »`Suggests: file`« steht, weil `gentoo` einige Funktionen des Pakets `file` nutzen kann.

Zeile 9 ist die Homepage-URL. Nehmen wir an, diese sei http://www.obsession.se/gentoo/.

Zeile 12 enthält eine Kurzbeschreibung. Terminals sind typischerweise 80 Zeichen breit, also sollte die Kurzbeschreibung nicht länger als etwa 60 Zeichen sein. Ich ändere es in `fully GUI-configurable, two-pane X file manager`.

In die Zeile 13 kommt eine ausführliche Beschreibung. Sie sollte aus einem kleinen Text bestehen, der mehr über das Paket verrät. Die erste Spalte jeder Zeile muss leer sein. Es dürfen keine leeren Zeilen vorkommen, Sie können aber welche simulieren, indem Sie einen einzelnen »`.`« (Punkt) in die Zeile einsetzen. Es darf nach der ausführlichen Beschreibung auch nicht mehr als eine Leerzeile vorkommen. [34]

Wir können zwischen die Zeilen 6 und 7 die Felder `Vcs-*` einfügen, um das Versionskontrollsystem (VCS) zu dokumentieren. [35] Wir nehmen an, dass das Paket `gentoo` sein VCS im Git-Service von Debian Alioth unter `git://git.debian.org/git/collab-maint/gentoo.git` hat.

Zum Schluss ist dies die aktualisierte Datei `control`:

     1 Source: gentoo
     2 Section: x11
     3 Priority: optional
     4 Maintainer: Josip Rodin <joy-mg@debian.org>
     5 Build-Depends: debhelper (>=10), xlibs-dev, libgtk1.2-dev, libglib1.2-dev
     6 Standards-Version: 4.0.0
     7 Vcs-Git: https://anonscm.debian.org/git/collab-maint/gentoo.git
     8 Vcs-browser: https://anonscm.debian.org/git/collab-maint/gentoo.git
     9 Homepage: http://www.obsession.se/gentoo/
    10
    11 Package: gentoo
    12 Architecture: any
    13 Depends: ${shlibs:Depends}, ${misc:Depends}
    14 Suggests: file
    15 Description: fully GUI-configurable, two-pane X file manager
    16  gentoo is a two-pane file manager for the X Window System. gentoo lets the
    17  user do (almost) all of the configuration and customizing from within the
    18  program itself. If you still prefer to hand-edit configuration files,
    19  they're fairly easy to work with since they are written in an XML format.
    20  .
    21  gentoo features a fairly complex and powerful file identification system,
    22  coupled to an object-oriented style system, which together give you a lot
    23  of control over how files of different types are displayed and acted upon.
    24  Additionally, over a hundred pixmap images are available for use in file
    25  type descriptions.
    26  .
    29  gentoo was written from scratch in ANSI C, and it utilizes the GTK+ toolkit
    30  for its interface.

(Die Zeilennummerierung habe ich hinzugefügt.)

## 4.2. `copyright`

Diese Datei enthält Informationen über das Copyright und die Lizenz der Quellen der Originalautoren. Debian Policy Manual, Kapitel 12.5 »Copyright information« gibt den Inhalt vor und DEP-5: Machine-parseable `debian/copyright` bietet Hilfestellungen für ihr Format.

Dh_make kann eine Vorlage für die Datei `copyright` erzeugen. Verwenden Sie hier die Option »`--copyright gpl2`«, um eine Vorlage für das Paket `gentoo` zu erhalten, das unter GPL-2 veröffentlicht wurde.

Sie müssen hier fehlende Informationen eintragen, um die Datei zu vervollständigen, beispielsweise die Quelle, von der Sie das Paket bezogen haben, die tatsächlichen Copyright-Vermerke und die Lizenz. Bei den verbreiteten Lizenzen von freier Software (GNU GPL-1, GNU GPL-2, GNU GPL-3, LGPL-2, LGPL-2.1, LGPL-3, GNU FDL-1.2, GNU FDL-1.3, Apache-2.0, 3-Clause BSD, CC0-1.0, MPL-1.1, MPL-2.0 oder der Artistic license) können Sie auf die entsprechende Datei im Verzeichnis `/usr/share/common-licenses/` verweisen, das auf jedem Debian-System existiert. Anderenfalls müssen Sie die vollständige Lizenz einfügen.

Zusammengefasst sollte die Datei `copyright` von `gentoo` so aussehen:

     1 Format: https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
     2 Upstream-Name: gentoo
     3 Upstream-Contact: Emil Brink <emil@obsession.se>
     4 Source: http://sourceforge.net/projects/gentoo/files/
     5
     6 Files: *
     7 Copyright: 1998-2010 Emil Brink <emil@obsession.se>
     8 License: GPL-2+
     9
    10 Files: icons/*
    11 Copyright: 1998 Johan Hanson <johan@tiq.com>
    12 License: GPL-2+
    13
    14 Files: debian/*
    15 Copyright: 1998-2010 Josip Rodin <joy-mg@debian.org>
    16 License: GPL-2+
    17
    18 License: GPL-2+
    19  This program is free software; you can redistribute it and/or modify
    20  it under the terms of the GNU General Public License as published by
    21  the Free Software Foundation; either version 2 of the License, or
    22  (at your option) any later version.
    23  .
    24  This program is distributed in the hope that it will be useful,
    25  but WITHOUT ANY WARRANTY; without even the implied warranty of
    26  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
    27  GNU General Public License for more details.
    28  .
    29  You should have received a copy of the GNU General Public License along
    30  with this program; if not, write to the Free Software Foundation, Inc.,
    31  51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
    32  .
    33  On Debian systems, the full text of the GNU General Public
    34  License version 2 can be found in the file
    35  '/usr/share/common-licenses/GPL-2'.

(Die Zeilennummerierung habe ich hinzugefügt.)

Bitte befolgen Sie das »HOWTO«, das von den FTP-Masters zur Verfügung gestellt wird und an debian-devel-announce geschickt wurde: http://lists.debian.org/debian-devel-announce/2006/03/msg00023.html.

## 4.3. `changelog`

Dies ist eine zwingend vorgeschriebene Datei, deren Format im Debian Policy Manual, Kapitel 4.4 »debian/changelog« beschrieben wird. Dieses Format benötigen dpkg und andere Programme, um die Versionsnummer, Revision, Distribution und die Dringlichkeit Ihres Pakets zu bestimmen.

Für Sie ist die Datei ebenfalls wichtig, weil es sinnvoll ist, alle von Ihnen vorgenommenen Änderungen zu dokumentieren. Damit können Leute, die Ihr Paket herunterladen, einfacher herausfinden, ob es Probleme mit dem Paket gibt, die sie kennen sollten. Diese Datei wird im Binärpaket als `/usr/share/doc/gentoo/changelog.Debian.gz` gespeichert.

dh_make hat eine Standardvorlage erstellt, die so aussieht:

    1  gentoo (0.9.12-1) unstable; urgency=medium
    2
    3   * Initial release. (Closes: #nnnn)  <nnnn ist die Fehlernummer Ihres ITP>
    4
    5  -- Josip Rodin <joy-mg@debian.org>  Mon, 22 Mar 2010 00:37:31 +0100
    6

(Die Zeilennummerierung habe ich hinzugefügt.)

In der Zeile 1 stehen der Paketname, die Version, die Distribution und die Dringlichkeit. Der Name muss mit dem Namen des Quellpakets übereinstimmen, die Distribution sollte `unstable` sein und die Dringlichkeit sollte auf `medium` gesetzt werden, falls es keinen besonderen Grund für einen anderen Wert gibt.

Zeilen 3-5 sind ein Protokolleintrag, in denen Sie die in dieser Paketrevision gemachten Änderungen dokumentieren können (hier kommen keine Änderungen des Originalautors hinein; für diese Zwecke gibt es eine spezielle Datei, die von den Originalautoren erstellt wurde und die Sie später als `/usr/share/doc/gentoo/changelog.gz` installieren werden). Wir nehmen an, dass die Nummer Ihres ITP-Fehlerberichts (»Intent To Package«; Absicht, ein Paket zu erstellen) »`12345`« lautet. Neue Zeilen werden direkt unter der obersten Zeile, die mit einem Stern (»`*`«) beginnt, eingefügt. Sie können das mit dch(1) erledigen. Sie können dies per Hand mit einem Texteditor bearbeiten, solange Sie den von dch(1) verwandten Formatierungskonventionen folgen.

Um zu verhindern, dass ein Paket versehentlich hochgeladen wird, bevor es fertig ist, empfiehlt es sich, den Distributionswert auf einen ungültigen Ausdruck `UNRELEASED` zu setzen.

Schließlich kommen Sie zu einer Datei wie dieser hier:

    1  gentoo (0.9.12-1) UNRELEASED; urgency=low
    2
    3   * Initial Release. Closes: #12345
    4   * This is my first Debian package.
    5   * Adjusted the Makefile to fix $(DESTDIR) problems.
    6
    7  -- Josip Rodin <joy-mg@debian.org>  Mon, 22 Mar 2010 00:37:31 +0100
    8

(Die Zeilennummerierung habe ich hinzugefügt.)

Sobald Sie mit allen Änderungen zufrieden und sie im `changelog` dokumentiert haben, sollten Sie den Wert der Distribution von `UNRELEASED` auf den Ziel-Distributionswert `unstable` (oder sogar `experimental`) ändern. [36]

Sie können später mehr über Aktualisierungen der Datei `changelog` in Kapitel 8, Aktualisieren des Pakets lesen.

## 4.4. `rules`

Wir werfen nun einen Blick auf die genauen Regeln, die dpkg-buildpackage(1) verwenden wird, um das Paket zu bauen. Diese Datei ist in Wirklichkeit ein weiteres `Makefile`, aber anders als das von den Originalautoren mitgelieferte. Im Unterschied zu den anderen Dateien im Verzeichnis `debian` ist diese Datei als ausführbar gekennzeichnet.

### 4.4.1. Ziele der Datei `rules`

Jede `rules`-Datei, wie jedes andere `Makefile`, besteht aus mehreren Regeln, von der jede ein Ziel und eine Ausführung definiert.[37] Eine neue Regel beginnt mit der Ziel-Deklaration in der ersten Spalte. Die folgenden Zeilen beginnen mit einem Tabulator (ASCII 9), nach dem das Rezept zur Durchführung des Ziels angegeben wird. Leere Zeilen und Zeilen, die mit einem `#` (Hash) anfangen, werden als Kommentare behandelt und ignoriert. [38]

Eine Regel, die Sie ausführen möchten, wird durch ihren Zielnamen als Befehlszeilenargument aufgerufen. Beispielsweise führen `debian/rules `build`` und `fakeroot make -f debian/rules `binary`` die Regeln für die Ziele ``build`` respektive ``binary`` aus.

Es folgt eine vereinfachte Erklärung der Ziele:

- `clean`-Ziel: Löschen aller kompilierten, erzeugten und nicht benötigten Dateien im Bauverzeichnis (erforderlich)

- `build`-Ziel: Bauen der kompilierten Programme und formatierten Dokumente aus den Quellen im Bauverzeichnis (erforderlich)

- `build-arch`-Ziel: Bauen der kompilierten architekturabhängigen Programme aus den Quellen im Bauverzeichnis (erforderlich)

- `build-indep`-Ziel: Bauen der architekturunabhängigen formatierten Dokumente aus den Quellen im Bauverzeichnis (erforderlich)

- `install`-Ziel: Installieren der Dateien in einen Verzeichnisbaum unterhalb des Verzeichnisses `debian` für jedes Binärpaket. Falls sie festgelegt wurden, hängen `binary*`-Ziele effektiv von diesem Ziel ab (optional)

- `binary`-Ziel: Erstellen aller Binärpakete (effektiv ist dies die Kombination der `binary-arch`- und `binary-indep`-Ziele) (erforderlich) [39]

- `binary-arch`-Ziel: Erstellen Architektur-abhängiger (`Architecture: any`) Binärpakete im übergeordneten Verzeichnis (erforderlich) [40]

- `binary-indep`-Ziel: Erstellen Architektur-unabhängiger (`Architecture: all`) Binärpakete im übergeordneten Verzeichnis (erforderlich) [41]

- `get-orig-source`-Ziel: Herunterladen der neuesten Version des Quellpakets von dem Archiv der Originalautoren (optional)

Sie sind jetzt wahrscheinlich überwältigt, aber nach der genaueren Betrachtung der Datei `rules`, die uns dh_make als Vorgabe erstellt hat, wird alles viel einfacher werden.

### 4.4.2. Die vorgegebene Datei `rules`

Neuere Versionen von dh_make erzeugen als Vorgabe eine sehr einfache, doch mächtige Datei `rules`, indem sie den Befehl dh verwenden:

     1 #!/usr/bin/make -f
     2 # See debhelper(7) (uncomment to enable)
     3 # output every command that modifies files on the build system.
     4 #DH_VERBOSE = 1
     5
     6 # see FEATURE AREAS in dpkg-buildflags(1)
     7 #export DEB_BUILD_MAINT_OPTIONS = hardening=+all
     8
     9 # see ENVIRONMENT in dpkg-buildflags(1)
    10 # package maintainers to append CFLAGS
    11 #export DEB_CFLAGS_MAINT_APPEND  = -Wall -pedantic
    12 # package maintainers to append LDFLAGS
    13 #export DEB_LDFLAGS_MAINT_APPEND = -Wl,--as-needed
    14
    15
    16 %:
    17         dh $@

(Die Zeilennummerierung habe ich hinzugefügt und auch einige Kommentare verkürzt. In der richtigen `rules`-Datei sind die führenden Leerzeichen Tabulatoren.)

Sie sind wahrscheinlich mit ähnlichen Zeilen wie der Zeile 1 aus Shell- oder Perl-Skripten vertraut. Sie teilt dem Betriebssystem mit, dass das Skript mit `/usr/bin/make` verarbeitet werden soll.

In Zeile 4 kann das Kommentarzeichen entfernt werden, um die Variable `DH_VERBOSE` auf 1 zu setzen. Dann gibt der Befehl dh aus, welche dh_*-Befehle er ausführt. Sie können hier auch eine Zeile »`export DH_OPTIONS=-v`« hinzufügen. Dann gibt jeder dh_*-Befehl aus, welche Befehle von jedem dh_*-Befehl ausgeführt werden. Das hilft Ihnen dabei, zu verstehen, was genau hinter den Kulissen dieser einfachen `rules`-Datei passiert. So können Sie Probleme besser finden. Das neue dh ist als ein zentraler Bestandteil der `debhelper`-Werkzeuge entwickelt worden und versteckt nichts vor Ihnen.

In den Zeilen 16 und 17 wird die gesamte Arbeit mit einer impliziten Regel, die die Muster-Regel verwendet, erledigt. Das Prozentzeichen steht für ein »beliebiges Ziel«, das dann lediglich ein Programm aufruft, nämlich dh mit dem Namen des Ziels. [42] Der Befehl dh ist ein Skript, das abhängig vom übergebenen Argument die entsprechenden Sequenzen von dh_*-Programmen ausführt. [43]

- »`debian/rules clean`« ruft »`dh clean`« auf, das wiederum folgendes ausführt:

      dh_testdir
      dh_auto_clean
      dh_clean

- »`debian/rules build`« ruft »`dh build`« auf, das wiederum folgendes ausführt:

      dh_testdir
      dh_auto_configure
      dh_auto_build
      dh_auto_test

- »`fakeroot debian/rules binary`« ruft »`fakeroot dh binary`« auf, das wiederum folgendes ausführt [44]:

      dh_testroot
      dh_prep
      dh_installdirs
      dh_auto_install
      dh_install
      dh_installdocs
      dh_installchangelogs
      dh_installexamples
      dh_installman
      dh_installcatalogs
      dh_installcron
      dh_installdebconf
      dh_installemacsen
      dh_installifupdown
      dh_installinfo
      dh_installinit
      dh_installmenu
      dh_installmime
      dh_installmodules
      dh_installlogcheck
      dh_installlogrotate
      dh_installpam
      dh_installppp
      dh_installudev
      dh_installwm
      dh_installxfonts
      dh_bugfiles
      dh_lintian
      dh_gconf
      dh_icons
      dh_perl
      dh_usrlocal
      dh_link
      dh_compress
      dh_fixperms
      dh_strip
      dh_makeshlibs
      dh_shlibdeps
      dh_installdeb
      dh_gencontrol
      dh_md5sums
      dh_builddeb

- »`fakeroot debian/rules binary-arch`« ruft »`fakeroot dh binary-arch`« auf, das wiederum dieselbe Sequenz ausführt wie »`fakeroot dh binary`«, allerdings wird an jeden Befehl die Option »`-a`« angehängt.

- »`fakeroot debian/rules binary-indep`« ruft »`fakeroot dh binary-indep`« auf, das wiederum fast dieselbe Sequenz ausführt wie »`fakeroot dh binary`«, allerdings wird an jeden Befehl die Option »`-i`« angehängt und die Befehle dh_strip, dh_makeshlibs und dh_shlibdeps werden weggelassen.

Die Funktion der Befehle dh_* sind größtenteils aus ihren Namen selbsterklärend. [45] Es gibt einige bemerkenswerte, für die es Sinn ergibt, hier unter der Annahme einer typischen Bauumgebung, basierend auf einem `Makefile`, eine stark vereinfachte Erläuterung bereitzustellen: [46]

- dh_auto_clean führt normalerweise folgendes aus, wenn ein `Makefile` existiert und das Ziel `distclean` enthält. [47]

      make distclean

- dh_auto_configure führt normalerweise folgendes aus, wenn die Datei `configure` existiert (Argumente zur besseren Lesbarkeit abgekürzt).

      ./configure --prefix=/usr --sysconfdir=/etc --localstatedir=/var ...

- dh_auto_build führt normalerweise folgendes aus, um das erste Ziel des `Makefile`s auszuführen, falls dieses existiert.

      make

- dh_auto_test führt normalerweise folgendes aus, falls ein `Makefile` mit dem Ziel `test` existiert. [48]

      make test

- dh_auto_install führt normalerweise folgendes aus, falls ein `Makefile` mit dem Ziel `install` existiert (Zeile zur besseren Lesbarkeit umgebrochen).

      make install \
        DESTDIR=/Pfad/zum/Paket_Version-Revision/debian/Paket

Alle Ziele, die den Befehl fakeroot erfordern, werden dh_testroot enthalten. Falls Sie nicht diesen Befehl benutzen, um vorzugeben, »root« zu sein, wird er mit einer Fehlermeldung beendet.

Das Wichtigste, was Sie über die Datei `rules` wissen müssen, die von dh_make erzeugt wurde, ist, dass sie lediglich ein Vorschlag ist. Sie funktioniert für die meisten Pakete, aber für etwas kompliziertere Pakete sollten Sie sich nicht scheuen, sie für Ihre Zwecke anzupassen.

Obwohl »`install`« kein erforderliches Ziel ist, wird es unterstützt. »`fakeroot dh install`« verhält sich wie »`fakeroot dh binary`«, stoppt aber nach dh_fixperms.

### 4.4.3. Anpassungen der Datei `rules`

Es gibt viele Arten, die `rules`-Datei anzupassen, die den neuen Befehl dh verwendet.

Der Befehl »`dh $@`« kann wie folgt angepasst werden: [49]

- Unterstützung des Befehls dh_python2 hinzufügen (die beste Wahl für Python). [50]

  - Aufnahme des Pakets `python` in »`Build-Depends`«.

  - Verwenden Sie »`dh $@ --with python2`«.

  - Hiermit werden Python-Module mit dem Rahmenwerk `python` bearbeitet.

- Unterstützung für den Befehl dh_pysupport hinzufügen. (veraltet)

  - Aufnahme des Pakets `python-support` in »`Build-Depends`«.

  - Verwenden Sie »`dh $@ --with pysupport`«.

  - Hiermit werden Python-Module mit dem Rahmenwerk `python-support` bearbeitet.

- Unterstützung für den Befehl dh_pycentral hinzufügen. (veraltet)

  - Aufnahme des Pakets `python-central` in »`Build-Depends`«.

  - Verwenden Sie stattdessen »`dh $@ --with python-central`«.

  - Hierdurch wird auch der Befehl dh_pysupport deaktiviert.

  - Hiermit werden Python-Module mit dem Rahmenwerk `python-central` bearbeitet.

- Unterstützung für den Befehl dh_installtex hinzufügen.

  - Aufnahme des Pakets `tex-common` in »`Build-Depends`«.

  - Verwenden Sie stattdessen »`dh $@ --with tex`«.

  - Hiermit werden Type-1-Schriften, Muster für Silbentrennung und Formate für TeX registriert.

- Unterstützung für die Befehle dh_quilt_patch und dh_quilt_unpatch hinzufügen.

  - Aufnahme des Pakets `quilt` in »`Build-Depends`«.

  - Verwenden Sie stattdessen »`dh $@ --with quilt`«.

  - Hiermit werden für ein Quellpaket im Format `1.0` aus Dateien im Verzeichnis `debian/patches` Patches auf die ursprünglichen Quellen angewendet und auch wieder rückgängig gemacht.

  - Dies wird nicht benötigt, falls Sie das neue Quellpaketformat `3.0 (quilt)` benutzen.

- Unterstützung für den Befehl dh_dkms hinzufügen.

  - Aufnahme des Pakets `dkms` in »`Build-Depends`«.

  - Verwenden Sie stattdessen »`dh $@ --with dkms`«.

  - Hiermit wird die korrekte Verwendung von DKMS durch die Kernel-Modul-Pakete sichergestellt.

- Unterstützung für die Befehle dh_autotools-dev_updateconfig und dh_autotools-dev_restoreconfig hinzufügen.

  - Aufnahme des Pakets `autotools-dev` in »`Build-Depends`«.

  - Verwenden Sie stattdessen »`dh $@ --with autotools-dev`«.

  - Hiermit werden die Dateien `config.sub` und `config.guess` aktualisiert und wiederhergestellt.

- Unterstützung für den Befehle dh_autoreconf und dh_autoreconf_clean hinzufügen.

  - Aufnahme des Pakets `dh-autoreconf` in »`Build-Depends`«.

  - Verwenden Sie stattdessen »`dh $@ --with autoreconf`«.

  - Hiermit werden die Dateien des GNU-Bausystems aktualisiert und nach dem Bau wiederhergestellt.

- Unterstützung für den Befehl dh_girepository hinzufügen.

  - Aufnahme des Pakets `gobject-introspection` in »`Build-Depends`«.

  - Verwenden Sie stattdessen »`dh $@ --with gir`«.

  - Das berechnet Abhängigkeiten für Pakete, die GObject-Introspektionsdaten ausliefern und erstellt die Ersetzungsvariable `${gir:Depends}` für die Paketabhängigkeiten.

- Unterstützung für die Vervollständigung in der bash hinzufügen.

  - Aufnahme des Pakets `bash-completion` in »`Build-Depends`«.

  - Verwenden Sie stattdessen »`dh $@ --with bash-completion`«.

  - Hiermit wird die Vervollständigung durch bash unter Verwendung einer Konfigurationsdatei in `debian/`Paket`.bash-completion` installiert.

Viele dh_*-Befehle, die vom neuen dh-Befehl aufgerufen werden, können durch entsprechende Konfigurationsdateien im `debian`-Verzeichnis angepasst werden. Siehe Kapitel 5, Andere Dateien im Verzeichnis `debian` sowie die Handbuchseite jedes Befehls für Anpassungen dieser Funktionalitäten.

Es kann nötig sein, über dh aufgerufene dh_*-Befehle mit zusätzlichen Argumenten oder zusätzliche Befehle mit ihnen auszuführen oder sie ganz auszulassen. In solchen Fällen können Sie ein `override_dh_`foo``-Ziel mit der entsprechenden Regel in der Datei `rules` erstellen, das ein `override_dh_`foo``-Ziel für den Befehl dh_`foo` definiert, den Sie ändern wollen. Im Grunde bedeutet das nur »führe stattdessen mich aus«. [51]

Bitte beachten Sie, dass die dh_auto_*-Befehle dazu neigen, mehr als die in dieser stark vereinfachten Erklärung dargestellten Tätigkeiten zu erledigen, um Randfälle zu berücksichtigen. Es ist keine gute Idee, `override_dh_*`-Ziele zu verwenden, um die vereinfachten äquivalenten Befehle als Ersatz zu verwenden (außer beim Ziel `override_dh_auto_clean`), da damit solche pfiffigen `debhelper`-Funktionalitäten umgangen werden.

Falls Sie beispielsweise mittels der Autotools Systemkonfigurationsdaten des aktuellen `gentoo`-Pakets im Verzeichnis `/etc/gentoo` statt im normalen Verzeichnis `/etc` speichern wollen, können Sie das Vorgabeargument `--sysconfig=/etc` für ./configure im Befehl dh_auto_configure durch folgendes außer Kraft setzen:

    override_dh_auto_configure:
            dh_auto_configure -- --sysconfig=/etc/gentoo

Die nach dem `--` übergebenen Argumente werden zu den vorgegebenen Argumenten des automatisch ausgeführten Programms hinzugefügt, um sie zu überschreiben. Die Benutzung des Befehls dh_auto_configure ist besser als der direkte Aufruf von ./configure, weil in diesem Fall lediglich das Argument `--sysconfig` überschrieben wird und andere, sehr wohl beabsichtigte, Argumente für den Befehl ./configure erhalten bleiben.

Falls das `Makefile` in den Quellen von `gentoo` zum Bauen explizit das Ziel `build` benötigt, [52], können Sie ein Ziel namens `override_dh_auto_build` erstellen, um dies zu ermöglichen.

    override_dh_auto_build:
            dh_auto_build -- build

Hiermit wird sichergestellt, dass `$(MAKE)` mit allen voreingestellten Argumenten des Befehls dh_auto_build plus dem Argument `build` ausgeführt wird.

Falls das `Makefile` in den Quellen von `gentoo` zum Aufräumen für das Debianpaket explizit das Ziel `packageclean` benötigt statt der Ziele `distclean` oder `clean`, können Sie ein Ziel namens `override_dh_auto_clean` erstellen, um dies zu nutzen.

    override_dh_auto_clean:
            $(MAKE) packageclean

Falls das `Makefile` in den Quellen von `gentoo` das Ziel `test` enthält, das Sie im Paketbau-Prozess für Debian nicht ausführen wollen, können Sie ein leeres Ziel namens `override_dh_auto_test` erstellen, um dies zu übergehen.

    override_dh_auto_test:

Wenn `gentoo` eine unübliche ursprüngliche Changelog-Datei namens `FIXES` enthält, wird diese standardmäßig von dh_installchangelogs nicht installiert. Der Befehl dh_installchangelogs braucht den Namen `FIXES` als Argument, um die Datei zu installieren. [53]

    override_dh_installchangelogs:
            dh_installchangelogs FIXES

Wenn Sie den neuen dh-Befehl benutzen, wird es schwierig, die genauen Effekte von expliziten Zielen wie den in Abschnitt 4.4.1, „Ziele der Datei `rules`“ aufgelisteten zu verstehen. Eine Ausnahme stellt `get-orig-source` dar. Bitte beschränken Sie daher - soweit möglich - explizite Ziele auf solche mit den Namen `override_dh_*` sowie vollständig davon unabhängige.

[27] In diesem Kapitel werden zur Vereinfachung Dateien im Verzeichnis `debian` ohne das einleitende `debian/` referenziert, wann immer die Bedeutung eindeutig ist.

[28] Lesen Sie das Debian Policy Manual, Kapitel 2.4 »Sections« und Liste der Abschnitte in `sid`.

[29] Lesen Sie das Debian Policy Manual, Kapitel 2.5 »Priorities«.

[30] Lesen Sie das Debian Policy Manual, Kapitel 7.7 »Relationships between source and binary packages - Build-Depends, Build-Depends-Indep, Build-Conflicts, Build-Conflicts-Indep«

[31] Diese etwas merkwürdige Situation ist eine Besonderheit, die in dem Debian Policy Manual, Fußnote 55 sehr gut dokumentiert ist. Es liegt nicht an der Verwendung des Befehls dh in der Datei `debian/rules`, sondern daran, wie das Programm dpkg-buildpackage arbeitet. Dieselbe Situation gilt auch für das »auto build system« von Ubuntu.

[32] Lesen Sie Debian Policy Manual, Kapitel 5.6.8 »Architecture« für die genauen Details.

[33] Lesen Sie Debian Policy Manual, Kapitel 7 »Declaring relationships between packages«.

[34] Diese Beschreibungen sind auf Englisch. Übersetzungen dieser Beschreibungen werden durch das Debian Description Translation Project - DDTP bereitgestellt.

[35] Lesen Sie Debian-Entwicklerreferenz, 6.2.5. »Ort des Versionsverwaltungssystems«.

[36] Falls Sie den Befehl `dch -r` zur Durchführung dieser letzten Änderung verwenden, stellen Sie sicher, dass Sie die Datei `changelog` explizit im Editor speichern.

[37] Sie können das Schreiben einer `Makefile` erlernen, indem Sie Debian Reference, 12.2. "Make" lesen. Die komplette Dokumentation ist als http://www.gnu.org/software/make/manual/html_node/index.html oder als Paket `make-doc` im Archivbereich `non-free` verfügbar.

[38] Debian Policy Manual, Kapitel 4.9 »Main building script: debian/rules« erklärt die Details.

[39] Dieses Ziel wird von »`dpkg-buildpackage`« wie in Abschnitt 6.1, „Kompletter (Neu-)Bau“ beschrieben benutzt.

[40] Dieses Ziel wird von »`dpkg-buildpackage -B`« wie in Abschnitt 6.2, „Autobuilder“ beschrieben benutzt.

[41] Dieses Ziel wird von »`dpkg-buildpackage -A`« benutzt.

[42] Dies verwendet die neuen Möglichkeiten von `debhelper` v7+. Dessen Designkonzepte werden in »Not Your Grandpa's Debhelper« erklärt, das auf der DebConf9 vom `debhelper`-Betreuer präsentiert wurde. Unter `lenny` erzeugte dh_make eine wesentlich kompliziertere Datei `rules` mit expliziten Regeln und vielen dh_*-Skripten für jede der Regeln, wobei die meisten jetzt unnötig sind (und das Alter des Pakets zeigen). Der neue dh-Befehl ist einfacher und befreit uns von der »manuellen« Durchführung dieser Routinearbeit. Sie haben mit den `override_dh_*`-Zielen weiterhin die vollständige Kontrolle über diesen Prozess mit den Zielen `override_dh_*`. Siehe Abschnitt 4.4.3, „Anpassungen der Datei `rules`“. Er basiert lediglich auf dem Paket `debhelper` und verschleiert den Prozess des Paketbaus nicht, wie dies beim Paket `cdbs` sein kann.

[43] Sie können überprüfen, welche Sequenzen von dh_*-Programmen für ein bestimmtes ``Ziel`` tatsächlich aufgerufen werden, indem Sie »`dh `Ziel` --no-act`« oder »`debian/rules -- '`Ziel` --no-act'`« ausführen. Dadurch werden die Sequenzen nicht ausgeführt.

[44] Im folgenden Beispiel wird angenommen, dass `debian/compat` einen Wert gleich oder größer als 9 hat, um die Python-Unterstützungsbefehle automatisch aufzurufen.

[45] Für die komplette Information darüber, was die ganzen dh_*-Skripte genau durchführen und wie ihre Optionen lauten, lesen Sie bitte deren Handbuchseiten und die Dokumentation von `debhelper`.

[46] Diese Befehle unterstützen andere Bauumgebungen wie `setup.py`, die durch Ausführen von `dh_auto_build --list` in einem Paketbauverzeichnis aufgelistet werden können.

[47] Tatsächlich wird nach dem ersten verfügbaren Ziel aus der Liste `distclean`, `realclean` oder `clean` in dem `Makefile` gesucht und dieses ausgeführt.

[48] Tatsächlich wird nach dem ersten verfügbaren Ziel aus der Liste `test` oder `check` in dem `Makefile` gesucht und dieses ausgeführt.

[49] Falls ein Paket die Datei `/usr/share/perl5/Debian/Debhelper/Sequence/`Eigener_Name`.pm` installiert, können Sie dessen angepasste Funktion mittels »`dh $@ --with `Eigener-Name``« aktivieren.

[50] Die Benutzung des Befehls dh_python2 wird gegenüber den Befehlen dh_pysupport oder dh_pycentral bevorzugt. Verwenden Sie nicht den Befehl dh_python.

[51] Falls Sie unter `Lenny` das Verhalten eines dh_*-Skripts ändern wollten, mussten Sie die entsprechende Zeile in der Datei `rules` aufsuchen und dort anpassen.

[52] dh_auto_build ohne Argumente führt das erste Ziel in dem `Makefile` aus.

[53] Die Dateien `debian/changelog` und `debian/NEWS` werden immer automatisch installiert. Das Changelog der Originalautoren wird gefunden, indem die Dateinamen in Kleinbuchstaben umgewandelt werden und mit `changelog`, `changes`, `changelog.txt` und `changes.txt` verglichen werden.

Kapitel 3. Den Quellcode verändern |  | Kapitel 5. Andere Dateien im Verzeichnis `debian`