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


Guide du nouveau responsable Debian
Chapitre 4 - Fichiers nécessaires dans le répertoire debian


Un nouveau sous-répertoire se trouve dans le répertoire des sources du programme, nommé debian. Certain 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.


4.1 Fichier control

Ce fichier contient plusieurs valeurs utilisées par dpkg, dselect, apt-get, apt-cache, aptitude et d'autres outils de gestions de paquets pour gérer le paquet. Il 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 (>= 7.0.50~)
      6 Standards-Version: 3.8.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 à 6 sont les informations de contrôle pour le paquet source.

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 sections : main (logiciels libres), non-free (logiciels non libres), et contrib (logiciels libres qui dépendent de logiciels non libres). Des sous-sections logiques décrivent de manière concise le type de paquets qui s'y trouvent, par exemple admin pour les programmes destinés aux administrateurs, base pour les outils fondamentaux, 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. Lisez la Charte Debian, 2.4 « Sections » et la liste des sections dans <tt>Sid</tt> pour des conseils.

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. Lisez la Charte Debian, 2.5 « Priorités » pour des informations sur ces valeurs :

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 délivrer les courriers relatifs aux bogues. Évitez d'utiliser des virgules, esperluettes (« & ») ou parenthèses.

La cinquième ligne 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 (voir la Charte Debian, 7.7 « Relations entre paquets sources et binaires — Build-Depends, Build-Depends-Indep, Build-Conflicts, Build-Conflicts-Indep »). 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ées par des virgules ; lisez ci-après les explications sur les dépendances entre binaires pour mieux comprendre la syntaxe de ces lignes :

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

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 l'architecture du CPU pour laquelle le paquet binaire peut être compilé. « any » est laissé car dpkg-gencontrol(1) trouvera la valeur appropriée pour chaque machine sur laquelle ce paquet 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 Fichier rules, Section 4.4 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é (voir dpkg(8), dselect(8), apt(8), aptitude(1), etc.)

Voici la signification des dépendances :

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és 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é. Ces versions sont précisées entre parenthèses après chaque nom de paquet individuel, et doivent contenir une relation de la liste suivante suivie par un 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. Ces paramètres seront remplacés par une liste générée par les autres composants de debhelper quand la commande dh_gencontrol(1) est exécutée.

dh_shlibdeps(1) parcourra le paquet après sa construction et son installation dans le répertoire temporaire, afin de rechercher les exécutables et bibliothèques, déterminer leurs dépendances en bibliothèques partagées, et détecter dans quels paquets elles se trouvent (libc6 ou xlib6g par exemple). La liste des bibliothèques partagées dépendantes est utilisée pour remplacer ${shlibs:Depends}.

La liste de paquets créée par dh_perl(1) est utilisée pour remplacer ${perl:Depends}.

Certaines commandes de debhelper peuvent rendre la création de paquet dépendante d'autres paquets. Cette liste de paquets nécessaires est utilisée pour remplacer ${misc:Depends}.

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 12 est la description courte. La plupart des écrans sont larges de 80 colonnes, aussi cela 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.

Le champ Vcs-* documenté dans la référence du développeur, 6.2.5 « Emplacement du système de gestion de versions » peut être inséré entre les lignes 6 et 7. Considérons que le paquet gentoo est 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 (>= 7.0.5), xlibs-dev, libgtk1.2-dev, libglib1.2-dev
      6 Standards-Version: 3.8.4
      7 Vcs-Git: git://git.debian.org/git/collab-maint/gentoo.git
      8 Vcs-browser: http://git.debian.org/?p=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 a 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 utilises the GTK+ toolkit
     30  for its interface.

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


4.2 Fichier copyright

Ce fichier contient les informations sur les ressources en amont, le copyright et la licence du paquet. Le format n'est pas dicté par la Charte Debian, mais son contenu l'est (Charte Debian, 12.5 « Informations sur le copyright »). Vous pouvez aussi consulter la DEP-5 : debian/copyright analysable automatiquement.

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 package publié sous GPL-2.

