Chapitre 2. Premiers pas

Table des matières

2.1. Processus de construction de paquet Debian
2.2. Choix du programme
2.3. Obtenir le programme et l'essayer
2.4. Systèmes de construction simples
2.5. Systèmes de construction portables répandus
2.6. Nom et version de paquet
2.7. Configuration de dh_make
2.8. Paquet Debian non natif initial

Commencez par créer votre propre paquet (ou, encore mieux, par en adopter un).

Si vous faites un paquet Debian à partir d'un programme amont, le processus typique de construction de paquet Debian implique de créer plusieurs fichiers au nom spécifique pour chaque étape comme suit :

Veuillez remarquer que le caractère séparant paquet de version a été modifié : le tiret (-) dans le nom de l'archive source a été remplacée par un tiret bas (_) dans les noms de fichier de paquet Debian.

Dans les noms de fichier précédents, la partie paquet du nom de fichier est remplacé par le nom du paquet, la partie version par la version amont, la partie révision par la révision Debian et la partie arch par l'architecture du paquet, conformément à la Charte Debian. [5]

Chaque étape de ces grandes lignes sera expliquée avec des exemples détaillés dans les sections suivantes.

Vous avez probablement choisi le paquet que vous voulez créer. La première chose à faire est de vérifier si le paquet ne se trouve pas déjà dans l'archive de la distribution en utilisant ce qui suit :

