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.
AUßER KRAFT SETZENDE UND HOOK-ZIELE
Eine debian/rules-Datei, die dh benutzt, kann einen Befehl aus jedem Schritt einer Sequenz, der ausgeführt wird, außer Kraft setzen, indem ein außer Kraft setzendes Ziel definiert wird. Es ist auch möglich, Befehle vor oder nach jedem Schritt einzuspeisen, ohne den Schritt selbst zu beeinflussen.
Befehle vor
oder nach einem Schritt einspeisen
Hinweis: Diese Funktionalität erfordert Debhelper
12.8 oder neuer, zudem muss das Paket
Kompatibilitätsmodus 10 oder neuer nutzen.
Um Befehle vor dh_Befehl einzuspeisen, fügen Sie den Rules-Dateien ein Ziel namens execute_before_dh_Befehl hinzu. Analog fügen Sie, wenn Sie nach dh_Befehl Befehle einspeisen wollen, execute_after_dh_Befehl hinzu. Beide Ziele können für denselben dh_Befehl benutzt werden und das sogar, wenn der Befehl außer Kraft gesetzt wurde (wie nachfolgend in "Einen Befehl außer Kraft setzen" beschrieben).
Wenn diese Ziele definiert sind, wird dh die Ziele vor beziehungsweise nach dem Aufruf von dh_Befehl (oder dessen außer Kraft setzendem Ziel) aufrufen.
Einen Befehl
außer Kraft setzen
Um dh_Befehl außer Kraft zu setzen, fügen
Sie der Datei »rules« ein Ziel mit Namen
override_dh_Befehl hinzu. Wenn es
normalerweise dh_Befehl ausführen würde,
wird dh stattdessen dieses Ziel aufrufen. Das
außer Kraft setzende Ziel kann dann den Befehl mit
zusätzlichen Optionen oder stattdessen ganz andere
Befehle ausführen. Lesen Sie die folgenden
Beispiele.
Architekturabhängige/-unabhängige
außer Kraft setzende und Hook-Ziele
Außer Kraft setzende und Hook-Ziele können
außerdem definiert werden, um nur ausgeführt zu
werden, wenn architekturab- oder -unabhängige Pakete
gebaut werden. Benutzen Sie Ziele mit Namen wie
override_dh_Befehl-arch und
override_dh_Befehl-indep.
Diese Funktionalität ist seit Debhelper 8.9.7 (für außer Kraft setzende Ziele) und 12.8 (für Hook-Ziele) verfügbar.
Komplett
leere Ziele
Als besondere Optimierung wird dh ein Ziel
überspringen, falls es komplett leer ist. Dies ist
für außer Kraft setzende Ziele am
nützlichsten, wobei der Befehl einfach nur
übersprungen wird, ohne den Mehraufwand, ein Scheinziel
aufzurufen.
Beachten Sie, das das Ziel komplett leer sein muss, damit dies funktioniert.
# ü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)
Überprüfung,
dass Ziele von dh aufgenommen werde
Um zu bestätigen, dass dh ein außer Kraft
setzendes oder Hook-Ziel gefunden hat, können Sie
beispielsweise folgenden Befehl verwenden:
$ dh binary --no-act | grep dh_install | head -n5
dh_installdirs
dh_install
debian/rules execute_after_dh_install
dh_installdocs
dh_installchangelogs
Das debian/rules execute_after_dh_install in der Ausgabe zeigt an, dass dh ein execute_after_dh_install-Ziel registrierte und es direkt nach dh_install(1) ausführen würde.
Beachten Sie, dass "Komplett leere Ziele" im oberen Listing weggelassen wurde. Damit wird es etwas schwieriger zu finden, wenn Sie nach dem Weglassen eines Befehlsnamens suchen. Aber andererseits bleibt das Prinzip dasselbe.
Caveats with
hook targets and makefile conditionals
If you choose to wrap a hook target in makefile
conditionals, please be aware that dh computes all
the hook targets a head of time and caches the result for
that run. Furthermore, the conditionals will be invoked
again when dh calls the hook target later and will
assume the answer did not change.
The parsing and caching often happens before dh knows whether it will build arch:any (-a) or/and arch:all (-i) packages, which can produce confusing results - especially when dh_listpackages(1) is part of the conditional.
Most of the problems can be avoided by making the hook target unconditional and then have the "body" be partially or completely conditional. As an example:
# SIMPLE: It is well-defined what happens. The hook target
# is always considered. The "maybe run this" bit is
# conditional but dh_foo is definitely skipped.
#
# Note: The conditional is evaluated "twice" where its
# influences what happens. Once when dh check which hook
# targets exist and once when the override_dh_foo hook target
# is run. If *either* times return false, "maybe run this"
# is skipped.
override_dh_foo:
ifneq (...)
maybe run this
endif
# SIMPLE: This is also well-defined. The hook target is always
# run and dh_bar is skipped. The "maybe run this" bit is
# conditional as one might expect.
#
# Note: The conditional is still evaluated multiple times (in
# different process each time). However, only the evaluation
# that happens when the hook target is run influences what
# happens.
override_dh_bar:
: # Dummy command to force the target to always be run
ifneq (...)
maybe run this
endif
# COMPLICATED: This case can be non-trivial and have sharp edges.
# Use at your own peril if dh_listpackages in the conditional.
#
# Here, either dh_baz is run normally OR "maybe run this" is run
# instead.
#
# And it gets even more complicated to reason about if dh needs to
# recurse into debian/rules because you have an "explicit"
# standard target (e.g. a "build-arch:" target separate from "%:").
ifneq (...)
override_dh_baz:
maybe run this
endif
These recipes are also relevant for conditional dependency targets, which are often seen in a variant of the following example:
COND_TASKS =
ifneq (...)
COND_TASKS += maybe-run-this
endif
...
maybe-run-this:
...
# SIMPLE: It is well-defined what happens. Either the
# $(COND_TASKS) are skipped or run.
#
# Note: The conditional is evaluated "twice" where its
# influences what happens. Once when dh check which hook
# targets exist and once when the override_dh_foo hook target
# is run. If *either* times return false, $(COND_TASKS)
# is skipped.
override_dh_foo: $(COND_TASKS)
# SIMPLE: This is also well-defined. The hook target is always
# run and dh_bar is skipped. The $(COND_TASKS) bit is
# conditional as one might expect.
#
# Note: The conditional is still evaluated multiple times (in
# different process each time). However, only the evaluation
# that happens when the hook target is run influences what
# happens.
override_dh_bar: $(COND_TASKS)
: # Dummy command to force the target to always be run
# COMPLICATED: This case can be non-trivial and have sharp edges.
# Use at your own peril if dh_listpackages in the conditional.
#
ifneq (...)
override_dh_baz: $(COND_TASKS)
endif
When in doubt, pick the relevant SIMPLE case in the examples above that match your need.
OPTIONEN
--with Add-on[,Add-on …]
fügt die Debhelper-Befehle, die durch das gegebene Add-on angegeben wurden, an geeigneten Stellen der Befehlssequenz, die ausgeführt wird, 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-Add-on-Schnittstelle finden Sie in der Datei PROGRAMMING .
Eine Build-Depends-Beziehung zum Paket dh-sequence-Erweiterung setzt ein --with Erweiterung voraus. Dies vermeidet, dass ein explizites --with in debian/rules benötigt wird, das nur vervielfältigt, 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 mit einem bestimmten Profil nützlich ist (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, Gegenstand zusätzlicher Beschränkungen sind, um sicherzustellen, dass das Ergebnis sogar dann deterministisch ist, wenn die Erweiterung nicht verfügbar ist (z.B. während einer Reinigung). 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 Add-on
das Gegenteil von --with, deaktiviert die Benutzung des angegebenen Add-ons. Diese Option kann mehrfach wiederholt werden oder es können mehrere Add-ons zum Deaktivieren durch Kommas getrennt aufgelistet werden.
--list, -l
listet alle verfügbaren Add-ons 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. Dies kann benutzt werden, um eine Option wie -v, -X oder -N sowie spezialisiertere Optionen zu setzen.
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 einfach »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 außer Kraft setzendes 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 können die automatisierten dh_auto_configure(1) und dh_auto_build(1) nicht abschätzen, was für ein merkwürdiges Paket zu tun ist. Hier nun, wie das Ausführen vermieden und stattdessen Ihre eigenen Befehle ausgeführt werden.
#!/usr/bin/make -f
%:
dh $@
override_dh_auto_configure:
./mondoconfig
override_dh_auto_build:
make universe-explode-in-delight
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. Hier wird gezeigt, wie dh_python2 benutzt wird.
#!/usr/bin/make -f
%:
dh $@ --with python2
Hier wird gezeigt, wie die Benutzung von Perls Bausystem Module::Build erzwungen wird, was nötig sein kann, falls Debhelper fälschlicherweise entdeckt, 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 mit clean 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, außer Kraft setzende 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ängigem außer Kraft setzen abgetrennt werden. Dies wird ü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 Dateimodusbits einer Datei ändern, aber nur, wenn Sie ein architekturabhängiges Paket bauen, da es 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
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 vermeiden, 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 außer Kraft setzenden 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 außer Kraft setzenden 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.
Jedesmal, wenn dh (im Kompatibilitätsmodus 9 oder älter) ausgeführt wird, untersucht es das Protokoll und findet den zuletzt protokollierten Befehl in der angegebenen Sequenz.
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
Dieses Programm ist Teil von Debhelper.
ÜBERSETZUNG
Diese Übersetzung wurde mit dem Werkzeug po4a <http://po4a.alioth.debian.org/>; durch Chris Leick c.leick [AT] vollbio.de und das deutsche Debian-Übersetzer-Team im Dezember 2011 erstellt.
Bitte melden Sie alle Fehler in der Übersetzung an debian-l10n-german [AT] lists.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 [AT] debian.org>