Chapitre 4. Fichiers nécessaires dans le répertoire debian

Ce fichier contient plusieurs valeurs utilisées par dpkg, dselect, apt-get, apt-cache, aptitude et d'autres outils de gestion de paquets pour gérer le paquet. Cela 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 <[email protected]>
 5 Build-Depends: debhelper (>=10)
 6 Standards-Version: 3.9.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 à 7 sont les informations de contrôle pour le paquet source. Les lignes 9 à 13 sont les informations de contrôle pour le paquet binaire.

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 plusieurs parties : main (logiciels libres), non-free (logiciels non libres), et contrib (logiciels libres qui dépendent de logiciels non libres). Chacune d'entre elles est divisée en sections qui classent les paquets en catégories grossières. Entre autres existent admin pour les programmes destinés aux administrateurs, 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. ^[28]

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

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

La ligne 5 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. ^[30] 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és par des virgules ; lisez ci-après les explications sur les dépendances entre paquets binaires pour mieux comprendre la syntaxe de ces lignes :

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

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 les architectures pour lesquelles le paquet binaire peut être compilé. Cette valeur est en général un des suivantes en fonction du type de paquet binaire : ^[32]

La ligne 10 est laissée telle quelle car c'est écrit en C. dpkg-gencontrol(1) indiquera la valeur d'architecture appropriée pour chaque machine sur laquelle ce paquet source 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 Section 4.4, « rules » 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é (consultez dpkg(8), dselect(8), apt(8), aptitude(1), etc.)

Voici une description simplifiée des relations entre paquets : ^[33]

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ées 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é. La restriction de chaque paquet particulier est indiquée entre parenthèses après son nom, et devrait contenir une relation dans la liste suivante suivie par une valeur de 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.

dh_shlibdeps(1) calcule les dépendances à des bibliothèques partagées pour les paquets binaires. Il crée une liste d'exécutables ELF et de bibliothèques partagées trouvées pour chaque paquet binaire. Cette liste est utilisée en remplacement de ${shlibs:Depends}.

dh_perl(1) calcule les dépendances de Perl. Il crée une liste de dépendances vers perl ou perlapi pour chaque paquet binaire. Cette liste est utilisée en remplacement de ${perl:Depends}.

Certaines commandes de debhelper peuvent rendre le paquet créé dépendant de paquets supplémentaires. Toutes ces commandes créent une liste de paquets nécessaires pour chaque paquet binaire. Cette liste est utilisée en remplacement de ${misc:Depends}.

dh_gencontrol(1) crée DEBIAN/control pour chaque paquet binaire en substituant ${shlibs:Depends}, ${perl:Depends}, ${misc:Depends}, etc.

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 9 est l'URL de la page d'accueil. Supposons qu'il s'agisse de http://www.obsession.se/gentoo/.

La ligne 12 est la description courte. Les terminaux sont larges de 80 colonnes par convention, aussi elle 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. ^[34]

Le champ Vcs-* pour documenter le système de gestion de versions (VCS) peut être inséré entre les lignes 6 et 7. ^[35] Considérons que le paquet gentoo a son VCS 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 <[email protected]>
 5 Build-Depends: debhelper (>=10), xlibs-dev, libgtk1.2-dev, libglib1.2-dev
 6 Standards-Version: 4.0.0
 7 Vcs-Git: https://anonscm.debian.org/git/collab-maint/gentoo.git
 8 Vcs-browser: https://anonscm.debian.org/git/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 an 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 utilizes the GTK+ toolkit
30  for its interface.

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

Ce fichier contient des renseignements sur le copyright et la licence des sources amont. La Charte Debian, 12.5 « Informations sur le copyright » impose son contenu et la DEP-5 : debian/copyright analysable automatiquement fournit des directives pour son format.

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

You must fill in missing information to complete this file, such as the place you got the package from, the actual copyright notice, and the license. For certain common free software licenses (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-2.0, 3-Clause BSD, CC0-1.0, MPL-1.1, MPL-2.0 or the Artistic license), you can just refer to the appropriate file in the /usr/share/common-licenses/ directory that exists on every Debian system. Otherwise, you must include the complete license.

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

 1 Format: https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
 2 Upstream-Name: gentoo
 3 Upstream-Contact: Emil Brink <[email protected]>
 4 Source: http://sourceforge.net/projects/gentoo/files/
 5
 6 Files: *
 7 Copyright: 1998-2010 Emil Brink <[email protected]>
 8 License: GPL-2+
 9
10 Files: icons/*
11 Copyright: 1998 Johan Hanson <[email protected]>
12 License: GPL-2+
13
14 Files: debian/*
15 Copyright: 1998-2010 Josip Rodin <[email protected]>
16 License: GPL-2+
17
18 License: GPL-2+
19  This program is free software; you can redistribute it and/or modify
20  it under the terms of the GNU General Public License as published by
21  the Free Software Foundation; either version 2 of the License, or
22  (at your option) any later version. 
23  .
24  This program is distributed in the hope that it will be useful,
25  but WITHOUT ANY WARRANTY; without even the implied warranty of
26  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
27  GNU General Public License for more details.
28  .
29  You should have received a copy of the GNU General Public License along
30  with this program; if not, write to the Free Software Foundation, Inc.,
31  51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
32  .
33  On Debian systems, the full text of the GNU General Public
34  License version 2 can be found in the file
35  '/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.

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=medium
2
3   * Initial release. (Closes: #nnnn)  <nnnn is the bug number of your ITP>
4
5  -- Josip Rodin <[email protected]>  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, et l'urgence devrait être en medium à moins qu’il n’existe une raison particulière pour une autre valeur.

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 juste en dessous de la première ligne qui commence avec une astérisque (*). Vous pouvez utiliser dch(1) pour le modifier. Vous pouvez éditer cela manuellement avec un éditeur de texte à condition de suivre les conventions de formatage utilisées par dch(1).

Pour éviter d'envoyer un paquet accidentellement avant qu'il ne soit terminé, il vaut mieux modifier la valeur de distribution à UNRELEASED qui n'est pas valable.

Vous obtiendrez quelque chose comme :

1  gentoo (0.9.12-1) UNRELEASED; 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 <[email protected]>  Mon, 22 Mar 2010 00:37:31 +0100
8

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

Une fois satisfait de toutes les modifications, correctement documentées dans changelog, vous devriez modifier la valeur de distribution d'UNRELEASED à la valeur de distribution cible unstable (ou même experimental). ^[36]

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

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.