[ précédent ] [ Table des matières ] [ 1 ] [ 2 ] [ 3 ] [ 4 ] [ 5 ] [ 6 ] [ 7 ] [ 8 ] [ 9 ] [ 10 ] [ 11 ] [ 12 ] [ A ] [ B ] [ C ] [ D ] [ E ] [ F ] [ G ] [ suivant ]


La Charte Debian
Chapitre 4 - Les paquets sources


4.1 La conformité aux manuels Debian

On indiquera la version la plus récente de la Charte Debian à laquelle s'est conformé le paquet lors de sa mise à jour la plus récente.

On peut utiliser cette valeur pour remplir automatiquement des rapports de bogue quand le paquet est vraiment trop vieux.

La version est indiquée dans le champ de contrôle Standards-Version. Le format de ce champ est décrit dans Standards-Version, Section 5.6.11.

Vous consulterez régulièrement, et notamment si votre paquet est obsolète, la plus récente version de la Charte Debian, et vous mettrez à jour votre paquet si nécessaire. Lorsque le paquet est conforme à la nouvelle norme, vous mettrez à jour le champ Standards-Version du paquet source et vous le diffuserez [13].


4.2 Les relations entre paquets

Les paquets source préciseront les paquets binaires qui doivent être installés et ceux qui ne doivent pas l'être, pour que leur construction réussisse. Si l'on doit, par exemple, compiler un paquet avec un compilateur particulier, une dépendance de compilation sera déclarée envers ce paquet.

Pour un très petit nombre de paquets, ceux dont on a toujours besoin pour compiler, lier et insérer dans un paquet Debian un programme classique écrit en C ou C++ comme « Hello world! », il n'est pas nécessaire de déclarer explicitement des relations de dépendance. Ces paquets, sur lesquels on peut trouver des renseignements dans la liste /usr/share/doc/build-essential/list (contenue dans le paquet build-essential), sont marqués build-essential [14].

La liste des dépendances de compilation ne contiendra que les paquets explicitement nécessaires à la compilation. Les paquets simplement demandés parce qu'un paquet de cette liste dépend d'eux ne doivent pas être déclarés [15].

Quand les relations de dépendance de compilation sont indiquées, on doit pouvoir compiler un paquet et produire un binaire opérationnel sur un système où les paquets essential et build-essential sont installés ainsi que ceux nécessaires pour que les relations de dépendance de compilation soient satisfaites (y compris les implicites). Cela signifie en particulier que, dans les relations de dépendance de compilation, on doit traiter rigoureusement les questions de version de manière à éviter les paquets mal ou stupidement configurés quand les relations de dépendances sont correctement satisfaites.

Le chapitre Comment déclarer des relations entre les paquets ?, Chapitre 7 explique les détails techniques.


4.3 Les modifications dans les sources amont

Si vous modifiez le code source d'une manière qui n'est pas liée au système Debian, vous enverrez ces changements aux auteurs, dans la forme qu'ils préféreront, de manière à ce qu'ils puissent être intégrés dans la version originale.

Si vous avez besoin de configurer le paquet de façon différente sous Debian et sous Linux et si les sources originaux ne proposent pas de manière de le faire, veuillez ajouter ces moyens de configuration. C'est, par exemple, un nouveau test d'autoconf ou un #define. Envoyez ensuite le correctif aux auteurs, en choisissant comme valeur par défaut la configuration qu'ils avaient choisie. Vous pouvez facilement remplacer la valeur par défaut dans votre debian/rules ou dans tout autre endroit approprié.

