[ << ] [ < ] [ Sommaire ] [ > ] [ >> ]

1. La politique concernant les ebuilds

• Principes généraux
• Principes spécifiques
• Politique sur les ebuilds
• Politique QA
• Variables

1.a. Principes généraux

Il existe un certain nombre de principes de développement généraux à suivre :

• Toujours vérifier les changements avec repoman : utilisez repoman commit à la place de cvs commit.
• Si un paquet est soit cassé dans sa version actuelle, soit utilise un processus de construction/installation vraiment horrible, jetez un coup d'œil sur ce que les autres distributions font pour ce paquet :
  • Debian
  • Mandriva
  • Fedora
• Votre paquet, une fois terminé et démasqué, est supposé « simplement fonctionner » pour les utilisateurs finaux. Avoir à bidouiller un paquet installé pour qu'il marche devrait être optionnel. Du coup, vous devez installer le paquet en question avec une configuration par défaut raisonnable.
• N'ayez pas peur de consulter notre documentation en ligne et les ebuilds écrits et maintenus par plusieurs développeurs expérimentés. Vous pouvez aussi contacter les développeurs expérimentés directement pour poser des questions techniques ou concernant la politique générale.
• Faites attention à ce que vous soumettez. Souvenez-vous que vos soumissions peuvent potentiellement affecter des milliers d'utilisateurs. Si votre soumission entraîne des problèmes dans l'arbre de Portage, ils doivent être résolu dans un temps très court.
• Tous les paquets doivent être accompagnés d'un fichier metadata.xml qui liste, entre autres, à quel groupe de travail (ou/et quels mainteneurs individuels) est affecté la maintenance du paquet.

1.b. Principes spécifiques

fPIC

Sur certaines architectures, les bibliothèques partagées doivent être construites avec l'option -fPIC. Sur x86 et d'autres, les bibliothèques partagées peuvent parfois être construites sans -fPIC, mais cela impliquerait du gaspillage et peut causer une perte de performance. Si vous rencontrez un paquet qui ne construit pas ses bibliothèques avec -fPIC, corrigez le Makefile pour construire uniquement ses bibliothèques partagées avec -fPIC. Plus d'informations sur -fPIC sont disponibles sur http://www.gentoo.org/proj/en/hardened/pic-internals.xml. En cas de doute, veuillez demander de l'aide, par exemple sur la liste de diffusion gentoo-dev ou le canal IRC #gentoo-dev.

Perl

Les nouveaux modules Perl doivent être ajoutés dans Portage uniquement si l'une des conditions suivantes est vérifiée :

• le module est nécessaire pour satisfaire une dépendance ;
• le module ne peut pas être récupéré avec g-cpan ;
• le module ajoute une fonctionnalité à un ebuild déjà existant ;
• le module fournit des outils, des applications ou autres fonctionnalités (c'est-à-dire plus que ce qu'offrent leurs .PM).

Merci de vous assurer qu'au moins une personne du groupe de travail sur Perl approuve votre ajout.

1.c. Politique sur les ebuilds

Politique des noms des ebuilds

Le nom des fichiers ebuilds comporte quatre sous-sections logiques :

