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 <joy-mg@debian.org>, 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 v7 comme suit :

$ echo 7 > debian/compat

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. ^[55] 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 :

Pour obtenir des renseignements sur les scripts du responsable, consultez Section 5.19, « {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 :

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 fournit 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.fr.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.fr.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 byte-compilés 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 ? :-)

Le fichier paquet.init est installé comme un script qui sert à démarrer et arrêter le démon en /etc/init.d/paquet. Un squelette de modèle générique est fournit par la commande dh_make en init.d.ex. Vous devrez sans doute le renommer et le modifier, beaucoup, en vous assurant que les en-têtes respectent la Linux Standard Base (LSB). Il est installé dans le répertoire temporaire par dh_installinit(1).

Le fichier paquet.default est installé en tant que /etc/default/paquet. Ce fichier définit les valeurs par défaut des variables utilisées par le script d'initialisation. Ce fichier est le plus souvent utilisé pour désactiver le démarrage d'un démon ou pour paramétrer quelques options ou temps limites. Si le script d'initialisation contient certaines fonctionnalités paramétrables, elles ont leur place dans ce fichier paquet.default au lieu du le script d'initialisation lui-même.

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).^[56] 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'un espace puis du répertoire d'installation (par rapport au répertoire d'installation). 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 (/usr/share/doc/lintian/lintian.html/index.fr.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.

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 le paquet gentoo, créez le fichier gentoo.manpages contenant :

docs/gentoo.1

Les utilisateurs de X Window ont un gestionnaire de fenêtres avec un menu qui peut être configuré pour lancer des programmes. S'ils ont installé le paquet menu de Debian, un ensemble de menus pour chaque programme sur le système sera créé pour eux.

Voici le fichier menu.ex créé par défaut par dh_make :

?package(gentoo):needs=X11|text|vc|wm \
        section=Applications/see-menu-manual\
        title=gentoo command=/usr/bin/gentoo

Le premier champ après les deux points est needs, il indique le genre d'interface dont a besoin le programme. Changez ceci en une des alternatives énumérées, par exemple text ou X11.

Le suivant est la section où l'entrée de menu et de sous-menu devrait apparaître. ^[58]

Le champ title est le nom du programme. Vous pouvez le commencer par une majuscule si vous le souhaitez. Mais gardez-le court.

Enfin, le champ command est la commande qui exécute le programme.

Une fois le fichier renommé en menu, l'entrée de menu peut être modifiée comme ceci :

?package(gentoo): needs=X11 \
        section=Applications/Tools \
        title=Gentoo command=gentoo

Vous pouvez aussi ajouter d'autres champs comme longtitle, icon, hints, etc. Consultez dh_installmenu(1), menufile(5), update-menus(1) et la sous-charte de menu Debian pour obtenir plus de renseignements.

La commande dh_installchangelogs(1) l'installe.

Ces fichiers postinst, preinst, postrm, et prerm ^[59] 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 personnalisant vos 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 à jour devraient être silencieuses et non intrusives (les utilisateurs existants ne devraient pas remarquer la mise à jour à 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 ces 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 d'état de santé extérieur à Debian ou « Debian External Health Status » (DEHS).

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.

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

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. ^[60] 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. ^[61]

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 typiquement 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 amonts.

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 toutes contenues dans le répertoire debian sont empaquetées dans le fichier debian.tar.gz. Puisque la commande dpkg-source peut gérer les correctifs au format quilt des sources 3.0 (quilt) sans le paquet quilt, il n'est pas nécessaire d'ajouter quilt en Build-Depends. ^[62]

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. ^[63]

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.