Chapitre 5. Autres fichiers dans le répertoire debian

Table des matières

5.1. README.Debian
5.2. compat
5.3. conffiles
5.4. paquet.cron.*
5.5. dirs
5.6. paquet.doc-base
5.7. docs
5.8. emacsen-*
5.9. paquet.examples
5.10. paquet.init et paquet.default
5.11. install
5.12. paquet.info
5.13. paquet.links
5.14. {paquet.,source/}lintian-overrides
5.15. manpage.*
5.15.1. manpage.1.ex
5.15.2. manpage.sgml.ex
5.15.3. manpage.xml.ex
5.16. paquet.manpages
5.17. NEWS
5.18. {post,pre}{inst,rm}
5.19. paquet.symbols
5.20. TODO
5.21. watch
5.22. source/format
5.23. source/local-options
5.24. source/options
5.25. patches/*

The dh_make command had major updates since this old document was written. So some parts of this document aren't applicable any more.

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.

The debmake command is used in place of the dh_make command in my new Guide for Debian Maintainers.

Pour contrôler la plupart des actions de debhelper lors de la construction du paquet, placez des fichiers de configuration optionnels dans le répertoire debian. Ce chapitre présentera globalement le rôle de ces fichiers et leur format. Veuillez consulter la Charte Debian et la référence du développeur Debian pour les principes d'empaquetage.

The dh_make command will create some template configuration files under the debian directory. Take a look at all of them.

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

Certains modèles de fichiers de configuration de debhelper risquent de ne pas être créés par la commande dh_make. Dans ce cas, vous devez les créer avec un éditeur.

Pour activer certains d'entre eux, veuillez suivre les instructions suivantes :

Les fichiers de configuration de debhelper sans préfixe paquet comme install sont relatifs au premier paquet binaire. Lorsqu'il y a plusieurs paquets binaires, leur configuration respective peut être précisée en ajoutant leur nom en préfixe du nom de fichier de configuration : paquet-1.install, paquet-2.install, etc.

Tous les détails ou différences entre le paquet original et votre version Debian devraient être documentés ici.

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

gentoo for Debian
-----------------
<possible notes regarding this package - if none, delete this file>
 -- Josip Rodin <[email protected]>, Wed, 11 Nov 1998 21:02:14 +0100

Si vous n'avez rien à documenter, effacez ce fichier, consultez dh_installdocs(1).

Le fichier compat définit le niveau de compatibilité de debhelper. Actuellement, vous devriez le définir à debhelper v10 comme suit :

$ echo 10 > debian/compat

Vous pouvez utiliser le niveau de compatibilité v9 dans certaines circonstances pour une compatibilité avec les anciennes versions. Cependant, utiliser un niveau inférieur à v9 n’est pas recommandé et devrait être évité pour les nouveaux paquets.

Une des choses les plus irritantes à propos des logiciels est de consacrer beaucoup de temps et d'efforts pour configurer un programme, et de voir une seule mise à jour détruire tous ses changements. Debian résout ce problème en marquant ces fichiers de configuration comme des conffiles. [54] Lors de la mise à jour d'un paquet, une question sera posée, permettant de garder les anciens fichiers de configuration ou non.

dh_installdeb(1) considère automatiquement tous les fichiers du répertoire /etc comme des conffiles, donc si tous les fichiers de configuration de votre programme sont dans ce répertoire, il n'est pas nécessaire de les indiquer dans ce fichier. Pour la plupart des paquets, le seul endroit devant contenir des conffiles est /etc, donc ce fichier ne devrait pas exister.

Si votre programme utilise des fichiers de configuration, mais les réécrit aussi de son côté, il vaut mieux ne pas les marquer comme conffiles, parce que dpkg va alors interroger les utilisateurs pour vérifier les modifications tout le temps.

Si le programme que vous empaquetez force tous les utilisateurs à modifier les fichiers de configuration du répertoire /etc, il y a deux façons classiques de ne pas les marquer comme conffiles, et garder dpkg silencieux :

  • créer un lien symbolique dans le répertoire /etc vers un fichier du répertoire /var créé par les scripts du responsable ;

  • créer un fichier généré par les scripts du responsable dans le répertoire /etc.

Pour obtenir des renseignements sur les scripts du responsable, consultez Section 5.18, « {post,pre}{inst,rm} ».

Si le paquet a besoin d'exécuter des tâches régulièrement pour fonctionner correctement, vous pouvez utiliser ces fichiers pour les configurer. Vous pouvez programmer des tâches régulières horaires, quotidiennes, mensuelles ou qui se produiront au moment que vous préférez. Les noms de fichiers sont :

  • paquet.cron.hourly — installé comme /etc/cron.hourly/paquet et exécuté une fois par heure ;

  • paquet.cron.daily — installé comme /etc/cron.daily/paquet et exécuté une fois par jour ;

  • paquet.cron.weekly — installé comme /etc/cron.weekly/paquet et exécuté une fois par semaine ;

  • paquet.cron.monthly — installé comme /etc/cron.monthly/paquet et exécuté une fois par mois ;

  • paquet.cron.d — installé comme /etc/cron.d/paquet et exécuté à tout autre moment.

La plupart de ces fichiers sont des scripts shell, à l'exception de paquet.cron.d dont le format est celui de crontab(5).

Aucun fichier cron.* n'est nécessaire pour configurer la rotation des journaux ; pour cela, voyez dh_installlogrotate(1) et logrotate(8).

Ce fichier indique les répertoires nécessaires mais qui ne sont pas créés par la procédure d'installation normale (make install DESTDIR=... invoquée par dh_auto_install). C'est souvent dû à un problème avec le Makefile.

Les fichiers énumérés dans un fichier install n'ont pas besoin que leurs répertoires soient créés avant, consultez Section 5.11, « install ».

Il est préférable d'essayer d'exécuter l'installation, et d'utiliser seulement ce recours si vous avez des problèmes. Il n'y a pas de barre oblique (/) au début des noms de répertoire dans la liste du fichier dirs.

Si votre paquet est fourni avec une autre documentation que des pages de manuel et d'information, vous devriez utiliser le fichier doc-base pour l'enregistrer, de sorte que l'utilisateur puisse la trouver avec par exemple dhelp(1), dwww(1) ou doccentral(1).

Cela inclut normalement les fichiers HTML, PS et PDF, inclus dans /usr/share/doc/nomdepaquet/.

Voici ce à quoi le fichier gentoo.doc-base de gentoo ressemble :

Document: gentoo
Title: Gentoo Manual
Author: Emil Brink
Abstract: This manual describes what Gentoo is, and how it can be used.
Section: File Management
Format: HTML
Index: /usr/share/doc/gentoo/html/index.html
Files: /usr/share/doc/gentoo/html/*.html

Pour obtenir plus de renseignements sur le format de ce fichier, consultez install-docs(8) et la copie locale /usr/share/doc/doc-base/doc-base.html/index.html du manuel Debian de doc-base.

Pour obtenir plus de renseignements sur l'installation de documentation supplémentaire, consultez Section 3.3, « Installation des fichiers à leur emplacement ».

Ce fichier spécifie les noms des fichiers de documentation que dh_installdocs(1) peut installer pour vous dans le répertoire temporaire.

Par défaut, il inclut tous les fichiers, existant dans le répertoire racine des sources, qui sont nommés BUGS, README*, TODO, etc.

Pour gentoo, d'autres fichiers sont aussi inclus :

BUGS
CONFIG-CHANGES
CREDITS
NEWS
README
README.gtkrc
TODO

Si votre paquet fournit des fichiers Emacs qui peuvent être compilés en bytecode au moment de l'installation, vous pouvez utiliser ces fichiers pour les configurer.

Ils sont installés dans le répertoire temporaire par dh_installemacsen(1).

Si vous n'en avez pas besoin, effacez-les.

La commande dh_installexamples(1) installe les fichiers et répertoires énumérés ici comme des fichiers d'exemple.

Si votre paquet est un démon qui doit être exécuté au démarrage du système, vous avez de toute évidence ignoré les recommandations initiales, n'est-ce-pas ? :-)

Please read dh_installinit(1) dh_installsystemd(1) to provide startup script.

The package.default file will be installed as /etc/default/package. This file sets defaults that are sourced by the init script. This package.default file is most often used to set some default flags or timeouts. If your init script has certain configurable features, you can set them in the package.default file, instead of in the init script itself.

Si le programme amont fournit un fichier pour le script d'initialisation, vous avez le choix de l'utiliser ou non. Si vous n'utilisez pas leur script d'initialisation, créez-en un nouveau en paquet.init. Cependant, si le script d'initialisation amont semble fonctionnel et s'installe au bon endroit, il vous faudra tout de même configurer le lien symbolique rc*. Pour cela, il faut remplacer dh_installinit dans le fichier rules avec les lignes suivantes :

override_dh_installinit:
        dh_installinit --onlyscripts

Si vous n'en avez pas besoin, effacez ces fichiers.

Si des fichiers doivent être installés dans le paquet mais que make install normal ne le fait pas, il faut ajouter les noms de fichiers et leur destination dans ce fichier install. Ils sont installés par dh_install(1).[55] Vous devriez d'abord vérifier s'il n'y a pas un outil plus approprié à utiliser. Par exemple, les documents devraient être dans le fichier docs et non dans celui-ci.

Ce fichier install possède une ligne par fichier installé, avec le nom du fichier (par rapport au répertoire de construction principal) suivi d'une espace puis du répertoire d'installation (par rapport au répertoire d'install). Par exemple, si un binaire src/truc n'est pas installé, le fichier install pourrait ressembler à :

src/truc usr/bin

Cela signifie que lors de l'installation du paquet, il y aura une commande exécutable /usr/bin/truc.

Ce fichier install peut renseigner seulement le nom du fichier sans le répertoire d'installation quand le chemin relatif n'est pas modifié. Ce format est normalement utilisé pour un gros paquet qui découpe le résultat de la construction en plusieurs paquets binaires à l'aide de paquet-1.install, paquet-2.install, etc.

La commande dh_install finira par chercher les fichiers dans debian/tmp, s'il ne les trouve pas dans le répertoire courant (ou quelque soit l'endroit où il lui a été demandé de chercher avec --sourcedir).

Si le paquet possède des pages d'information, vous devriez les installer avec dh_installinfo(1) en les énumérant dans un fichier paquet.info.

Pour créer des liens symboliques supplémentaires dans les répertoires de construction du paquet en tant que responsable du paquet, vous devriez les installer avec dh_link(1) en énumérant leurs chemins complets de fichiers source et destination dans un fichier paquet.links.

Si lintian signale des erreurs dans son diagnostic alors que la Charte accepte des exceptions à certaines règles, vous pouvez utiliser paquet.lintian-overrides ou source/lintian-overrides pour le rendre silencieux. Veuillez lire le manuel utilisateur de Lintian (https://lintian.debian.org/manual/index.html) et vous abstenir d'en abuser.

paquet.lintian-overrides concerne le paquet binaire appelé paquet, il est installé en usr/share/lintian/overrides/paquet par la commande dh_lintian.

source/lintian-overrides concerne le paquet source. Il n'est pas installé.

Le programme devrait être livré avec une page de manuel. Sinon, vous devriez en créer au moins une. La commande dh_make crée quelques modèles de fichiers pour pages de manuel. Ils doivent être copiés et modifiés pour chaque commande à laquelle il manque une page de manuel. Veuillez vous assurer d'avoir effacé les modèles non utilisés.

Les pages de manuel sont normalement écrites en nroff(1). L'exemple manpage.1.ex est aussi écrit en nroff. Lisez la page de manuel man(7) pour une brève description sur la façon d'éditer ce genre de fichiers.

Le nom de fichier de la page de manuel devrait donner le nom du programme qu'elle documente, donc manpage doit être renommé en gentoo. Le nom de fichier inclut aussi .1 comme premier suffixe, qui signifie que c'est une page de manuel pour une commande utilisateur. Assurez-vous de vérifier que cette section est effectivement la bonne. Voici une courte liste des sections de pages de manuel :

Ainsi, la page de manuel de gentoo devrait être appelée gentoo.1. S'il n'y avait pas de page de manuel gentoo.1 dans les sources originales, il aurait fallu renommer le modèle manpage.1.ex en gentoo.1 puis le modifier à partir des informations de l'exemple et de la documentation amont.

La commande help2man peut aussi être utilisée pour créer une page de manuel à partir de la sortie de --help et --version pour chaque programme. [56]

Si le paquet possède des pages de manuel, vous devriez les installer avec dh_installman(1) en les énumérant dans un fichier paquet.manpages.

Pour installer docs/gentoo.1 en tant que page de manuel du paquet gentoo, créez le fichier gentoo.manpages contenant :

docs/gentoo.1

La commande dh_installchangelogs(1) l'installe.

Les fichiers postinst, preinst, postrm, et prerm [57] sont nommés scripts du responsable. Ces scripts sont placés dans la zone de contrôle du paquet et sont exécutés par dpkg lorsque le paquet est installé, mis à jour ou supprimé.

En tant que responsable débutant, vous devriez éviter de modifier manuellement les scripts du responsable parce qu'ils ont tendance à être complexes. Pour obtenir plus de renseignements, consultez dans la Charte Debian, chapitre 6 « scripts du responsable et procédure d'installation » et examinez les fichiers d'exemple fournis par dh_make.

Si vous préférez n'en faire qu'à votre tête en créant vos propres scripts du responsable pour un paquet, vous devriez les essayer non seulement lors de l'installation et la mise à jour, mais aussi pour la désinstallation et la purge.

Les mises à niveau vers de nouvelles versions devraient être silencieuses et non intrusives (les utilisateurs existants ne devraient pas remarquer la mise à niveau à part en constatant la résolution de vieux bogues et peut-être l'arrivée de nouvelles fonctionnalités).

Lorsque la mise à niveau est forcément intrusive (par exemple des fichiers de configuration dispersés dans plusieurs répertoires personnels avec des structures complètement différentes), vous pouvez envisager en dernier recours de basculer le paquet vers un état de repli sûr (par exemple en désactivant un service) et en fournissant la documentation adéquate conformément à la Charte Debian (README.Debian et NEWS.Debian). N'embêtez pas l'utilisateur avec des notes debconf déclenchées par les scripts du responsable lors des mises à niveau.

Le paquet ucf fournit un dispositif à la conffile pour conserver les modifications des utilisateurs pour les fichiers qui n'ont pas été marqués comme conffiles comme ceux gérés par les scripts du responsable. Cela permet de réduire les problèmes associés à ces fichiers.

Ces scripts du responsable font partie des améliorations de Debian qui expliquent pourquoi les gens choisissent Debian. Prenez garde de ne pas les transformer en source d'agacement.

L'empaquetage de bibliothèque n'est pas facile pour un mainteneur débutant, et devrait être évité. Cela dit, si le paquet fournit des bibliothèques, des fichiers debian/paquet.symbols devraient exister. Consultez Section A.2, « Gestion de debian/paquet.symbols ».

La commande dh_installdocs(1) l'installe.

Le format du fichier watch est documenté dans la page de manuel uscan(1). Le fichier watch configure le programme uscan (dans le paquet devscripts) pour surveiller le site sur lequel vous avez obtenu les sources. C'est également utilisé par le service Debian Package Tracker.

Voici ce qu'il contient :

# watch control file for uscan
version=3
http://sf.net/gentoo/gentoo-(.+)\.tar\.gz debian uupdate

Normalement, avec un fichier watch, la page servie à l'URL http://sf.net/gentoo est téléchargée pour chercher des liens sous la forme <a href=...>. Le nom de base (juste après la dernière /) de chaque URL liée est comparé au motif de l'expression rationnelle Perl gentoo-(.+)\.tar\.gz (consultez perlre(1)). Parmi les fichiers correspondants, celui avec le plus grand numéro de version est téléchargé puis le programme uupdate est exécuté pour créer une arborescence source mise à jour.

Bien que ce soit vrai pour les autres sites, le service de téléchargement de SourceForge en http://sf.net est une exception. Quand le fichier watch comporte une URL correspondant au motif d'expression rationnelle ^http://sf\.net/, le programme uscan le remplace par http://qa.debian.org/watch/sf.php/ et applique ensuite cette règle. Le service de redirection en http://qa.debian.org/ est conçu pour offrir un service stable vers le fichier voulu pour les motifs watch de la forme http://sf.net/projet/nom-d-archive-(.+)\.tar\.gz. Le but est de résoudre le problème lié au fréquent changement d'URL SourceForge.

Si la source propose une signature cryptographique pour l’archive, il est recommandé de vérifier son authenticité en utilisant l’option pgpsigurlmangle comme expliqué dans uscan(1).

Dans le fichier debian/source/format, il devrait y avoir une seule ligne indiquant le format voulu du paquet source (consulter en dpkg-source(1) pour une liste exhaustive). Après Squeeze, il devrait contenir selon les cas :

  • 3.0 (native) pour les paquets Debian natifs ;

  • 3.0 (quilt) pour tout le reste.

Le récent format source 3.0 (quilt) enregistre les modifications dans un ensemble de correctifs quilt dans debian/patches. Ces changements sont alors appliqués automatiquement lors de l'extraction du paquet source. [58] Les modifications Debian sont simplement conservées dans une archive debian.tar.gz contenant tous les fichiers du répertoire debian. Ce nouveau format permet d'inclure des fichiers binaires comme des icônes PNG sans bidouillage. [59]

Quand dpkg-source extrait un paquet source au format 3.0 (quilt), il applique automatiquement tous les correctifs énumérés dans debian/patches/series. Vous pouvez éviter que les correctifs soient appliqués à la fin de l'extraction avec l'option --skip-patches.

Lors de la maintenance de paquet Debian avec un système de gestion de version, il faut généralement créer une branche (par exemple, upstream) pour suivre les sources amont, et une autre branche (typiquement master avec Git) pour suivre le paquet Debian. Pour cette dernière, il est préférable de garder les sources amont non modifiés aux côtés des fichiers debian/* du paquet Debian pour faciliter la fusion avec les nouveaux sources d’amont.

Après la construction d'un paquet, les sources sont normalement laissés modifiés (« patched »). dquilt pop -a doit être exécuté avant d'envoyer vers la branche master. Créer un fichier optionnel debian/source/local-options contenant unapply-patches permet d'automatiser cela. Ce fichier n'est pas inclus dans le paquet source créé et modifie seulement le comportement de construction local. Ce fichier peut aussi contenir abort-on-upstream-changes (consultez dpkg-source(1)).

unapply-patches
abort-on-upstream-changes

Les fichiers créés automatiquement dans l'arborescence source peuvent être assez agaçants pour l'empaquetage puisqu'ils sont à l'origine de grands fichiers de correctif sans signification. Des modules personnalisés comme dh_autoreconf permettent d'atténuer ce problème comme décrit en Section 4.4.3, « Personnalisation du fichier rules ».

Vous pouvez fournir une expression rationnelle Perl en argument de l'option --extend-diff-ignore de dpkg-source(1) pour ignorer les modifications faites aux fichiers créés automatiquement lors de la création du paquet source.

Comme solution générique pour aborder ce problème de fichiers créés automatiquement, vous pouvez enregistrer ces arguments d'option de dpkg-source dans le fichier source/options du paquet source. L'exemple suivant permet de sauter la création de fichiers de correctif pour config.sub, config.guess et Makefile :

extend-diff-ignore = "(^|/)(config\.sub|config\.guess|Makefile)$"

L'ancien format source 1.0 créait un unique et gros fichier diff.gz contenant les fichiers de maintenance du paquet dans debian et les correctifs aux sources. Un tel paquet est un peu délicat à inspecter et à comprendre pour chaque modification de l'arbre source par la suite. Ce n'est pas conseillé.

Le nouveau format source 3.0 (quilt) conserve les correctifs dans les fichiers debian/patches/* en utilisant la commande quilt. Ces correctifs et les autres données de paquet qui sont tous contenus dans le répertoire debian sont empaquetés dans le fichier debian.tar.gz. Puisque la commande dpkg-source peut gérer les correctifs au format quilt dans le source 3.0 (quilt) sans le paquet quilt, il n'est pas nécessaire d'ajouter quilt à Build-Depends. [60]

La commande quilt est expliquée en quilt(1). Elle enregistre les modifications des sources comme une pile de fichiers correctifs -p1 dans le répertoire debian/patches et l'arborescence source n'est pas modifiée en dehors du répertoire debian. L'ordre d'application de ces correctifs est enregistré dans le fichier debian/patches/series. Vous pouvez appliquer (« push »), enlever (« pop »), et rafraîchir (« refresh ») les correctifs facilement. [61]

En Chapitre 3, Modification du code source, trois correctifs ont été créés dans debian/patches.

Puisque les correctifs Debian sont localisés en debian/patches, veuillez vous assurer d'avoir configuré correctement la commande dquilt conformément à la description en Section 3.1, « Configuration de quilt ».

Quand quelqu'un (éventuellement vous-même) fournit un correctif toto.patch par la suite, la modification d'un paquet source 3.0 (quilt) est assez simple :

$ dpkg-source -x gentoo_0.9.12.dsc
$ cd gentoo-0.9.12
$ dquilt import ../toto.patch
$ dquilt push
$ dquilt refresh
$ dquilt header -e
... description du correctif

Les correctifs conservés au nouveau format source 3.0 (quilt) doivent être sans approximation (« fuzz »). Vous pouvez vous en assurer avec dquilt pop -a; while dquilt push; do dquilt refresh; done.



[55] Cela remplace la commande obsolète dh_movefiles(1) configurée par le fichier files.

[56] Remarquez que la page de manuel initiale créée par help2man prétendra que des renseignements supplémentaires sont disponibles dans le système d'information. Si la commande n'a pas non plus de page info, vous devriez modifier manuellement la page créée par la commande help2man.

[57] Malgré l'utilisation de raccourcis bash pour présenter les noms des fichiers {pre,post}{inst,rm}, vous devriez utiliser une syntaxe pure POSIX pour les scripts du responsable pour être compatibles avec dash comme interpréteur de commande du système.

[58] Consulter DebSrc3.0 pour un résumé de la conversion des sources aux formats source 3.0 (quilt) et 3.0 (native).

[59] En fait, ce nouveau format permet de gérer des archives amont multiples et plusieurs méthodes de compression. Ces considérations sortent du cadre de ce document.

[60] Plusieurs méthodes de maintenance des ensembles de correctifs ont été proposées et sont utilisées dans les paquets Debian. Le système quilt est le système de maintenance conseillé. Parmi d'autres, dpatch, dbs et cdbs existent. La plupart d'entre eux conservent de tels correctifs dans des fichiers debian/patches/*.

[61] Si vous demandez à un parrain d'envoyer le paquet, cette sorte de séparation claire et la documentation de vos modifications sont très importantes pour accélérer l'examen du paquet.