Ubuntu logo

Packaging Guide

2. Aperçu élémentaire du dossier debian/

Cet article va vous expliquer brièvement les différents fichiers importants pour l’empaquetage des paquets Ubuntu, contenus dans le répertoire debian/. Les plus importants d’entre eux sont changelog, control, copyright et rules. Ceux-ci sont nécessaires pour tous les paquets. Certains fichiers supplémentaires dans debian/ peuvent être utilisés afin de personnaliser et de configurer le comportement du paquet. Certains de ces fichiers sont décrits dans cet article, mais il n’est pas censé constituer une liste exhaustive.

2.1. Le changelog

Ce fichier est, comme son nom l’indique, une liste des modifications apportées à chaque version. Il possède un format spécifique donnant le nom du paquet, la version, la distribution, les modifications, et qui les a apportées à un moment donné. Si vous avez une clé GPG (voir : Obtenir configuration), assurez-vous d’utiliser les mêmes nom et adresse email dans le changelog que dans votre clé. Ce qui suit est un modèle de changelog :

package (version) distribution; urgency=urgency

 * change details
  - more change details
 * even more change details

-- maintainer name <email address>[two spaces]  date

Le format (particulièrement celui de la date) est important. La date doit être au format RFC 5322, obtenu en utilisant la commande date -R. Pour plus de commodité, la commande dch est utilisée pour éditer le changelog. Elle mettra automatiquement la date à jour.

Les points mineurs sont indiquées par un tiret “-”, tandis que les points majeurs utilisent un astérisque “*”.

Si vous êtes parti de zéro pour l’empaquetage, dch --create (dch est dans le paquet devscripts) vous créera un debian /changelog standard.

Voici un exemple de fichier changelog pour bonjour:

hello (2.8-0ubuntu1) trusty; urgency=low

  * New upstream release with lots of bug fixes and feature improvements.

-- Jane Doe <packager@example.com>  Thu, 21 Oct 2013 11:12:00 -0400

Notez que la version comporte un -0ubuntu1 annexé, c’est la révision de la distribution, utilisée de telle sorte que l’empaquetage peut être mis à jour (pour par exemple corriger des bogues) avec de nouveaux ajouts dans la même version de la source.

Ubuntu et Debian ont des systèmes légèrement différents d’incrémentation de version de paquets pour éviter que des paquets issus d’une source de même version entrent en conflit. Lorsqu’un paquet Debian a été modifié dans Ubuntu, il présente un ubuntuX (où X est le numéro de révision Ubuntu) annexé à la fin de la version Debian. Donc, si le paquet Debian hello 2.6-1 a été modifié par Ubuntu, la chaîne de version indiquera 2.6-1ubuntu1. Si ce paquet pour l’application n’existe pas dans Debian, la révision Debian est 0 (par exemple, hello 2.6-0ubuntu1).

For further information, see the changelog section (Section 4.4) of the Debian Policy Manual.

2.2. Le fichier de contrôle.

Le fichier control contient les informations que les gestionnaires de paquets (comme apt-get, synaptic ou adept) utilisent, les moments de construction des dépendances, les informations concernant les mainteneurs et plus encore.

Pour le paquet hello de Ubuntu, le fichier control ressemble à ceci :

Source: hello
Section: devel
Priority: optional
Maintainer: Ubuntu Developers <ubuntu-devel-discuss@lists.ubuntu.com>
XSBC-Original-Maintainer: Jane Doe <packager@example.com>
Standards-Version: 3.9.5
Build-Depends: debhelper (>= 7)
Vcs-Bzr: lp:ubuntu/hello
Homepage: http://www.gnu.org/software/hello/

Package: hello
Architecture: any
Depends: ${shlibs:Depends}
Description: The classic greeting, and a good example
 The GNU hello program produces a familiar, friendly greeting. It
 allows non-programmers to use a classic computer science tool which
 would otherwise be unavailable to them. Seriously, though: this is
 an example of how to do a Debian package. It is the Debian version of
 the GNU Project's `hello world' program (which is itself an example
 for the GNU Project).

Le premier paragraphe décrit le paquet source, y compris la liste des paquets nécessaires pour construire le paquet depuis son source dans le champ Build-Depends. Il contient également des méta-informations comme le nom du mainteneur, la version de la Charte Debian à laquelle le paquet se conforme, l’emplacement du dépôt du contrôle de version de l’empaquetage et la page d’accueil en amont.

