• Home
• Discover Logram
• Forums
• Documentation
• Development
• Demands
• Downloads

La création de paquets Logram est aisée, mais faire des paquets de première qualité est difficile. Cette page décrit tout ce qui permet de créer de meilleurs paquets. Et de meilleurs paquets font un meilleur Logram.

Conventions de nommage

Un paquet doit être nommé avec consistance pour s'intégrer à ce que les utilisateurs ont l'habitude de rencontrer dans Logram.

• Le nom doit être en minuscules, dépourvu de nombres et de tout caractères spéciaux. Seuls les tirets sont autorisés. Regex : [a-z-]+
• Toute bibliothèque (paquet qui contient des .a, .so, .la, etc) doit commencer par le préfixe «lib» et se terminer par un nombre (seul nombre permis) : sa SOVERSION. Par exemple, si la bibliothèque Foo contient «/usr/lib/libfoo.so.2.1.5», son nom de paquet sera «libfoo2».
• Si votre paquet possède des sous-paquets (donc au moins les symboles de débogage), ces sous-paquets doivent avoir un nom de la forme nom-du-paquet-nom-du-sous-paquet.

Découpage des paquets

Chaque application ou bibliothèque doit être découpée pour limiter l'installation de données non-voulues par l'utilisateur. Si un paquet source contient plusieurs paquets (exemple : e2fsprogs qui contient des binaires, libuuid et libblkid), ils doivent être découpés.

• paquet : Paquet principal contenant l'objet même de la source (par exemple, les binaires de e2fsprogs).
• paquet-dbg : Paquet contenant les symboles de débogage. Présence d'un éventuel numéro SOVERSION dans le nom (libgpgme11-dbg)
• paquet-dev : Si paquet est une bibliothèque, fichiers de développement. Absence de SOVERSION (libgpgme-dev), sauf si la bibliothèque empaquetée casse la compatibilité source à chaque version majeure (Qt et KDE par exemple).
• paquet-doc : Si paquet vient avec une documentation lourde (fichiers PDF, etc), elles doivent se trouver dans un autre paquet. Absence ou présence de SOVERSION dans les mêmes conditions que pour paquet-dev.

Si un paquet source contient des paquets n'ayant rien à voir avec la source (exemple : e2fsprofs et libuuid, dans le même fichier .tar.gz), leur nom ne peut pas commencer par paquet.

Si leur version diffère, ils doivent faire l'objet de deux fichier metadata.xml, donc de deux paquets sources au sens Logram (par exemple : e2fsprogs-bin, e2fsprogs-libuuid et e2fsprogs-libblkid).

Paquets de développement

Les paquets de développement doivent contenir les fichiers suivants. Ces fichiers ne peuvent se retrouver dans le paquet binaire correspondant.

• Les includes, donc le contenu de /usr/include.
• Les pages de manuel décrivant l'API (/usr/share/man/man2, etc).
• Les pages d'info (/usr/share/info) décrivant les API. Si elles sont trop lourdes (plus de 1Mio), il est préférable de les mettre dans un paquet paquet-doc.
• Les fichiers .so, se terminant par .so, donc avec rien d'autre après. Ils doivent être des liens symboliques vers des fichiers .so.SOVERSION.
• Les fichiers .a et .la.
• D'éventuels scripts d'aide à la compilation, comme les fichiers .pc (pkgconfig).

Paquets de débogage

Tout paquet contenant des binaires doit être pourvu de son paquet de débogage. Un paquet de débogage se crée en quelques étapes :

• Tout d'abord, s'assurer que le paquet est compilé avec l'option "-g" de GCC. Pour cela, utiliser la ligne de commande «CFLAGS="-g -O2" ./configure ...» est très facile.
• Ensuite, à la fin du script build, appeler lh_strip, qui se charge de tout. lh_strip doit s'appeler depuis le dossier de construction : «(cd {{builddir}} && lh_strip)». Si votre paquet est gros, il est possible d'accélérer le stripping en évitant de stripper des fichiers non-exécutables. Pour cela, il suffit de passer des paramètres à lh_strip : «lh_strip usr/bin usr/lib sbin». Remarquez qu'il n'y a pas de slash au début des dossiers.
• Il faut alors créer un paquet binaire (architecture : any) contenant tout le contenu de /usr/lib/debug.

Dépendances

Les dépendances des paquets sont relativement simples, et doivent être ajoutées à tout paquet binaire contenant des bibliothèques ou des exécutables :

