Dans la distribution Debian, les paquets binaires sont générés à partir des sources Debian, qui sont dans un format spécial pour faciliter la construction automatique des binaires.
Il y avait une version précédente d'un format source Debian qui est obsolète. Les instructions pour convertir les vieux paquets sont données dans le manuel des principes Debian.
De nombreux outils sont fournis pour manipuler les paquets sources. Ils emballent et déballent les sources et aident à la construction des paquets binaires et à gérer la distribution des nouvelles versions.
Le manuel présente une introduction et un exemple d'utilisation courante de ces
outils, pour avoir de plus amples informations sur leurs options et leurs
opérations, voir dpkg-source(1)
.
Le paquet hello
est un exemple de construction de paquet source
Debian et de mise en oeuvre des utilitaires qui y sont impliqués.
Ce programme est fréquemment utilisé sur la ligne de commande, et est aussi
appelé à partir des scripts de construction automatique de paquet indépendant,
tel que dpkg-buildpackage
.
Pour extraire un paquet, on utilise:
dpkg-source -x ../chemin/du/fichier.dsc
Avec le fichier .tar.gz et le fichier .diff.gz (si c'est utile) dans le même répertoire. Il extrait un paquet package-version et s'il est présent un paquet package-version.orig dans le même répertoire.
Pour créer une paquet, on utilise:
dpkg-source -b package-version
Ceci créera les fichiers .dsc, .tar.gz et
.diff.gz (si c'est utile) dans le répertoire courant.
dpkg-source
n'efface pas l'arborescence des sources. Ceci doit
être fait séparément, si nécessaire.
Voir aussi Les paquets sources comme archives, Section 3.3.
dpkg-buidpackage
est un script qui fait appel à
dpkg-source
avec les règles du fichier debian/rules :
clean, build, et binary et les
programmes dpkg-genchanges
et pgp
pour construire une
distribution signée de paquets source et binaire.
Il est généralement utilisé sur la ligne de commande, à la racine du répertoire source à créer ou à détruire. Il peut être invoqué sans arguments. Les arguments utiles sont:
pgp
dans la variable PATH. pgp-command doit avoir le même
comportement que pgp
.
dpkg-buildpackage
ne
fera aucune action pour obtenir les privilèges root, afin que pour démarrer la
plupart des paquets root soit nécessaire.
dpkg-source(1)
).
Ce programme est habituellement appelé à partir du fichier debian/rules (voir L'arbre source débianisé, Section 3.2) depuis la racine de l'arborescence source.
Ceci est généralement fait juste avant que les fichiers et les répertoires,
dans le répertoire temporaire où le paquet est en train de se construire, ont
établi leurs permissions et leurs propriétaires et avant la construction du
paquet par dpkg-deb
[4].
dpkg-gencontrol doit être appelé après que tous les fichiers du paquet aient été mis en place dans le répertoire temporaire de construction, afin que le calcul de la taille du paquet installé soit correct.
Il est aussi nécessaire pour dpkg-gencontrol
d'être exécuté après
dpkg-shlibdeps
afin que les variables de substitutions, créées par
dpkg-shlibdeps
dans le fichier debian/substvars,
soient disponibles.
Pour un paquet qui génère seulement un paquet binaire, et qui est construit dans le répertoire debian/tmp par rapport à la racine du paquet source, il suffit d'appeler:
dpkg-gencontrol
Les sources qui construisent plusieurs binaires utiliseront:
dpkg-gencontrol -Pdebian/tmp-pkg -ppackage
L'argument P indique à dpkg-gencontrol
que le paquet
est en train de se construire dans un répertoire différent que celui par défaut
et -p indique quel fichier de contrôle de paquet doit être généré.
dpkg-gencontrol
ajoute aussi des informations à la liste des
fichiers du répertoire debian/file pour un futur appel à
dpkg-genchanges.
Ce programme est habituellement appelé à partir du fichier
debian/rules, juste avant dpkg-gencontrol
(voir L'arbre source débianisé, Section 3.2),
à la racine de l'arborescence source.
Les arguments sont des exécutables [5] [6] pour lesquels les dépendances des librairies partagées devraient être incluses dans le fichier de contrôle de paquet.
Si certains exécutables librairies partagées doivent seulement justifier d'un Recommends ou d'un Suggests, ou si certains demandent un Pre-Depends, ceci peut être réaliser en utilisant l'option -ddependency-field avant ces exécutables (chaque option -d prends effet jusqu'au prochain -d).
dpkg-shlibdeps
ne modifie pas directement le fichier de contrôle.
Par défaut, il ajoute au fichier debian/substvars des variables
comme shlibs:Depends. Ces variables doivent être référencées dans
le champ dépendance dans la section appropriée des paquets binaires du fichier
de contrôle source.
Par exemple, le paquet procps
génère deux types de binaires, des
binaires simples comme ps
qui requièrent une pré-dépendance, et
des binaires utilisant ncurses
comme top
qui
nécessitent seulement une recommandation. Cela peut être indiqué dans le
fichier debian/rules par:
dpkg-shlibdeps -dPre-Depends ps -dRecommends top
Et ensuite dans le fichier principal de contrôle debian/control:
... Package: procps Pre-Depends: ${shlibs:Pre-Depends} Recommends: ${shlibs:Recommends} ...
Les sources qui produisent plusieurs paquets binaires avec des exigences
différentes de dépendance de librairie partagée peuvent utiliser l'option
-pvarnameprefix pour écraser le préfixe
shlib: par défaut (un appel à dpkg-shlibdeps
par
réglage de cette option). Elles peuvent ainsi produire plusieurs ensembles de
variables de dépendance, chacune de la forme
varnameprefix:dependencyfield, qui peuvent être référencées dans les
parties appropriées des fichiers de contrôle des paquets binaires.
Certains chargements de paquets nécessitent d'inclure des fichiers en plus des fichiers des paquets sources et binaires.
dpkg-distaddfile
ajoute une ligne au fichier
debian/files afin qu'il soit inclus dans le fichier
.changes lorsque dpkg-genchanges
sera lancé.
Il est habituellement invoqué à partir de la cible binary du fichier debian/rules:
dpkg-distaddfile filename section priority
L'argument nom du fichier filename est relatif au répertoire où
dpkg-genchanges
s'attend à le trouver, généralement au dessus de
la racine de l'arborescence source. La règle de debian/rules
devrait placer ce fichier juste avant ou juste après l'appel à
dpkg-distaddfile
.
Les arguments section et priority sont placés sans modification dans le fichier résultat .changes. Voir Section et Priority, Section 4.2.9.
Ce programme est généralement appelé par des scripts de construction
automatique de paquet indépendant tels que dpkg-buildpackage
mais
peut être aussi appelé sur la ligne de commande.
Il est habituellement exécuté à la racine du répertoire de l'arbre source construit, et quand il est invoqué sans arguments, il écrira directement un fichier .changes basé sur les informations des fichiers de contrôle et de changement des paquets sources, et des paquets sources et binaires qui ont dû être construit.
Ce programme est utilisé en interne par dpkg-source
et autres. Il
peut être aussi occasionnellement utilisé dans debian/rules et
autre part. Il analyse un fichier changelog, par défaut
debian/changelog, et affiche sur la sortie standard une
représentation formatée de fichier de contrôle des informations contenues.
La structure de l'archive source, décrit ci-dessous, a été conçu pour permettre à un arbre source débianisé, avec les informations de contrôle associées, d'être dupliqué et facilement transporté. L'arbre source débianisé est une version du programme original avec certains fichiers ajoutés pour le processus de débianisation, ainsi que n'importe quels changements nécessaires réalisés sur les codes sources et scripts d'installation.
Les fichiers supplémentaires crées pour la Debian sont dans le répertoire debian à la racine de l'arbre source débianisé. Ils sont décrits ci-dessous.
Ce fichier est un makefile exécutable, qui contient les règles spécifiques au paquet pour compiler et construire les binaires des paquets sources.
Il doit commencer par une ligne:
#!/usr/bin/make -f
afin de pouvoir être appelé directement sans faire make
.
Les règles nécessaires sont:
Pour certains paquets, notamment ceux où le même arbre source est compilé de différentes façons pour obtenir deux paquets binaires, la règle build n'a aucun sens. Pour ces paquets, il est bon de prévoir deux règles ou plus (build-a et build-b ou autre) pour chaque manière de construire le paquet et une règle build qui ne produit rien. La règle binary s'occupera de construire le paquet pour chaque cas possible et de créer le paquet binaire de chacun d'eux.
La règle build ne doit pas effectuer d'actions qui exigent les privilèges de root.
La règle build peut avoir besoin d'exécuter d'abord la règle clean. Voir ci-dessous.
Quand un paquet possède une routine de configuration qui prend du temps, ou
quand le makefile est pauvrement conçu, ou quand build a
besoin d'exécuter clean d'abord, il est alors intéressant
d'exécuter touch build
quand le processus build est
terminé. Cela assurera que si build de debian/rules
est exécuté à nouveau, il ne reconstruira pas le programme complet.
binary devrait être généralement une règle, avec aucune commande, qui dépend simplement de binary-arch et binary-indep.
Les deux règles de binary (binary-arch et
binary-indep) devrait dépendre de la règle build,
ci-dessus, afin que le paquet soit construit si ce n'est pas déjà le cas. Il
doit ensuite créer les paquets binaires pertinents en utilisant
dpkg-gencontrol
pour créer leurs fichiers de contrôle et
dpkg-build
pour les binaires, et les placer le répertoire parent
du répertoire racine.
Si une des deux règles n'a pas de commandes (ce sera toujours le cas, si le source génère seulement un paquet binaire dépendant de l'architecture ou non), elle doit tout de même exister.
Les paquets binaires, Chapter 2 décrivent comment construire les paquets binaires.
La règle binary doit être invoquée avec le privilège root.
Si le fichier build est mis à jour par touch
à la fin
de la règle build, comme suggéré ci-dessus, c'est la première
chose qui doit être effacée par la règle clean, afin que si on
exécute de nouveau build après une interruption,
clean ne pense pas que tout est déjà fait.
La règle clean doit être invoquée sous root, si binary a été invoqué depuis le dernier clean, ou si build a été invoqué sous root (étant donné que build peu créer des répertoires par exemple).
Cette règle peut être invoquée dans n'importe quelle répertoire et doit s'occuper de nettoyer ses fichiers temporaires. Elle est optionnelle, mais la fournir, si c'est possible, est une bonne idée.
Les règles build, binary et clean doivent être invoquées dans le répertoire courant du répertoire racine du paquet.
Des règles supplémentaires peuvent exister dans debian/rules, soit comme des interfaces publiées ou non documentées ou pour l'utilisation interne du paquet.
Ce fichier contient les détails indépendants des versions des paquets sources et des paquets binaires qu'il crée.
C'est une série d'ensemble de champ de contrôle, chacun syntaxiquement similaire à un fichier de contrôle de paquet binaire. Les ensembles sont séparés par une ou plusieurs lignes vides. Le premier ensemble contient en général les informations sur le paquet source; chaque ensemble suivant décrit un paquet binaire que l'arbre source construit.
la syntaxe et la sémantique des champs sont décrites ci-dessous dans Les fichiers de contrôle et leurs champs, Chapter 4.
Les champs généraux (indépendant des paquets binaires) sont:
Les champs pour les paquets binaires sont:
Ces champs sont utilisés par dpkg-gencontrol
pour générer les
fichiers de contrôle pour les paquets binaires (voir ci-dessus), par
dpkg-genchanges
pour générer le fichier .changes qui
accompagne le chargement et par dpkg-source
quand il crée le
fichier de contrôle source .dsc comme une partie de l'archive
source.
Les champs peuvent contenir des références aux variables, leurs valeurs seront
substituées par dpkg-gencontrol
, dpkg-genchanges
ou
dpkg-source
quand ils génèrent leurs fichiers de sortie. Voir debian/substvars et
substitutions de variables, Section 3.2.3 pour détails.
Des champs utilisateurs supplémentaires peuvent être ajoutés au fichier de contrôle du paquet source. Ces champs seront ignorés, ne seront pas copiés dans les fichiers de contrôle des paquets sources ou binaires (par exemple) ou dans les fichiers de contrôle de chargement.
Si tu souhaites ajouter des champs supplémentaires non supportés à ces fichiers de sortie, tu dois utiliser le mécanisme décrit ci-dessous.
Les champs du fichier principal d'information de contrôle de source avec des noms commençant par X, suivis par une ou plusieurs lettres BCS et un tiret -, seront copiés vers les fichiers de sortie. Seule la partie du nom du champ qui se trouve après le tiret sera utilisée dans le fichier de sortie. Si la lettre B est utilisée, le champ apparaîtra dans les fichiers de contrôle des paquets binaires, si c'est la lettre S, dans les fichiers de contrôle de paquet source, et si c'est la lettre C, dans les fichiers de contrôle de chargement (.changes).
Par exemple, le fichier principal d'information de contrôle source contient le champ suivant:
XBS-Comment: I stand between the candle and the star.
alors les fichiers de contrôle des paquets sources et binaires contiendront le champ:
Comment: I stand between the candle and the star.
Ce fichier enregistre les changements des parties spécifiques Debian d'un paquet [7].
Il a un format spécial qui permet aux outils de construction de paquets de découvrir quelle version du paquet est en train de se construire et de trouver d'autres informations spécifiques à la version.
Le format est une série d'entrée comme ça:
package (version) distributions(s); urgency=urgency * détails des modifications plus de détails * encore plus de détails -- nom du mainteneur et adresse email date
package et version sont le nom du paquet source et le numéro de version.
distribution(s) listent les distributions où cette version devrait être installée quand elle est chargée. C'est copié du champ Distributions dans le fichier .changes. Voir Distribution, Section 4.2.14.
urgency est la valeur pour le champ Urgency dans le fichier .changes pour le chargement. Voir Urgency, Section 4.2.15. Il n'est pas possible de spécifier une urgency contenant des virgules; les virgules sont utilisées pour séparer les couples (mot clé=valeur) dans le format du fichier d'enregistrement de dpkg (bien qu'il n'y ait pour l'instant seulement un mot clé utile: urgency).
Les détails des modifications peuvent être, en fait, n'importe quelles séries de ligne commençant au moins par deux espaces, mais par convention, chaque modification commence par une étoile * et un espace, les lignes de continuation sont indentées pour les amener en face du texte de la ligne précédente. Les lignes vides peuvent être utilisées pour séparer les groupes de modifications, si désiré.
Le nom du mainteneur et son adresse email ne sont pas nécessairement les mêmes que ceux du mainteneur habituel du paquet. Ils doivent correspondre à la personne qui s'est occupée ce cette version. Les informations seront copiées dans le fichiers .changes, et plus tard, utilisées pour envoyer un acquittement quand le chargement sera installé.
La date doit être dans le format RFC822 [8]; elle doit inclure le nom du fuseau horaire (timezone) spécifié numériquement, et en option le nom du fuseau ou son abréviation.
La première ligne 'titre' avec le nom du paquet doit commencer sur la marge de gauche, la ligne de 'fin' avec les détails sur le mainteneur et la date, doit être précédée par exactement un espace. Les détails du mainteneur et la date doivent être séparés exactement par deux espaces.
Un mode Emacs pour éditer ce format est disponible:
debian-changelog-mode. Tu peux sélectionner ce mode
automatiquement quand tu édites un fichier changelog Debian en
ajoutant une clause de variables locales à la fin du fichier
changelog
.
Il est possible d'utiliser un format différent de celui proposé, en fournissant un analyseur avec le format que tu veux utiliser.
De façon à ce que dpkg-parsechangelog
exécute ton parseur
(analyseur), tu dois inclure une ligne à l'intérieur des 40 dernières lignes de
ton fichier s'apparentant à l'expression régulière Perl:
\schangelog-format:\s+([0-9a-z)+\W
La partie entre parenthèses doit être le nom du format, par exemple:
@@@ changelog-format: joebloggs @@@
Les noms de format de fichier changelog
sont des chaînes
alphanumériques non vides.
Si une telle ligne existe, alors dpkg-parsechangelog
cherchera
l'analyseur dans:
/usr/lib/dpkg/parsechangelog/nom-format ou /usr/local/lib/dpkg/parsechangelog/nom-format
Une erreur est renvoyée si le fichier n'est pas trouvé ou s'il n'est pas
exécutable. Le format changelog
par défaut est dpkg
et un analyseur est fourni avec le paquet dpkg.
L'analyseur sera invoqué avec le fichier changelog
ouvert sur
l'entrée standard au début. Il doit lire le fichier (ou le parcourir avec
seek) pour trouver l'information et retourner cette information analysée sur la
sortie standard sous la forme d'une série de champ de contrôle dans le format
standard. Par défaut, il devrait retourner seulement les informations les plus
récentes du fichier changelog
; il doit accepter l'option
-vversion pour retourner les informations de changement
de toutes les versions présentes strictement supérieures version et
rendre une erreur pour une version non présente dans le fichier
changelog
.
Les champs sont:
Si plusieurs versions sont retournées (à cause de l'utilisation de l'option -v), la valeur urgency doit être la plus grande listée au début de n'importe quelle version requise suivie par les commentaires concaténés (séparés par un espace) de toutes les versions requises, les champs: le mainteneur, la version, la distribution et la date proviennent toujours de la version la plus récente .
Pour le format du champ Changes voir Changes, Section 4.2.18.
Si le format du fichier changelog qui est en train d'être analysé, laisse toujours ou presque toujours une ligne vide entre les notes de modifications individuelles, ces lignes vides peuvent être supprimées, pour rendre le résultat de sortie plus compact.
Si le format de changelog
ne contient pas de date ou d'information
sur le nom du paquet, ces informations doivent être omises en sortie.
L'analyseur ne doit pas essayer de les synthétiser ou de les trouver à partir
d'autres sources. Si le fichier changelog
n'a pas le format
attendu, l'analyseur doit se terminer avec un statut différent de zéro, plutôt
que d'essayer de se débrouiller tant bien que mal et générer des sorties
incorrectes.
L'analyseur du fichier changelog
ne doit pas du tout interagir
avec l'utilisateur.
Quand dpkg-gencontrol
, dpkg-genchanges
et
dpkg-source
génèrent des fichiers de contrôle, ils font de la
substitution de variable sur leurs sorties juste avant de les écrire. Les
substitutions de variable ont la forme
${nom-variable}. Le fichier optionnel
debian/substvars contient les substitutions de variable à
utiliser. Les variables peuvent être aussi positionnées directement à partir
de debian/rules en utilisant l'option -v par les
commandes de paquetage source et certaines variables prédéfinies sont
disponibles.
Ceci est habituellement généré et modifié dynamiquement par les règles de debian/rules, dans ce cas, il doit être enlevé par la règle clean.
Voir dpkg-source(1)
pour plus de détails sur les substitutions de
variables source, incluant aussi le format de debian/substvars.
Ce fichier n'est pas un fichier permanent de l'arbre source, il est utilisé
pendant la construction des paquets pour enregistrer quels fichiers sont en
train d'être générés. dpkg-genchanges
l'utilise quand il génère
un fichier .changes.
Ce fichier ne doit pas exister dans un paquet source expédié, et il doit être effacé par la règle clean (ainsi que n'importe quels fichiers de sauvegarde ou temporaire tel que files.new [9]). Il peut aussi être sage, pour assurer un nouveau départ, de l'enlever ou de le vider au début de la règle binary.
dpkg-gencontrol
ajoute une entrée à ce fichier, pour le fichier
.deb qui sera crée par dpkg-deb
à partir du fichier
de contrôle qu'il génère, ainsi pour la plupart des paquets, il n'y a qu'à
effacer ce fichier dans la règle clean.
Si un chargement de paquet inclut des fichiers à côté des paquets sources et
binaires dont les fichiers de contrôle ont été crée par
dpkg-gencontrol
, alors ils doivent être placés dans le répertoire
parent du répertoire racine du paquet et dpkg-distaddfile
doit
être appelé pour ajouter ces fichiers à la liste debian/files.
C'est l'emplacement temporaire, pour la construction des paquets binaires pour
la règle binary. Le répertoire tmp sert de racine à
l'arbre du système de fichier qui est en train de se construire (par exemple en
utilisant la règle d'installation du Makefile
du paquet original
et en le redirigeant dans tmp), et il contient aussi le
sous-répertoire DEBIAN. Voir Création des paquets binaires - dpkg-deb,
Section 2.1.
Si plusieurs paquets binaires sont générés à partir du même arbre source, il est habituel d'utiliser plusieurs répertoires debian/tmp-truc, par exemple tmp-a ou tmp-doc.
Quelque soit les répertoires tmp crées et utilisés par binary, la règle clean doit bien sûr les effacer.
Sur les sites FTP, les paquets sources contiennent trois fichiers qui ont des liens. Tu dois avoir les bonnes versions pour les trois pour pouvoir les utiliser.
Le fichier de contrôle du paquet source est généré par dpkg-source
quand il crée l'archive source, à partir des autres fichiers dans le paquet
source, décrit ci-dessus. Quand on le déballe, il est vérifié par rapport aux
autres fichiers et répertoires dans les autres parties du paquet source, comme
décrit ci-dessous.
tar
compressé (avec gzip -9
)
contenant le code source de l'auteur original du programme. Le fichier
tar
est déballé dans un répertoire paquet-version-
originale.orig. Il ne contient aucun fichier en dehors de
ses sous-répertoires.
diff -u
) donnant les
changements requis pour modifier le source original en source Debian. Ces
changements peuvent inclure seulement une édition ou une création de fichier
tout bonnement. Les permissions des fichiers, les cibles des liens symboliques
et les caractéristiques des fichiers spéciaux ou "pipes" ne peuvent
pas être changés et aucun fichier ne doit être enlevé ou renommé.
Tous les répertoires dans le fichier diff doivent exister, sauf le
sous-répertoire debian à la racine de l'arbre source, qui sera
crée par dpkg-source
, si nécessaire, lors de l'extraction.
Le programme dpkg-source
rendra automatiquement exécutable le
fichier debian/rules (voir ci-dessous).
S'il n'y a pas de code source original, par exemple, si le paquet a été
spécialement préparé pour la Debian ou si le mainteneur Debian est le même que
le mainteneur original, le format est alors légèrement différent: il n'y pas de
fichier diff et le fichier tar
est nommé
paquet-version.tar.gz et contient un répertoire
paquet-version.
dpkg-source
dpkg-source -x
est la manière recommandée pour extraire un paquet
source Debian. Cependant, si le programme n'est pas disponible, il est
possible d'extraire une archive source Debian comme suit:
tar
, pour créer un répertoire
.orig.
patch -p0
.
tar
de nouveau, si tu veux une copie du code
source original à côté de la version débianisée.
Il n'est pas possible de générer une archive source Debian valide sans utiliser
dpkg-source
. En particulier, essayer d'utiliser diff
directement pour générer le fichier .diff.gz ne fonctionnera pas.
Le paquet source ne doit contenir de liens physiques [10] [11] , de fichiers spéciaux de périphériques, de sockets ou de fichiers "setuid" ou "setgid" [12].
Les outils de paquetage source gèrent les modifications entre les fichiers
sources originaux et ceux débianisés en utilisant diff
et
patch
. Modifier l'arbre source original inclus dans
.orig.tar.gz en un source débianisé ne doit pas impliquer de
changements qui ne peuvent pas être maintenus par ces outils. Les changements
problématiques qui provoquent une erreur de la part de dpkg-source
pour construire le paquet source sont:
Les modifications qui afficheront un avertissement de la part de
dpkg-source
sont:
Les changements qui ne sont pas représentés, et qui ne sont pas détectés par
dpkg-source
sont:
Le répertoire Debian debian/rules est manipulé spécialement par
dpkg-source
. Avant d'appliquer les changements, il créera le
répertoire debian, après quoi il rendra exécutable le fichier
debian/rules.
Le manuel de programmation de dpkg
15 avril 2002cure@cnam.fr
jacolot@ubolib.univ-brest.fr