Chapitre 4. Fichiers nécessaires dans le répertoire `debian`

# Chapitre 4. Fichiers nécessaires dans le répertoire `debian`

La réécriture de ce tutoriel avec des contenus à jour et des exemples pratiques supplémentaires est disponible sur Guide du responsable Debian. Veuillez utiliser ce nouveau tutoriel comme document principal.

Un nouveau sous-répertoire se trouve dans le répertoire des sources du programme, nommé `debian`. Certains fichiers de ce répertoire sont à modifier pour personnaliser le comportement du paquet. Les plus importants sont `control`, `changelog`, `copyright` et `rules`, ils sont nécessaires pour tous les paquets. [27]

## 4.1. `control`

Ce fichier contient plusieurs valeurs utilisées par dpkg, dselect, apt-get, apt-cache, aptitude et d'autres outils de gestion de paquets pour gérer le paquet. Cela est défini par la Charte Debian, 5 « Fichiers de contrôle et leurs champs ».

Le fichier `control` créé par dh_make ressemble à :

     1 Source: gentoo
     2 Section: unknown
     3 Priority: extra
     4 Maintainer: Prénom Nom <votre.adresse.mail@example.org>
     5 Build-Depends: debhelper (>=10)
     6 Standards-Version: 3.9.4
     7 Homepage: <URL amont, si pertinente>
     8
     9 Package: gentoo
    10 Architecture: any
    11 Depends: ${shlibs:Depends}, ${misc:Depends}
    12 Description: <description courte de 60 caractères au maximum>
    13  <description longue, indentée par des espaces>

(Les numéros de ligne ont été ajoutés.)

Les lignes 1 à 7 sont les informations de contrôle pour le paquet source. Les lignes 9 à 13 sont les informations de contrôle pour le paquet binaire.

La ligne 1 est le nom du paquet source.

La ligne 2 est la section de la distribution à laquelle ce paquet appartient.

Comme vous avez pu le constater, l'archive Debian est divisée en plusieurs parties : `main` (logiciels libres), `non-free` (logiciels non libres), et `contrib` (logiciels libres qui dépendent de logiciels non libres). Chacune d'entre elles est divisée en sections qui classent les paquets en catégories grossières. Entre autres existent `admin` pour les programmes destinés aux administrateurs, `devel` pour les outils de programmation, `doc` pour la documentation, `libs` pour les bibliothèques, `mail` pour les lecteurs et les démons de courrier électronique, `net` pour les applications et démons de réseau, `x11` pour les programmes X11 qui ne conviennent pas mieux ailleurs, et bien d'autres. [28]

Changez la section en x11 (le préfixe `main/` est implicite, et peut donc être omis).

La ligne 3 décrit l'importance pour l'utilisateur d'installer ce paquet : [29]

- la priorité `optional` fonctionne habituellement pour les nouveaux paquets qui ne sont pas en conflit avec d'autres se réclamant de priorité `required`, `important` ou `standard`.

Les sections et les priorités sont utilisées par des interfaces comme aptitude quand elles trient les paquets et sélectionnent les valeurs par défaut. Quand vous enverrez le paquet dans Debian, les valeurs de ces deux champs peuvent être modifiées par les responsables des archives, auquel cas vous serez notifié par courrier.

Comme c'est un paquet de priorité normale et qu'il n'entre pas en conflit avec quoi que ce soit, il suffit de laisser la priorité à `optional`.

La ligne 4 est le nom et l'adresse électronique du responsable. Assurez-vous que ce champ contient un en-tête `To` valable pour un courrier électronique, car après l'envoi du paquet, le système de suivi des bogues l'utilisera pour vous distribuer les courriers relatifs aux bogues. Évitez d'utiliser les virgules, esperluettes (`&`) ou parenthèses.

La ligne 5 contient la liste des paquets nécessaires pour construire le paquet dans le champ `Build-Depends`. Le champ `Build-Depends-Indep` peut-être ajouté dans une ligne supplémentaire. [30] Certains paquets comme `gcc` ou `make` sont implicites, puisqu'ils dépendent de `build-essential`. Si d'autres outils sont nécessaires pour construire le paquet, vous devez les ajouter à ces champs. Les multiples éléments sont séparés par des virgules ; lisez ci-après les explications sur les dépendances entre paquets binaires pour mieux comprendre la syntaxe de ces lignes :

- pour tous les paquets empaquetés avec la commande dh dans le fichier `debian/rules`, `debhelper (>=9)` doit faire partie du champ `Build-Depends` pour être conforme à la Charte Debian au sujet de la cible `clean` ;