• Commencez par ajouter la ligne «[plugin name="shlibdeps" /]» dans votre package. Ainsi, les dépendances pouvant être trouvées par exploration des fichiers ELF sont reconnues et ajoutées dans les paquets binaires. Cette méthode permet au serveur de construction de recompiler votre paquet et de changer les dépendances en fonction d'une SOVERSION ayant changé (mais ayant gardé la compatibilité source). De plus, le serveur de construction peut s'assurer qu'une dépendance de type «foo>=version» sera présente, avec version égal à la version du paquet source. Plus de problèmes de paquets lancés avec des bibliothèques plus anciennes que les fichiers d'en-tête qui ont servi à compiler le paquet. Notez que si un des paquets binaire généré par la source dépend d'un autre paquet binaire de cette source, ce sera détecté et la dépendance sera de type «foo=version».
• Ajoutez également les dépendances à l'exécution, que vous trouverez normalement dans la documentation accompagnant le paquet.
• Les paquets -dev, -doc et -dbg doivent dépendre de leur paquet binaire à leur version exacte : «depend type="depend" string="paquet-binaire={{version}}"», en gardant le {{version}} qui est une variable étendue par Setup.
• Les paquets -dev doivent également dépendre de toutes les bibliothèques utilisées par leur paquet binaire, en y ajoutant le suffixe «-dev», si ce nouveau paquet existe. Sinon, il faut trouver le paquet de développement de chaque bibliothèque utilisée. La version minimum de ces dépendances doit être la version minimum nécessaire pour que le paquet compile, pas forcément celle que vous avez utilisé. N'obligez pas les testeurs à se mettre à jour si ce n'est pas obligatoire.

Descriptions et titre

Chaque paquet dispose de trois champs à remplir : title, shortdesc et description. Voici ce qu'il faut mettre dedans :

Pour un paquet binaire

• title : Le titre du paquet. Si le paquet est graphique et qu'il dispose une entrée dans le menu, le texte de cette entrée doit être pris. Par exemple : «Navigateur web FireFox». Si ce paquet n'a pas d'entrée dans le menu, alors il faut le décrire brièvement et donner son nom : «Lecteur audio Amarok». Si le paquet n'est pas graphique, alors sa description brève est nécessaire : «Shell Bash», «Bibliothèque de gestion vectorielle», etc.
• shortdesc : Description courte, en une ligne. Si le paquet est graphique et qu'il dispose d'une entrée dans le menu, la description de cette entrée doit être utilisée si elle décrit le paquet. Exemple : «Éditeur de texte avancé». Sinon, il faut décrire le plus brièvement ce qu'est le programme. Exemple : «Navigateur web modulaire et respectueux des standards». Si le titre du paquet décrit le paquet, donc s'il n'avait pas de nom ou d'entrée dans le menu, son titre peut être réutilisé ici. En effet, le titre et la description courte ne sont pas affichés en même temps et peuvent donc se répéter.
• description : Description longue. Doit décrire ce que fait le programme ou la bibliothèque avec précision, dans le premier paragraphe. Des termes légèrement techniques sont autorisés, mais il faut que ça reste compréhensible pour tout le monde «FireFox est le navigateur web de la Fondation Mozilla. Il est conçu pour promouvoir les standards du web et tente de donner à l'utilisateur la meilleure expérience de navigation possible. Il dispose d'une riche collection d'add-ons permettant de personnaliser le navigateur et de lui ajouter des fonctionnalités». Le deuxième paragraphe contient, si nécessaire, des informations plus techniques, communautaires, d'un intérêt moindre pour l'utilisateur lambda : «Utilisant la bibliothèque graphique GTK, FireFox s'intègre mieux à GNOME. Une extension existe néanmoins pour son intégration à KDE, mais sous cet environnement de bureau, Konqueror, Rekonq ou Arora sont conseillés.». Finalement, le dernier paragraphe (ou deuxième s'il n'y a pas de deuxième) peut parler un peu plus de la communauté. «FireFox est utilisé par environ 30% des utilisateurs d'Internet, et sa popularité augmente de jours en jours. Néanmoins, il souffre de quelques problèmes, comme une consommation excessive des ressources et une lenteur sur certains sites web. Des alternatives se développent donc, comme Chromium.».

Pour un sous-paquet

• title : Titre simple et moins descriptif du genre «Fichiers de débogage de FireFox».
• shortdesc : Description courte du paquet principal, ou, si elle est trop longue, titre du paquet principal. Ensuite, séparé par une virgule, la description de ce paquets. Exemple : «Navigateur web FireFox, fichiers de débogage», «Bibliothèque de gestion vectorielle, documentation», etc.
• description : Le premier paragraphe est le premier paragraphe du paquet principal. Si le paquet principal dispose d'autres paragraphes s'appliquant également au sous-paquet, ils peuvent également être recopiés, mais il ne faut pas trop le faire, ça diminue le rapport signal/bruit de la description. Vient ensuite un dernier paragraphe décrivant le paquet. À nouveau, c'est simple : «Ce paquet contient les fichiers de débogage de FireFox permettant de retracer son exécution avec précision et ainsi de découvrir ce qui provoque des imperfections ou plantages.», «Ce paquet contient les fichiers de développement {et la documentation => si nécessaire} de Xul, permettant aux développeurs de créer des applications utilisant cette bibliothèque.», «Ce paquet contient la documentation exhaustive fournie par Perl, permettant de le maîtriser et d'utiliser tout son potentiel».

