Provided by: debhelper_13.18ubuntu2.1_all bug

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
       Les cibles de réécriture et d'accroche peuvent aussi être définies pour n'être exécutées
       que lors de la construction de paquets dépendants ou indépendants de l'architecture.
       Utilisez des cibles avec des noms comme override_dh_commande-arch et
       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 et ne
       dépend d'aucune autre cible. 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
       Depuis debhelper 13.10, vous pouvez utiliser dh_assistant(1) pour voir quelles cibles
       réécrites ou quelles cibles d'accroche seront vues par dh. Voici un exemple d'exécution de
       dh_assistant(1) avec sa sortie :

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

       commands-not-in-path est utile pour repérer les erreurs dans les noms de cible d'accroche.
       Une valeur non vide implique qu'une ou plusieurs cibles d'accroche sont liées à une
       commande qui n'est pas installée ou qu'aucune commande de ce nom n'existe. Il est
       généralement préférable de faire une double vérification de cela.

       En plus, l'attribut is-empty pour chaque cible d'accroche peut être utilisé pour voir si
       une cible d'accroche déclenche l'optimisation des "Cibles complètement vides".

       Si vous êtes intéressés par d'autres attributs, consultez dh_assistant(1) pour plus de
       détails.

       La vérification des cibles est récupérée par dh (quand debhelper est antérieur à la
       version 13.10)

       Sur les anciennes versions de debhelper, vous devez utiliser dh avec --no-act. 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é.
             #
             # 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 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

RAJOUTS DH FOURNIS PAR DEBHELPER

       L'objectif principal des rajouts de dh est de fournir une intégration aisée des fonctions
       fournies par une partie tierce à debhelper. Néanmoins, debhelper lui-même fournit aussi
       quelques séquences qui peuvent être utiles dans certains cas. Elles sont documentées dans
       la liste suivante :

       build-stamp
           Un rajout particulier pour contrôler si dh (dans compat 10 ou ultérieur) va créer des
           fichiers témoins pour indiquer si la cible de construction a été exécutée avec succès.
           Consultez "FONCTIONNEMENT INTERNE" pour plus de détails.

           Ce rajout est actif par défaut mais peut être désactivé en utilisant dh $@ --without
           build-stamp

       dwz (obsolète)
           Ajoute dh_dwz(1) à la séquence dans le niveau de compatibilité 11 ou inférieur.
           Obsolète dans compat 12 ou ultérieur.

       elf-tools
           Ce rajout ajoute à la séquence des outils liés aux fichiers ELF tels que dh_strip(1)
           et dh_shlibdeps(1)

           Ce rajout est actif de façon conditionnelle par défaut pour les paquets spécifiques à
           une architecture – c'est-à-dire qu'il est ignoré pour les paquets arch:all. Dans le
           cas particulier où vous avez besoin que ces outils fonctionnent sur des paquets
           arch:all, vous pouvez utilisez --with elf-tools pour l'activer de façon
           inconditionnelle.

       installinitramfs (obsolète)
           Ajoute dh_installinitramfs(1) à la séquence dans le niveau de compatibilité 11 ou
           inférieur. Obsolète dans compat 12 ou ultérieur.

       root-sequence (interne)
           Ce rajout est réservé à une utilisation interne.

       single-binary
           Un rajout à usage spécifique qui fait exécuter debhelper en mode « binaire unique ».

           Quand il est actif, il passe --destdir=debian/paquet/ à dh_auto_install(1). Cela fait
           que chaque fichier « installé » par le système de construction amont fait partie du
           paquet binaire (unique) par défaut sans avoir à utiliser d'autres assistants comme
           dh_install(1).

           Le rajout refusera de s'activer par précaution quand le paquet source liste deux
           paquets binaires ou plus dans debian/control.

           Avant compat 15, c'était le comportement par défaut quand il n'y avait qu'un seul
           paquet binaire listé dans debian/control. Dans compat 15 et ultérieurs, ce rajout doit
           être activé de façon explicite pour que cette fonctionnalité soit activée.

           La raison pour requérir cela comme choix explicite est que s'il est implicite,
           debhelper changera silencieusement le comportement lors de l'ajout d'un nouveau paquet
           binaire. Cela a provoqué de nombreux bogues critiques quand les responsables ont
           renommé un binaire et ajouté des paquets de transition dans l'intention de prendre en
           charge des mises à niveau en douceur. Le résultat sera souvent que deux paquets
           binaires vides sont versés dans l'archive et que les utilisateurs sont contrariés
           parce que leurs « mises à niveau » suppriment leurs programmes.

       systemd (obsolète)
           Ajoute dh_systemd_enable(1) et dh_systemd_start(1) à la séquence dans le niveau de
           compatibilité 10 ou inférieur. Obsolète dans compat 11 ou ultérieurs.

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> ».