NAME¶

dh - Debhelper-Befehls-Sequenzer

ÜBERSICHT¶

dh Sequenz [--with Add-on[,Add-on …]] [--list] [Debhelper-Optionen]

BESCHREIBUNG¶

dh führt eine Sequenz von Debhelper-Befehlen aus. Die unterstützten Sequenzen entsprechen den Zielen einer debian/rules-Datei: build-arch, build-indep, build, clean, install-indep, install-arch, install, binary-arch, binary-indep und binary.

OVERRIDE- UND HOOK-ZIELE¶

Eine debian/rules-Datei, die dh benutzt, kann einen Befehl in jedem Schritt einer Sequenz außer Kraft setzen, indem sie ein Override-Ziel (Override target) definiert. Es ist auch möglich, Befehle vor oder nach jedem Schritt einzuspeisen, ohne den Schritt selbst zu beeinflussen.

     # überspringt dh_bar auf die gute und optimierte Art
     # hier wird eine Begründung zum Überspringen von dh_bar eingefügt
     override_dh_bar:
     # überspringt dh_foo auf die langsame Art
     override_dh_foo:
        # hier wird eine Begründung des Überspringens von dh_foo eingefügt
        # (diese Kommentare verursachen die Ausführung eines Scheinziels)

    $ dh_assistant detect-hook-targets
    {
       "commands-not-in-path": [
          "dh_foo"
       ],
       "hook-targets": [
          {
             "command": "dh_strip_nondeterminism",
             "is-empty": true,
             "package-section-param": null,
             "target-name": "override_dh_strip_nondeterminism"
          },
          {
             "command": "dh_foo",
             "is-empty": false,
             "package-section-param": "-a",
             "target-name": "override_dh_foo-arch"
          }
       ]
    }

    $ dh binary --no-act | grep dh_install | head -n5
         dh_installdirs
         dh_install
         debian/rules execute_after_dh_install
         dh_installdocs
         dh_installchangelogs

      # EINFACH: Es ist durchdefiniert, was passieren wird. Das Hook-Ziel 
      # wird immer berücksichtigt. Der »vielleicht ausführen«-Teil hat eine 
      # Bedingung, aber dh_foo wird mit Sicherheit übersprungen.
      #
      # Hinweis: Der Bedingungsteil wird »zweimal« untersucht, bevor er 
      # beeinflusst, was passiert. Einmal, wenn dh nachsieht, welche 
      # Hook-Ziele vorkommen und das zweite Mal, wenn das Hook-Ziel override_dh_foo 
      # ausgeführt wird. Falls *eines* davon FALSE zurückliefert, wird »vielleicht 
      # ausführen« übersprungen.
      override_dh_foo:
      ifneq (...)
          vielleicht ausführen
      endif
      # EINFACH: Dies hier ist genauso durchdefiniert. Das Hook-Ziel wird immer 
      # ausgeführt und dh_bar wird übersprungen. Der »vielleicht ausführen«-Teil ist 
      # bedingt, so wie man es erwarten würde.
      #
      # Hinweis: Die Bedingung wird trotzdem mehrmals überprüft (jedes 
      # Mal in einem anderen Prozess).  Nur die Untersuchung während des 
      # Laufs des Hook-Ziels beeinflusst, was passiert.
      override_dh_bar:
          : # Scheinbefehl, der erzwingt, dass das Ziel immer ausgeführt wird
      ifneq (...)
          vielleicht ausführen
      endif
      # KOMPLIZIERT: Dieser Fall ist ggf. nicht trivial und hat seine Haken.
      # Benutzen Sie es auf eigene Verantwortung, wenn dh_listpackages in der Bedingung steckt.
      #
      # Hier wird entweder dh_baz normal ODER stattdessen »vielleicht ausführen« ausgeführt.
      #
      # Es wird noch komplizierter, wenn die Frage aufkommt, ob dh in 
      # debian/rules rekursiv arbeiten muss, weil Sie ein »explicit« Standardziel 
      # (z. B. ein »build-arch:«-Ziel, das von »%:« getrennt ist) haben.
      ifneq (...)
      override_dh_baz:
          vielleicht ausführen
      endif

      COND_TASKS =
      ifneq (...)
      COND_TASKS += vielleicht-ausführen
      endif
      ...
      vielleicht-ausführen:
          ...
      # EINFACH: Es ist durchdefiniert, was passiert. Die 
      # $(COND_TASKS) werden entweder übersprungen oder nicht.
      #
      # Hinweis: Die Bedingung wird »zweimal« überprüft und beeinflusst immer, 
      # was passiert. Einmal, wenn dh nachsieht, welche Hook-Ziele 
      # vorhanden sind, und einmal, wenn das Hook-Ziel override_dh_foo 
      # ausgeführt wird. Wenn bei *einem* der beiden Male ein FALSE       # zurückgeliefert wird, wird $(COND_TASKS) übersprungen
      override_dh_foo: $(COND_TASKS)
      # EINFACH: Dieses hier ist genauso durchdefiniert. Das Hook-Ziel 
      # wird ausgeführt und dh_bar wird übersprungen. Der $(COND_TASKS)-Teil 
      # ist so bedingt wie man erwarten würde.
      #
      # Hinweis: Die Bedingung wird trotzdem mehrmals überprüft (jedes       # Mal in einem anderen Prozess. Nur die Überprüfung während des Laufs des 
      # Hook-Ziels beeinflusst, was passiert.
      override_dh_bar: $(COND_TASKS)
          : # Scheinbefehl, der das Ziel zwingt, immer ausgeführt zu werden
      # KOMPLIZIERT: Dieser Fall kann kompliziert sein und seine Haken haben.
      # Verwenden Sie es auf Ihre eigene Verantwortung, wenn dh_listpackages in der Bedingung vorkommt.
      #
      ifneq (...)
      override_dh_baz: $(COND_TASKS)
      endif

