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


Guide du nouveau responsable Debian
Chapitre 4 - Ce qui est requis sous debian/


Il y a un nouveau sous-répertoire sous le répertoire des sources du programme (« gentoo-0.9.12 »), nommé « debian ». Il y a un certain nombre de fichiers dans ce répertoire que vous devriez éditer pour configurer le comportement du paquet. Les plus importants d'entre eux sont « control », « changelog », « copyright » et « rules », qui sont requis pour tous les paquets.


4.1 Fichier « control »

Ce fichier contient plusieurs valeurs que dpkg, dselect et d'autres outils de gestions de paquets vont utiliser pour gérer le paquet.

Voici le fichier « control » que dh_make crée pour nous.

       1  Source: gentoo
       2  Section: unknown
       3  Priority: optional
       4  Maintainer: Josip Rodin <joy-mg@debian.org>
       5  Build-Depends: debhelper (>> 3.0.0)
       6  Standards-Version: 3.6.2
       7
       8  Package: gentoo
       9  Architecture: any
       10 Depends: ${shlibs:Depends}
       11 Description: <insert up to 60 chars description>
       12  <insert long description, indented with spaces>

(J'ai ajouté les numéros de ligne.)

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 dans laquelle ce paquet va.

Comme vous l'avez constaté, 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). Sous celles-ci, il y a des sous-sections logiques qui décrivent de manière concise les paquets qui s'y trouvent. Ainsi nous avons « admin » pour les programmes réservés à l'administrateur, « base » pour les outils de base, « devel » pour les outils de programmation, « doc » pour la documentation, « libs » pour les bibliothèques « mail » pour les lecteurs et les démons de courriel, « net » pour les applications et démons réseaux, « x11 » pour les programmes X11 qui ne sont pas plus appropriés ailleurs, et bien d'autres.

Changeons donc la section en x11 (le préfixe « main/ » est implicite, donc nous pouvons l'omettre).

La ligne 3 décrit l'importance pour l'utilisateur d'installer ce paquet. Lisez la Charte Debian pour des informations sur ces valeurs. La priorité « optional » marche habituellement pour les nouveaux paquets.

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

Comme c'est un paquet de priorité normale et qu'il n'entre pas en conflit avec quoi que ce soit, nous le laissons à « optional ».

La ligne 4 est le nom et l'adresse électronique du responsable. Assurez-vous que ce champ contient un en-tête « To: » valide pour un courrier électronique, car après le téléchargement, le système de suivi des bogues l'utilisera pour vous délivrer les courriels de bogues. Évitez d'utiliser des virgules, esperluètes (« & ») ou parenthèses.

La ligne 5 contient la liste des paquets nécessaires pour construire le paquet. Certains paquets comme gcc ou make sont implicites, voyez le paquet build-essential pour les détails. Si un compilateur non standard ou un autre outil est nécessaire pour construire le paquet, vous devez l'ajouter dans la ligne « Build-Depends ». Les différentes entrées sont séparées par des virgules ; lisez ci-dessous les explications sur les dépendances entre binaires pour mieux comprendre la syntaxe de ce champ.

Vous pouvez avoir aussi ici des champs Build-Depends-Indep, Build-Conflicts et d'autres champs. Ces données seront utilisées par le logiciel de construction de paquets automatique Debian pour créer les paquets binaires pour d'autres plates-formes d'ordinateurs. Lisez la Charte Debian pour plus d'informations sur les dépendances de construction et la Référence du Développeur pour plus d'informations sur ces autres plates-formes (architectures) et comment porter des logiciels vers celles-ci.

Voici une bidouille que vous pouvez utiliser pour découvrir les paquets dont le vôtre a besoin pour être construit :

       strace -f -o /tmp/log ./configure
       # ou make à la place de ./configure, si votre paquet n'utilise pas autoconf
       for x in `dpkg -S $(grep open /tmp/log|\
                           perl -pe 's!.* open\(\"([^\"]*).*!$1!' |\
                           grep "^/"| sort | uniq|\
                           grep -v "^\(/tmp\|/dev\|/proc\)" ) 2>/dev/null|\
                           cut -f1 -d":"| sort | uniq`; \
             do \
               echo -n "$x (>=" `dpkg -s $x|grep ^Version|cut -f2 -d":"` "), "; \
             done

Pour déterminer manuellement la dépendance de construction exacte pour /usr/bin/foo, vous exécuterez

       objdump -p /usr/bin/foo | grep NEEDED

et pour chaque bibliothèque listée, par exemple libfoo.so.6, exécutez

       dpkg -S libfoo.so.6

Ensuite vous prenez simplement la version -dev de chaque paquet comme entrée « Build-deps ». Si vous utilisez ldd à cet effet, il va rapporter les dépendances de bibliothèque indirectes, ayant pour résultat un problème de dépendances de constructions excessives.

Il se trouve que Gentoo a aussi besoin de xlibs-dev, libgtk1.2-dev et libgl1.2-dev pour être construit, aussi nous les ajouterons ici à côté de debhelper.

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

La ligne 8 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 9 décrit l'architecture CPU pour laquelle le paquet binaire peut être compilé. Nous le laissons à « any » car dpkg-gencontrol(1) trouvera la valeur appropriée pour toute machine sur laquelle ce paquet sera compilé.

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

La ligne 10 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:, 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 expliqué (voir dpkg(8), dselect(8), apt(8), aptitude(1), etc.).

Voici ce que les dépendances veulent dire :

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 symboles barre verticale | (symbole tube).

Le domaine d'application des champs peut être restreint à des versions particulières de chaque paquet nommé. Ces versions sont listé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 >> pour strictement plus petit, plus petit ou égal, exactement égal, plus grand ou égal et strictement plus grand, respectivement. Par exemple,

       Depends: foo (>= 1.2), libbar1 (= 1.3.4)
       Conflicts: baz
       Recommends: libbaz4 (>> 4.0.7)
       Suggests: quux
       Replaces: quux (<< 5), quux-foo (<= 7.6)

La dernière caractéristique que vous devez connaître est ${shlibs:Depends}. Lorsque votre paquet aura été construit et installé dans le répertoire temporaire, dh_shlibdeps(1) le scannera pour les exécutables et bibliothèques, déterminera leurs dépendances en bibliothèques partagées et détectera dans quels paquets elles se trouvent. Il passera la liste à dh_gencontrol(1) qui l'insérera à la bonne place, et vous ne devrez pas vous en soucier.

Ceci étant dit, nous pouvons laisser la ligne Depends: exactement comme elle est maintenant, et insérer après une ligne disant Suggests: file, car gentoo peut utiliser certaines fonctionnalités fournies par ce programme/paquet.

La ligne 11 est la description courte. L'écran de la plupart des gens est large de 80 colonnes, aussi cela ne devrait pas dépasser les 60 caractères. Je le change en « fully GUI configurable X file manager using GTK+ ».

À la ligne 12 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.

Finalement, voici le fichier control mis à jour :

       1  Source: gentoo
       2  Section: x11
       3  Priority: optional
       4  Maintainer: Josip Rodin <joy-mg@debian.org>
       5  Build-Depends: debhelper (>> 3.0.0), xlibs-dev, libgtk1.2-dev, libglib1.2-dev
       6  Standards-Version: 3.5.2
       7
       8  Package: gentoo
       9  Architecture: any
       10 Depends: ${shlibs:Depends}
       11 Suggests: file
       12 Description: fully GUI configurable GTK+ file manager
       13  gentoo is a file manager for Linux written from scratch in pure C. It
       14  uses the GTK+ toolkit for all of its interface needs.  gentoo provides
       15  100% GUI configurability; no need to edit config files by hand and re-
       16  start the program. gentoo supports identifying the type of various
       17  files (using extension, regular expressions, or the 'file' command),
       18  and can display files of different types with different colors and icons.
       19  .
       20  gentoo borrows some of its look and feel from the classic Amiga file
       21  manager "Directory OPUS" (written by Jonathan Potter).

(J'ai ajouté les numéros de ligne.)


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 (voir section 12.6 « Copyright Information »).

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

       1  This package was debianized by Josip Rodin <joy-mg@debian.org> on
       2  Wed, 11 Nov 1998 21:02:14 +0100.
       3
       4  It was downloaded from <fill in ftp site>
       5
       6  Upstream Author(s): <put author(s) name and email here>
       7
       8  Copyright:
       9
       10 <Must follow here>

(J'ai ajouté les numéros de ligne.)

Les choses importantes à ajouter à ce fichier sont l'endroit où vous avez trouvé ce paquet, ainsi que le copyright et la licence d'exploitation réelle (incluez-la en entier). Si la licence est une des licences de logiciel libre populaires comme GNU GPL ou LGPL, BSD 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.

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

       1  This package was debianized by Josip Rodin <joy-mg@debian.org> on
       2  Wed, 11 Nov 1998 21:02:14 +0100.
       3
       4  It was downloaded from: ftp://ftp.obsession.se/gentoo/
       5
       6  Upstream Author: Emil Brink <emil@obsession.se>
       7
       8  This software is copyright (c) 1998-99 by Emil Brink, Obsession
       9  Development.
       10
       11 You are free to distribute this software under the terms of
       12 the GNU General Public License.
       13 On Debian systems, the complete text of the GNU General Public
       14 License can be found in the file `/usr/share/common-licenses/GPL'.

(J'ai ajouté les numéros de ligne.)


4.3 changelog

C'est un fichier requis, qui a un format spécial décrit dans la Charte section 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 aussi important, puisqu'il est bon de documenter toutes les modifications que vous avez faites. Cela aidera les gens qui téléchargent votre paquet à voir s'il y a des problèmes non résolus à propos desquels ils doivent être immédiatement mis au courant. Il sera sauvé sous « /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.
       4
       5  -- Josip Rodin <joy-mg@debian.org>  Wed, 11 Nov 1998 21:02:14 +0100
       6

(J'ai ajouté les numéros de ligne.)

La ligne 1 est 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 », et l'urgence ne devrait pas être changée en quoique ce soit de plus haut que « low ». :-)

Les lignes 3 à 5 sont l'entrée d'audit, où vous documentez les modifications faites dans la révision du paquet (pas les modifications amont – il y a un fichier spécial pour cela, créé par les auteurs en amont, que vous installerez comme /usr/share/doc/gentoo/changelog.gz). Les nouvelles lignes doivent être ajoutées juste avant la première ligne qui commence avec une astérisque (« * »). Vous pouvez le faire avec dch(1), emacs(1), ou manuellement avec un éditeur de texte.

Vous obtiendrez quelque chose comme :

       1  gentoo (0.9.12-1) unstable; urgency=low
       2
       3   * Initial Release.
       4   * This is my first Debian package.
       5   * Adjusted the Makefile to fix $DESTDIR problems.
       6
       7  -- Josip Rodin <joy-mg@debian.org> Wed, 11 Nov 1998 21:02:14 +0100
       8

(J'ai ajouté les numéros de ligne.)

Vous pouvez en apprendre plus sur la mise à jour du fichier changelog plus loin dans Mettre à jour le paquet, Chapitre 9.


4.4 fichier « rules »

Maintenant nous devons examiner les règles que dpkg-buildpackage(1) va utiliser pour créer vraiment le paquet. Ce fichier est en fait un autre Makefile, mais différent de celui/ceux des sources amont. Contrairement aux autres fichiers sous debian/, celui-ci est marqué comme exécutable.

Chaque fichier « rules », comme tout autre Makefile, consiste en plusieurs règles indiquant comment manipuler les sources. Les règles sont des cibles, noms de fichiers ou d'actions à exécuter (par exemple, « build: » ou « install: »). Les règles que vous voulez exécuter doivent être données comme paramètre à la ligne de commande (par exemple, « rules build » ou « rules install »). Après le nom de la cible, vous pouvez nommer les dépendances, le programme ou le fichier dont la cible dépend. Après cela il peut y avoir un nombre quelconque de commandes indentées par <tab>, jusqu'à ce qu'une ligne vide soit trouvée. Une nouvelle règle commence avec une déclaration de cible dans 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 nous donne par défaut. Vous devriez avoir lu l'entrée « make » dans info pour plus d'information.

Ce qu'il faut savoir à propos du fichier rules créé par dh_make, est qu'il s'agit juste d'une suggestion. Il fonctionnera pour des paquets simples, mais pour ceux qui sont plus compliqués, vous ne devez pas craindre de le modifier pour le faire correspondre à vos besoins. Les seules choses que vous ne pouvez pas changer sont les noms des règles, car tous les outils utilisent ces noms comme requis par la Charte.

Voici (approximativement) ce à quoi ressemble le fichier par défaut debian/rules généré pour nous par dh_make :

       1  #!/usr/bin/make -f
       2  # Sample debian/rules that uses debhelper.
       3  # GNU copyright 1997 to 1999 by Joey Hess.
       4
       5  # Uncomment this to turn on verbose mode.
       6  #export DH_VERBOSE=1
       7
       8  # This is the debhelper compatibility version to use.
       9  export DH_COMPAT=4
       10 
       11 CFLAGS = -g
       12 ifneq (,$(findstring noopt,$(DEB_BUILD_OPTIONS)))
       13 CFLAGS += -O0
       14 else
       15 CFLAGS += -O2
       16 endif
       17
       18 build: build-stamp
       19 build-stamp:
       20        dh_testdir
       21
       22        # Add here commands to compile the package.
       23        $(MAKE)
       24        #docbook-to-man debian/gentoo.sgml > gentoo.1
       25
       26        touch build-stamp
       27
       28 clean:
       29        dh_testdir
       30        dh_testroot
       31        rm -f build-stamp
       32
       33        # Add here commands to clean up after the build process.
       34        -$(MAKE) clean
       35
       36        dh_clean
       37
       38 install: build
       39        dh_testdir
       40        dh_testroot
       41        dh_clean -k
       42        dh_installdirs
       43
       44        # Add here commands to install the package into debian/gentoo.
       45        $(MAKE) install DESTDIR=$(CURDIR)/debian/gentoo
       46
       47 # Build architecture-independent files here.
       48 binary-indep: build install
       49 # We have nothing to do by default.
       50
       51 # Build architecture-dependent files here.
       52 binary-arch: build install
       53        dh_testdir
       54        dh_testroot
       55 #      dh_installdebconf
       56        dh_installdocs
       57        dh_installexamples
       58        dh_installmenu
       59 #      dh_installlogrotate
       60 #      dh_installemacsen
       61 #      dh_installpam
       62 #      dh_installmime
       63 #      dh_installinit
       64        dh_installcron
       65        dh_installman
       66        dh_installinfo
       67 #      dh_undocumented
       68        dh_installchangelogs ChangeLog
       69        dh_link
       70        dh_strip
       71        dh_compress
       72        dh_fixperms
       73 #      dh_makeshlibs
       74        dh_installdeb
       75 #      dh_perl
       76        dh_shlibdeps
       77        dh_gencontrol
       78        dh_md5sums
       79        dh_builddeb
       80
       81 binary: binary-indep binary-arch
       82 .PHONY: build clean binary-indep binary-arch binary install

(J'ai ajouté les numéros de ligne. Dans le debian/rules réel, les espaces en début de ligne sont des codes TAB).

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 signification des variables DH_* mentionnées des lignes 6 à 9 devrait être évidente à partir du commentaire. Pour plus d'informations sur DH_COMPAT, lisez la section « Debhelper compatibility levels » de la page de manuel debhelper(1).

Les lignes 11 à 16 sont un squelette de support pour les paramètres DEB_BUILD_OPTIONS, décrits dans la Charte section 10.1 « Binaries ». Fondamentalement, ces choses déterminent si l'exécutable doit être construit avec les symboles de débogage, et s'ils doivent être retirés à l'installation. Une fois encore, il s'agit juste d'un squelette, une indication que vous devriez le faire. Vous devriez vérifier comment le système de construction amont gère l'inclusion des symboles de débogage, et comment il les retire à l'installation, et implémenter cela vous-même.

D'habitude, vous pouvez dire à gcc de compiler avec « -g » en utilisant la variable CFLAGS — si c'est le cas pour votre paquet, propagez la variable en ajoutant CFLAGS="$(CFLAGS)" à l'invocation de $(MAKE) dans la règle de construction (voir plus bas). Alternativement, si votre paquet utilise un script de configuration autoconf, vous pouvez la lui passer en préfixant la chaîne ci-dessus à l'appel de ./configure dans la règle de construction.

Pour ce qui est de retirer les symboles, les programmes sont configurés couramment pour s'installer avec, et souvent sans option pour changer cela. Heureusement, vous avez toujours dh_strip(1) qui détecte quand le drapeau DEB_BUILD_OPTIONS=nostrip est mis, et qui quitte silencieusement.

Les lignes 18 à 26 décrivent la règle « build » (et son enfant « build-stamp »), qui exécute make avec le fichier Makefile de l'application pour compiler le programme. Si votre paquet utilise les utilitaires GNU configure pour construire les exécutables, soyez absolument certain d'avoir lu /usr/share/doc/autotools-dev/README.Debian.gz. Nous en dirons plus sur l'exemple commenté docbook-to-man plus loin dans manpage.1.ex, manpage.sgml.ex, Section 5.8.

La règle « clean », spécifiée aux lignes 28 à 36, efface tous les binaires inutiles et les trucs générés automatiquement, laissés là par une construction du paquet. Cette règle doit être opérationnelle tout le temps (même si les répertoires sources sont nettoyés !), donc vous devriez utiliser les options pour forcer (par exemple pour rm, c'est « -f ») ou pour ignorer la valeur de retour (les échecs), avec un « - » devant le nom de la commande.

Le processus d'installation, la règle « install », commence à la ligne 38. Fondamentalement, elle exécute la règle install du fichier Makefile du programme, mais installe dans le répertoire $(CURDIR)/debian/gentoo – c'est pour cette raison que nous avons spécifié $(DESTDIR) comme racine de l'installation dans le Makefile de gentoo.

Comme le commentaire le laisse penser, la règle « binary-indep », sur la ligne 48, est utilisée pour construire des paquets indépendants de l'architecture. Comme il n'y en a pas dans cet exemple, rien n'est fait.

Ensuite on trouve la règle « binary-arch », des lignes 52 à 79, pour laquelle nous exécutons plusieurs petits utilitaires du paquet debhelper qui font quelques opérations sur votre paquet pour le rendre conforme à la Charte Debian.

Si votre paquet est un « Architecture: all », vous devez inclure toutes les commandes pour construire le paquet sous la règle « binary-indep », et laisser la règle « binary-arch » vide.

Les noms des programmes debhelper commencent par dh_ et la suite indique ce que chaque petit utilitaire fait. Tout cela est plutôt explicite, mais voici quelques explications supplémentaires :

Pour une information plus complète sur ce que font tous ces scripts dh_*, et ce que sont leurs options, lisez les pages de manuel respectives. Il y en a d'autres, potentiellement très utiles, qui ne sont pas mentionnés ici. Si vous en avez besoin, lisez la documentation de debhelper.

La section binary-arch est celle où vous devriez vraiment commenter ou retirer toutes les lignes qui appellent des fonctionnalités dont vous n'avez pas besoin. Pour gentoo, je commente les lignes concernant exemples, cron, init, man et info, simplement parce que gentoo n'en a pas besoin. De plus, à la ligne 68, je remplace « ChangeLog » par « FIXES », parce que c'est le nom du fichier des modifications amont.

Les deux dernières lignes (avec toutes celles qui ne sont pas expliquées ici) sont juste des choses plus ou moins nécessaires, à propos desquelles vous pouvez lire le manuel de make, et la Charte Debian. Pour l'instant il n'est pas important d'en savoir plus.


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


Guide du nouveau responsable Debian

version 1.2.3, 18 janvier 2005.

Josip Rodin joy-mg@debian.org

Mohammed Adnène Trojette adn+deb@diwi.org
et les membres de la liste debian-l10n-french@lists.debian.org
Frédéric Dumont (ancien traducteur) frederic.dumont@easynet.be