pkg-ver{_suf{#}}{-r#}.ebuild

La première sous-section, pkg, est le nom du paquet qui doit toujours contenir des caractères choisis parmi les minuscules, les chiffres de 0 à 9, le tiret -, le soulignement _ ou le plus +. Par exemple, on a util-linux, sysklogd et gtk+. Nous avons quelques paquets dans Portage qui ne suivent pas cette règle, mais les vôtres devront la respecter.

La seconde sous-section ver est la version du paquet qui doit normalement être la même que la version de l'archive source principale. La version est en général constituée de deux ou trois (ou plus) nombres séparés par un point, comme 1.2 ou 4.5.2 et peuvent comporter une lettre seule suivant immédiatement le dernier chiffre. Par exemple, 1.4b ou 2.6h. La version du paquet est liée au nom du paquet par un tiret. Par exemple, vous aurez foo-1.0 ou bar-2.4.6.

La troisième sous-section, {_suf{#}}, est optionnelle et peut contenir un suffixe pré-défini parmi ceux listés (du plus vieux au plus récent) ci-dessous :

Tous ces suffixes doivent être suivis immédiatement d'un entier positif non nul, comme par exemple linux-2.4.0_pre10. En supposant des versions identiques, les suffixes sont ordonnés ainsi (le premier étant le plus vieux) : _alpha < _beta < _pre < _rc < (aucun suffixe) < _p.

En comparant deux suffixes identiques avec les entiers qui les suivent, celui qui a le numéro le plus grand sera considéré comme plus récent. Par exemple, foo-1.0_alpha4 est plus récent que foo-1.0_alpha3.

La quatrième sous-section dans le nom du paquet est le numéro de révision spécifique à Gentoo Linux ({-r#}). Cette sous-section comme le suffixe est optionnelle. # est un entier positif non nul, ce qui donne par exemple paquet-4.5.3-r3.

Le numéro de révision est indépendant de la version de l'archive source et est utilisé pour informer les utilisateurs qu'une révision provenant de Gentoo Linux, pour un paquet particulier, est disponible. Les sorties initiales d'ebuilds ne doivent pas avoir de numéro de révision. Par exemple, paquet-4.5.3 est considéré par Portage comme ayant un numéro de révision de zéro. Cela signifie que le décompte se fait ainsi : 1.0 (version initiale), 1.0-r1, 1.0-r2, etc.

Choisir la version et incrémenter une révision

Le numéro de révision d'un paquet doit être augmenté par les développeurs Gentoo quand l'ebuild a changé à un point tel que les utilisateurs peuvent vouloir faire une mise à jour. Typiquement, c'est le cas quand des correctifs sont fait sur un ebuild qui affectent les fichiers installés résultant, mais l'ebuild utilise la même archive source, comme pour l'ebuild précédent. Si vous faites un changement interne stylistique à un ebuild qui ne change aucun fichier installé alors il n'y a pas besoin de remonter le numéro de révision. D'ailleurs, si vous corrigez un problème de compilation sur un ebuild qui affecte des utilisateurs, il n'y a pas besoin de remonter le numéro de version, dans la mesure où ceux pour qui cela fonctionnait parfaitement ne verront aucune différence en installant la nouvelle révision et ceux qui avaient un problème n'ont pas pu installer leur paquet (puisque la compilation avait échoué), et donc n'ont pas besoin d'avoir un nouveau numéro de révision pour les forcer à mettre à jour. Une incrémentation de révision n'est également pas nécessaire si une minorité d'utilisateurs seraient affectés et que le paquet prend un temps de compilation important : faites appel à votre bon sens pour juger de la circonstance.

Les ebuilds devraient se calquer sur la version précédente pour s'assurer que des correctifs ne sont pas supprimés accidentellement. Les correctifs doivent inclure des commentaires appropriés dans l'ebuild pour expliquer ce qu'ils font et pourquoi ils sont nécessaires. Si vous n'êtes pas très familier avec les correctifs ou que vous n'arrivez pas à déterminer si ils sont toujours nécessaires, vous ne devez pas mettre à jour l'ebuild.

Virtuals

Portage supporte un concept appelé les paquets virtuels (virtual packages en anglais). En les utilisant, vous permettez d'avoir un nom catégorie/paquet particulier qui pointe vers un autre.

Voici un exemple d'utilisation des paquets virtuels. Imaginons que vous créez un nouveau paquet cron appelé foocron. Gentoo Linux est préparé actuellement pour que tout ce qui nécessite l'usage d'un paquet cron dépend du paquet virtual/cron. Cela permet aux ebuilds de s'assurer qu'il y a plusieurs paquets pour cron disponibles et l'utilisateur peut de manière arbitraire choisir l'un ou l'autre, selon ses préférences. Pour ajouter foocron-1.0.ebuild dans le système, vous devrez ajouter une ligne dans l'ebuild comme suit :

PROVIDE="virtual/cron"

Maintenant, dès que foocron-1.0 sera installé, le paquet virtual/cron sera enregistré. Si vous n'aviez aucun paquet cron installé auparavant, cela signifiera que tous les paquets dépendant de virtual/cron auront cette dépendance satisfaite de manière complète. Remarquez qu'il est possible de spécifier une valeur PROVIDE à tous les types de paquets. Il faut juste ne pas commencer par virtual. Cela dit, vous devez utiliser la catégorie virtual/, sauf dans le cas où vous utilisez la fonctionnalité proposée par PROVIDE pour pointer vers des paquets qui ont été renommés.

Il y a une seconde composante dans l'implémentation des paquets virtuels dans Gentoo. Qu'arrive-t-il si aucun paquet n'est installé pour fournir virtual/cron ? Comment Portage choisira-t-il le « bon » cron à installer pour satisfaire une dépendance à virtual/cron ? Portage s'en charge en utilisant un fichier de correspondance de profil spécifique de paquets virtuels, nommé virtuals qui est présent dans /etc/make.profile. Si vous jetez un coup d'œil dans le vôtre, vous verrez que le contenu ressemble un peu à ceci :

virtual/lpr             net-print/cups
virtual/python          dev-lang/python
virtual/mta             net-mail/ssmtp

La première ligne de ce fichier indique à Portage que si un paquet dépend de virtual/lpr et qu'aucun paquet fournissant cette dépendance n'est installé et que le paquet virtual/lpr n'est pas disponible dans l'arbre de Portage, alors net-print/cups devra être installé pour satisfaire cette dépendance. net-print/cups contient une ligne PROVIDE="virtual/lpr" pour que les prochaines dépendances sur virtual/lpr puissent être satisfaites.

Parlons désormais de la conduite à suivre pour les développeurs. Si vous devez ajouter un paquet foocron, vous devrez évidemment vous assurez que tous les programmes qui dépendent de virtual/cron peuvent fonctionner correctement avec votre paquet. Si vous voulez ajouter un paquet foobarosité qui dépend de virtual/cron, vous devrez probablement vous assurer que tous les paquets proposant virtual/cron pourront faire fonctionner correctement votre paquet.

Avant de créer des nouveaux paquets virtuels, merci de commencer à en parler sur la liste de diffusion interne pour les développeurs. Maintenir informés les développeurs de nouveaux paquets virtuels est essentiel pour s'assurer de leur utilisation uniforme.

Visibilité des variables

Quand un ebuild est lu par Portage, les fonctions et les variables qu'il définit sont chargées en mémoire par l'interpréteur. Cependant, seules les variables et les instructions qui ne font pas partie d'une fonction telle que src_compile() sont exécutées lors de la compilatin de l'ebuild.

Le code compris dans des fonctions a une visibilité locale alors que tout ce qui n'est pas dans une fonction a une visibilité globale et est exécuté à chaque utilisation de l'ebuild.

Une application externe comme grep, sed ou awk ne devrait jamais être utilisée dans la partie à visibilité globale pour des raisons de performance. De plus, les fonctionnalités internes de bash telles que le remplacement de texte doivent être utilisées au maximum. Veuillez consulter Advanced Bash Scripting Guide pour les détails.

De plus, une application externe n'est pas nécessairement disponible sur le système de l'utilisateur. En utilisant l'application externe dans une fonction telle que pkg_setup(), il est possible de garantir sa présence en l'ajoutant dans la variable ${DEPEND} de l'ebuild.

Politique des sources CVS

Il y a deux moyens de construire un ebuild basé sur des sources à partir de l'arbre de développement CVS. Le premier moyen (traditionnel) est de créer un ebuild « instantané CVS » en créant votre propre instantané archivé de l'arbre CVS récupéré, en mettant les sources en miroir avec les dépôts officiels de fichiers distribués, puis vous écrivez un ebuild qui utilise spécifiquement cette archive. Nous appellerons désormais ce type d'ebuilds « ebuilds d'instantané CVS ».

L'autre méthode pour créer un ebuild utilisant le CVS consiste à utiliser cvs.eclass pour créer un ebuild CVS « live ». Un tel ebuild récupérera de manière dynamique la dernière archive sur le dépôt CVS mise sur le CVS, assurant ainsi que les sources sont les plus à jour possible. Nous les nommerons les « ebuilds 'live' ».

Les paragraphes suivants détaillent la politique relative à l'utilisation des ebuilds basés sur CVS. Remarquez qu'elle définit des règles strictes à propos de l'ajout de ce type d'ebuilds dans l'arbre de Portage.

Les ebuilds d'instantané CVS sont largement préférés aux ebuilds « live » utilisant cvs.eclass.

Les ebuilds d'instantané CVS sont autorisés si un instantané du CVS contient les correctifs connus qui sont nécessaires au bon fonctionnement du paquet logiciel ou si la version CVS d'un paquet logiciel particulier est connue pour ou a été prouvée comme fonctionnant mieux que les versions sorties sous forme de paquet.

Les ebuilds « live » sont généralement utilisés uniquement pour les commodités des développeurs et devraient toujours être masqués avec un mot-clef de type ~[arch]. Il est impossible de garantir le bon fonctionnement d'un ebuild « live » dans la mesure où l'arbre cvs du serveur peut changer à tout moment, ce qui explique le masquage systématique.

Que ce soit pour un ebuild « live » ou un ebuild d'instantané CVS, vous, développeur serez responsable du bon fonctionnement de l'ebuild. Il est particulièrement difficile de s'en assurer pour les ebuilds « live » pour des raisons évidentes.

Si les ebuilds (quel que soit le type) ne fonctionnent pas correctement, ils doivent être corrigés ou supprimés de l'arbre de Portage. Si ce sont des ebuilds « live », ils doivent être marqués en ~[arch] à vie. Cette exception est expliquée plus bas.

Si un ou plusieurs utilisateurs demandent un ebuild « live », vous pouvez en ajouter un pour eux. Il doit avoir des mots-clef en ~[arch] afin que les autres utilisateurs ne puissent l'installer inconsciemment.

De cette manière, les utilisateurs qui le veulent peuvent l'installer, mais les autres utilisateurs seront protégés de son installation accidentelle. Encore une fois, cela ne s'applique que dans les situations où les utilisateurs demandent de manière spécifique un ebuild « live ». Les ebuilds d'instantanés CVS ne doivent être ajoutés à l'arbre de Portage que dans l'intention de les mettre en stable ou pour proposer des fonctionnalités améliorées par rapport aux versions habituelles de sortie d'un même logiciel.

ebuilds soumis par les utilisateurs

Les ebuilds soumis par les utilisateurs ne doivent jamais être considérés comme sûr et doivent toujours être audités et testés de manière suffisante, avant de les soumettre au CVS. Si un ebuild soumis par un utilisateur a des problèmes, vous en serez tenu pour responsable direct. En l'incorporant au CVS, vous affirmez que cet ebuild suit tous les standards de développement de Gentoo Linux.

Assurez-vous que l'ebuild soumis par l'utilisateur ne contient pas d'en-tête personnalisées comme celle-ci :

# Ebuild updated by: me <me@me.com>

Ces informations doivent être ajoutées au ChangeLog en utilisant la syntaxe correcte des commentaires de ChangeLog. Toujours s'assurer que le ChangeLog attribue les crédits à l'utilisateur qui a proposé l'ebuild. Ces informations doivent apparaître dans la première entrée du ChangeLog.

Assurez-vous également que tous les nouveaux ebuilds que vous soumettez au CVS contiennent la ligne suivante :

# $Header: $

Un certain nombre d'ebuilds soumis par les utilisateurs sont basés sur des fichiers utilisant rsync qui peuvent contenir des lignes d'en-tête incorrectes.

Encouragez les utilisateurs à proposer des « diffs » sur les ebuilds existants s'ils proposent une mise à jour. En faisant cela, nous pouvons mieux éviter d'avoir à réintroduire des correctifs de bogues déjà identifiés et corrigés auparavant dans les nouveaux ebuilds. Si vous ne travaillez pas à partir d'un diff soumis par un utilisateur, alors utilisez la commande diff pour voir les changements, en gardant un œil sur tout ce qui devrait apparaître dans le nouveau ebuild et qui était présent dans l'actuel, ou sur tout ce qui dans le nouvel ebuild devrait être corrigé ou supprimé.

En général, laissez l'utilisateur faire ce travail pour qu'il obtienne de lui-même un ebuild correct, sauf si vous voulez nettoyer l'ebuild sans le consulter. Toutefois, il est toujours meilleur de laisser l'utilisateur faire ce travail pour qu'il puisse apprendre de ses erreurs et soumettre des ebuilds plus propres dans le futur. N'oubliez pas de toujours remercier pour toute soumission, même si elle n'est pas vraiment bonne. Soyez poli, mais honnête. Si un ebuild n'est pas utilisable, on peut dire à l'utilisateur d'une manière non insultante que leur ebuild ne convient pas, sans porter atteinte à leur capacité actuelle à écrire un ebuild. Souvenez-vous que les utilisateurs qui proposent des ebuilds cassés peuvent être dans le futur des membres productifs et expérimentés pour notre projet dans le futur, c'est-à-dire s'ils reçoivent suffisamment d'encouragements et de support et continuent à s'améliorer.

1.d. Politique QA

Politique de sortie de Portage et baselayout

Seul les membres de l'équipe Portage peuvent sortir des nouvelles versions de Portage. Personne d'autre n'est autorisé à sortie de nouvelle version de Portage.

Seul les membres de l'équipe baselayout peuvent sortir des nouvelles versions. Personne d'autre n'est autorisé à sortie de nouvelle version de sys-apps/baselayout.

Paquets masqués

/usr/portage/profiles/package.mask contient une liste des paquets qui ne doivent pas être installés par les utilisateurs et des commentaires détaillant la raison du masquage. Package.mask est utilisé pour empêcher d'installer des paquets qui sont cassés, qui cassent d'autres éléments ou qui ont mal été testés avant d'avoir un mot-clef en ~ARCH dans l'arbre. Quand vous ajoutez un ebuild à package.mask, toujours soumettre package.mask avant de soumettre l'ebuild masqué. Cela empêche l'ebuild d'être récupéré par des utilisateurs avant que la mise à jour de package.mask ait été faite.

Une attention particulière doit être apportée quand un paquet est enlevé de package.mask. Gardez à l'esprit que si un ebuild est dans package.mask, c'est pour une bonne raison. Si vous n'avez pas masqué vous-même l'ebuild, toujours contacter le développeur cité dans les commentaires de package.mask avant de prendre une initiative. De plus, si le paquet masqué est un paquet core, une dépendance d'un paquet core, ou si démasquer le paquet peut avoir des effets secondaires, le changement doit être fait après discussion interne sur la liste de diffusion des développeurs.

~ARCH dans la variable KEYWORDS

L'objectif de ~arch est de permettre de tester des nouveaux paquets ajoutés dans Portage.

Il y a une différence entre utiliser package.mask et ~arch pour les ebuilds. L'utilisation de ~arch dénote que l'ebuild a besoin d'être testé. L'utilisation de package.mask dénote que l'application ou la bibliothèque est clairement instable. Par exemple si gimp-1.2.0 est une version stable des développeurs de Gimp et qu'un nouveau correctif est disponible en tant que 1.2.1, alors le développeur doit marquer l'ebuild comme ~arch pour qu'il soit testé dans Portage parce que la version est considérée comme stable par Gimp. Un autre exemple, si Gimp décide de proposer une version de développement ou instable marquée 1.3.0, alors les ebuilds résultant doivent être mis dans package.mask car le logiciel lui-même est qualifié de logiciel en développement et qu'il n'est pas recommandé par les développeurs à la distribution.

Tous les nouveaux paquets qui entrent dans Portage doivent être marqués d'un ~arch pour les architectures sur lesquelles cette version est connue comme fonctionnant. Le développeur qui soumet l'ebuild doit vérifier qu'il est en état de fonctionnement et que la variable KEYWORDS est correcte.

Déplacer des versions de paquet de ~ARCH à ARCH

Quand une version de paquet a été testée pendant une période de temps suffisante et considérée comme stable, et quand le mainteneur Gentoo de ce paquet est sûr que la mise à jour n'entraînera pas de problèmes sur une machine d'utilisateur normal, alors cette version peut passer de ~ARCH à ARCH. Une indication pour savoir si un paquet est stable peut être de constater qu'aucun rapport de bogue sur un mois après l'introduction du nouveau paquet n'a été effectué pour cette version.

C'est au mainteneur du paquet de décider quelles versions sont stables ou si les versions de développement doivent être mises dans package.mask ou laissés en ~arch.

Vous devez également vous assurer que toutes les dépendances pour cette version de paquet sont également en ARCH.

1.e. Variables

Variables requises

La politique de Gentoo Linux requiert que tous les ebuilds contiennent les variables KEYWORDS, LICENSE et SLOT. HOMEPAGE, SRC_URI et DESCRIPTION doivent être ajoutés sauf dans certains cas très spéciaux. DEPEND (et si besoin est, RDEPEND) doivent être inclus si votre paquet a respectivement des dépendances à la compilation ou à l'exécution.

DEPEND et RDEPEND

Utilisez DEPEND pour définir les dépendances nécessaires à la compilation d'un paquet particulier et RDEPEND pour les dépendances nécessaires à l'exécution d'un paquet particulier. Vous n'avez besoin de spécifier explicitement RDEPEND que si les dépendances de lancement de l'ebuild sont différentes de celles spécifiées dans DEPEND ; Si RDEPEND n'est pas spécifié, la valeur par défaut sera celle de DEPEND. Ne jamais initialiser RDEPEND à DEPEND par vous-même dans un ebuild.

# Acceptable :
RDEPEND="${DEPEND}
         net-ftp/curl
         virtual/libc"
# Non acceptable :
RDEPEND="${DEPEND}"

Il est également important de remarquer que seules les dépendances de RDEPEND sont satisfaites quand on installe un paquet binaire .tbz2. Utilisez ces informations pour vous aider à choisir les bonnes dépendances RDEPEND. Sinon, RDEPEND aura les dépendances de DEPEND.

Un paquet doit dépendre de la version la plus ancienne qui satisfait la dépendance. Si le paquet fonctionne avec libfoo-1.2.x, ne le faites pas dépendre de libfoo-2.x juste parce que c'est la version que vous avez d'installée.

En général, les paquets doivent dépendre de =libfoo-1.2* à la place de >=libfoo-1.2. Sinon, votre paquet va commencer à créer des problèmes quand le paquet libfoo-2.0 sera disponible.

Dépendre d'un paquet virtuel comme virtual/foo ne fonctionne que si les différents paquets proposant de valider la dépendance virtual/foo ont des interfaces identiques. Considérons par exemple virtual/jdk-1.3. Certains paquets ne fonctionnent pas avec ibm-jdk-1.3 alors qu'ils fonctionneront bien avec sun-jdk-1.3. Pour cette raison, assurez-vous que votre paquet a été testé avec tous les paquets ayant une correspondance virtuelle avant de le démasquer. Il peut arriver que la dépendance soit correcte seulement pour un certain nombre d'entre eux, mais qu'elle ne soit pas correcte pour le paquet virtuel lui-même.

[ << ] [ < ] [ Sommaire ] [ > ] [ >> ]

Ce document est protégé par la licence Creative Commons : Paternité - Partage des Conditions Initiales à l'Identique 2.5.