OPTIONEN¶

--with Erweiterung[,Add-on …]

fügt die Debhelper-Befehle, die durch die genannte Erweiterung angegeben wurden an geeigneten Stellen der ausgeführten Befehlssequenz hinzu. Diese Option kann mehr als einmal wiederholt werden oder es können mehrere Add-ons durch Kommas getrennt aufgeführt werden. Dies wird benutzt, wenn es ein Fremdpaket gibt, das Debhelper-Befehle bereitstellt. Dokumentation über die Sequenz-Erweiterungsschnittstelle finden Sie in der Datei PROGRAMMING.

Eine Build-Depends-Beziehung zum Paket dh-sequence-Erweiterung setzt eine --with-Erweiterung voraus. Das vermeidet, dass ein explizites --with in debian/rules benötigt wird, das nur dupliziert, was bereits über die Bauabhängigkeiten in debian/control erklärt wurde. Die Beziehung kann (seit 12.5) optional gemacht werden, z. B. über Bauprofile. Dies versetzt Sie in die Lage, einfach eine Erweiterung zu deaktivieren, die nur zu einem bestimmten Profil passt (z. B. um Bootstrapping zu erleichtern).

Ab Debhelper 12.5 können Erweiterungen auch im reinen indep-Modus (über Build-Depends-Indep) oder reinen arch-Modus (über Build-Depends-Arch) aktiviert werden. Derartige Erweiterungen sind nur in der bestimmten Sequenz aktiv (z. B. binary-indep), die Abhängigkeitsverwaltung für Cross-Bauen vereinfachen.

Bitte beachten Sie, dass Erweiterungen, die über Build-Depends-Indep oder Build-Depends-Arch aktiviert wurden, zusätzlichen Beschränkungen unterliegen, die sicherzustellen, dass das Ergebnis sogar dann deterministisch ist, wenn die Erweiterung nicht verfügbar ist (z. B. während des Aufräumens). Dies impliziert, dass einige Erweiterungen mit diesen Beschränkungen inkompatibel sind und nur über Build-Depends (oder manuell über debian/rules) benutzt werden können. Derzeit können derartige Erweiterungen nur Befehle zu Sequenzen hinzufügen.

--without Erweiterung

das Gegenteil von --with, deaktiviert die Benutzung der angegebenen Erweiterung. Diese Option kann mehrfach wiederholt werden oder es können mehrere Erweiterungen zum Deaktivieren durch Kommas getrennt aufgelistet werden.

--list, -l

listet alle verfügbaren Erweiterungen auf.

Wenn es nur mit dieser Option aufgerufen wird, kann dh aus jedem Verzeichnis aufgerufen werden (d.h. es benötigt keinen Zugriff auf Dateien aus einem Quellpaket).

