[ previous ] [ Contents ] [ 1 ] [ 2 ] [ 3 ] [ 4 ] [ 5 ] [ 6 ] [ 7 ] [ 8 ] [ 9 ] [ 10 ] [ 11 ] [ 12 ] [ 13 ] [ A ] [ B ] [ C ] [ D ] [ E ] [ F ] [ G ] [ next ]

La Charte Debian
Chapter 5 - Considérations sur la construction de paquet


5.1 Timbres à date

Les responsables de paquets préserveront, autant que possible, les dates de modification des fichiers sources d'un paquet[17].


5.2 debian/rules - Le principal script de construction

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 :

build, build-arch (facultative), build-indep (facultative)
La cible build procédera à la configuration non interactive et à la compilation du paquet. Quand un paquet possède une routine interactive de configuration préalable à la construction, soit le paquet source débianisé doit être construit après cette opération (afin qu'il puisse être construit sans ré-exécuter cette configuration), soit la routine de configuration doit devenir non interactive. (Cette dernière façon est préférable quand la routine détecte des caractéristiques propres à l'architecture.)

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, binary-arch, binary-indep
La cible binary doit être tout ce qui est nécessaire à l'utilisateur pour construire le(s) paquet(s) binaire(s). Toutes ces cibles doivent être non-interactives. Cette cible a deux parties : 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].

clean
Cette cible doit nettoyer les effets obtenus par les cibles build et binary, mais elle doit laisser les fichiers de sortie créés par la cible binary dans le répertoire parent. Cette cible ne doit pas être interactive.

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).

get-orig-source (facultatif)
Cette cible va chercher la plus récente version du paquet original dans un site d'archive autorisé (par FTP ou WWW, par exemple), s'occupe des arrangements nécessaires pour le mettre sous la forme d'un fichier tar (une archive source) décrite ci-dessus, et le laisse dans le répertoire en cours.

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.


5.3 debian/changelog

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.


5.3.1 Comment définir des formats alternatifs pour le fichier changelog

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.


5.4 debian/substvars et le remplacement de variables

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.


5.5 debian/files

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.


5.6 Restrictions sur les objets dans les paquets source

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].


5.7 La description des paquets - le champ Description

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.


5.7.1 Remarques sur la rédaction des descriptions

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.


[ previous ] [ Contents ] [ 1 ] [ 2 ] [ 3 ] [ 4 ] [ 5 ] [ 6 ] [ 7 ] [ 8 ] [ 9 ] [ 10 ] [ 11 ] [ 12 ] [ 13 ] [ A ] [ B ] [ C ] [ D ] [ E ] [ F ] [ G ] [ next ]

La Charte Debian

version 3.5.6.1 cvs 1.68 03/2002
Ian Jackson ijackson@gnu.ai.mit.edu
Christian Schwarz schwarz@debian.org
révision : David A. Morris bweaver@debian.org
La liste de diffusion « Debian Policy » debian-policy@lists.debian.org