Note that in Ubuntu, we set the Maintainer field to a general address because anyone can change any package (this differs from Debian where changing packages is usually restricted to an individual or a team). Packages in Ubuntu should generally have the Maintainer field set to Ubuntu Developers <ubuntu-devel-discuss@lists.ubuntu.com>. If the Maintainer field is modified, the old value should be saved in the XSBC-Original-Maintainer field. This can be done automatically with the update-maintainer script available in the ubuntu-dev-tools package. For further information, see the Debian Maintainer Field spec on the Ubuntu wiki.

Chaque paragraphe supplémentaire décrit un paquet binaire à compiler.

For further information, see the control file section (Chapter 5) of the Debian Policy Manual.

2.4. Le fichier des règles

Le dernier fichier que nous devons examiner est rules. Il complète tout le travail de création de notre paquet. Il s’agit d’un Makefile ayant pour objectifs de compiler et d’installer l’application, puis de créer le fichier .deb à partir des fichiers installés. Il a également pour objectif de nettoyer tous les fichiers de construction de telle sorte que vous vous retrouvez au final uniquement avec un paquet source.

Voici une version simplifiée du fichier de règles créé par dh_make (qui peut être trouvé dans le paquet dh-make):

#!/usr/bin/make -f
# -*- makefile -*-

# Uncomment this to turn on verbose mode.
#export DH_VERBOSE=1

%:
       dh  $@

Passons ce fichier en revue de détails. Tout ce qu’il fait est de passer chaque cible construite qu’appelle ce debian/rules comme argument à /usr/bin/dh, qui appelle lui-même toutes les commandes dh_* nécessaires.

dh exécute une séquence de commandes de debhelper. Les séquences prises en charge correspondent aux objectifs du fichier « debian/rules » : « build », « clean », « install », « binary-arch », « binary-indep » et « binary ». Afin de voir quelles commandes sont lancées dans chaque cible, exécutez :

$ dh binary-arch --no-act

Les commandes de la séquence binary-indep sont passées avec l’option « -i » pour s’assurer qu’elles ne fonctionnent que sur des paquets binaires indépendants, et les commandes de la séquence binary-arch sont passées avec l’option « -a » pour s’assurer qu’elles ne fonctionnent que sur les paquets dépendants de l’architecture.

Chaque commande debhelper s’enregistrera après une exécution réussie dans debian/package.debhelper.log. (Que dh_clean efface.) Ainsi, dh peut révéler quelles commandes ont déjà été exécutées, pour quels paquets, et ignorera une nouvelle instance d’exécution de ces commandes.

A chaque exécution de dh, il examine le journal, et retrouve les dernières commandes historisées dans une séquence spécifiée. Il continue ensuite avec la commande suivante de la séquence. Les options --until, --before, --after, et --remaining modifient ce comportement.

Si debian/rules contient une cible nommée override_dh_command, alors quand il arrive à cette commande de la séquence, dh traitera cette cible à partir du fichier de règles, plutôt que de lancer la commande réelle. La cible modifiée peut ensuite exécuter la commande avec des options supplémentaires, ou exécuter des commandes complètement différentes à la place. (Notez que pour utiliser cette fonctionnalité, vous devez construire les dépendances à partir de debhelper 7.0.50 ou supérieur.)

Jetez un œil à usr/share/doc/debhelper/examples/ et man dh pour plus d’exemples. Voir également la section rules (Section 4.9) de la Charte Debian.

2.5. Les fichiers additionnels

2.5.1. Le fichier d’installation

Le fichier install est utilisé par dh_install pour installer les fichiers dans le paquet binaire. Il s’utilise classiquement dans deux cas :

  • Pour installer des fichiers dans votre paquet lorsqu’ils ne sont pas gérés par le système de construction en amont.

  • Fractionner un important et unique paquet source en plusieurs paquets binaires.

Dans le premier cas, le fichier install doit comporter une ligne par fichier installé, en précisant à la fois le fichier et le répertoire d’installation. Par exemple, le fichier install suivant installera le script foo dans le répertoire racine du paquet source de usr/bin et un fichier desktop dans le répertoire debian de usr/share/applications :

foo usr/bin
debian/bar.desktop usr/share/applications

