[ précédent ] [ Table des matières ] [ 1 ] [ 2 ] [ 3 ] [ 4 ] [ 5 ] [ 6 ] [ 7 ] [ 8 ] [ 9 ] [ 10 ] [ 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 <jrodin@jagor.srce.hr>
       5  Build-Depends: debhelper (>> 3.0.0)
       6  Standards-Version: 3.5.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 de 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 pas vraiment 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 (un 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 le manuel des Normes pour des informations sur ces valeurs. La priorité « optional » marche habituellement pour les nouveaux paquets.

Les sections et les priorités sont utilisés par des interfaces comme dselect quand elles trient les paquets et sélectionnent les défauts. Quand vous téléchargerez votre paquet sur Debian, la valeur 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 mél du responsable. Assurez-vous que ce champ contient une entête « To: » valide pour un courriel, 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 aussi avoir Build-Depends-Indep, Build-Conflicts et d'autres champs ici. Ces données seront utilisées par le logiciel de construction de paquets automatique Debian pour créer les paquets binaires pour d'autres plate-formes d'ordinateurs. Lisez le manuel des Normes pour plus d'informations sur les dépendances de construction et la Référence du Développeur pour plus d'information sur ces autres plate-formes (architectures) et comment porter des logiciels vers celles-ci.

Voici une bidouille que vous pouvez utiliser pour découvrir les paquets dont le votre 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

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 du standard de Normes Debian que ce paquet respecte, la version du manuel des Normes 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 ne doit pas être 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 tard 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. À part 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 restreints à 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}. Après que votre paquet ait é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 10 est celle où la liste de suggestions va. Ici on ne met que « file », parce que gentoo peut utiliser certaines capacités de ce programme/paquet.

La ligne 11 est la description courte. L'écran de la plupart de gens est large de 80 colonnes, aussi cela ne devrait pas dépasser les 60 caractères. Je le change en « A 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 <jrodin@jagor.srce.hr>
       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: A 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 amonts, le copyright et la licence du paquet. Le format n'est pas dicté par les Normes, mais son contenu l'est (voir section 13.6 « Copyright Information »).

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

       1  This package was debianized by Josip Rodin <jrodin@jagor.srce.hr> 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 <jrodin@jagor.srce.hr> 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 le manuel des Normes section 5.3 « 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 si 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 c'est à ceci qu'il ressemble :

       1  gentoo (0.9.12-1) unstable; urgency=low
       2
       3   * Initial Release.
       4
       5  -- Josip Rodin <jrodin@jagor.srce.hr>  Wed, 11 Nov 1998 21:02:14 +0100
       6
       7  Local variables:
       8  mode: debian-changelog
       9  End:

(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 <jrodin@jagor.srce.hr> 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 construire 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 argument à la ligne de commande (par exemple, 'rules build' ou 'rules install'). Après le nom de cible, vous pouvez nommer les dépendances, programme ou 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 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 le manuel des Normes.

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=3
        10
        11 ifneq (,$(findstring debug,$(DEB_BUILD_OPTIONS)))
        12         CFLAGS += -g
        13 endif
        14 ifeq (,$(findstring nostrip,$(DEB_BUILD_OPTIONS)))
        15         INSTALL_PROGRAM += -s
        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  #/usr/bin/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).

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 de la description courte. Pour plus d'information 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 les Normes section 11.1 « Binaries ». Fondamentalement, ces choses déterminent si l'exécutable doit être construit avec les symboles de débogage, et si ils devraient ê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 (vois 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 à ./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. 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 (p.e. 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 aux Normes 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 dans le manuel de make, et dans le manuel des Normes. 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 ] [ suivant ]

Guide du nouveau responsable Debian

version 1.2, 6 avril 2002.

Josip Rodin jrodin@jagor.srce.hr
Traducteur : Frédéric Dumont frederic.dumont@easynet.be