--no-act

gibt Befehle aus, die für eine angegebene Sequenz ausgeführt würden, führt sie aber nicht aus.

Beachten Sie, dass dh normalerweise die Ausführung von Befehlen, von denen es weiß, dass sie nichts tun, überspringt. Mit »--no-act« wird die vollständige Liste der Befehle der Reihe nach ausgegeben.

Andere an dh übergebene Optionen werden an jeden Befehl, den es ausführt, weitergereicht. Damit kann eine Option wie -v, -X oder -N sowie spezialisiertere Optionen gesetzt werden.

BEISPIELE¶

Um zu sehen, welche Befehle in einer Sequenz enthalten sind, ohne tatsächlich etwas zu tun, geben Sie Folgendes ein:

        dh binary-arch --no-act

Dies ist eine sehr einfache »rules«-Datei für Pakete, bei denen die vorgegebenen Befehlssequenzen ohne zusätzliche Optionen arbeiten.

        #!/usr/bin/make -f
        %:
                dh $@

Oft möchten Sie eine Option an einen speziellen Debhelper-Befehl übergeben. Der einfachste Weg, dies zu tun, besteht darin, ein Override-Ziel für diesen Befehl hinzuzufügen.

        #!/usr/bin/make -f
        %:
                dh $@
        override_dh_strip:
                dh_strip -Xfoo
        override_dh_auto_configure:
                dh_auto_configure -- --with-foo --disable-bar

Manchmal ist ein Paket den dh_auto_configure(1) und dh_auto_build(1) so fremd, dass sie nicht automatisch einschätzen können, was daran zu machen ist. Um ihre Ausführung zu verhindern und stattdessen Ihre eigenen Befehle einzusetzen, schreiben Sie Folgendes:

        #!/usr/bin/make -f
        %:
                dh $@
        override_dh_auto_configure:
                ./mondoconfig
        override_dh_auto_build:
                mach-dass-sich-das-Universum-in-Wohlgefallen-auflöst

Ein weiterer häufiger Fall ist, dass Sie vor oder nach der Ausführung eines besonderen Debhelper-Befehls manuell etwas tun möchten.

        #!/usr/bin/make -f
        %:
                dh $@
        # Beispiel geht von Debhelper/12.8 und Kompatibilitätsstufe 10+ aus
        execute_after_dh_fixperms:
                chmod 4755 debian/foo/usr/bin/foo

Falls Sie auf einer älteren Debhelper-Kompatibilitätsstufe sind, würde das Beispiel wie folgt aussehen:

        #!/usr/bin/make -f
        %:
                dh $@
        # ältere Debhelper-Versionen oder Verwendung von Kompatibilitätsstufe 9
        #und niedriger
        override_dh_fixperms:
                dh_fixperms
                chmod 4755 debian/foo/usr/bin/foo

Python-Werkzeuge werden aufgrund ständiger Änderungen in diesem Bereich nicht standardmäßig von dh ausgeführt. Sie können dh_python2 folgendermaßen benutzen.

        #!/usr/bin/make -f
        %:
                dh $@ --with python2

So wird die Benutzung von Perls Bausystem Module::Build erzwungen wird, was nötig sein kann, falls Debhelper fälschlicherweise feststellt, dass das Programm MakeMaker verwendet.

        #!/usr/bin/make -f
        %:
                dh $@ --buildsystem=perl_build

Hier ein Beispiel für das außer Kraft setzen, wobei die dh_auto_*-Befehle den Paketquelltext für ein Paket finden, bei dem der Quelltext in einem Unterverzeichnis liegt.

        #!/usr/bin/make -f
        %:
                dh $@ --sourcedirectory=src

Und hier ist ein Beispiel, wie dh_auto_*-Befehlen mitgeteilt wird, dass in einem Unterverzeichnis gebaut wird, das beim Aufräumen entfernt wird.

        #!/usr/bin/make -f
        %:
                dh $@ --builddirectory=build

Falls Ihr Paket parallel gebaut werden kann, benutzen Sie bitte entweder Kompatibilitätsmodus 10 oder übergeben Sie --parallel an Dh. Dann wird dpkg-buildpackage -j funktionieren.

        #!/usr/bin/make -f
        %:
                dh $@ --parallel