Si le paquet existe déjà, et bien, installez-le :-). S'il se trouve qu'il est orphelin (c'est à dire si son responsable est Debian QA Group), vous devriez pouvoir le reprendre s'il est toujours disponible. Vous pouvez aussi adopter un paquet dont le responsable a rempli une demande d'adoption (« Request for Adoption » ou RFA).[6]

Plusieurs ressources d'état de propriété de paquet Debian existent :

En remarque, il est important de souligner que Debian possède déjà des paquets pour quasiment tous les types de programme, et que le nombre de paquets déjà dans l'archive Debian est bien plus important que le nombre de personnes ayant les droits suffisants pour envoyer les mises à jour. Par conséquent, contribuer aux paquets existants déjà dans l'archive est bien plus apprécié (avec plus de chances d'être parrainé) des autres développeurs [7]. Il est possible de contribuer de plusieurs façons comme suit :

If you are able to adopt the package, get the sources (with something like apt-get source packagename) and examine them. This document unfortunately doesn't include comprehensive information about adopting packages. Thankfully you shouldn't have a hard time figuring out how the package works since someone has already done the initial setup for you. Keep reading, though; a lot of the advice below will still be applicable to your case.

Si le paquet est nouveau, et que vous aimeriez le voir dans Debian, procédez comme suit :

  • d'abord, assurez-vous que le programme fonctionne, et essayez-le pendant quelques temps pour confirmer son utilité ;

  • You must check that no one else is already working on the package on the Work-Needing and Prospective Packages site. If no one else is working on it, file an ITP (Intent To Package) bug report to the wnpp pseudo-package using reportbug. If someone's already on it, contact them if you feel you need to. If not — find another interesting program that nobody is maintaining.

  • le logiciel doit avoir une licence :

    • pour la section main (principale), la Charte Debian exige qu'il soit totalement conforme aux principes du logiciel libre selon Debian (« Debian Free Software Guidelines » ou DFSG) et qu’il ne dépende pas de paquets hors de main pour la compilation ou l'exécution. C'est le cas idéal ;

    • pour la section contrib (contributions), il doit être conforme à tous les DFSG mais peut dépendre de paquets hors de main pour la compilation ou l'exécution ;

    • pour la section non-free (non libre), il peut être non conforme aux DFSG mais doit être distribuable ;

    • en cas de doute sur la section à laquelle il devrait appartenir, envoyez la licence sur debian-legal@lists.debian.org et demandez conseil ;

  • The program should not introduce security and maintenance concerns into the Debian system.

    • The program should be well documented and its code needs to be understandable (i.e., not obfuscated).

    • vous devriez contacter les auteurs du programme pour vérifier qu'ils sont d'accord pour la création du paquet et bienveillants envers Debian. Il est important de pouvoir consulter les auteurs en cas de problèmes spécifiques au programme, n'essayez donc pas de créer un paquet à partir d'un logiciel non maintenu ;

    • le programme ne devrait certainement pas être exécuté setuid root, ou encore mieux, il ne devrait pas être setuid ou setgid pour quoi que ce soit ;

    • le programme ne devrait ni être un démon, ni s'installer dans un répertoire */sbin, ni ouvrir un port en tant que superutilisateur.

Of course, the last one is just a safety measure, and is intended to save you from enraging users if you do something wrong in some setuid daemon… When you gain more experience in packaging, you'll be able to package such software.

En tant que nouveau responsable vous devriez acquérir de l'expérience dans l'empaquetage de paquets plus faciles plutôt que de créer des paquets compliqués :

  • paquets simples :

    • paquet binaire unique, arch = all (collection de données comme par exemple des fonds d'écran) ;

    • paquet binaire unique, arch = all (exécutables écrits en langage interprété comme le shell POSIX) ;

  • paquet de complexité intermédiaire :

    • paquet binaire unique, arch = any (exécutables binaires ELF provenant de langages comme C ou C++) ;

    • plusieurs paquets binaires, arch = any + all (paquets pour exécutables binaires ELF et documentation) ;

    • sources amont dans un autre format que tar.gz ou tar.bz2 ;

    • sources amont contenant du contenu non distribuable ;

  • paquets plus compliqués :

    • paquet de module interpréteur utilisé par d'autres programmes ;

    • paquet de bibliothèque générique ELF utilisé par d'autres paquets ;

    • plusieurs paquets binaires dont un paquet de bibliothèque ELF ;

    • paquet source avec plusieurs sources amont ;

    • paquets de modules du noyau ;

    • paquets de correctifs du noyau ;

    • paquets avec des scripts du responsable non triviaux.

Ce n'est pas si difficile d'empaqueter des paquets plus compliqués, mais cela exige un peu plus de connaissances. Vous devriez chercher de l'aide particulière pour chaque fonctionnalité compliquée. Par exemple, certains langages ont leur propre sous-charte :

There is another old Latin saying: fabricando fit faber (practice makes perfect). It is highly recommended to practice and experiment with all the steps of Debian packaging with simple packages while reading this tutorial. A trivial upstream tarball, hello-sh-1.0.tar.gz, created as follows may offer a good starting point:[8]

$ mkdir -p hello-sh/hello-sh-1.0; cd hello-sh/hello-sh-1.0
$ cat > hello <<EOF
#!/bin/sh
# (C) 2011 Truc Bidule, GPL2+
echo "Bonjour !"
EOF
$ chmod 755 hello
$ cd ..
$ tar -cvzf hello-sh-1.0.tar.gz hello-sh-1.0

La première chose à faire est de trouver et télécharger le code source d'origine. Supposons que vous ayez déjà le fichier source pris sur la page web de l'auteur. Les sources pour les logiciels UNIX libres sont d'habitude distribués au format tar+gzip avec l'extension .tar.gz, ou au format tar+bzip2 avec l'extension .tar.bz2. Elles contiennent normalement un sous-répertoire nommé paquet-version avec toutes les sources dedans.

If the latest version of the source is available through a Version Control System (VCS) such as Git, Subversion, or CVS, you need to get it with git clone, svn co, or cvs co and repack it into tar+gzip format yourself by using the --exclude-vcs option.

Si les sources du programme sont disponibles dans un autre format d'archive (par exemple, le programme se termine par .Z ou .zip [9]), vous devriez le décompresser à l'aide des outils adéquats et le recompresser.

Si le programme est distribué avec du contenu non compatible avec les principes du logiciel libre selon Debian, vous devriez aussi le décompresser pour enlever ce contenu et le recompresser avec une version amont modifiée contenant dfsg.

Comme exemple, le programme nommé gentoo (un gestionnaire de fichiers utilisant GTK+) sera utilisé. [10]

Créez un sous-répertoire dans votre répertoire personnel nommé debian ou deb ou quoi que ce soit d'adéquat (par exemple le nom du programme, ~/gentoo, ferait l'affaire dans ce cas). Placez l'archive téléchargée dedans, et décompressez-la avec tar xzf gentoo-0.9.12.tar.gz. Assurez-vous qu'aucun message d'avertissement ne se produit, même sans importance, sinon les outils de décompression d'autres personnes pourraient ne pas gérer ces problèmes, et être incapables de les décompresser. La ligne de commande de votre interpréteur devrait ressembler à ceci :

$ mkdir ~/gentoo ; cd ~/gentoo
$ wget http://www.example.org/gentoo-0.9.12.tar.gz
$ tar xvzf gentoo-0.9.12.tar.gz
$ ls -F
gentoo-0.9.12/
gentoo-0.9.12.tar.gz

Maintenant vous avez un autre sous-répertoire, nommé gentoo-0.9.12. Allez dans ce répertoire et lisez attentivement la documentation fournie. Il s'agit généralement de fichiers nommés README*, INSTALL*, *.lsm ou *.html. Vous devez trouver les instructions pour compiler et installer le programme (elles supposent très probablement que vous voulez l'installer dans le répertoire /usr/local/bin ; ce n'est pas le cas, mais ce point sera traité plus tard en Section 3.3, « Installation des fichiers à leur emplacement »).

Vous devriez commencer la création du paquet avec un répertoire source complètement propre (originel), ou simplement avec les sources fraîchement décompressées.

Des programmes simples sont généralement fournis avec un fichier Makefile et peuvent être compilés en appelant simplement make. [11] Certains d'entre eux gèrent make check, qui exécute des vérifications internes. L'installation dans les répertoires de destination se fait normalement avec make install.

Maintenant, essayez de compiler et d'exécuter le programme, pour vous assurer qu'il fonctionne correctement et ne casse rien d'autre quand il est installé ou utilisé.

Sachez aussi que vous pouvez généralement utiliser make clean (ou mieux, make distclean) pour nettoyer le répertoire de compilation. Parfois, make uninstall peut être utilisé pour retirer tous les fichiers installés.

De nombreux logiciels libres sont écrits en C et C++. Beaucoup d'entre eux utilisent les Autotools ou CMake pour les rendre portables sur différentes architectures. Ces outils de construction doivent être utilisés pour créer les Makefile et d'autres fichiers sources nécessaires. Ensuite, de tels programmes sont construits en utilisant l'habituel make; make install.

Les Autotools sont les outils de construction GNU. Ils comprennent Autoconf, Automake, Libtool et gettext. Vous pouvez reconnaître de telles sources à l'aide des fichiers configure.ac, Makefile.am et Makefile.in. [12]

La première étape du travail des Autotools est généralement faite par les auteurs amont qui exécutent autoreconf -i -f dans le répertoire des sources et distribuent les fichiers créés avec les sources.

configure.ac-----+-> autoreconf -+-> configure
Makefile.am -----+        |      +-> Makefile.in
src/Makefile.am -+        |      +-> src/Makefile.in
                          |      +-> config.h.in
                      automake
                      aclocal
                      aclocal.m4
                      autoheader

Modifier les fichiers configure.ac et Makefile.am nécessite un peu de connaissance de autoconf et automake. Consultez info autoconf et info automake.

La deuxième étape du travail des Autotools est habituellement que les utilisateurs se procurent ces sources et exécutent ./configure && make dans le répertoire des sources pour compiler le programme en une commande exécutable binaire.

Makefile.in -----+                +-> Makefile -----+-> make -> binaire
src/Makefile.in -+-> ./configure -+-> src/Makefile -+
config.h.in -----+                +-> config.h -----+
                 |
  config.status -+
  config.guess --+

Vous pouvez modifier plein de choses dans le fichier Makefile ; vous pouvez, par exemple, modifier l'emplacement par défaut du répertoire d'installation en utilisant la commande ./configure --prefix=/usr.

Bien que ce ne soit pas nécessaire, mettre à jour configure et les autres fichiers avec autoreconf -i -f peut améliorer la compatibilité des sources. [13]

CMake est un système de construction alternatif. De tels sources peuvent être reconnus avec le fichier CMakeLists.txt.

Si le code source amont est distribué sous le nom de gentoo-0.9.12.tar.gz, vous pouvez prendre gentoo comme nom de paquet (source) et 0.9.12 comme version amont. Ces désignations seront aussi utilisées dans le fichier debian/changelog décrit plus loin dans Section 4.3, « changelog ».

Although this simple approach works most of the time, you may need to adjust package name and upstream version by renaming the upstream source to follow Debian Policy and existing convention.

You must choose the package name to consist only of lower case letters (a-z), digits (0-9), plus (+) and minus (-) signs, and periods (.). It must be at least two characters long, must start with an alphanumeric character, and must not be the same as existing packages. It is a good idea to keep its length within 30 characters. [14]

Si l'amont utilise quelques termes génériques comme test-suite comme nom, il vaut mieux les renommer pour identifier son contenu de façon explicite et éviter de polluer l'espace de nom. [15]

You should choose the upstream version to consist only of alphanumerics (0-9A-Za-z), plus signs (+), tildes (~), and periods (.). It must start with a digit (0-9). [16] It is good idea to keep its length within 8 characters if possible. [17]

If upstream does not use a normal versioning scheme such as 2.30.32 but uses some kind of date such as 11Apr29, a random codename string, or a VCS hash value as part of the version, make sure to remove them from the upstream version. Such information can be recorded in the debian/changelog file. If you need to invent a version string, use the YYYYMMDD format such as 20110429 as upstream version. This ensures that dpkg interprets later versions correctly as upgrades. If you need to ensure smooth transition to the normal version scheme such as 0.1 in the future, use the 0~YYMMDD format such as 0~110429 as the upstream version.

Les chaînes de version [18] peuvent être comparées en utilisant dpkg(1) comme suit :

$ dpkg --compare-versions ver1 op ver2

La règle de comparaison de version peut être résumée par :

  • les chaînes sont comparées en commençant par le début ;

  • les lettres sont plus grandes que les nombres ;

  • les nombres sont comparés comme des entiers ;

  • les lettres sont comparées dans l'ordre de leur code ASCII ;

  • des règles particulières sont appliquées pour les points (.), plus (+) et tildes (~) comme suit :

    0.0 < 0.5 < 0.10 < 0.99 < 1 < 1.0~rc1 < 1.0 < 1.0+b1 < 1.0+nmu1 < 1.1 < 2.0

Un cas délicat se produit quand une version amont gentoo-0.9.12-ReleaseCandidate-99.tar.gz est publiée comme une préversion de gentoo-0.9.12.tar.gz. Vous devez vous assurer que la mise à niveau fonctionne correctement en renommant les sources amont en gentoo-0.9.12~rc99.tar.gz.

Configurez les variables d'environnement de l'interpréteur de commandes $DEBEMAIL et $DEBFULLNAME de telle sorte que plusieurs outils de maintenance Debian identifient l’adresse électronique et le nom à utiliser pour les paquets : [19]

$ cat >>~/.bashrc <<EOF
DEBEMAIL="your.email.address@example.org"
DEBFULLNAME="Prénom Nom"
export DEBEMAIL DEBFULLNAME
EOF
$ . ~/.bashrc

Les paquets Debian normaux sont des paquets Debian non natifs réalisés à partir de programmes amont. Pour créer un paquet Debian non natif à partir d'une source amont gentoo-0.9.12.tar.gz, vous pouvez lui créer un paquet Debian non natif initial en appelant la commande dh_make comme suit :

$ cd ~/gentoo
$ wget http://www.example.org/gentoo-0.9.12.tar.gz
$ tar xvzf gentoo-0.9.12.tar.gz
$ cd gentoo-0.9.12
$ dh_make -f ../gentoo-0.9.12.tar.gz

Bien sûr, remplacez le nom de fichier par celui de votre archive source d'origine. [20] Consultez dh_make(8) pour plus de précisions.

You should see some output asking you what sort of package you want to create. Gentoo is a single binary package — it creates only one binary package, i.e., one .deb file — so we will select the first option (with the s key), check the information on the screen, and confirm by pressing ENTER. [21]

Cette exécution de dh_make crée une copie de l'archive amont en gentoo_0.9.12.orig.tar.gz dans le répertoire parent pour permettre ensuite la création d'un paquet source Debian non natif nommé debian.tar.gz plus tard :

$ cd ~/gentoo ; ls -F
gentoo-0.9.12/
gentoo-0.9.12.tar.gz
gentoo_0.9.12.orig.tar.gz

Veuillez remarquer deux caractéristiques du nom de fichier gentoo_0.9.12.orig.tar.gz :

  • le nom de paquet et la version sont séparés par le caractère tiret bas (_) ;

  • la chaîne .orig est insérée avant le .tar.gz.

Vous devriez aussi remarquer que de nombreux fichiers modèles sont créés dans les sources sous le répertoire debian. Ce sera expliqué en Chapitre 4, Fichiers nécessaires dans le répertoire debian et Chapitre 5, Autres fichiers dans le répertoire debian. Vous devriez aussi comprendre que l'empaquetage ne peut pas être un processus complètement automatisé. Vous aurez à modifier les sources amont pour Debian (consultez Chapitre 3, Modification du code source). Après cela, vous devez utiliser les méthodes correctes pour construire les paquets Debian (Chapitre 6, Construction du paquet), les vérifier (Chapitre 7, Contrôle des erreurs du paquet) et les envoyer (Chapitre 9, Envoi de paquet). Toutes ces étapes seront expliquées.

Si vous effacez par mégarde quelques fichiers modèles en travaillant dessus, vous pouvez les retrouver en exécutant de nouveau dh_make avec l'option --addmissing dans une arborescence de paquet Debian.

La mise à jour d'un paquet existant peut devenir compliquée puisqu'il pourrait utiliser d'anciennes techniques. Lors de l'apprentissage des bases, veuillez vous en tenir aux cas d'empaquetage récent ; des explications sont données plus loin en Chapitre 8, Mise à jour de paquet.

Please note that the source file does not need to contain any build system discussed in Section 2.4, « Systèmes de construction simples » and Section 2.5, « Systèmes de construction portables répandus ». It could be just a collection of graphical data, etc. Installation of files may be carried out using only debhelper configuration files such as debian/install (see Section 5.11, « install »).



[4] Les paquets source Debian non natifs au style plus ancien de format 1.0 utilisent à la place paquet_version-révision.diff.gz.

[5] Consultez 5.6.1 « Source », 5.6.7 « Paquet » et 5.6.12 « Version ». L'architecture du paquet doit suivre la Charte Debian, 5.6.8 « Architecture » et est automatiquement attribuée par le processus de construction du paquet.

[7] Cela dit, il existera toujours des paquets qui vaudront la peine d'être empaquetés.

[8] Ne vous inquiétez pas du Makefile manquant. Vous pouvez installer la commande hello en utilisant simplement debhelper comme en Section 5.11, « install », ou en modifiant le source amont pour ajouter un nouveau Makefile avec la cible install comme en Chapitre 3, Modification du code source.

[9] Vous pouvez identifier le format de l'archive en utilisant la commande file si l'extension du fichier ne suffit pas.

[10] Ce programme est déjà empaqueté. La version actuelle utilise Autotools comme structure de construction et est substantiellement différente des exemples suivants qui étaient basés sur la version 0.9.12.

[11] Many modern programs come with a script named configure, which when executed creates a Makefile customized for your system.

[12] Autotools is too big to deal with in this small tutorial. This section is meant to provide keywords and references only. Please make sure to read the Autotools Tutorial and the local copy of /usr/share/doc/autotools-dev/README.Debian.gz, if you need to use it.

[13] Vous pouvez automatiser ce processus en utilisant le paquet dh-autoreconf. Consultez Section 4.4.3, « Personnalisation du fichier rules ».

[14] La longueur par défaut du champ de nom de paquet dans aptitude est de 30 caractères. Plus de 90 % des paquets ont un nom de paquet inférieur à 24 caractères.

[15] If you follow the Debian Developer's Reference 5.1. "New packages", the ITP process will usually catch this kind of issue.

[16] Cette règle plus stricte devrait permettre d'éviter toute confusion de noms de fichier.

[17] La longueur par défaut du champ de version dans aptitude est de 10 caractères. La révision Debian précédée par un tiret en utilise au moins 2. Plus de 80 % des paquets ont une version amont inférieure à 8 caractères et une révision Debian inférieure à 2 caractères. Plus de 90 % des paquets ont une version amont inférieure à 10 caractères et une révision Debian inférieure à 3 caractères.

[18] Les chaînes de version peuvent être version amont (version), révision Debian (révision) ou version (version-révision). Consultez Section 8.1, « Nouvelle révision Debian » pour la façon dont la révision Debian est incrémentée.

[19] Le texte qui suit présuppose que l'interpréteur de commandes que vous utilisez à la connexion est Bash. Si vous utilisez un autre interpréteur de commandes, par exemple zsh, il est nécessaire d'utiliser le fichier de configuration correspondant au lieu de ~/.bashrc.

[20] If the upstream source provides the debian directory and its contents, run the dh_make command with the extra option --addmissing. The new source 3.0 (quilt) format is robust enough not to break even for these packages. You may need to update the contents provided by the upstream version for your Debian package.

[21] Il y a plusieurs choix à ce moment : s pour un seul paquet binaire, i pour un paquet binaire indépendant de l'architecture, m pour plusieurs paquets binaires, l pour un paquet de bibliothèque, k pour un paquet de module du noyau, n pour un paquet de correctif du noyau et b pour un paquet cdbs. Ce document se concentre sur l'utilisation de la commande dh (du paquet debhelper) pour créer un seul paquet binaire, mais effleure aussi son utilisation pour les paquets binaires indépendants de l'architecture ou de plusieurs paquets binaires. Le paquet cdbs propose une autre infrastructure de scripts de paquet que la commande dh et sort du cadre de ce document.