Provided by: debhelper_13.6ubuntu1_all 
NOM
dh - Automate de commandes debhelper
SYNOPSIS
dh suite [--with rajout[,rajout ...]] [--list] [options_de_debhelper]
DESCRIPTION
dh exécute une suite de commandes debhelper. Les suites acceptées correspondent aux blocs d'un fichier
debian/rules : build-arch, build-indep, build, clean, install-indep, install-arch, install, binary-arch,
binary-indep et binary.
CIBLES DE RÉÉCRITURE ET D'ACCROCHE
Un fichier debian/rules utilisant dh peut réécrire la commande exécutée à n'importe quelle étape d'une
séquence, en définissant une cible de réécriture. Il est possible d'injecter une commande avant ou après
une étape sans affecter l'étape elle-même.
Injection de commandes avant ou après une étape
Note : Cette fonctionnalité requiert debhelper 12.8 ou plus et le paquet doit utiliser le mode de
compatibilité 10 ou plus.
Pour injecter des commandes avant dh_command, ajoutez une cible nommée execute_before_dh_command aux
fichiers de règles. De la même manière, si vous voulez injecter des commandes après dh_command, ajoutez
la cible execute_after_dh_command. Les deux cibles peuvent être utilisées pour la même dh_command, et
même si la commande est réécrite (comme décrit plus loin dans "Réécriture d'une commande").
Quand ces cibles sont définies, dh appellera les cibles respectivement avant ou après qu'il invoque
dh_command (ou sa cible réécrite).
Réécriture d'une commande
Pour réécrire la commande dh_commande, ajoutez une cible appelée override_dh_commande au fichier rules.
dh exécutera ce bloc au lieu d'exécuter dh_commande, comme il l'aurait fait sinon. La commande exécutée
peut être la même commande avec des options supplémentaires ou une commande entièrement différente.
Consultez les exemples ci-dessous.
Cibles de réécriture et d'accroche dépendantes ou indépendantes de l'architecture
The override and hook targets can also be defined to run only when building architecture dependent or
architecture independent packages. Use targets with names like override_dh_command-arch and
execute_after_dh_command-indep.
Cette fonctionnalité est disponible depuis debhelper 8.9.7 (pour les cibles de réécriture) et 12.8 pour
les cibles d'accroche.
Cibles complètement vides
Comme optimisation particulière, dh ignorera une cible si elle est complètement vide. C'est surtout utile
pour les cibles réécrites où la commande sera simplement ignorée sans la charge de l'invocation d'une
cible factice.
Notez que la cible doit être complètement vide pour que cela fonctionne :
# Ignorer dh_toto – la bonne façon optimisée
# Mettre ici une raison pour ignorer dh_toto
override_dh_toto:
# Ignorer dh_titi – la façon lente
override_dh_titi:
# Mettre ici une raison pour ignorer dh_titi
# (ces commentaires font qu'une cible factice est exécutée)
La vérification des cibles est récupérée par dh
Si vous voulez confirmer que dh a vu une cible de réécriture ou d'accroche, vous pouvez utiliser la
commande suivante comme exemple :
$ dh binary --no-act | grep dh_install | head -n5
dh_installdirs
dh_install
debian/rules execute_after_dh_install
dh_installdocs
dh_installchangelogs
Le debian/rules execute_after_dh_install dans la sortie signale que dh a enregistré une cible
execute_after_dh_install et devrait l'exécuter immédiatement après dh_install(1).
Notez que les "Cibles complètement vides" seront omises dans la liste ci-dessus. Cela rend un peu plus
difficile le repérage lors de la recherche de l'omission d'un nom de commande. Mais autrement, le
principe reste le même.
Mises en garde sur les cibles d'accroche et les conditions de makefile
Si vous choisissez d'envelopper une cible d'accroche dans des conditions de makefile, soyez conscient que
dh calcule toutes les cibles d'accroche à l'avance et met en cache le résultat pour cette exécution. En
outre, les conditions seront de nouveau invoquées quand dh appelle la cible d'accroche plus tard et
supposera que la réponse n'a pas changé.
L'analyse et la mise en cache se produit souvent avant que dh ne sache s'il va construire des paquets
arch:any (-a) ou/et arch:all (-i) ce qui peut produire des résultats déconcertants – particulièrement si
dh_listpackages(1) fait partie des conditions.
La majorité des problèmes peut être évitée en rendant la cible d'accroche inconditionnelle et ensuite en
mettant le « corps » partiellement ou complètement conditionnel. Par exemple :
# SIMPLE : ce qui arrive est bien défini. La cible d'accroche
# est toujours prise en compte. La partie « maybe run this » est
# conditionnelle mais dh_toto est définitivement oublié.
#
# S<Note :> La condition est évaluée « deux fois » où elle influence
# ce qui arrive. Une fois quand dh vérifie quelles cibles
# d'accroche existent et une fois quand la cible d'accroche
# override_dh_toto est exécutée. Si *une* fois, la sortie est
# I<faux>, « maybe run this » est ignoré.
override_dh_toto:
ifneq (...)
maybe run this
endif
# SIMPLE : cela est aussi bien défini. La cible d'accroche est
# toujours exécutée et dh_titi est ignoré. La partie « may be
# run this » est conditionnelle comme on pourrait s'y attendre.
#
# Note : La condition est encore évaluée plusieurs fois (dans
# différent processus chaque fois). Néanmoins, seule l'évaluation
# qui survient quand la cible d'accroche est exécutée influence ce
# qui arrive.
override_dh_titi:
: # Commande factice pour toujours forcer l'exécution de la cible
ifneq (...)
maybe run this
endif
# COMPLIQUÉ : Ce cas peut ne pas être trivial et présenter des
# difficultés. À utiliser à vos risques et périls si dh_listpackages
# est dans la condition.
#
# Ici, soit dh_truc est exécuté normalement OU « maybe run this »
# est exécuté à sa place.
#
# Cela devient encore plus compliqué à résoudre si dh a besoin d'itérer
# dans debian/rules parce qu'il y a une cible normale « explicite »
# (par exemple une cible « build-arch: » séparée de « %: »).
ifneq (...)
override_dh_truc:
maybe run this
endif
Ces recettes sont aussi pertinentes pour des cibles de dépendance conditionnelles qui sont souvent
illustrées par une variante de l'exemple suivant :
COND_TASKS =
ifneq (...)
COND_TASKS += maybe-run-this
endif
...
maybe-run-this:
...
# SIMPLE : ce qui arrive est bien défini. Soit les
# $(COND_TASKS) sont ignorées soit elles sont exécutées.
#
# Note : La condition est évaluée « deux fois » où elle influence
# ce qui arrive. Une fois quand dh vérifie quelles cibles
# d'accroche existent et une fois quand la cible d'accroche
# override_dh_toto est exécutée. Si *une* fois, la sortie est
# # I<faux>, $(COND_TASKS) sont ignorées.
override_dh_toto: $(COND_TASKS)
# SIMPLE : ceci est aussi bien défini. La cible d'accroche est
# toujours exécutée et dh_titi est ignoré. La partie $(COND_TASKS)
# est conditionnelle comme on pourrait s'y attendre.
#
# Note : La condition est encore évaluée plusieurs fois (dans
# différent processus chaque fois). Néanmoins, seule l'évaluation
# qui survient quand la cible d'accroche est exécutée influence ce
# qui arrive.
override_dh_titi: $(COND_TASKS)
: # Commande factice pour toujours forcer l'exécution de la cible
# COMPLIQUÉ : ce cas peut ne pas être trivial et présenter des
# difficultés. À utiliser à vos risques et périls si dh_listpackages
# est dans la condition.
#
ifneq (...)
override_dh_truc: $(COND_TASKS)
endif
En cas de doute, choisissez le cas SIMPLE qui correspond à vos besoins parmi les exemples ci-dessus.
OPTIONS
--with rajout[,rajout ...]
Ajoute les commandes debhelper indiquées par les rajouts au bon endroit dans la séquence exécutée.
Cette option peut être présente plusieurs fois ou bien plusieurs rajouts peuvent être indiqués en les
séparant par des virgules. Cela est utile lorsqu'un paquet tiers fournit des commandes debhelper.
Consulter le fichier PROGRAMMING pour obtenir des informations à propos de l'interface de ces
rajouts.
Une relation Build-Depends sur le paquet dh-sequence-rajout implique --with rajout. Cela évite un
--with explicite dans debian/rules qui dupliquerait ce qui est écrit dans les dépendances de
construction dans debian/control. La relation peut (depuis 12.5) être rendue optionnelle au moyen de
build-profiles par exemple. Cela permet de désactiver facilement un rajout qui est utile uniquement
avec certains profils (par exemple pour faciliter l'amorçage).
Depuis debhelper 12.5, les rajouts peuvent aussi être activés en mode « indep seulement » (au moyen
de Build-Depends-Indep) ou en mode « arch seulement » (au moyen de Build-Depends-Arch). Ces rajouts
sont seulement actifs dans la séquence particulière (par exemple binary-indep) qui simplifie la
gestion des dépendances pour les constructions croisées.
Veuillez noter que les rajouts activés avec Build-Depends-Indep ou Build-Depends-Arch sont soumis à
des contraintes supplémentaires pour s'assurer que le résultat est déterministe même quand le rajout
n'est pas disponible (par exemple pendant le nettoyage). Cela implique que certains rajouts sont
incompatibles avec ces restrictions et ne peuvent être utilisés qu'avec Build-Depends (ou
manuellement avec debian/rules). Actuellement, ces rajouts peuvent seulement ajouter des commandes à
des séquences.
--without rajout
L'inverse de --with, désactive le rajout donné. Cette option peut être présente plusieurs fois ou
bien plusieurs rajouts peuvent être indiqués en les séparant par des virgules.
--list, -l
Liste tous les rajouts disponibles.
Lorsqu'il est appelé uniquement avec cette option, dh peut être invoqué depuis n'importe quel
répertoire (c'est-à-dire qu'il ne nécessite l'accès à aucun fichier d'un paquet source).
--no-act
Affiche les commandes qui seraient utilisées pour une séquence donnée, sans les exécuter.
Veuillez remarquer que dh élimine les commandes en cours lorsqu'il sait qu'elles ne font rien. Avec
l'option --no-act, la liste complète des commandes dans une séquence est affichée.
Les autres options fournies à dh sont passées en paramètre à chaque commande exécutée. Cela est utile
tant pour les options comme -v, -X ou -N que pour des options plus spécialisées.
EXEMPLES
Pour voir quelles commandes sont présentes dans une séquence, sans rien faire :
dh binary-arch --no-act
C'est un fichier rules très simple, pour les paquets où les séquences de commandes par défaut
fonctionnent sans aucune option particulière.
#!/usr/bin/make -f
%:
dh $@
Il est fréquent de vouloir passer une option à une commande debhelper. Le moyen le plus simple de le
faire consiste à ajouter une cible pour surcharger la commande.
#!/usr/bin/make -f
%:
dh $@
override_dh_strip:
dh_strip -Xtoto
override_dh_auto_configure:
dh_auto_configure -- --with-toto --disable-titi
Parfois les automatismes de dh_auto_configure(1) et de dh_auto_build(1) n'arrivent pas à deviner ce qu'il
faut faire pour certains paquets tordus. Voici comment indiquer vos propres commandes plutôt que de
laisser faire l'automatisme.
#!/usr/bin/make -f
%:
dh $@
override_dh_auto_configure:
./mondoconfig
override_dh_auto_build:
make universe-explode-in-delight
Un autre cas habituel consiste à vouloir faire quelque chose avant ou après l'exécution d'une certaine
commande debhelper.
#!/usr/bin/make -f
%:
dh $@
# L'exemple suppose debhelper/12.8 et compat 10+
execute_after_dh_fixperms:
chmod 4755 debian/truc/usr/bin/truc
Si vous avez une version de debhelper plus ancienne ou un niveau de compatibilité inférieur, l'exemple
ci-dessus devrait être écrit de cette manière.
#!/usr/bin/make -f
%:
dh $@
# Versions anciennes de debhelper ou avec un niveau
# de compatibilité 9 ou moins.
override_dh_fixperms:
dh_fixperms
chmod 4755 debian/truc/usr/bin/truc
Les outils Python ne sont pas exécutés par défaut par dh, à cause des modifications incessantes dans ce
domaine. Voici comment utiliser dh_python2.
#!/usr/bin/make -f
%:
dh $@ --with python2
Voici comment forcer l'utilisation du processus de construction Module::Build, propre à Perl, qui
pourrait être indispensable si debhelper détectait, à tort, que le paquet utilise MakeMaker.
#!/usr/bin/make -f
%:
dh --buildsystem=perl_build $@
Voici un exemple de remplacement où les commandes dh_auto_* cherchent la source du paquet car elle est
située dans un sous-répertoire.
#!/usr/bin/make -f
%:
dh $@ --sourcedirectory=src
Voici un exemple d'utilisation des commandes dh_auto_* pour réaliser la construction dans un
sous-répertoire qui sera ensuite supprimé lors du clean :
#!/usr/bin/make -f
%:
dh $@ --builddirectory=build
Si le paquet peut être construit en parallèle, veuillez utiliser le niveau de compatibilité 10 ou passer
l'option --parallel à dh. Dans ce cas dpkg-buildpackage -j fonctionnera.
#!/usr/bin/make -f
%:
dh $@ --parallel
Si votre paquet ne peut être construit de manière fiable en utilisant plusieurs processus légers,
veuillez passer l'option --no-parallel à dh (ou la commande adéquate dh_auto_*) :
#!/usr/bin/make -f
%:
dh $@ --no-parallel
Voici un moyen d'empêcher dh d'exécuter plusieurs commandes, en définissant des blocs de substitution
vides pour chaque commande que vous ne voulez pas lancer.
#!/usr/bin/make -f
%:
dh $@
# Commandes que l'on ne veut pas S<exécuter :>
override_dh_auto_test override_dh_compress override_dh_fixperms:
Un long processus de construction pour un paquet de documentation à part peut être séparé en utilisant
des réécritures pour les paquets indépendants de l'architecture. Elles seront ignorées lors de
l'exécution des suites build-arch et binary-arch.
#!/usr/bin/make -f
%:
dh $@
override_dh_auto_build-indep:
$(MAKE) -C docs
# Aucun test nécessaire pour la documentation
override_dh_auto_test-indep:
override_dh_auto_install-indep:
$(MAKE) -C docs install
En plus de l'exemple précédent, il peut être nécessaire de modifier les droits d'un fichier, mais
seulement lors de la construction du paquet dépendant de l'architecture, puisqu'il n'est pas présent lors
de la construction de la documentation toute seule.
# L'exemple suppose debhelper/12.8 et compat 10+
execute_after_dh_fixperms-arch:
chmod 4755 debian/truc/usr/bin/truc
DEBHELPER PROVIDED DH ADDONS
The primary purpose of dh addons is to provide easy integration with third-party provided features for
debhelper. However, debhelper itself also provide a few sequences that can be useful in some cases. These
are documented in this list:
build-stamp
A special addon for controlling whether dh (in compat 10 or later) will create stamp files to tell
whether the build target has been run successfully. See "INTERNALS" for more details.
This addon is active by default but can disabled by using dh $@ --without build-stamp
dwz (obsolete)
Adds dh_dwz(1) to the sequence in compat level 11 or below. Obsolete in compat 12 or later.
elf-tools
This addon adds tools related to ELF files to the sequence such as dh_strip(1) and dh_shlibdeps(1)
This addon is conditionally active by default for architecture specific packages - that is, it is
skipped for arch:all packages. In the special case where you need these tools to work on arch:all
packages, you can use --with elf-tools to activate it unconditionally.
installinitramfs (obsolete)
Adds dh_installinitramfs(1) to the sequence in compat level 11 or below. Obsolete in compat 12 or
later.
root-sequence (internal)
This is reserved for internal usage.
single-binary
A special-purpose addon that makes debhelper run in "single binary" mode.
When active, it will pass --destdir=debian/package/ to dh_auto_install(1). This makes every file
"installed" by the upstream build system part of the (only) binary package by default without having
to use other helpers such as dh_install(1).
The addon will refuse to activate when the source package lists 2 or more binary packages in
debian/control as a precaution.
Before compat 15. this behaviour was the default when there was only a single binary package listed
in debian/control. In compat 15 and later, this addon must explicitly be activated for this feature
to work.
The rationale for requiring this as an explicit choice is that if it is implicit then debhelper will
silently change behaviour on adding a new binary package. This has caused many RC bugs when
maintainers renamed a binary and added transitional packages with the intention of supporting
seamless upgrades. The result would often be two empty binary packages that were uploaded to archive
with users frustrated as their "upgrade" removed their programs.
systemd (obsolete)
Adds dh_systemd_enable(1) and dh_systemd_start(1) to the sequence in compat level 10 or below.
Obsolete in compat 11 or later.
FONCTIONNEMENT INTERNE
Si vous êtes curieux de connaître le fonctionnement interne de dh, voici ce qu'il y a sous le capot.
Dans les niveaux de compatibilité 10 (ou supérieurs), dh crée un fichier debian/debhelper-build-stamp
après la construction pour ne pas la refaire. Il est possible d'éviter la création de ce fichier en
passant l'argument --without=build-stamp à dh. Cela rend le comportement des construction « no clean »
plus cohérent avec l'usage courant au détriment de possiblement effectuer la construction et le test deux
fois (la seconde en tant que « root » ou avec fakeroot(1)).
À l'intérieur d'une cible de réécriture, les commandes dh_* écrivent dans un journal
debian/paquet.debhelper.log pour savoir quelle commande a été exécutée pour quel paquet. Ces fichiers
journaux seront supprimés une fois la cible de réécriture terminée.
Dans les niveaux de compatibilité 9 et précédents, chaque commande debhelper, qui s'accomplit
correctement, est journalisée dans debian/package.debhelper.log (que dh_clean supprimera). Ainsi dh peut
déterminer quelles commandes ont déjà été exécutées et pour quels paquets. De cette manière il pourra
passer outre l'exécution de ces commandes ultérieurement.
Chaque fois que dh est exécuté (en v9 ou précédente), il examine le journal et recherche la dernière
commande exécutée dans la séquence indiquée. Puis il exécute la commande suivante dans cette séquence.
Une suite peut aussi exécuter des cibles dépendantes dans debian/rules. Par exemple, la suite « binary »
exécute la cible « install ».
dh utilise la variable d'environnement DH_INTERNAL_OPTIONS pour transmettre des informations aux
commandes debhelper exécutées au sein des blocs surchargés. Le contenu (et l'existence même) de cette
variable d'environnement, comme son nom l'indique, est sujet à des modifications permanentes.
Les commandes des séquences build-indep, install-indep et binary-indep sont appelées avec l'option -i
pour être certain qu'elles ne s'accompliront que sur des paquets indépendants de l'architecture.
Symétriquement les commandes des séquences build-arch, install-arch et binary-arch sont appelées avec
l'option -a pour être certain qu'elles ne s'accompliront que sur des paquets dépendants de
l'architecture.
VOIR AUSSI
debhelper(7)
Ce programme fait partie de debhelper.
AUTEUR
Joey Hess <joeyh@debian.org>
TRADUCTION
Cette traduction est maintenue à l'aide de l'outil po4a <URL:http://po4a.alioth.debian.org/> par l'équipe
francophone de traduction de Debian.
Veuillez signaler toute erreur de traduction en écrivant à <debian-l10n-french@lists.debian.org> ou par
un rapport de bogue sur le paquet debhelper.
Vous pouvez toujours avoir accès à la version anglaise de ce document en utilisant la commande « man -L C
<section> <page_de_man> ».
13.6ubuntu1 2022-02-07 DH(1)