Falls Ihr Paket nicht verlässlich unter Verwendung mehrerer Threads gebaut werden kann, übergeben Sie bitte --no-parallel an Dh (oder den zuständigen dh_auto_*-Befehl):

        #!/usr/bin/make -f
        %:
                dh $@ --no-parallel

Es folgt eine Möglichkeit, die Ausführung mehrerer Befehle, die Sie nicht ausführen möchten, durch dh zu verhindern, indem Sie leere Override-Ziele für jeden Befehl definieren.

        #!/usr/bin/make -f
        %:
                dh $@
        # nicht auszuführende Befehle:
        override_dh_auto_test override_dh_compress override_dh_fixperms:

Ein langer Bauprozess für ein separates Dokumentationspaket kann durch Benutzung von architekturabhängigen Außerkraftsetzungen (Overrides) abgetrennt werden. Diese Ziele werden übersprungen, wenn »build-arch«- und »binary-arch«-Sequenzen ausgeführt werden.

        #!/usr/bin/make -f
        %:
                dh $@
        override_dh_auto_build-indep:
                $(MAKE) -C docs
        # Keine Tests für Dokumente nötig
        override_dh_auto_test-indep:
        override_dh_auto_install-indep:
                $(MAKE) -C docs install

Angenommen, Sie möchten zusätzlich zum vorhergehenden Beispiel die Dateimodusbits einer Datei ändern, aber nur, wenn Sie ein architekturabhängiges Paket bauen, da sie beim Bauen der Dokumentation nicht vorhanden ist.

        # Beispiel geht von Debhelper/12.8 und Kompatibilitätsstufe 10+ aus
        execute_after_dh_fixperms-arch:
                chmod 4755 debian/foo/usr/bin/foo

VON DEBHELPER ANGEBOTENE DH-ERWEITERUNGEN¶

Der Hauptzweck von dh-Erweiterungen besteht darin, die Integration von Drittanbieter-Funktionalitäten für Debhelper zu erleichtern. Debhelper selbst bietet ebenfalls einige Sequenzen an, die die in bestimmten Fällen nützlich sein könnten. Sie sind in der folgenden Liste dokumentiert:

build-stamp

Eine spezielle Erweiterung, mit der gesteuert werden kann, ob dh (Kompatibilitätsstufe 10 oder darüber) Stempeldateien anlegen soll, aus denen ersichtlich ist, dass das Bauziel erfolgreich ausgeführt worden ist. Siehe "INTERNALS" für weitere Details.

Diese Erweiterung ist standardmäßig aktiv, kann aber mit dh $@ --without build-stamp abgeschaltet werden.

dwz (überholt)

Fügt in Kompatibilitätsstufe 11 und früher dh_dwz(1) zur Sequenz hinzu. Ist in Stufe 12 und darüber überholt.

elf-tools

Diese Erweiterung fügt der Sequenz Werkzeuge für ELF-Dateien hinzu, unter anderem dh_strip(1) und dh_shlibdeps(1).

Diese Erweiterung ist unter Bedingungen standardmäßig für architekturspezifische Pakete aktiviert – das heißt, sie wird für arch:all-Pakete übersprungen. Falls Sie diese Werkzeuge in einem speziellen Fall auch auf arch:all-Pakete ansetzen müssen, können Sie sie mit --with elf-tools ohne die Bedingungen aktivieren.

installinitramfs (überholt)

Fügt der Sequenz in der Kompatibilitätsstufe 11 und darunter dh_installinitramfs(1) hinzu. Ist in Stufe 12 und neuer überholt.

root-sequence (intern)

Diese ist für den internen Gebrauch reserviert.

single-binary

Eine Spezialerweiterung, die dafür sorgt, dass Debhelper im »single-binary«-Modus läuft.

Wenn sie aktiv ist, übergibt sie --destdir=debian/Paket/ an dh_auto_install(1). Dadurch wird jede vom Bausystem der Originalautoren »installierte« Datei standardmäßig zu einem Teil des (einzigen) Binärpakets, ohne dass andere Helfer wie dh_install(1) eingesetzt werden müssen.

Als Vorsichtsmaßnahme lässt sich diese Erweiterung nicht aktivieren, wenn das Quellpaket in debian/control zwei oder mehr Binärpakete auflistet.

Vor Kompatibilitätsstufe 15 war dies das Standardverhalten, wenn nur ein einzelnes Binärpaket in debian/control aufgelistet war. In Stufe 15 und darüber muss die Erweiterung explizit aktiviert werden, um es zu aktivieren.