Style d'écriture

Le public cible de ces descriptions est l'utilisateur lambda, sauf pour les paquets expressément conçus pour les utilisateurs avancés, c'est à dire les -dev, -doc, -dbg et les paquets contenant des utilitaires comme GCC, libtool, LaTex, etc. Si un paquet appartient à un certain milieu (Rosegarden : l'audio assistée par ordinateur), on peut décrire le paquet en sachant que le lecteur de cette description connaît ce milieu et son jargon.

Traductions

Chaque fichier metadata.xml possède une langue primaire, c'est à dire la langue maternelle de son empaqueteur. Toute chaîne non-traduite sera affichée dans cette langue.

Il y a un certain degré de traduction qu'il faut remplir :

• Pour entrer dans Logram Experimental, les titres, descriptions courtes et le changelog doivent être traduits dans toutes les langues supportées par Logram (français et anglais).
• Pour entrer dans Logram Core, les descriptions longues doivent également être traduites et dépourvues de fautes d'orthographe ou de grammaire.

Si vous avez du mal pour une traduction, demandez sur le forum. Pas mal de membres sont francophones, donc une traduction anglais=>français sera faite en quelques minutes. Dans l'autre sens, il faudra peut-être un peu plus de temps, mais ça ne posera pas de difficulté.

De plus, si votre traduction n'est pas excellente mais suffisante pour entrer dans Experimental, votre paquet sera accessible depuis ce site web, et les membres pourront se servir de la page de wiki qui y est associée pour traduire ce que vous avez entré (et également corriger des fautes). La prochaine fois que le serveur de construction Logram compilera votre paquet, ses descriptions seront à jour et traduites.

Bonnes pratiques pour le paquet source

La partie source des paquets contient les script de construction. Voici un exemple montrant comment bien faire cette partie :

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45

<script type="header"><![CDATA[
    # Cette variable sera inclue avant l'exécution de chaque autre script.
    # Elle permet de facilement changer toute allusion aux versions dans
    # le script de construction. Ainsi, quand une nouvelle version sort,
    # il suffit de changer cette variable et le changelog, et tout marche
    VERSION="1.2"
]]></script>
<script type="download"><![CDATA[
    # Téléchargement
    #   -c Ne pas retélécharger quelque-chose qu'on a déjà
    #   -q Ne pas flooder la sortie avec des étoiles, etc
    wget -c -q ftp://ftp.gnu.org/gnu/paquet/paquet-$VERSION.tar.bz2 || exit 1

    # Désempaquetage
    tar -xf paquet-$VERSION.tar.bz2

    # Éventuellement, patches
    cd paquet-$VERSION
    patch -Np1 -i "{{controldir}}/patch-de-la-mort-qui-tue.patch"
]]></script>
<script type="build"><![CDATA[
    cd paquet-$VERSION

    # Configuration
    # ATTENTION : CFLAGS et CXXFLAGS sont définies avec des valeurs communes à
    #             Logram (-g -O2 -m... en fonction du processeur). Ne l'écrasez pas,
    #             bien que sed peut être utilisé pour retirer des flags posant problème
    #             et vous pouvez en ajouter.
    ./configure --prefix=/usr \\
                --mandir=/usr/share/man \\
                --infodir=/usr/share/info \\
                --sysconfdir=/etc || exit 1

    # Construction
    make || exit 1

    # Installation
    make "DESTDIR={{builddir}}" install || exit 1

    # Ajustements
    cd "{{builddir}}" || exit 1
    rm -f usr/share/info/dir
    mv lib/*.{so,a,la} usr/lib # Fichiers de dev toujours dans /usr/*
    lh_strip bin sbin lib usr/bin usr/sbin usr/lib # lh_strip tout à la fin
]]></script>

Autres

• Si votre paquet installe des pages de documentation au format info, supprimez le fichier {{builddir}}/usr/share/info/dir, qui ne contient rien et qui entre en conflit avec celui du système. Pour mettre à jour l'index de l'arbre info, utilisez le trigger update-info. Pour cela, ajoutez

  1	<trigger>update-info {{instroot}}</trigger>

  dans le package du paquet contenant les pages d'info. Ce script se chargera de mettre à jour les pages d'info.

• LPM, quand il construit votre paquet, lance une série de tests dessus. Ces tests sont des plugins, comme shlibdeps qui permet d'ajouter les dépendances ELF. Ces plugins peuvent ajouter des remarques qui seront affichées dans la console. Vous devez en tenir compte et les corriger pour voir votre paquet accepté.

Si tous ces tests passent et que vous avez bien vérifié les points cités ici, votre paquet est normalement d'une qualité suffisante pour entrer dans Logram Experimental, puis dans Logram Core, si toutes ses dépendances y sont déjà.