[ précédent ] [ Table des matières ] [ 1 ] [ 2 ] [ 3 ] [ 4 ] [ 5 ] [ 6 ] [ 7 ] [ 8 ] [ 9 ] [ suivant ]


Guide du nouveau responsable Debian
Chapitre 5 - Autres fichiers dans le répertoire debian


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ésente globalement le rôle de ces fichiers et leur format. Veuillez vous reporter à la Charte Debian et à la référence du développeur Debian pour les principes d'empaquetage.

La commande dh_make crée quelques modèles de fichiers de configuration dans le répertoire debian. La plupart d'entre-eux ont une extension « .ex ». Certains d'entre-eux ont le nom du paquet binaire comme préfixe : paquet. Regardez les tous.

La commande dh_make ne crée pas tous les modèles de fichiers de configuration pour debhelper. 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.


5.1 Fichier README.Debian

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
     -----------------
     
     <considérations éventuelles à propos de ce paquet - sinon, effacer ce fichier>
     
      -- Prénom Nom <votre.adresse.mail@example.org>, Mon, 22 Mar 2010 00:37:31 +0100

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


5.2 Fichier compat

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

5.3 Fichier conffiles

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 les fichiers de configuration de sorte que quand vous mettez à jour un paquet, il vous sera demandé si vous voulez gardez votre ancienne configuration ou pas.

Depuis debhelper V3, dh_installdeb(1) va automatiquement considérer tous les fichiers du répertoire /etc comme des fichiers de configuration, 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 (et ce devrait toujours être le cas) contenant des fichiers de configuration 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 fichiers de configuration, parce que dpkg va alors interroger les utilisateurs pour vérifier les modifications tout le temps.

Si le programme que vous empaquetez oblige chaque utilisateur à modifier les fichiers de configuration du répertoire /etc, il y a deux façons usuelles de ne pas les marquer comme fichiers de configuration pour que dpkg reste silencieux :

Pour plus d'informations sur les scripts du responsable, veuillez consulter Fichier {post|pre}{inst|rm}, Section 5.18.


5.4 Fichiers paquet.cron.*

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

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

Ceci n'inclut pas la rotation des journaux ; pour cela, voyez dh_installlogrotate(1) et logrotate(8).


5.5 Fichier dirs

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

Les fichiers énumérés dans le fichier install n'ont pas besoin que les répertoires soient créés avant, cf. Fichier install, Section 5.11.

Il est préférable d'essayer d'exécuter d'abord 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.


5.6 Fichier paquet.doc-base

Si votre paquet est fournit avec une autre documentation que des pages de manuel et des documents info, 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 plus d'informations sur le format de ce fichier, voir install-docs(8) et le manuel de doc-base, en /usr/share/doc/doc-base/doc-base.html/index.html.

Pour plus d'informations sur l'installation de documentation supplémentaire, voir Installation des fichiers à leur emplacement, Section 3.3.


5.7 Fichier docs

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.

Pourgentoo, sont aussi inclus :

     BUGS
     CONFIG-CHANGES
     CREDITS
     NEWS
     README
     README.gtkrc
     TODO

5.8 Fichier emacsen-*

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.


5.9 Fichier paquet.examples

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


5.10 Fichiers paquet.init et paquet.default

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 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 norme de hiérarchie de fichiers (cf. /usr/share/doc/debian-policy/fhs/). Il est installé dans le répertoire temporaire par dh_installinit(1).

Le fichier paquet.default est installé en /etc/default/paquet. Ce fichier définit les valeurs par défaut des variables utilisées par le script .init. La plupart du temps, ce fichier est utilisé pour désactiver le démarrage d'un démon, paramétrer quelques drapeaux (« flags ») ou temps limites. Si le script init contient certaines fonctionnalités paramétrables, elles ont leur place dans ce fichier .default, pas dans le script init.

Si le programme amont possède un fichier init, vous avez le choix de l'utiliser ou non. Si vous n'utilisez pas leur script init.d, créez-en un nouveau en debian/paquet.init. Cependant, si le script init amont semble fonctionnel et s'installe au bon endroit, il vous faudra tout de même configurer le lien symbolique rc*. Pour ce faire il faudra 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.


5.11 Fichier install

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. Il sont installés par dh_install(1).[34] 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 est oublié lors de l'installation, le fichier install ressemblera à :

     src/toto/monbin usr/bin

Cela signifie que lors de l'installation du paquet, il y aura un fichier binaire /usr/bin/monbin.

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 multiples 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).


5.12 Fichier paquet.info

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


5.13 Fichiers {paquet.|source/}lintian-overrides

Si lintian signale des erreurs dans son diagnostique 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 /usr/share/doc/lintian/lintian.html/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é.