Dass jetzt die ausdrückliche Aktivierung nötig ist, hat den Hintergrund, dass es ansonsten nicht bemerkt wird, wenn eine neues Binärpaket hinzukommt und Debhelper sein Verhalten anpasst. Deswegen kam es in der Vergangenheit zu vielen veröffentlichungskritischen Fehlern und zur Einführung von Übergangspaketen, die nahtlose Upgrades ermöglichen sollten. Das Ergebnis waren dann oft zwei leere Binärpakete, die ins Archiv hochgeladen wurden und Anwender frustrierten, weil nach dem Upgrade ihre Programme fort waren.

systemd (überholt)

Fügt der Sequenz in Kompatibilitätsstufe 10 und darunter dh_systemd_enable(1) und dh_systemd_start(1) hinzu. Ist in Stufe 11 und darüber überholt.

INTERNA¶

Falls Sie neugierig auf die Interna von dh sind, ist hier beschrieben, wie es unter der Haube arbeitet.

Im Kompatibilitätsmodus 10 (oder höher) erzeugt dh eine Stempeldatei debian/debhelper-build-stamp, nachdem die Bauschritte abgeschlossen sind, um ein erneutes Ausführen zu vermeiden. Es ist möglich, die Stempeldatei zu verhindern, indem --without=build-stamp an dh übergeben wird. Dies sorgt dafür, dass »unsauber« gebaute Pakete sich eher so verhalten, wie es manche Leute erwarten. Allerdings wird der Bau und das Testen möglicherweise zweimal ausgeführt (das zweite Mal als root oder unter fakeroot(1)).

Innerhalb eines Override-Ziels werden dh_*-Befehle eine debian/package.debhelper.log-Protokolldatei erzeugen, um den Überblick zu behalten, für welche Pakete die Befehle ausgeführt wurden. Diese Protokolldateien werden entfernt, sobald die Override-Ziele erledigt sind.

Im Kompatibilitätsmodus 9 oder älter wird jeder Debhelper-Befehl in debian/package.debhelper.log aufgezeichnet, wenn er erfolgreich ausgeführt wurde. (Was durch dh_clean gelöscht wird.) Daher kann dh sagen, welche Befehle bereits für welche Pakete ausgeführt wurden und die erneute Ausführung dieser Befehle überspringen.

Jedes Mal, wenn dh (im Kompatibilitätsmodus 9 oder älter) ausgeführt wird, geht es das Protokoll durch, um festzustellen, welcher Befehl in der angegebenen Sequenz zuletzt ausgeführt wurde. Es fährt dann mit dem nächsten Befehl fort.

Eine Sequenz kann außerdem abhänge Ziele in debian/rules ausführen. Die Sequenz »binary« führt zum Beispiel das Ziel »install« aus.

dh benutzt die Umgebungsvariable DH_INTERNAL_OPTIONS, um Informationen an die Debhelper-Befehle durchzureichen, die innerhalb der Ziele ausgeführt werden. Der Inhalt (und die tatsächliche Existenz) dieser Umgebungsvariable ist, wie der Name schon andeutet, Gegenstand dauernder Änderungen.

Befehle in den Sequenzen build-indep, install-indep und binary-indep werden an die Option -i übergeben, um sicherzustellen, dass sie nur auf architekturunabhängigen Paketen funktionieren. Befehle in den Sequenzen build-arch, install-arch und binary-arch werden an die Option -a übergeben, um sicherzustellen, dass sie nur auf architekturabhängigen Paketen funktionieren.

SIEHE AUCH¶

debhelper(7)

Dieses Programm ist Teil von Debhelper.

ÜBERSETZUNG¶

Diese Übersetzung wurde mit dem Werkzeug po4a <http://po4a.alioth.debian.org/> durch Chris Leick c.leick@vollbio.de und das deutsche Debian-Übersetzer-Team im Dezember 2011 erstellt.

Bitte melden Sie alle Fehler in der Übersetzung an debian-l10n-german@lists.debian.org oder als Fehlerbericht an das Paket debhelper.

Sie können mit dem folgenden Befehl das englische Original anzeigen man -L en Abschnitt Handbuchseite

AUTOR¶

Joey Hess <joeyh@debian.org>