Les responsables de paquets préserveront, autant que possible, les dates de modification des fichiers sources d'un paquet[17].
Ce fichier doit être un makefile exécutable et doit contenir des règles permettant la compilation du paquet et la construction de paquet(s) binaire(s) à partir des sources.
Il doit commencer par la ligne #!/usr/bin/make -f, afin de pouvoir
être appelé directement sans passer par make
.
Puisqu'un script debian/rules interactif ne peut pas compiler un
paquet automatiquement et empêche une reproduction de ce paquet binaire par
d'autres personnes, toutes les cibles exigées DOIVENT être
non-interactives. Au minimum, les cibles exigées sont celles qu'appelle
dpkg-buildpackage
, à savoir, clean, binary,
binary-arch, binary-indep, et build. Il s'ensuit
qu'une cible dont dépendent ces cibles, doit être aussi non interactive.
Les cibles nécessaires et les cibles facultatives sont :
Pour certains paquets, notamment ceux où la même arborescence source est compilée différemment pour obtenir des paquets binaires différents, la cible build n'a aucun sens. Pour ces paquets, il suffit de prévoir deux cibles ou plus (build-a, build-b, ...) pour chaque manière de construire le paquet et une cible build qui ne produit rien. La cible binary s'occupera de construire le paquet pour chaque cas possible et de créer le paquet binaire correspondant à chacun d'eux.
La cible build ne doit pas effectuer d'actions qui exigent les privilèges de root.
La cible build peut avoir besoin d'exécuter d'abord la cible 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 d'abord besoin d'exécuter clean, il est alors intéressant d'exécuter touch build quand le processus de construction est terminé. On s'assure ainsi que si debian/rules build est lancé à nouveau, il ne reconstruira pas le programme complet [18].
binary-arch
construit les paquets binaires qui sont spécifiques à
une architecture particulière, et binary-indep construit les
paquets qui ne le sont pas.
binary peut être (et c'est communément le cas) une cible sans commande, qui dépend simplement de binary-arch et de binary-indep.
Les deux cibles binary-* dépendront soit de la cible
build, soit de l'une des cibles build-arch ou
build-indep si elles sont proposées, afin que le paquet soit
construit s'il ne l'a pas déjà été. Les paquets binaires pertinents seront
ensuite créés en utilisant dpkg-gencontrol
pour créer leurs
fichiers de contrôle et dpkg-deb
pour construire les binaires et
les placer dans le répertoire parent du répertoire le plus élevé.
Les cibles binary-arch et binary-indep doivent exister. Si l'une des deux cibles binary-* n'a rien à faire (ce sera toujours le cas si le source crée un seul paquet binaire, qu'il soit dépendant de l'architecture ou pas), elle doit tout de même exister, et doit toujours se dérouler correctement.
La cible binary doit être invoquée avec les privilèges de root [19].
Si un fichier build est créé par touch
à la fin de la
cible build, comme suggéré ci-dessus, c'est la première chose qui
sera effacée par la cible clean ; ainsi build,
exécuté de nouveau après un nettoyage (clean) interrompu, ne
pensera pas que tout est déjà fait.
La cible clean peut avoir besoin d'être invoquée par root, si binary a été invoqué depuis le dernier clean, ou si build a été invoqué par root (étant donné que build peut créer des répertoires par exemple).
Cette cible peut être invoquée dans n'importe quel répertoire et s'occupera de supprimer tous ses fichiers temporaires.
Elle est facultative mais la proposer, quand c'est possible, est une bonne idée.
Les cibles build, binary et clean doivent être invoquées avec comme répertoire actuel, le répertoire de plus haut niveau du paquet.
Des cibles supplémentaires peuvent exister dans debian/rules, soit comme des interfaces publiées ou non documentées soit pour l'utilisation interne du paquet.
Ce sont les variables de make
à travers
dpkg-architecture
qui déterminent l'architecture sur
laquelle et pour laquelle on construit. On peut obtenir, aussi bien
pour la machine sur laquelle on construit que pour la machine pour laquelle on
construit, la chaîne indiquant l'architecture Debian et la chaîne indiquant
l'architecture à la façon GNU. Voici une liste de variables acceptées
par make
:
où « * » représente BUILD pour une indication de la machine sur laquelle on construit, ou bien HOST pour une indication de la machine pour laquelle on construit.
On peut assurer une compatibilité ascendante dans le fichier rules en
fixant par défaut les bonnes variables à des valeurs adéquates ; veuillez
consulter la documentation de dpkg-architecture
pour des
précisions.
Il est important de comprendre que la chaîne DEB_*_ARCH détermine seulement l'architecture Debian sur ou pour laquelle on construit. On ne l'utilisera pas pour avoir des renseignements sur le CPU ou le Système ; les variables GNU sont là pour ça.
Ce fichier enregistre les modifications apportées aux éléments Debian d'un paquet[20].
Son format spécial permet aux outils de construction de paquets de découvrir quelle version du paquet est en train de se construire et de trouver des informations spécifiques à cette version.
Le format ressemble à une suite d'entrées :
paquet (version) distribution(s); urgency=urgency * détails des modifications plus de détails * encore plus de détails -- nom du responsable <adresse électronique> [deux espaces] date
Les entrées paquet et version représentent le nom du paquet source et le numéro de version.
L'entrée distribution(s) liste les distributions dans lesquelles cette version sera installée. Elle est copiée dans le champ Distributions du fichier .changes. Voyez Distribution, Section 3.2.4.
urgency est la valeur pour le champ Urgency du fichier .changes pour le chargement. Une urgency ne peut pas contenir de 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 qu'un seul mot-clé utile : urgency)[21].
L'énoncé des modifications peut n'être qu'une suite de lignes commençant par au moins deux espaces, mais par convention, on commence une modification par une étoile « * » suivie d'un espace ; les lignes de continuation sont décalées pour les amener en face du texte de la ligne précédente. On peut séparer si l'on veut les groupes de modifications par des lignes vides.
Si par cette mise à jour sont corrigés des bogues enregistrés par le système de suivi de bogues (BTS), ils seront automatiquement fermés par l'installation de ce paquet dans l'archive Debian et une chaîne closes: Bug#nnnnn sera insérée dans les notes de modifications[22].
Le nom de responsable et son adresse électronique utilisés dans le changelog seront ceux de la personne installant cette version. Ils ne sont pas nécessairement ceux du responsable habituel du paquet. Ces informations seront copiées dans le champ Changed-By du fichier .changes, et plus tard, utilisées pour envoyer un accusé de réception quand le chargement aura été installé.
La date doit être dans le format RFC 822 [23] ; elle doit inclure le nom du fuseau horaire (timezone) spécifié sous forme de chiffre, et en option le nom du fuseau ou son abréviation entre parenthèses.
La première ligne de « titre » avec le nom du paquet commencera sur la marge de gauche, la ligne de « fin » avec les renseignements sur le responsable et la date, doit être précédée par exactement un espace. Les éléments responsable et date doivent être séparés exactement par deux espaces.
Il est possible d'utiliser un format différent de celui proposé, en fournissant un analyseur pour le format qu'on veut utiliser.
Un analyseur de changelog ne doit pas être interactif.
Quand dpkg-gencontrol
, dpkg-genchanges
et
dpkg-source
créent des fichiers de contrôle, ils procèdent au
remplacement des variables qu'ils doivent écrire dans ces fichiers. Les
substitutions de variable sont de la forme
${variable-nom}. Le fichier facultatif
debian/substvars contient les remplacements de variable à
utiliser. On peut aussi fixer directement les variables dans le fichier
debian/rules en utilisant l'option -V des commandes
d'empaquetage des sources ; certaines variables pré-définies sont disponibles.
Le fichier debian/substvars est habituellement créé et modifié dynamiquement par les cibles de debian/rules, et dans ce cas, il doit être supprimé par la cible clean.
Voyez dpkg-source(1)
pour plus de détails sur les remplacements de
variables source, et sur le format de debian/substvars.
Ce fichier n'est pas un fichier permanent de l'arborescence source ; il est
utilisé pendant la construction des paquets pour enregistrer quels fichiers
sont en train d'être créés. dpkg-genchanges
l'utilise quand il
crée un fichier .changes.
Ce fichier ne doit pas exister dans le paquet source qu'on propose, et il doit être supprimé par la règle clean (ainsi que n'importe quel fichier temporaire ou de sauvegarde tel que files.new [24]). Il peut aussi être sage, pour garantir un nouveau départ, de l'enlever ou de le vider au début de la cible binary.
Quand dpkg-gencontrol
est exécuté pour un paquet binaire, il
ajoute une entrée dans le fichier debian/files pour le fichier
.deb qui sera créé quand dpkg-deb --build sera
exécuté pour ce paquet binaire. Ainsi pour la plupart des paquets, il n'y a
rien d'autre à faire que de supprimer ce fichier dans la cible
clean.
Quand une installation de paquet inclut des fichiers autres que ceux du paquet
source ou des paquets binaires dont les fichiers de contrôle ont été créés par
dpkg-gencontrol
, ces fichiers seront placés dans le répertoire
parent du répertoire racine du paquet et dpkg-distaddfile
sera
appelé pour ajouter ces fichiers à la liste debian/files.
Un paquet source ne peut pas contenir des liens « en dur »[25][26], des fichiers spéciaux pour les device, des sockets ou des fichiers setuid ou setgid[27].
La description d'un programme est faite pour permettre à l'utilisateur qui n'a jamais entendu parler de ce programme auparavant de savoir s'il veut l'installer. Elle donnera des informations sur les conflits et dépendances significatives entre ce paquet et les autres, afin que l'utilisateur sache pourquoi ces conflits et dépendances ont été déclarés.
La ligne de résumé sera brève -- moins de 80 caractères.
Ne mettez pas le nom du paquet dans la ligne de résumé. Le logiciel sait déjà l'afficher, et ce n'est pas nécessaire de l'indiquer. N'oubliez pas que dans beaucoup de cas, l'utilisateur ne peut lire que la ligne de résumé : il faut donc la rendre aussi instructive que possible.
N'essayez pas de poursuivre la ligne du résumé dans la description étendue. Cela ne fonctionnera pas correctement quand la description complète est affichée et cela n'aura aucun sens quand seul le résumé (la ligne de résumé) est disponible.
La description étendue décrira ce que fait le paquet, et comment il se relie au reste du système (en termes, par exemple, de sous-systèmes, de partie de ...).
Le champ description doit être compréhensible pour tout le monde, y compris ceux qui n'ont aucune idée sur ce que fait le paquet[28].
Mettez les informations importantes d'abord, à la fois dans le résumé et dans la description étendue. Quelques fois, seule la première partie du résumé ou de la description sera affichée. En principe on peut supposer qu'il y a une manière de voir l'ensemble de la description étendue.
Quand on le souhaite, on peut inclure des informations sur les dépendances ou sur d'autres choses dans la description étendue.
N'utilisez pas le caractère de tabulation, son effet est imprévisible.
La Charte Debian
version 3.5.6.1 cvs 1.68 03/2002ijackson@gnu.ai.mit.edu
schwarz@debian.org
bweaver@debian.org
debian-policy@lists.debian.org