5.14 Fichiers manpage.*

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 page de manuel. Ils doivent être copiés et modifiés pour chaque commande sans page de manuel. Assurez-vous d'avoir effacé les modèles non utilisés.


5.14.1 Fichier manpage.1.ex

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 description brève de la façon d'éditer ce genre de fichier.

Le nom de fichier de la page de manuel devrait inclure 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 :

     Section |     Description      |     Notes
        1     Commandes utilisateur   Commandes ou scripts exécutables.
        2     Appels système          Fonctions fournies par le noyau.
        3     Appels bibliothèque     Fonctions des bibliothèques système.
        4     Fichiers spéciaux       D'ordinaire trouvés dans /dev.
        5     Formats de fichiers     Par ex. le format /etc/password.
        6     Jeux                    Ou d'autres programmes frivoles.
        7     Paquets de macros       Comme les macros de man.
        8     Administration système  Programmes normalement exécutés par root.
        9     Routines noyau          Appels non standards et routines internes.

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. [35]


5.14.2 Fichier manpage.sgml.ex

D'un autre côté, si vous préférez écrire du SGML plutôt que du nroff, vous pouvez utiliser le modèle manpage.sgml.ex. Si vous le faites, vous devez :


5.14.3 Fichier manpage.xml.ex

Si vous préférez XML à SGML, vous pouvez utiliser le modèle manpage.xml.ex. Si vous le faites, vous devez :


5.15 Fichier paquet.manpages

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

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

     docs/gentoo.1

5.16 Fichier menu

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 section, avec le menu et le sous-menu dans lesquels l'entrée devrait apparaître. La liste actuelle des sections [36] est dans : /usr/share/doc/debian-policy/menu-policy.html/ch2.html#s2.1.

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. Voir dh_installmenu(1), menufile(5), update-menus(1) et /usr/share/doc/debian-policy/menu-policy.html/ pour plus d'informations.


5.17 Fichier NEWS

La commande dh_installchangelogs(1) l'installe.


5.18 Fichier {post|pre}{inst|rm}

Ces fichiers postinst, preinst, postrm, et prerm [37] 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 plus d'informations, regardez 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 à jour 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 de remettre une configuration par défaut sûre du paquet (par exemple avec service désactivé), et de fournir les documentations adéquates requises par la Charte Debian (README.Debian et NEWS.Debian) en dernier ressort. N'embêtez pas l'utilisateur avec une note debconf déclenchée par ces scripts du responsable lors des mises à jour.

Le paquet ucf fournit un dispositif à la conffile pour conserver les modifications des utilisateurs pour les fichiers qui n'ont pas été marqués 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 sont des améliorations Debian qui expliquent pourquoi les gens choisissent Debian. Prenez garde de ne pas les ennuyer avec ces scripts.


5.19 Fichier TODO

La commande dh_installdocs(1) l'installe.


5.20 Fichier watch

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 l'état de santé exterieur à Debian ou « Debian External Health Status » (DEHS).

Voici ce qu'il contient ici :

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

Normalement, avec ce 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=...> ». Ces liens sont comparés au nom de base (juste après la dernière « / ») « gentoo-(.+)\.tar\.gz » comme motif d'expression rationnelle Perl (cf. perlre(1)). Parmi les fichiers concordants, 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 à partir de ce fichier.

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 concordant avec le 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 un fichier watch avec « 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 pour ce domaine.


5.21 Fichier source/format

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. [38] 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. [39]

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.


5.22 Fichier source/local-options

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 »). « quilt 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 » (voir dpkg-source(1)).


5.23 Fichiers patches/*

L'ancien format source 1.0 créait un unique et gros fichier diff.gz avec les fichiers de maintenance de paquet dans debian/ et les correctifs. 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 des sources 3.0 (quilt) sans le paquet quilt, il n'est pas nécessaire d'ajouter quilt en Build-Depends. [40]

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. [41]

En Modification du code source, Chapitre 3, 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 quilt conformément à la description en Configuration de quilt, Section 3.1.

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
     $ quilt import ../toto.patch
     $ quilt push
     $ quilt refresh
     $ quilt header -e
     ... description du correctif

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


[ précédent ] [ Table des matières ] [ 1 ] [ 2 ] [ 3 ] [ 4 ] [ 5 ] [ 6 ] [ 7 ] [ 8 ] [ 9 ] [ suivant ]


Guide du nouveau responsable Debian

version 1.2.25, 2010-12-21 14:06:56 UTC

Josip Rodin joy-mg@debian.org

Traduction par Frédéric Dumont frederic.dumont@easynet.be
Mohammed Adnène Trojette adn+deb@diwi.org
David Prévot david@tilapin.org
et les membres de la liste debian-l10n-french@lists.debian.org