Vous vérifierez que l'outil configure détecte la bonne déclaration d'architecture (reportez-vous à la section Les chaînes de spécification d'architecture, Section 11.1 pour plus de précisions).

Si vous avez besoin de modifier un Makefile qui utilise des scripts configure de style « GNU », vous modifierez les fichiers .in, plutôt que directement le Makefile. Cela permet à l'utilisateur de reconfigurer le paquet si nécessaire. Vous ne devez pas configurer le paquet et modifier le Makefile produit ! Cela rend impossible la reconfiguration ultérieure du paquet par un autre utilisateur sans perdre vos modififications.


4.4 Changelog Debian : debian/changelog

Ce fichier, debian/changelog, enregistre les modifications apportées à la version d'un paquet Debian. [16] Cela comprend les modifications du paquet Debian par rapport au paquet source ainsi que les autres changements et mises à jour concernant le paquet [17].

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

urgency est la valeur pour le champ Urgency du fichier .changes pour l'envoi du paquet sur le serveur (voir Urgency, Section 5.6.17). 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) [18].

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'une 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[19]. Cette information est transmise par le champ Closes du fichier .changes (voir Closes, Section 5.6.22).

Le nom du 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, (voir Changed-By, Section 5.6.4), 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 [20] ; elle doit inclure le nom du fuseau horaire 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 une espace. Les éléments responsable et date doivent être séparés exactement par deux espaces.

Veuillez consulter Les fichiers « Changelog », Section 12.7 pour des informations supplémentaires sur la manière de placer les fichiers changelog dans les paquets binaires.


4.4.1 Autres formats pour le fichier changelog

Pour les paquets non expérimentaux, le fichier debian/changelog doit utiliser un format reconnu par la version la plus récente de dpkg.

Si vous souhaitez utiliser un autre format, vous pouvez le faire tant que vous fournissez un outil d'analyse (« parser ») pour ce format. Cet outil doit avoir une API compatible avec celle attendue par dpkg-genchanges et par dpkg-gencontrol [21] et il ne doit pas interagir avec l'utilisateur.


4.5 Copyright : debian/copyright

Tout paquet doit être accompagné par une copie verbatim de son copyright et de sa licence de distribution dans le fichier /usr/share/doc/paquet/copyright (voir Les informations de copyright, Section 12.5 pour plus de détails). Veuillez également consulter Considérations sur le copyright, Section 2.3 pour d'autres considérations reliées aux copyrights des paquets.


4.6 La détection des erreurs dans les makefiles

Quand make appelle une commande dans un makefile (incluant les makefiles originaux de votre paquet et debian/rules), cela se fait par sh. Or sh traite mal les erreurs : si vous incluez un mini-script shell en tant que commande dans votre makefile, vous constaterez que si vous n'avez pas de mécanisme de détection d'erreur, make continuera aveuglément malgré les problèmes rencontrés.

Chaque fois que vous mettez plus d'une commande shell (cela inclut l'utilisation d'une boucle) dans une commande du makefile, vous devez vous assurer que les erreurs sont détectées. Pour de simples commandes composées comme changer de répertoire et exécuter un programme, il est suffisant d'utiliser && à la place du point-virgule. Pour des commandes plus complexes incluant la plupart des boucles et des instructions conditionnelles, vous ajouterez la commande set -e au début de chacun de ces mini-scripts shell que sont les commandes d'un makefile.


4.7 Cachets de date

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


4.8 Restrictions sur les objets dans les paquets source

Un paquet source ne peut pas contenir des liens « en dur » [23], des fichiers spéciaux pour les périphériques, des sockets ou des fichiers setuid ou setgid[24].


4.9 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 ne pas être 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 (toutes nécessaires sauf celles marquées facultatives) sont :

build

La cible build procédera à la configuration et à la compilation du paquet. Quand un paquet possède une routine interactive de configuration préalable à la construction, soit le paquet source debianisé 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 du super-utilisateur.

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

build-arch (facultative), build-indep (facultative)

Un paquet peut aussi proposer les deux cibles build-arch et build-indep. Si la cible build-arch existe, elle fera la configuration et la compilation nécessaires pour créer les paquets binaires pour chaque architecture (ce sont les paquets dont le champ Architecture dans le fichier debian/control est différent de all). De même, si la cible build-indep existe, elle fera la configuration et la compilation nécessaires pour créer les paquets binaires indépendant d'une architecture (ce sont les paquets dont le champ Architecture dans le fichier debian/control vaut all). La cible build dépendra des cibles build-arch et build-indep qui sont données par le fichier rules.

Quand manque l'une des cibles build-arch et build-indep (ou les deux), un appel à debian/rules avec l'une des cibles manquantes provoquera un code d'erreur égal à 2. Quand une cible manque, make produit automatiquement ce code.

Les cibles build-arch et build-indep ne doivent pas effectuer d'actions qui exigent les privilèges de root.

binary, binary-arch, binary-indep

La cible binary doit comprendre tout ce qui est nécessaire à l'utilisateur pour construire le(s) paquet(s) binaire(s) à partir du paquet source. 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.

Les cibles binary doivent être invoquées avec les privilèges de root [26].

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.

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 ê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 (facultative)

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 courant, 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.


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


4.11 Adresse optionnelle du code source amont : debian/watch

Il s'agit d'un fichier de contrôle optionnel, mais recommandé pour l'utilitaire uscan qui définit comment scanner automatiquement les sites FTP et HTTP pour des mises à jour nouvellement disponibles du paquet. C'est utilisé par http://dehs.alioth.debian.org/ et d'autres outils d'Assurance Qualité de Debian pour aider au contrôle de qualité et à la maintenance de la distribution dans son ensemble.


4.12 Liste des fichiers créés : 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 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 [27]). 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.


[ précédent ] [ Table des matières ] [ 1 ] [ 2 ] [ 3 ] [ 4 ] [ 5 ] [ 6 ] [ 7 ] [ 8 ] [ 9 ] [ 10 ] [ 11 ] [ 12 ] [ A ] [ B ] [ C ] [ D ] [ E ] [ F ] [ G ] [ suivant ]


La Charte Debian

version 3.7.2.2

La liste de diffusion Debian-Policy