Les choses à ajouter obligatoirement à ce fichier sont l'endroit où vous avez trouvé ce paquet, ainsi que le copyright et la licence d'exploitation réelle. Si la licence est une des licences de logiciel libre populaires comme 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 ou Artistic, vous pouvez juste faire référence au fichier approprié dans le répertoire /usr/share/common-licenses/, qui existe sur chaque système Debian. Sinon, vous devez inclure la licence en entier.

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

      1 Format-Specification: http://svn.debian.org/wsvn/dep/web/deps/dep5.mdwn?op=file&rev=135
      2 Name: gentoo
      3 Maintainer: Prénom Nom <votre.adresse.mail@example.org>
      4 Source: http://sourceforge.net/projects/gentoo/files/
      5
      6 Copyright: 1998-2010 Emil Brink <emil@obsession.se>
      7 License: GPL-2+
      8
      9 Files: icons/*
     10 Copyright: 1998 Johan Hanson <johan@tiq.com>
     11 License: GPL-2+
     12
     13 Files: debian/*
     14 Copyright: 2010 Prénom Nom <votre.adresse.mail@example.org>
     15 License: GPL-2+
     16
     17 License: GPL-2+
     18  This program is free software; you can redistribute it and/or modify
     19  it under the terms of the GNU General Public License as published by
     20  the Free Software Foundation; either version 2 of the License, or
     21  (at your option) any later version. 
     22  .
     23  This program is distributed in the hope that it will be useful,
     24  but WITHOUT ANY WARRANTY; without even the implied warranty of
     25  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
     26  GNU General Public License for more details.
     27 .
     28  You should have received a copy of the GNU General Public License along
     29  with this program; if not, write to the Free Software Foundation, Inc.,
     30  51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
     31  .
     32  On Debian systems, the full text of the GNU General Public
     33  License version 2 can be found in the file
     34  `/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 Fichier 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=low
     2
     3   * Initial release (Closes: #nnnn)  <nnnn est le numéro de bogue de votre ITP>
     4
     5  -- Prénom Nom <votre.adresse.mail@example.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 (ou même experimental) [17], et l'urgence ne devrait pas être changée en quoique ce soit de supérieur à « low ». :-)

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 au niveau de la première ligne qui commence avec une astérisque (« * »). Vous pouvez utiliser dch(1) pour le modifier.

Vous obtiendrez quelque chose comme :

     1  gentoo (0.9.12-1) unstable; 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.)

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


4.4 Fichier 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

Tout fichier rules, comme tout autre Makefile, consiste en plusieurs cibles et leurs règles précisant comment gérer le code source. La Charte Debian, 4.9 « Script de construction principal : debian/rules » l'explique en détail.

Voici une explication simplifiée des cibles :

Les règles à exécuter sont en paramètres de ligne de commande (par exemple, « ./debian/rules build » ou « fakeroot make -f debian/rules binary »). Après le nom de la cible, vous pouvez nommer la dépendance, programme ou fichier dont la cible dépend. Ensuite, il peut y avoir un certain nombre de commandes, indentées par tab. Une nouvelle règle commence par la déclaration de cible dès la première colonne. Les lignes vides ainsi que celles qui commencent par un « # » (dièse) sont considérées comme des commentaires et sont ignorées.

Tout ceci vous semble probablement confus pour l'instant, mais cela va devenir clair à l'examen du fichier rules que dh_make donne par défaut. Vous pouvez aussi lire « info make » pour plus d'informations.


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 # -*- makefile -*-
      3 # Exemple de debian/rules utilisant debhelper.
      4 # Ce fichier a initialement été écrit par Joey Hess et Craig Small.
      5 # En tant qu'exception particulière, lorsque ce fichier est copié
      6 # par dh-make dans un fichier de sortie dh-make, vous pouvez
      7 # utiliser ce fichier sans restriction. Cette exception particulière
      8 # a été ajoutée par Craig Small dans la version 0.37 de dh-make.
      9
     10 # Décommentez la ligne suivante pour le mode volubile.
     11 #export DH_VERBOSE=1
     12
     13 %:
     14        dh $@

(Les numéros de ligne ont été ajoutés. Dans le vrai fichier rules, le grand espace 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 11 peut être décommentée pour configurer la variable DH_VERBOSE à 1. Dans ce cas, la commande dh indiquera quelles commandes dh_* elle exécute. Vous pouvez également ajouter ici une ligne« export DH_OPTIONS=-v ». Dans ce cas, chaque commande dh_* indiquera quelles commandes elle exécute. Ceci 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 un élément essentiel des outils debhelper et ne vous cache rien.

Tout le travail est réalisé aux lignes 13 et 14. Le caractère pourcent (« % ») représente toutes les cibles qui appellent alors un seul programme, dh avec le nom de la cible. [21] La commande dh est un script d'emballage qui exécute les séquences opportunes de programmes dh_* dépendant de ses paramètres : [22]

Le rôle des commandes dh_* est presque évident d'après leur nom. [24] Les plus remarquables d'entre-elles valent la peine d'en faire ici une présentation (très) simplifiée, dans l'hypothèse d'un environnement de construction basé sur Makefile : [25]

Les cibles ayant besoin de la commande fakeroot contiennent dh_testroot. Si vous ne vous faites pas passer pour le superutilisateur lors de l'utilisation de cette commande, elle se terminera en erreur.

Le plus important à propos du fichier rules créé par dh_make, c'est qu'il s'agit d'une simple 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. Les seules choses à ne pas pas changer sont les noms des règles, car tous les outils utilisent ces noms, conformément à la Charte.

Bien que la cible « install » ne soit pas obligatoire, elle est gérée. « 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 : [28]

Pour les sources utilisant Autotools, la combinaison « dh --with autotools-dev --with autoreconf $@ » est la plus courante avec le système de construction GNU.

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. Voir Autres fichiers dans le répertoire debian, Chapitre 5 et la page de manuel de chaque commande pour la personnalisation de telles fonctionnalités.

Certaines commandes dh_* invoquées par la nouvelle commande dh doivent parfois utiliser des paramètres, exécuter des commandes supplémentaires, ou être ignorées. Pour ce faire, créez une cible override_dh_toto avec sa règle dans le fichier rules uniquement pour la commande dh_toto à remplacer. Son rôle est fondamentalement de dire « exécute-moi à la place ». [30]

Les commandes dh_auto_* ont tendance à en faire plus que ce ce qui a été présenté (très) simplement, pour prendre en compte toutes les situations délicates. L'utilisation d'une commande équivalente simplifiée à la place de celles des cibles override_dh_* (à part pour la cible override_dh_auto_clean) est une mauvaise idée qui risque de détruire les fonctionnalités intelligentes de debhelper.

Pour conserver les données de configuration du paquet gentoo dans le répertoire /etc/gentoo plutôt que dans le répertoire consacré /etc, il suffit de remplacer l'option --sysconfig=/etc donnée par la commande dh_auto_configure à la commande ./configure avec : [31]

     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 à la commande ./configure puisqu'elle remplacera seulement l'option --sysconfig et conservera les autre options pertinentes de la commande ./configure.

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

     override_dh_auto_build:
             dh_auto_build -- build

Ceci garanti d'exécuter $(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 à la place des cibles distclean ou clean dans le fichier Makefile, vous pouvez créer une cible override_dh_auto_clean pour ce faire.

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

     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 Cibles du fichier rules, Section 4.4.1 (à part get-orig-source) peut être rendue difficile. Veuillez limiter les cibles explicites aux cibles override_dh_*, et à celle complètement indépendantes, si possible.


[ 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