- les paquets source de paquets binaires avec `Architecture: any` sont reconstruits par les empaqueteurs automatiques (« autobuilder »). Puisque la procédure des serveurs d'empaquetage automatique installe seulement les paquets indiqués dans le champ `Build-Depends` avant d'exécuter `debian/rules build` (consultez Section 6.2, « Serveurs d'empaquetage automatique (« autobuilder ») »), ce champ `Build-Depends` doit indiquer pratiquement tous les paquets nécessaires et `Build-Depends-Indep` est rarement utilisé ;

- pour les paquets source de paquets binaires dont tous sont `Architecture: all`, le champ `Build-Depends-Indep` peut indiquer tous les paquets nécessaires à moins qu'ils ne soient déjà indiqués dans le champ `Build-Depends` pour être conforme à la Charte Debian au sujet de la cible `clean`.

En cas de doute, utilisez le champ `Build-Depends` pour être sûr. [31]

Pour déterminer les paquets nécessaires à la construction, exécutez la commande :

    $ dpkg-depcheck -d ./configure

Pour déterminer manuellement les dépendances de construction exactes pour `/usr/bin/toto`, exécutez :

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

et pour chaque bibliothèque affichée, par exemple libtoto.so.6, exécutez :

    $ dpkg -S libtoto.so.6

Ajoutez ensuite simplement la version `-dev` de chaque paquet dans le champ `Build-Depends`. Si vous utilisez ldd à cet effet, des dépendances de bibliothèque indirectes seront indiquées, introduisant un problème de dépendances de construction excessives.

`gentoo` a aussi besoin de `xlibs-dev`, `libgtk1.2-dev` et `libgl1.2-dev` pour être construit, ils doivent donc être ajoutés à côté de `debhelper`.

La ligne 6 est la version de la Charte Debian que ce paquet respecte, celle que vous lisez quand vous créez le paquet.

En ligne 7 vous pouvez indiquer l'URL de la page d'accueil du programme amont.

La ligne 9 est le nom du paquet binaire. C'est d'ordinaire le même que le nom du paquet source, mais ce n'est pas nécessairement le cas.

La ligne 10 décrit les architectures pour lesquelles le paquet binaire peut être compilé. Cette valeur est en général un des suivantes en fonction du type de paquet binaire : [32]

- `Architecture: any`

  - le paquet binaire créé dépend de l'architecture, en général dans un langage compilé ;

- `Architecture: all`

  - le paquet binaire créé est indépendant de l'architecture, en général du texte, des images ou des scripts en langage interprété.

La ligne 10 est laissée telle quelle car c'est écrit en C. dpkg-gencontrol(1) indiquera la valeur d'architecture appropriée pour chaque machine sur laquelle ce paquet source sera compilé.

Si le paquet est indépendant d'une architecture (par exemple, un script shell ou Perl, ou un document), changez ce paramètre en `all`, et lisez plus loin en Section 4.4, « `rules` » comment utiliser la règle `binary-indep` au lieu de `binary-arch` pour construire le paquet.

La ligne 11 montre une des caractéristiques les plus puissantes du système de paquet Debian. Les paquets peuvent être liés entre eux de plusieurs façons. Hormis `Depends`, les autres champs décrivant ces relations sont `Recommends`, `Suggests`, `Pre-Depends`, `Breaks`, `Conflicts`, `Provides` et `Replaces`.

Les outils de gestion de paquets se comportent d'ordinaire de la même manière quand ils gèrent ces relations ; sinon, ce sera précisé (consultez dpkg(8), dselect(8), apt(8), aptitude(1), etc.)

Voici une description simplifiée des relations entre paquets : [33]

- `Depends`

  le paquet ne sera pas installé sans que les paquets dont il dépend ne soient installés. Utilisez-le si le programme ne s'exécute absolument pas (ou cause des dégâts sérieux) si un paquet particulier n'est pas présent ;

- `Recommends`

  à utiliser pour les paquets qui ne sont pas vraiment indispensables mais qui sont généralement utilisés avec le programme. Lorsqu'un utilisateur installe le paquet, toutes les interfaces devraient proposer d'installer les paquets recommandés. aptitude et apt-get installent par défaut les paquets recommandés avec le paquet (mais l'utilisateur peut désactiver ce comportement). dpkg ignorera ce champ ;

- `Suggests`

  à utiliser pour les paquets qui fonctionnent bien avec le programme mais qui ne sont pas du tout indispensables. Lorsqu'un utilisateur installe le programme, il ne lui sera probablement pas proposé d'installer les paquets suggérés. aptitude peut être configuré pour installer les paquets suggérés avec le paquet mais ce n'est pas le comportement par défaut. dpkg et apt-get ignoreront ce champ ;

- `Pre-Depends`

  cela est plus fort que `Depends`. Le paquet ne sera pas installé avant que les paquets dont il pré-dépend ne soient installés et correctement configurés. Utilisez-le très rarement et seulement après en avoir discuté sur la liste de discussion debian-devel@lists.debian.org. Autrement dit : ne l'utilisez pas du tout ; :-)

- `Conflicts`

  le paquet ne sera pas installé tant que les paquets avec lesquels il est en conflit n'aient été retirés. À utiliser si le programme ne peut absolument pas fonctionner ou s'il cause d'énormes problèmes quand un paquet particulier est présent ;

- `Breaks`

  les paquets énumérés seront cassés une fois que le paquet ait été installé. En général, une entrée `Breaks` indique qu'elle s'applique aux versions antérieures à une certaine valeur. La résolution de conflit se fait en utilisant des gestionnaires de paquets de haut niveau pour généralement mettre à niveau les paquets énumérés ;

- `Provides`

  quand il y a plusieurs alternatives pour certains types de paquets, des noms virtuels ont été définis. La liste complète est disponible dans le fichier virtual-package-names-list.txt.gz. À utiliser si le programme fournit une fonction d'un paquet virtuel existant ;

- `Replaces`

  à utiliser quand le programme remplace des fichiers d'un autre paquet, ou remplace complètement un autre paquet (utilisé en conjonction avec `Conflicts`). Les fichiers du paquet nommé seront écrasés par les fichiers de votre paquet.

Tous ces champs ont une syntaxe uniforme. Il s'agit d'une liste de paquets séparés par des virgules. Ces noms de paquets peuvent aussi être une liste d'alternatives, séparées par des barres verticales `|` (symbole tube ou « pipe »).

Le domaine d'application des champs peut être restreint à des versions particulières de chaque paquet nommé. La restriction de chaque paquet particulier est indiquée entre parenthèses après son nom, et devrait contenir une relation dans la liste suivante suivie par une valeur de numéro de version. Les relations autorisées sont `<<`, `<=`, `=`, `>=` et `>>` (respectivement : strictement plus petit, plus petit ou égal, exactement égal, plus grand ou égal et strictement plus grand). Par exemple :

    Depends: toto (>= 1.2), libbidule1 (= 1.3.4)
    Conflicts: machin
    Recommends: libmachin4 (>> 4.0.7)
    Suggests: truc
    Replaces: truc (<< 5), truc-toto (<= 7.6)

La dernière fonctionnalité à connaître est `${shlibs:Depends}`, `${perl:Depends}`, `${misc:Depends}`, etc.

dh_shlibdeps(1) calcule les dépendances à des bibliothèques partagées pour les paquets binaires. Il crée une liste d'exécutables ELF et de bibliothèques partagées trouvées pour chaque paquet binaire. Cette liste est utilisée en remplacement de `${shlibs:Depends}`.

dh_perl(1) calcule les dépendances de Perl. Il crée une liste de dépendances vers `perl` ou `perlapi` pour chaque paquet binaire. Cette liste est utilisée en remplacement de `${perl:Depends}`.

Certaines commandes de `debhelper` peuvent rendre le paquet créé dépendant de paquets supplémentaires. Toutes ces commandes créent une liste de paquets nécessaires pour chaque paquet binaire. Cette liste est utilisée en remplacement de `${misc:Depends}`.

dh_gencontrol(1) crée `DEBIAN/control` pour chaque paquet binaire en substituant `${shlibs:Depends}`, `${perl:Depends}`, `${misc:Depends}`, etc.

Cela dit, le champ `Depends` peut rester exactement comme il est maintenant, et une autre ligne avec `Suggests: file` peut être ajoutée, car `gentoo` peut utiliser certaines fonctionnalités fournies par le paquet `file`.

La ligne 9 est l'URL de la page d'accueil. Supposons qu'il s'agisse de http://www.obsession.se/gentoo/.

La ligne 12 est la description courte. Les terminaux sont larges de 80 colonnes par convention, aussi elle ne devrait pas dépasser les 60 caractères. `fully GUI-configurable, two-pane X file manager` convient ici.

À la ligne 13 commence la description longue. Celle-ci devrait être un paragraphe qui donne plus de détails sur le paquet. La colonne 1 de chaque ligne doit être vide. Il ne peut y avoir de ligne vide, mais vous pouvez mettre un seul `.` (point) dans la colonne 2 pour simuler une ligne vide. De plus, il ne peut pas y avoir plus d'une ligne vide après la description longue. [34]

Le champ `Vcs-*` pour documenter le système de gestion de versions (VCS) peut être inséré entre les lignes 6 et 7. [35] Considérons que le paquet `gentoo` a son VCS localisé sur le service Git d'Alioth en `git://git.debian.org/git/collab-maint/gentoo.git`.

Finalement, voici le fichier `control` mis à jour :

     1 Source: gentoo
     2 Section: x11
     3 Priority: optional
     4 Maintainer: Prénom Nom <votre.adresse.mail@example.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.

(Les numéros de ligne ont été ajoutés.)

## 4.2. `copyright`

Ce fichier contient des renseignements sur le copyright et la licence des sources amont. La Charte Debian, 12.5 « Informations sur le copyright » impose son contenu et la DEP-5 : `debian/copyright` analysable automatiquement fournit des directives pour son format.

dh_make peut proposer un modèle de fichier `copyright`. L'option `--copyright gpl2` peut être utilisée ici pour obtenir un modèle de fichier pour le paquet `gentoo` publié sous GPL-2.

You must fill in missing information to complete this file, such as the place you got the package from, the actual copyright notice, and the license. For certain common free software licenses (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 or the Artistic license), you can just refer to the appropriate file in the `/usr/share/common-licenses/` directory that exists on every Debian system. Otherwise, you must include the complete license.

En bref, voici ce à quoi le fichier `copyright` de `gentoo` devrait ressembler :

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

(Les numéros de ligne ont été ajoutés.)

Veuillez suivre les indications fournies par les responsables de l'archive et envoyées sur la liste debian-devel-announce : http://lists.debian.org/debian-devel-announce/2006/03/msg00023.html.

## 4.3. `changelog`

C'est un fichier obligatoire, avec un format spécifique décrit dans la Charte Debian, 4.4 « debian/changelog ». Ce format est utilisé par dpkg et d'autres programmes pour obtenir le numéro de version, de révision, de distribution et l'urgence de votre paquet.

Pour vous, il est également important, puisqu'il est bon de documenter toutes les modifications effectuées. Cela permettra aux personnes qui téléchargent le paquet de voir s'il y a des problèmes à connaître. Il sera conservé en `/usr/share/doc/gentoo/changelog.Debian.gz` dans le paquet binaire.

dh_make en crée un par défaut, et il ressemble à ceci :

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

(Les numéros de ligne ont été ajoutés.)

La ligne 1 contient le nom du paquet, la version, la distribution et l'urgence. Le nom doit correspondre au nom du paquet source, la distribution devrait être `unstable`, et l'urgence devrait être en medium à moins qu’il n’existe une raison particulière pour une autre valeur.

Les lignes 3 à 5 composent l'entrée de journal, où vous documentez les modifications effectuées dans la révision du paquet (pas les modifications amont — il y a un fichier spécial pour cela, créé par les auteurs amont, que vous installerez comme `/usr/share/doc/gentoo/changelog.gz`). Supposons que votre rapport de bogue ITP (« Intent To Package » ou intention d'empaqueter) avait pour numéro `12345`. Les nouvelles lignes doivent être insérées juste en dessous de la première ligne qui commence avec une astérisque (`*`). Vous pouvez utiliser dch(1) pour le modifier. Vous pouvez éditer cela manuellement avec un éditeur de texte à condition de suivre les conventions de formatage utilisées par dch(1).

Pour éviter d'envoyer un paquet accidentellement avant qu'il ne soit terminé, il vaut mieux modifier la valeur de distribution à `UNRELEASED` qui n'est pas valable.

Vous obtiendrez quelque chose comme :

    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  -- Prénom Nom <votre.adresse.mail@example.org>  Mon, 22 Mar 2010 00:37:31 +0100
    8

(Les numéros de ligne ont été ajoutés.)

Une fois satisfait de toutes les modifications, correctement documentées dans `changelog`, vous devriez modifier la valeur de distribution d'`UNRELEASED` à la valeur de distribution cible `unstable` (ou même `experimental`). [36]

Vous pouvez en apprendre plus sur la mise à jour du fichier `changelog` plus loin en Chapitre 8, Mise à jour de paquet.

## 4.4. `rules`

Il faut maintenant examiner les règles utilisées par dpkg-buildpackage(1) pour créer vraiment le paquet. Ce fichier est en fait un autre `Makefile`, mais différent de ceux des sources amont. Contrairement aux autres fichiers de `debian`, celui-ci est marqué comme exécutable.

### 4.4.1. Cibles du fichier `rules`

Tous les fichiers `rules`, comme n'importe quel `Makefile`, sont constitués de plusieurs règles, chacune d'entre elles définissant une cible et comment la réaliser. [37] Une nouvelle règle commence avec la déclaration de sa cible en première colonne. Les lignes suivantes commençant par une tabulation (caractère ASCII 9 : TAB) indiquent ce qui doit être réalisé pour cette cible. Les lignes vides et celles qui commencent par dièse (`#`) sont traitées comme des commentaires et sont ignorées. [38]

Une règle que vous voulez exécuter est appelée par le nom de sa cible comme un argument de la ligne de commande. Par exemple `debian/rules `build`` et `fakeroot make -f debian/rules `binary`` exécutent respectivement les règles pour les cibles ``build`` et ``binary``.

Voici une explication simplifiée des cibles :

- `clean` (obligatoire) : pour nettoyer tous les fichiers compilés, créés et inutiles de l'arborescence de construction ;

- `build` (obligatoire) : pour construire les programmes compilés et les documents formatés à partir des sources dans l'arborescence de construction ;

- `build-arch` (obligatoire) : pour construire les programmes compilés dépendants de l'architecture à partir des sources dans l'arborescence de construction ;

- `build-indep` (obligatoire) : pour construire les documents formatés indépendants de l'architecture à partir des sources dans l'arborescence de construction ;

- `install` (optionnelle) : pour installer les fichiers dans l'arborescence de chaque paquet binaire dans le répertoire `debian`. Si elles existent, les cibles `binary*` dépendent en réalité de cette cible.

- `binary` (obligatoire) : pour créer tous les paquets binaires (en réalité, une combinaison des cibles `binary-arch` et `binary-indep`) ; [39]

- `binary-arch` (obligatoire) : pour créer tous les paquets binaires dépendants de l'architecture (`Architecture: any`) dans le répertoire parent ;[40]

- `binary-indep` (obligatoire) : pour créer tous les paquets binaires indépendants de l'architecture (`Architecture: all`) dans le répertoire parent ;[41]

- `get-orig-source` (optionnelle) : pour obtenir la dernière version du paquet source d'origine à partir d'une archive amont.

Vous vous sentez sans doute submergé pour l'instant, mais les choses vont vraiment se simplifier à l'examen du fichier `rules` que dh_make donne par défaut.

### 4.4.2. Fichier `rules` par défaut

Les versions récentes de dh_make créent un fichier `rules` par défaut très simple mais aussi très puissant en utilisant la commande dh :

     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 $@

(Les numéros de ligne ont été ajoutés et certains commentaires réduits. Dans le vrai fichier `rules`, l’espace de début est une tabulation.)

Vous avez probablement l'habitude de la ligne 1 avec les scripts shell et Perl. Cela signifie que ce fichier doit être exécuté par `/usr/bin/make`.

La ligne 4 peut être décommentée pour configurer la variable `DH_VERBOSE` à 1, afin que la commande dh affiche les commandes dh_* qu'elle exécute. Vous pouvez également ajouter ici une ligne `export DH_OPTIONS=-v`, afin que chaque commande dh_* affiche les commandes qu'elle exécute. Cela permet de comprendre ce qui se passe exactement derrière ce simple fichier `rules`, et de déboguer ses problèmes. Ce nouveau dh est conçu pour constituer un élément essentiel des outils `debhelper` sans rien vous cacher.

Lines 16 and 17 are where all the work is done with an implicit rule using the pattern rule. The percent sign means "any targets", which then call a single program, dh, with the target name. [42] The dh command is a wrapper script that runs appropriate sequences of dh_* programs depending on its argument. [43]

- `debian/rules clean` exécute `dh clean`, qui exécute à son tour :

      dh_testdir
      dh_auto_clean
      dh_clean

- `debian/rules build` exécute `dh build`, qui exécute à son tour :

      dh_testdir
      dh_auto_configure
      dh_auto_build
      dh_auto_test

- `fakeroot debian/rules binary` exécute `fakeroot dh binary`, qui exécute à son tour : [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` exécute `fakeroot dh binary-arch`, qui exécute à son tour la même séquence que `fakeroot dh binary` mais avec l'option `-a` ajoutée à chaque commande ;

- `fakeroot debian/rules binary-indep` exécute `fakeroot dh binary-indep`, qui exécute à son tour à peu près la même séquence que `fakeroot dh binary` à l'exception de dh_strip, dh_makeshlibs et dh_shlibdeps, et avec l'option `-i` ajoutée à chaque commande restante.

Le rôle des commandes dh_* est presque évident d'après leur nom. [45] Les plus remarquables d'entre elles valent la peine d'être (très) brièvement présentées de façon simplifiée, dans l'hypothèse d'un environnement de construction basé sur un `Makefile` : [46]

- dh_auto_clean exécute normalement ce qui suit si un `Makefile` fournit la cible `distclean` : [47]

      make distclean

- dh_auto_configure exécute normalement ce qui suit si `./configure` existe (les paramètres sont abrégés pour la lisibilité) :

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

- dh_auto_build exécute normalement ce qui suit pour exécuter la première cible de `Makefile` si elle existe :

      make

- dh_auto_test exécute normalement ce qui suit si un `Makefile` fournit la cible `test` : [48]

      make test

- dh_auto_install exécute normalement ce qui suit si un `Makefile` fournit la cible `install` (la ligne est coupée pour la lisibilité) :

      make install \
        DESTDIR=/chemin/vers/paquet_version-révision/debian/paquet

Toutes les cibles ayant besoin de la commande fakeroot contiendront dh_testroot, qui se terminera en erreur si vous n'utilisez pas cette commande afin de vous faire passer pour le superutilisateur.

Le plus important à propos du fichier `rules` créé par dh_make, c'est qu'il ne s'agit que d'une suggestion. Il fonctionnera pour la plupart des paquets, mais pour les plus compliqués, vous ne devez pas hésiter à le modifier pour le faire correspondre à vos besoins.

Bien que la cible `install` ne soit pas obligatoire, elle est prise en charge. `fakeroot dh install` se comporte comme `fakeroot dh binary` mais s'arrête après dh_fixperms.

### 4.4.3. Personnalisation du fichier `rules`

Il existe plusieurs façons de personnaliser le fichier `rules` créé avec la nouvelle commande dh.

La commande `dh $@` peut être personnalisée comme suit : [49]

- ajout de l'assistance pour la commande dh_python2 (la meilleure solution pour Python) : [50]

  - ajout de `python` à `Build-Depends`,

  - utilisation de `dh $@ --with python2`,

  - conséquence : gestion des modules Python avec la structure `python` ;

- ajout de l'assistance pour la commande dh_pysupport (obsolète) :

  - ajout de `python-support` à `Build-Depends`,

  - utilisation de `dh $@ --with pysupport`,

  - conséquence : gestion des modules Python avec la structure `python-support` ;

- ajout de l'assistance pour la commande dh_pycentral (obsolète) :

  - ajout de `python-central` à `Build-Depends`,

  - utilisation de `dh $@ --with python-central` à la place,

  - conséquence : désactivation de la commande dh_pysupport,

  - conséquence : gestion des modules Python avec la structure `python-central` ;

- ajout de l'assistance pour la commande dh_installtex :

  - ajout de `tex-common` à `Build-Depends`,

  - utilisation de `dh $@ --with tex` à la place,

  - conséquence : enregistrement des fontes de Type 1, des modèles de césure et des formats avec TeX ;

- ajout de l'assistance pour les commandes dh_quilt_patch et dh_quilt_unpatch :

  - ajout de `quilt` à `Build-Depends`,

  - utilisation de `dh $@ --with quilt` à la place,

  - conséquence : application et retrait des correctifs au code source amont à partir des fichiers du répertoire `debian/patches` pour les paquets source au format `1.0`,

  - inutile pour les paquets source au format `3.0 (quilt)` ;

- ajout de l'assistance pour la commande dh_dkms :

  - ajout de `dkms` à `Build-Depends`,

  - utilisation de `dh $@ --with dkms` à la place,

  - conséquence : gestion correcte de l'utilisation de DKMS par les paquets de modules du noyau ;

- ajout de l'assistance pour les commandes dh_autotools-dev_updateconfig et dh_autotools-dev_restoreconfig :

  - ajout de `autotools-dev` à `Build-Depends`,

  - utilisation de `dh $@ --with autotools-dev` à la place,

  - conséquence : mise à jour et restauration de `config.sub` et `config.guess` ;

- ajout de l'assistance pour les commandes dh_autoreconf et dh_autoreconf_clean :

  - ajout de `dh-autoreconf` à `Build-Depends`,

  - utilisation de `dh $@ --with autoreconf` à la place,

  - conséquence : mise à jour des fichiers du système de construction GNU et restauration de ceux-ci après la construction ;

- ajout de l'assistance pour la commande dh_girepository :

  - ajout de `gobject-introspection` à `Build-Depends`,

  - utilisation de `dh $@ --with gir` à la place,

  - conséquence : calcul des dépendances pour les paquets embarquant des données d'introspection GObject et génération de la variable de substitution `${gir:Depends}` pour les dépendances du paquet ;

- ajout de l'assistance pour la fonctionnalité de complétion de bash :

  - ajout de `bash-completion` à `Build-Depends`,

  - utilisation de `dh $@ --with bash-completion` à la place,

  - conséquence : installation des complétions de bash en utilisant un fichier de configuration `debian/`paquet`.bash-completion`.

De nombreuses commandes dh_* invoquées par la nouvelle commande dh peuvent être personnalisées par les fichiers de configuration correspondants dans le répertoire `debian`. Consultez Chapitre 5, Autres fichiers dans le répertoire `debian` et la page de manuel de chaque commande pour la personnalisation de telles fonctionnalités.

Certaines commandes dh_*, invoquées à l'aide de la nouvelle commande dh, doivent parfois être exécutées avec des arguments supplémentaires, exécuter d'autres commandes avec elles ou être ignorées. Pour cela, créez une cible `override_dh_`toto`` avec sa règle dans le fichier `rules` définissant une cible `override_dh_`toto`` pour remplacer la commande dh_`toto`. Son rôle est fondamentalement de dire exécute-moi à la place. [51]

Les commandes dh_auto_* ont tendance à en faire plus que ce qui a été présenté ici (très) simplement, pour prendre en compte toutes les situations délicates. Évitez d'utiliser les cibles `override_dh_*` pour remplacer `dh_*` par des commandes équivalentes simplifiées (à part pour la cible `override_dh_auto_clean`) car elles pourraient contourner des fonctionnalités intelligentes de `debhelper`.

Ainsi, par exemple pour conserver les données de configuration dans le répertoire `/etc/gentoo` au lieu du répertoire consacré `/etc` du dernier paquet `gentoo` utilisant Autotools, il suffit de remplacer l'option `--sysconfig=/etc` donnée par la commande dh_auto_configure à la commande ./configure avec :

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

Les options données après `--` sont ajoutées aux options par défaut du programme exécuté automatiquement dans le but de les remplacer. L'utilisation de la commande dh_auto_configure est ici préférable à l'appel de la commande ./configure puisqu'elle remplacera seulement l'option `--sysconfig` et conservera toutes les autres options à propos de la commande ./configure.

Si le `Makefile` des sources de `gentoo` nécessite de préciser `build` comme cible pour la construction [52], vous pouvez créer une cible `override_dh_auto_build` pour cela.

    override_dh_auto_build:
            dh_auto_build -- build

Cela garantit l'exécution de `$(MAKE)` avec toutes les options par défaut données à la commande dh_auto_build avec en plus le paramètre `build`.

Si le `Makefile` des sources de `gentoo` oblige à préciser la cible `packageclean` pour nettoyer le paquet Debian au lieu d'utiliser les cibles `distclean` ou `clean`, vous pouvez créer une cible `override_dh_auto_clean` pour l'activer.

    override_dh_auto_clean:
            $(MAKE) packageclean

Si le `Makefile` des sources pour `gentoo` contient une cible `test` dont vous ne voulez pas pour exécuter le processus de construction du paquet Debian, vous pouvez utiliser une cible `override_dh_auto_test` vide pour l'omettre.

    override_dh_auto_test:

Si `gentoo` possède un fichier journal de modification inhabituel appelé `FIXES`, dh_installchangelogs ne l'installera pas par défaut. La commande dh_installchangelogs a besoin de `FIXES` en option pour l'installer. [53]

    override_dh_installchangelogs:
            dh_installchangelogs FIXES

Lors de l'utilisation de la nouvelle commande dh, la compréhension des effets exacts des cibles explicites comme celles énumérées en Section 4.4.1, « Cibles du fichier `rules` » (à part `get-orig-source`) peut être rendue difficile. Veuillez limiter les cibles explicites aux cibles `override_dh_*`, et à celles complètement indépendantes, si possible.

[27] Dans ce chapitre, le préfixe `debian/` est omis pour simplifier l'écriture des fichiers du répertoire `debian` quand la signification n'est pas ambiguë.

[28] Consultez la Charte Debian, 2.4 « Sections » et la liste des sections dans `sid`.

[29] Consultez la Charte Debian, 2.5 « Priorités ».

[30] Consultez la Charte Debian, 7.7 « Relations entre paquets source et binaires — Build-Depends, Build-Depends-Indep, Build-Conflicts, Build-Conflicts-Indep »

[31] Cette situation quelque peu étrange est une fonctionnalité bien expliquée dans la Charte Debian, note de bas de page 55. Ce n'est pas lié à l'utilisation de la commande dh dans le fichier `debian/rules` mais au fonctionnement de dpkg-buildpackage. La même situation s'applique au système de construction automatique pour Ubuntu.

[32] Consultez la Charte Debian, 5.6.8 « Architecture » pour de plus amples précisions.

[33] Consultez la Charte Debian, 7 « Déclaration de relations entre paquets ».

[34] Ces descriptions sont en anglais. Les traductions de ces descriptions sont fournies par Le projet de traduction de descriptions de Debian — DDTP.

[35] Consultez la référence du Développeur Debian, 6.2.5. « Emplacement du système de gestion de versions ».

[36] Si vous utilisez la commande `dch -r` pour faire cette dernière modification, n'oublier pas de sauver le fichier `changelog` explicitement dans l'éditeur.

[37] Vous pouvez apprendre les bases pour écrire un `Makefile` dans la référence Debian, 12.2. « Make ». La documentation complète est disponible en http://www.gnu.org/software/make/manual/html_node/index.html et dans le paquet `make-doc` de la partie `non-free` de l'archive.

[38] La Charte Debian, 4.9 « Script de construction principal : debian/rules » explique les détails.

[39] Cette cible est utilisée par `dpkg-buildpackage` comme en Section 6.1, « Reconstruction complète ».

[40] Cette cible est utilisée par `dpkg-buildpackage -B` comme en Section 6.2, « Serveurs d'empaquetage automatique (« autobuilder ») ».

[41] Cette cible est utilisée par `dpkg-buildpackage -A`.

[42] Cela utilise les fonctionnalités du nouveau `debhelper` v7+. Ses concepts fondateurs sont expliqués dans la présentation Pas le debhelper de papy réalisé lors de Debconf9 par l'auteur de `debhelper`. Sous `Lenny`, dh_make créait un fichier `rules` beaucoup plus compliqué avec des règles explicites et de nombreux scripts dh_* énumérés pour chacune, la plupart n'étant plus nécessaires maintenant (et montrant l'âge du paquet). La nouvelle commande dh plus simple libère le responsable de ce travail de routine « manuel ». Vous gardez les pleins pouvoirs de personnalisation du processus avec les cibles `override_dh_*`. Consultez Section 4.4.3, « Personnalisation du fichier `rules` ». Il se base uniquement sur le paquet `debhelper` et ne rend pas obscur le processus de construction comme le paquet `cdbs` a tendance à le faire.

[43] You can verify the actual sequences of dh_* programs invoked for a given ``target`` without really running them by invoking `dh `target` --no-act` or `debian/rules -- '`target` --no-act'`.

[44] L'exemple suivant suppose que `debian/compat` a une valeur au moins égale à 9 pour éviter d'invoquer une commande d'assistance Python automatiquement.

[45] Pour obtenir des renseignements complets sur le rôle exact de tous ces scripts dh_* et sur leurs options, veuillez lire leur page de manuel respective et la documentation de `debhelper`.

[46] Ces commandes gèrent d'autres environnements, comme `setup.py`, qui peuvent être énumérés en exécutant `dh_auto_build --list` dans le répertoire d'un paquet source.

[47] En fait, il recherche la première cible disponible dans le `Makefile` parmi `distclean`, `realclean` et `clean`, et l'exécute.

[48] En fait, il recherche dans le `Makefile` la première cible disponible parmi `test` et `check`, et l'exécute.

[49] Si un paquet installe le fichier `/usr/share/perl5/Debian/Debhelper/Sequence/`nom_personnalise`.pm`, vous devriez déclencher sa fonction de personnalisation avec `dh $@ --with `nom-personnalise``.

[50] L'utilisation de la commande dh_python2 est préférable à dh_pysupport ou dh_pycentral. N'utilisez pas la commande dh_python.

[51] Avec `Lenny`, pour modifier le comportement d'un script dh_* il fallait trouver et adapter la ligne pertinente du fichier `rules`.

[52] dh_auto_build sans autre option exécutera la première cible du `Makefile`.

[53] Les fichiers `debian/changelog` et `debian/NEWS` sont toujours installés automatiquement. Le journal de modification amont est trouvé en convertissant les noms de fichiers en minuscule puis en vérifiant l'existence de `changelog`, `changes`, `changelog.txt` et `changes.txt`.

Chapitre 3. Modification du code source |  | Chapitre 5. Autres fichiers dans le répertoire `debian`