Lorsqu’un paquet source produit plusieurs paquets binaires dh va installer les fichiers dans debian/tmp plutôt que directement dans debian/<paquet>. Les fichiers installés dans debian/tmp peuvent alors être déplacés en paquets binaires séparés en utilisant plusieurs fichiers $package_name.install. Cela est couramment utilisé pour sortir de grandes quantités de données indépendantes de l’architecture hors de paquets dépendants de l’architecture ainsi qu’à l’intérieur de paquets Architecture : all. Dans ce cas, seul le nom des fichiers (ou des répertoires) à installer sont nécessaires, en omettant le répertoire d’installation. Par exemple, foo.install contenant uniquement des fichiers dépendants de l’architecture pourrait ressembler à :

usr/bin/
usr/lib/foo/*.so

Alors que le foo-common.install contenant uniquement des fichiers indépendants de l’architecture pourrait ressembler à :

/usr/share/doc/
/usr/share/icons/
/usr/share/foo/
/usr/share/locale/

Cela créera deux paquets binaires, `` foo`` et foo-common. Les deux exigeraient leur propre paragraphe dans debian/control.

Voir man dh_install et la section du fichier install (Section 5.11) du Nouveau Guide des Mainteneurs Debian pour plus de détails.

2.5.2. Le fichier watch

Le fichier debian/watch nous permet de vérifier automatiquement les nouvelles versions amont en utilisant l’outil uscan se trouvant dans le paquet devscripts. La première ligne du fichier doit être la version du format (3, au moment d’écrire ces lignes), tandis que les lignes suivantes contiennent des URL à analyser. Par exemple:

version=3

http://ftp.gnu.org/gnu/hello/hello-(.*).tar.gz

L’exécution de uscan dans le répertoire racine source ira comparer le numéro de version amont dans debian/changelog avec celui de la dernière version amont disponible. Si une nouvelle version amont est trouvée, elle sera automatiquement téléchargée. Par exemple :

$ uscan
hello: Newer version (2.7) available on remote site:
  http://ftp.gnu.org/gnu/hello/hello-2.7.tar.gz
  (local version is 2.6)
hello: Successfully downloaded updated package hello-2.7.tar.gz
    and symlinked hello_2.7.orig.tar.gz to it

If your tarballs live on Launchpad, the debian/watch file is a little more complicated (see Question 21146 and Bug 231797 for why this is). In that case, use something like:

version=3
https://launchpad.net/flufl.enum/+download http://launchpad.net/flufl.enum/.*/flufl.enum-(.+).tar.gz

Pour plus d’informations, consultez man uscan et la section fichier watch (Section 4.11) de la Charte Debian.

Pour une liste de paquets où les fichiers de rapport watch ne sont pas synchronisés avec l’amont, voir Etat de santé externe Ubuntu.

2.5.3. Le fichier source/format

Ce fichier indique le format du paquet source. Il doit contenir une seule ligne indiquant le format désiré :

  • 3.0 (native) pour les paquets Debian natifs (pas de version amont)

  • 3.0 (quilt) pour les paquets avec une archive séparée en amont

  • 1.0 pour les paquets souhaitant déclarer explicitement le format par défaut

Actuellement, le format de paquet source sera 1.0 par défaut si ce fichier n’existe pas. Vous pouvez rendre cela explicite dans le fichier source/format. Si vous choisissez de ne pas utiliser ce fichier pour définir le format de la source, Lintian vous avertira de ce fichier manquant. Cet avertissement est purement informatif et peut être ignoré en toute sécurité.

Nous vous encourageons à utiliser le nouveau format de source 3.0. Il fournit un certain nombre de nouvelles fonctionnalités :

  • Prise en charge de formats de compression supplémentaires : bzip2, lzma et xz

  • Prise en charge de plusieurs archives amont

  • Il n’est pas nécessaire de rempaqueter l’archive amont pour dépouiller le répertoire debian

  • Les changements spécifiques à Debian ne sont plus stockés dans un seul fichier .diff.gz, mais dans plusieurs correctifs compatibles avec quilt dans debian/patches/

https://wiki.debian.org/Projects/DebSrc3.0 summarizes additional information concerning the switch to the 3.0 source package formats.

See man dpkg-source and the source/format section (Section 5.21) of the Debian New Maintainers’ Guide for additional details.

2.6. Ressources supplémentaires

In addition to the links to the Debian Policy Manual in each section above, the Debian New Maintainers’ Guide has more detailed descriptions of each file. Chapter 4, “Required files under the debian directory” further discusses the control, changelog, copyright and rules files. Chapter 5, “Other files under the debian directory” discusses additional files that may be used.