Manuel du développeur Gentoo

Table des matières :

• Introduction
  Cette partie couvre l'ensemble des aspects qui s'appliquent à la plupart des domaines de développement de Gentoo. Cette section est surtout intéressante si vous êtes développeur Gentoo. Dans les autres cas, vous n'apprendrez pas grand chose d'intéressant en la lisant.
  1. Introduction
     Cette section indique l'ensemble des objectifs que se donne le manuel pour développeurs Gentoo.
  2. Devenir développeur
     Ce chapitre essaie d'expliquer comment devenir développeur pour le projet Gentoo.
  3. Ce qui est mis à disposition
     Cette section présente l'ensemble des services mis à la disposition des développeurs.
  4. Aide pour les nouveaux développeurs
     Cette section apporte de l'aide et un certain nombre d'instructions utiles pour les nouveaux développeurs Gentoo.
  5. La hiérarchie des développeurs
     Cette section présente la hiérarchie des développeurs Gentoo et du développement lui-même.
• Guides
  Cette section présente et explique les différents processus de développement et propose des standards à suivre par les développeurs Gentoo.
  1. Guide pour les ebuilds
     Cette section décrit le système Portage de Gentoo, comment créer des nouveaux paquets pour Gentoo. Il doit également être vu par les développeurs comme un standard. Ce document est en constante évolution et est mis à jour et modifié régulièrement. Vous devez utiliser ce document comme un complément aux pages man proposées par Portage (et tout particulièrement ebuild(5)) et aux politiques de développement de Gentoo.
  2. Guide pour les eclass
     Cette section propose aux développeurs un guide qui détaille le fonctionnement des eclass et comment ils peuvent être appliqués aux ebuilds.
  3. Erreurs classiques dans les ebuilds
     Cette section explique les erreurs fréquentes que l'on rencontre lors de l'écriture et la soumission d'ebuilds faits par des développeurs ou des contributeurs.
  4. Gentoo Metadata
     Cette section explique l'utilité et l'usage du fichier metadata.xml qui est utilisé dans l'arbre de Portage.
  5. Guide de maintenance des ebuilds
     Cette section décrit comment les développeurs devraient réaliser les tâches communes lors de la maintenance des ebuilds dans l'arbre Portage.
  6. Guide pour signer des modifications
     Cette section explique comment les développeurs peuvent signer des modifications dans l'arbre Portage en utilisant GPG.
• Les politiques
  Cette partie couvre l'ensemble des différentes politiques que doivent suivre les développeurs lors de la soumission d'éléments dans le CVS.
  1. La politique concernant les ebuilds
     Cette section présente la politique qui s'applique aux ebuilds dans Portage.
  2. La politique concernant l'étiquette
     Cette section présente l'étiquette que doit suivre tout développeur Gentoo.

A. Introduction

1. Introduction

1.a. Introduction

L'objectif de ce manuel est de proposer un cadre aux politiques de développement Gentoo, et de permettre à vous les développeurs d'être informés à propos des politiques, standards et procédures que Gentoo considère comme étant les valeurs qui sont au coeur de notre système de développement.

Ce manuel n'a pas pour but d'être le guide universel qui réponde à tout et nous préférons laisser une marge de manoeuvre importante aux développeurs. Ce manuel est plus fait pour vous donner un certain nombre de principes et nous pensons qu'ils feront de vous un bon développeur Gentoo. La suite ne dépend que de vous !

Si vous êtes nouveau dans le développement pour Gentoo ou même que vous êtes un vétéran et que vous avez un doute sur quoi que ce soit, vous pouvez poser votre question sur la liste de diffusion gentoo-dev ou sur le forum IRC #gentoo-dev.

1.b. Prérequis

Avant que vous ne commenciez à bricoler, il est important d'avoir avec vous une Gentoo en parfait état de fonctionnement, aussi bien dans une optique de documentation que pour le développement et nous vous recommandons d'avoir une bonne connaissance des thèmes abordés dans la section « Utiliser Gentoo » du manuel d'utilisateur pour vous aider dans votre travail de développement.

La grande majorité des thèmes abordés dans ce guide ont pour cible les développeurs, mais si vous êtes simplement intéressés de voir comment fonctionne le développement de Gentoo, ce guide pourrait vous donner une vue d'ensemble intéressante.

Le meilleur moyen d'être remarqué (et de devenir éventuellement un développeur Gentoo !) est de rapporter des bugs de manière efficace dans le Bugzilla de Gentoo, avec des correctifs si possible, et de nous aider en apportant votre aide dans ce que vous pensez être important pour que Gentoo s'améliore, soit en proposant des correctifs ajoutant des nouvelles fonctionnalités, soit en soumettant de nouveaux ebuilds, ou encore en résolvant des problèmes déjà détectés.

2. Devenir développeur

2.a. Introduction

Il y a plusieurs façons de devenir développeur pour Gentoo et cette section va vous les présenter. Il y a également un certain nombre d'étapes que doivent suivre les nouvelles recrues pour devenir développeurs officiels.

2.b. Aider

Tout d'abord, pour que l'on vous propose de devenir développeur, vous devez soit vous proposer à un poste, soit simplement aider que ce soit pour le support aux utilisateurs ou en rapportant des bogues. Nous remarquons les personnes qui contribuent régulièrement au projet Gentoo et nous essayons de les récompenser en leur donnant une chance de devenir des développeurs pour le projet Gentoo. Gentoo a de nombreuses portes d'entrée et l'équipe de recrutement pour les développeurs de Gentoo (la Gentoo Developer Relations Recruitment Team) est constamment à la recherche de nouveaux développeurs. Les auteurs de documents ou les mainteneurs des infrastructures Gentoo sont également très importants pour que le projet puisse fonctionner correctement.

Vous pouvez chercher des propositions de postes pour devenir développeurs dans le GWN (Gentoo Week News), ou en faisant un /topic sur le canal #gentoo-bugs des serveurs irc.freenode.net. Si vous pensez pouvoir correspondre à une proposition, essayez de vous trouver un mentor ou contactez les recruteurs Gentoo qui pourront vous trouver un mentor pour vous. Merci de ne pas remplir de bogues de type « nouveau développeur », dans la mesure où cette tache est attribuée à votre mentor et tous les bogues de ce type seront clos.

2.c. Parrainage

Tous les nouveaux développeurs ont un parrain (plus souvent appelé mentor). C'est un développeur Gentoo et il a pour tâche de guider un nouveau développeur, mais aussi de proposer de l'aide au développeur après que celui-ci ait passé les étapes de recrutement.

Un mentor doit vous assister en vous apportant des réponses pour toutes les questions que vous pourriez avoir. Il doit également vous faire prendre conscience des responsabilités que vous aurez vis-à-vis de Gentoo et notamment celles en relations avec les tâches que vous effectuerez dans un premier temps.

Une fois qu'un développeur accepte d'être le parrain d'un nouveau développeur, il devra faire un rapport de bogue et l'assigner aux recruteurs Gentoo. La page des recruteurs Gentoo explique en détail la démarche à suivre.

2.d. Attendre

Tous les nouveaux développeurs passent alors dans une période d'attente d'au plus un mois, selon le temps que le mentor juge nécessaire pour que le développeur soit prêt, ainsi que le temps d'avoir des retours d'expérience de la part d'autres membres du projet Gentoo. Durant cette période, le nouveau développeur devra remplir un quizz qui sera révisé par son mentor et les recruteurs Gentoo pour s'assurer que le développeur est prêt. Dans certains cas bien précis, la période d'attente sera déterminée par les recruteurs et/ou les responsables des relations entre développeurs Gentoo.

Deux quizz sont proposés : le quizz ebuild et le quizz personnel. Les développeurs qui devront travailler uniquement sur les infrastructures, les GLSAs ou autres domaines ne concernant pas les ebuilds devront réussir le quizz de personnel. Tout développeur qui aura à utiliser un accès à l'arbre de Portage devra réussir le quizz ebuild.

Une fois que le nouveau développeur a rempli le quizz, il devra l'envoyer à son mentor qui sera responsable de sa relecture, avec les membres de l'équipe des recruteurs Gentoo. Si les réponses montrent qu'elles correspondent à un standard satisfaisant, le recrutement pourra continuer. Sinon, le nouveau développeur peut refaire le quizz pour autant qu'il soit encore dans sa période d'attente.

Enfin, les nouveaux développeurs doivent être ouverts à toutes les questions que n'importe quel membre de l'équipe de recruteurs peut être amené à lui poser. Tout développeur qui ne répond pas rapidement verra son bogue « nouveau développeur » fermé, lequel pourra être ouvert de nouveau, à la discrétion des recruteurs Gentoo uniquement.

2.e. Faire le grand saut

Une fois que votre mentor et les recruteurs Gentoo ont relu votre quizz et qu'ils pensent que vous rentrez dans un standard acceptable, vous devrez l'envoyer accompagné d'une clef publique DSA2 SSH2 (un fichier id_dsa.pub) aux recruteurs Gentoo. Si les recruteurs considèrent votre quizz comme satisfaisant, ils vous donneront accès aux services dont vous aurez besoin.

Une fois passé cette étape, vous entrez dans une période probatoire de trente jours durant laquelle votre mentor sera responsable de vos actions, en apportant son cachet. Encore une fois, les recruteurs Gentoo peuvent rejeter un développeur durant cette période s'ils le jugent nécessaire.

3. Ce qui est mis à disposition

3.a. Introduction

Le projet Gentoo propose aux développeurs l'ensemble des services dont ceux-ci pourraient avoir besoin pour faciliter leurs efforts de développement. Si vous avez besoin d'un service non fourni à l'heure actuelle, n'hésitez pas à contacter l'équipe qui s'occupe de l'infrastructure de Gentoo.

Une fois que vous êtes un développeur autorisé, votre recruteur devrait vous organiser les services présentés dans ce chapitre de telle manière que vous puissiez les utiliser. Si vous avez un quelconque problème, voyez avec votre recruteur ou l'équipe citée plus haut pour avoir un accès au service demandé.

3.b. Bugzilla

Les développeurs peuvent changer tous les aspects des bogues dans le Bugzilla. Si vous avez un compte existant, votre adresse électronique devra être remplacée par votre adresse Gentoo par un administrateur de Bugzilla.

3.c. CVS

Tous les développeurs ne reçoivent pas un accès CVS. Si vous avez besoin d'un accès au CVS de l'arbre Portage de gentoo, gentoo-projects, ou gentoo-x86, demandez à une personne de l'équipe des recruteurs qui le fera pour vous. Vous devrez sûrement justifier votre besoin pour qu'ils valident votre demande.

3.d. IRC

Quand vous devenez développeur, vous recevez automatiquement un statut d'opérateur sur le canal de discussion #gentoo-dev, ce qui signifie que vous êtes développeur. Contactez l'équipe relationnelle des développeurs si vous ne l'êtes pas. De plus les responsables d'équipe peuvent décider de vous donner un statut d'opérateur sur des canaux de discussion spécialisés comme par exemple #gentoo-hardened. Un abus de pouvoir de la part d'un opérateur sur #gentoo-dev peut entraîner une perte immédiate de ce statut et éventuellement une suppression de votre statut de développeur. S'il vous a été donné des pouvoirs d'opérateur, nous vous demandons de les utiliser de manière constructive pour améliorer la bonne tenue des divers canaux de discussions et éviter tout débordements de la part d'utilisateurs ou de développeurs.

Le statut d'opérateur sur #gentoo est donné à la discrétion des relations entre développeurs : cela ne signifie en aucun cas que l'utilisateur est un développeur.

Des canaux de discussion spécifiques Gentoo sont proposés comme #gentoo-hardened ou #gentoo-server, et l'attribution du statut d'opérateur sur ceux-ci est laissé à la discrétion de l'équipe concernée -dans notre exemple, les équipes « hardened » et « server ».

Les canaux de discussion IRC appartiennent aux responsables de projet respectifs, que ce soient des responsables stratégiques ou opérationnels, et le propriétaire peut à sa guise « voicer » ou « dévoicer » des membres du public. Si vous pensez que ces pouvoirs sont utilisés de manière abusive ou sont utilisés à mauvais escient, parlez-en à l'équipe relationnelle des développeurs Gentoo.

3.e. Forums (facultatif)

Demandez à un administrateur des forums, soit sur #gentoo-forums, soit via forum-mods@gentoo.org, de mettre à jour votre statut sur les forums Gentoo si cela est nécessaire. Les comptes sur les forums ne sont pas une obligation de la part des développeurs.

3.f. Courrier électronique

Tous les développeurs disposent d'une adresse électronique du type pseudo@gentoo.org qui doit être utilisée pour le projet Gentoo.

Merci de lire la documentation sur le système de courrier électronique de Gentoo pour plus de détails.

3.g. Listes de diffusion

Tous les développeurs doivent s'inscrire sur les listes de diffusions gentoo-core et gentoo-dev. Contactez un membre de l'équipe de recrutement pour vous inscrire à la liste de diffusion réservée aux développeurs gentoo-core, ou si vous avez un quelconque problème. Si vous êtes inscrit à d'autres listes de diffutions, vous devez vous désinscrire et réinscrire en utilisant votre nouvelle adresse électronique. La liste gentoo-core est prévue pour les discussions internes, mais la plupart des sujets devraient être débattus dans la liste gentoo-dev.

3.h. Accès à un shell

Actuellement les développeurs ont un compte shell sur dev.gentoo.org (toucan.gentoo.org) qui leur propose un espace de stockage pour le courrier électronique, un relai SMTP ainsi qu'un tunnel IRC pour que les développeurs puissent accéder aux serveurs IRC de freenode.

Pour des raisons de sécurité, l'accès est restreint au protocole SSH à clefs que votre mentor aura dû mettre en place pour votre compte. Pour vous connectez avec votre clef SSH, veuillez lire la documentation pour l'accès ssh au CVS.

3.i. Politique d'utilisation des services

Les services proposés par Gentoo doivent uniquement être utilisés pour votre travail de développement pour Gentoo. L'équipe s'occupant de l'infrastructure a le droit de désactiver n'importe quel compte qui présente un risque de sécurité. Cela inclut les comptes inactifs qui seront suspendus par l'équipe gérant l'infrastructure, si vous êtes en état d'hibernation, et votre statut sur le canal de discussion IRC #gentoo-dev passera au statut de ``voice''.

Si un quelconque fichier sur votre compte est trouvé et désigné comme potentiellement nocif pour les autres développeurs ou utilisateurs de la machine ou simplement présente un risque pour le projet Gentoo (comme par exemple des fichiers .torrents illégaux), l'infrastructure Gentoo désactivera votre compte qui ne sera réactivé (s'il doit l'être) qu'après investigation de la part des relations des développeurs Gentoo. Dans la plupart des cas, votre statut de développeur sera suspendu si de tels fichiers sont trouvés. La même politique est appliquée pour le CVS gentoo et d'autres services qui vous sont proposés par Gentoo.

4. Aide pour les nouveaux développeurs

4.a. Utiliser CVS

Introduction

Ce guide n'a pas pour prétention de servir de manuel d'utilisation à CVS. Pour cela, vous pouvez aller lire la page d'information de CVS (info cvs) ou encore le tutoriel CVS de Gentoo. Ce guide s'intéresse plus spécifiquement à l'utilisation de CVS et Repoman dans l'arbre des ebuilds de Gentoo.

Configuration

En général vous aurez les lignes suivantes dans votre fichier ~/.cvsrc :

cvs -q -z0
diff -u -B
checkout -P
update -d -P

Pour être sûr que les « digests » sont corrects, mettez cvs dans les paramètres de la variable FEATURES.

Enfin, plusieurs personnes utilisant CVS aiment utiliser la compression (-z#). Nous demandons aux développeurs qui n'ont pas un accès Internet avec une bande passante limitée d'utiliser -z0 (pour le contenu du dépôt CVS, et la charge de serveur CVS, vous aurez probablement une augmentation de la vitesse de transfert si vous n'utilisez pas de compression).

Récupération des modules par CVS/SVN

Plusieurs modules sont utilisés dans le dépôt CVS de Gentoo. Les ebuilds sont gardés dans le module gentoo-x86. gentoo contient les pages XML du site Internet, la documentation, les répertoires des développeurs, les images de développeurs, etc. gentoo-projects contient différents projets et remplace généralement le module gentoo-src. gentoo-src est conservé pour des raisons historiques, aussi veuillez envisager un autre module si vous l'utilisez encore.

# cvs -d nom_utilisateur@cvs.gentoo.org:/var/cvsroot co gentoo-x86

Avant de travailler sur l'arbre, c'est toujours une bonne idée de faire une mise à jour pour vérifier les modifications et pour prévenir les conflits. Vous pouvez mettre à jour n'importe quel sous-répertoire de l'arbre, si vous ne souhaitez pas mettre à jour l'arbre complet. Mais il est parfois bon de mettre la totalité de l'arbre à jour :

# cd gentoo-x86
# cvs update

Gentoo offre également des services subversion pour ceux qui préferent SVN à CVS. Beaucoup de projets principaux comme portage et baselayout sont désormais hébergés sur subversion.

# svn co svn+ssh://username@cvs.gentoo.org/var/svnroot/portage

Mettre Portage à jour

Si vous voulez utiliser CVS en tant qu'arbre de Portage primaire, vous pouvez ajouter les lignes suivantes dans votre fichier de configuration /etc/make.conf, en remplaçant moi par votre nom d'utilisateur :

SYNC="cvs://moi@cvs.gentoo.org:/var/cvsroot"
CVSROOT=":ext:moi@cvs.gentoo.org:/var/cvsroot"

Que vous vouliez utiliser les sources CVS (CVS checkout) pour votre arbre de Portage primaire ou non, vous devez vous assurer que cvs est dans votre variable FEATURES dans le fichier /etc/make.conf. Cela assure que Portage téléchargera tous les fichiers référencés par un ebuild dans sa variable SRC_URI lors du digest.

Vous pouvez ajouter digest à votre variable FEATURES, pour que Portage crée automatiquement les nouveaux digests. Vous pouvez aussi ajouter autoaddcvs pour que repoman, l'outil que vous utiliserez pour soumettre des ebuilds, ajoute automatiquement les digests manquants à votre place dans le CVS.

Sur les architectures le permettant, vous pouvez également utiliser sandbox dans votre variable FEATURES pour vous assurer que les ebuilds ne modifient pas le système de fichiers racine directement.

Ajouter/Supprimer des paquets

Admettons que vous avez déjà ajouté un nouveau paquet foo dans app-misc.

(Remplacez CVSROOT par le répertoire de votre arbre CVS racine.)
# cd $CVSROOT/app-misc
(Toujours faire une mise à jour avant de
travailler sur une partie de l'arbre CVS !)
# cvs update
# mkdir foo
(Nous ajoutons maintenant le répertoire du paquet foo dans le dépôt CVS.)
# cvs add foo
# cd foo
(C'est mieux de garder les ebuilds en travaux
dans un overlay hors de l'arbre CVS.)
# cp /repertoire/pour/foo-1.0.ebuild ./
(N'oubliez pas de créer un ChangeLog - lire la page de manuel d'echangelog.)
(Assurez-vous que PORTDIR_OVERLAY est activé dans votre répertoire CVS quand
vous créez les digests.)
# ebuild foo-1.0.ebuild digest
# cvs add foo-1.0.ebuild ChangeLog files
(FEATURES=autoaddcvs le fera pour vous.)
# cvs add files/digest-foo-1.0

Souvenez-vous que vous devez également ajouter un fichier metadata.xml contenant des informations sur le mainteneur. Lire la section Metadata Gentoo pour plus d'informations.

À ce moment-là de votre travail, vous êtes prêt à soumettre votre travail (lire la section sur la soumission plus bas). Mais que se passe-t-il si vous voulez supprimer foo-1.0 quand foo-1.1 est sorti ?

# cd CVSROOT/app-misc/foo
# cvs update
# cvs remove foo-1.0.ebuild files/digest-foo-1.0

Nous sommes fin prêt à faire des soumissions. Vous pouvez passer au chapitre suivant.

Soumettre

Utilisez toujours repoman commit au lieu de cvs commit. Repoman est un outil d'assurance qualité (QA) qui réalise un certain nombre de vérifications de base et crée les fichiers Manifests. Si une partie des messages de sortie de repoman ne vous semble pas claire, lisez la page de manuel (man repoman). Il est possible que vous ayez besoin de taper un certain nombre de fois votre mot de passe. keychain vous sera alors d'un grand secours.

(Assurez-vous qu'il n'y a aucun fichier appartenant à l'utilisateur root
avant d'utiliser repoman !
"scan" recherche dans le répertoire courant des données QA. 
"full" est plus complet.)
# repoman scan
("commit" effectue une recherche, puis se charge de faire la soumission et met
les digests à jour. Assurez-vous d'avoir fourni un message de ChangeLog
au contenu complet et utile...)
# repoman commit

4.b. Divers

Mettre des fichiers sur les miroirs

La procédure pour déposer un nouveau fichier dans distfiles sur les miroirs Gentoo est très simple : il suffit de le copier dans le répertoire /space/distfiles-local sur le serveur dev.gentoo.org.

Courrier électronique

Notre infrastructure permet aux développeurs de gérer leur propre courrier. La documentation sur le courrier électronique Gentoo contient les instructions nécessaires pour configurer au mieux votre adresse courrier gentoo.org.

Écrire sur Planet Gentoo

Nous avons mis en place Planet Gentoo qui est un service permettant de regrouper les articles écrits par les développeurs contribuant au projet. C'est optionnel mais nous vous encourageons à y participer, il aide la communication entre les développeurs, et les utilisateurs peuvent le trouver intéressant à lire.

Pour pouvoir poster du contenu sur Planet, vous devez avoir votre propre weblog (ou « blog »). De nombreux sites proposent ce service gratuitiement. Vous pouvez également en héberger un vous-même si vous en avez les ressources. Nous pouvons aussi en héberger un pour vous.

Nous souhaitons que le contenu de Planet Gentoo reste lié à Gentoo et/ou au développement et aux événements liés à Gentoo.

Si nous hébergeons le blog pour vous demandons que vous gardiez son contenu dans le cadre du sujet (articles sur ou liés à Gentoo). Vous devez aussi comprendre que si vous perdez ou laissez tomber votre statut de développeur, vous ne pourrez plus écrire d'articles sur votre blog.

Si vous disposez d'un blog externe, vous devez alors être en mesure de proposer un flux XML de contenu (flux RSS par exemple). Si votre blog est divisé en catégories, vous devez pouvoir fournir un flux qui ne couvre que la catégorie « gentoo » et pas les autres. Ce ne devrait pas être un problème dans la mesure où presque tous les blogs proposent des flux standardisés.

Pour une question de bon sens, faites attention à ce que vous écrivez. Vos points de vue pourraient être interprétés de manière erronée. Faites attention à ne pas entacher notre image.

SI vous souhaitez contribuer à Planet Gentoo, envoyez un courrier électronique à user-relations@gentoo.org, soit en demandant qu'on vous héberge un weblog, soit en donnant des détails concernant votre blog actuel. Nous nous occuperons ensuite des détails et laisserons alors votre plume parler.

5. La hiérarchie des développeurs

5.a. Introduction

Ce chapitre a pour but d'expliquer la hiérarchie chez les développeurs Gentoo et de donner aux développeurs un aperçu de la structure de gestion au sein du projet Gentoo pour la partie développement.

5.b. La structure de gestion

L'objectif de la nouvelle structure de management était de résoudre un certain nombre de problèmes chroniques concernant le management, la coordination et la communication au sein du projet Gentoo. En particulier, nous n'avions pas bien défini la structure de management directionnel et les rendez-vous non officiels et réguliers qui permettent de communiquer les mises à jour de statuts entre les développeurs occupant des postes critiques. En règle générale, la plupart de la communication avait lieu sur IRC et de manière plus sporadique via courrier électronique. Pratiquement personne, pas même un haut responsable, n'était tenu de clôturer les projets en temps et en heure.

À cause de cet état de faits, il était difficile d'établir des objectifs et de vérifier l'état d'avancement des divers projets. Ce manque de communication et de coordination rendait également le management difficile pour les développeurs à haute responsabilité même pour leurs propres projets. De plus, un autre problème classique était que nous n'avions pas de rôles bien définis, ni ne savions l'étendue du pouvoir de prise de décision chez les développeurs à haute responsabilité. Du coup, de nombreuses personnes ayant une haute responsabilité allaient jusqu'à ne pas savoir si elles avaient l'autorité de gérer leur propres projets et sous-projets. Même si cela n'a jamais été l'intention des personnes à responsabilité, c'était le résultat malheureux et direct du processus de développement qui manquait de structure : personne ne savait ce qui se passait, et tout le monde renvoyait les décisions exécutives à prendre à l'architecte en chef.

Évidemment, un plan était nécessaire pour résoudre rapidement et de manière définitive ces problèmes, en améliorant la communication, la coordination et les responsabilités. Les rôles et le pouvoir décisionnel nécessaires avaient besoin d'être définis pour les développeurs à responsabilités pour qu'ils puissent avoir un poste clair et une pleine responsabilité dans la gestion de leurs projets, et qu'ils puissent ainsi s'assurer que leurs projets soient réalisés dans les délais, et correctement.

La liste suivante donne l'ensemble du système :

• Responsables de haut niveau : décident des efforts de développement à fournir ;
• Responsables de sous-projets : font le lien entre les efforts de développement et leurs équipes respectives ;
• Responsables d'équipe : supervisent leur équipe et s'assurent de leur productivité ;
• Développeurs : développent et améliorent Gentoo.

5.c. Responsables de haut niveau et de sous-projets

Les responsables de haut niveau travaillent sur la mise à exécution des aspects majeurs du développement, comme par exemple la coordination des sorties de projets Gentoo. Ils sont également responsables de la répartition des efforts de développement dans les divers projets, et comment Gentoo peut s'améliorer, en utilisant les retours d'expérience des développeurs et utilisateurs.

Les responsables de sous-projets ont pour tâche de coordonner les demandes des responsables haut niveau et celles de la communauté Gentoo avec leurs équipes. Par exemple, les nouvelles directives pour l'architecture x86 peuvent concerner les équipes base-system et kernel, qui devront alors être coordonnées par un responsable de sous-projet.

Les responsables de sous-projet sont optionnels, tout autant que les responsables de haut niveau. Cependant dans la plupart des cas votre équipe finira tôt ou tard par travailler sous les recommandations des responsables d'architecture.

5.d. Responsables d'équipe

Les responsables d'équipe sont responsables de l'organisation des développeurs de leur équipe et de la coordination des sorties publiques de projets. Ils doivent également résoudre les problèmes relatifs à leur équipe, et proposer des améliorations de leurs produits en utilisant les retours d'expérience venant de la communauté.

Les équipes n'ont pas nécessairement besoin de responsable, et certaines équipes travaillent avec un système on-corrige-quand-on-reçoit et cette solution donne parfois de meilleurs résultats que s'il y avait un responsable d'équipe. Mais la décision d'avoir ou non un responsable d'équipe reste une décision que doit prendre l'équipe elle-même.

La plupart des équipes font partie d'un regroupement d'équipes qui est constitué avec pour objectif l'organisation autour d'un effort particulier à fournir. Vous pouvez vous rapporter à la page sur le projet Metadata pour plus de détails.

5.e. Développeurs

Les développeurs sont responsables du développement de la distribution ou du projet sur lequel ils sont assignés. Certains développeurs font partie d'une équipe, d'autres travaillent sur un projet qui n'a pas d'équipe attribuée, ni de regroupement d'équipe.

Si un développeur a un quelconque problème, il peut en parler avec son responsable d'équipe, leur responsable de haut niveau ou peuvent également envoyer un courrier à une liste de diffusion comme gentoo-dev ou gentoo-core en demandant des avis ou commentaires sur un point précis.

B. Guides

1. Guide pour les ebuilds

1.a. L'arbre de Portage

Introduction

L'arbre de Portage se trouve en général dans /usr/portage et est organisé selon une structure hiérarchique constituée de répertoires de catégories, suivis des répertoires spécifiques aux paquets. Voici un exemple : vous pourrez trouver le fichier util-linux-2.11y.ebuild dans le répertoire /usr/portage/sys-apps/util-linux. Il peut y avoir plusieurs autres versions d'ebuilds pour util-linux à côté de util-linux-2.11y.ebuild. C'est dû au fait que tous les ebuilds pour un paquet particulier (quelle que soit la version) partagent le même répertoire ma_categorie/mon_paquet dans /usr/portage, à moins que vous ayez des surcouches « overlays » installées.

Récupérer une version de l'arbre de Portage avec CVS

Si vous n'êtes pas familier avec le fonctionnement de CVS, vous pouvez lire le tutoriel CVS pour plus d'informations.

L'arbre de Portage se trouve dans le module gentoo-x86 de l'arbre de Gentoo Linux. Pour récupérer ce module (environ 350 Mo), vous devez tout d'abord préparer CVS, comme spécifié dans le guide cité plus haut, puis récupérer le module gentoo-x86.

Ce qu'on (ne) peut (pas) mettre dans l'arbre de Portage

Avant d'écrire un ebuild, vérifiez sur bugs.gentoo.org qu'il n'en existe pas déjà un, mais qui n'aurait pas encore été mis dans Portage. Allez sur bugs.gentoo.org, choisissez query et sélectionnez Advanced Search. Pour le produit, prenez Gentoo Linux et comme composant, ebuilds. Dans le champ réservé à la recherche écrivez le nom de l'ebuild, puis comme statut, selectionnez NEW, ASSIGNED, REOPENED et RESOLVED (RESOLVED est important ici), puis envoyez la requête. Pour les fainéants, cliquez directement ici.

En règle générale, l'arbre de Portage ne doit être utilisé que pour stocker des fichiers .ebuild, ainsi que divers fichiers qui leur sont liés, comme par exemple les correctifs et des petits fichiers de configuration. Ce genre de fichiers doit être placé dans le répertoire /usr/portage/macat/monpaquet/files pour garder une organisation des répertoires /macat/monpaquet la plus propre et ordonnée possible. Les exceptions à cette règle sont réservées aux correctifs de taille importante qui doivent être placés sur les miroirs Gentoo pour que les utilisateurs ne perdent pas de bande passante et d'espace disque inutiles en les télechargeant. De plus, vous ne devriez pas ajouter des fichiers binaires (non-ASCII) au CVS dans l'arbre de Portage. Cependant, si vous devez le faire (par exemple, si vous devez ajouter une petite image de type PNG pour une raison quelconque), assurez-vous de l'ajouter au CVS en utilisant l'option -kb comme suit :

# cvs add -kb monimage.png

L'option -kb indique à CVS que monimage.png est un fichier binaire et qu'il doit être traité de manière particulière. Par exemple, lui demander les différences entre deux versions de ce fichier ne sera évidemment pas permis. De même, tant qu'on est sur le thème des ajouts de modifications, tous les correctifs que vous ajoutez à Portage ne devront pas être compressés. Cela permet à CVS de récupérer les modifications et d'informer correctement les développeurs de la présence de conflits.

Souvenez-vous que les paquets que vous soumettez doivent être prêts à l'utilisation de manière autonome s'ils sont soumis comme étant stables. Assurez-vous que vous disposez d'un bon environnement de configuration qui satisfasse le plus grand nombre de systèmes et d'utilisateurs qui utiliseront votre paquet. Si votre application a un problème et que vous n'êtes pas sûr de la solution pour le faire fonctionner, vous pouvez vous inspirer de ce que les responsables d'autres distributions ont mis en place pour obtenir un paquet fonctionnel. Vous pouvez regarder chez Mandriva ou Debian ou Fedora pour avoir de bons exemples.

Quand ils effectuent une soumission au CVS, tous les développeurs doivent utiliser repoman commit en lieu et place de cvs commit pour soumettre leurs ebuilds. Avant de faire une soumission, vous devez exécuter la commande repoman full pour vous assurer que vous n'avez rien oublié.

Politique de soumission au CVS

• Toujours exécuter repoman scan avant de soumettre son travail ;
• Exécutez repoman full avant de faire une soumission ;
• Toujours vérifier que package.mask est en règle en effectuant un emerge --pretend monpaquet avant de le soumettre et vérifiez qu'il n'y a aucun conflit ;
• Toujours mettre à jour le ChangeLog avant de faire une soumission ;
• Toujours mettre à jour en premier package.mask avant de mettre à jour le paquet concerné. Il peut y avoir des conflits lors de la soumission de package.mask ;
• Toujours faire des soumissions atomiques. Si vous soumettez un paquet avec une nouvelle licence ou un paquet masqué, alors il vous faudra tout d'abord soumettre la mise à jour de package.mask, puis soumettre l'ebuild, le ChangeLog et le metadata.xml d'une traite. Sauf si vous souhaitez corrompre les installations des utilisateurs...

Le répertoire de destination pour les fichiers

Comme remarqué précédemment, dans chaque sous-répertoire de paquet, il y a un répertoire files/. Tous les correctifs, fichiers de configuration et tous les fichiers annexes à votre paquet doivent être placés dans ce répertoire. Vous aurez probablement à vous demander comment nommer un correctif que vous avez vous-même créé, simplement pour que votre paquet puisse compiler avec un nom de version spécifique. Il vous faudra alors le nommer par exemple monpaquet-1.0-gentoo.diff ou plus simplement 1.0-gentoo.diff. Remarquez la présence de l'extension gentoo qui indique aux utilisateurs que ce correctif a été créé par les développeurs pour Gentoo Linux et n'a donc pas été récupéré sur une liste de diffusion ou ailleurs. Encore une fois, ne compressez pas les fichiers diffs, car CVS n'est pas très bon dans la gestion des fichiers binaires.

Préfixez ou suffixez (comme par exemple monpaquet-1.0) tous les fichiers que vous mettez dans le répertoire files/ afin que les fichiers utilisés pour chaque version d'un ebuild soit identifiables entre eux et que les changements entre les différentes révisions soient visibles. C'est en général une très bonne idée. Vous pouvez également utiliser un autre suffixe si vous voulez donner plus de sens au nom du correctif.

Si plusieurs fichiers doivent aller dans le répertoire files/, vous pouvez créer des sous-répertoires comme par exemple files/1.0/ et mettre les fichiers en question dans le bon sous-répertoire. Si vous utilisez cette méthode, vous n'avez pas besoin d'indiquer plus d'informations dans le nom des fichiers, ce qui est d'ailleurs l'usage habituel, car c'est plus commode.

1.b. Scripts ebuild

Introduction

Les scripts ebuild sont la base de l'ensemble du système de Portage. Ils contiennent toutes les informations nécessaires pour récupérer, désarchiver, compiler et installer un ensemble de sources. Ils contiennent aussi les informations nécessaires pour réaliser n'importe quelle tâche de pré/post installation/suppression ou de configuration. Si la plus grande partie de Portage est écrite en Python, les scripts ebuild sont, eux, écrits en bash, dans la mesure où bash nous permet d'appeler des commandes comme si elles étaient appelées depuis une invite de commande. Un des principes importants dans la conception est d'avoir des commandes dans le script qui sont analogues à celles que l'on taperait dans une console si l'on installait le paquet manuellement. Pour cela, utiliser une syntaxe bash est une vraiment bonne chose.

Les scripts ebuild sont interprétés par les commandes ebuild et emerge. Il faut imaginer la commande ebuild comme un outil de bas niveau. Il peut construire et installer un simple ebuild, mais pas plus. Il vérifiera si les dépendances sont satisfaites, mais il n'essayera pas de les résoudre automatiquement lui-même. D'un autre côté emerge est un outil de haut niveau par rapport à ebuild. Il a la capacité d'installer automatiquement les dépendances nécessaires et d'effectuer des vérifications d'installation (avec pretend) pour que l'utilisateur puisse voir quels sont les ebuilds qui seront installés et s'arrêter là. En général, emerge vole la vedette à ebuild dans tous les domaines, sauf un. Avec ebuild, vous pouvez effectuer les étapes les unes après les autres lors de l'installation d'un paquet (récupération des sources, désarchivage, compilation, installation, et fusion dans Portage). Pour les développeurs, c'est un outil de correction d'erreurs précieux, car il vous permettra d'isoler les problèmes d'un ebuild par parties spécifiques.

Nommer les fichiers ebuild

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.

Si vous faites des améliorations non triviales dans un fichier ebuild déjà existant, vous devez copier le fichier ebuild dans un nouveau fichier, avec un numéro de révision augmenté de 1. N'oubliez jamais de laisser une mention de vos modifications dans le fichier ChangeLog, vous pourriez avoir de sérieux problèmes si vous ne le faites pas (par exemple votre accès CVS pourrait être révoqué).

Et évidemment nous avons une cinquième partie dans le nom de l'ebuild... l'extension .ebuild elle-même.

Le contenu d'un fichier ebuild

Cette partie est une introduction aux ebuilds. Pour une liste complète de toutes les possibilités d'un ebuild, il existe une page de manuel qui détaille le format interne les variables et les fonctions qu'on peut trouver dans un script ebuild :man 5 ebuild.

En-têtes

Quand vous soumettez vos ebuilds, les en-têtes doivent être strictement identiques au contenu du fichier /usr/portage/header.txt. Ne les modifiez en aucune façon et vérifiez bien que la ligne $Header: $ est telle quelle.

Les trois premières lignes doivent être identiques à :

# Copyright 1999-2005 Gentoo Foundation
# Distributed under the terms of the GNU General Public License v2
# $Header: $

Les variables

La première partie de tous les fichiers ebuild est constituée d'un certain nombre de variables. Pour plus d'information sur ces variables, consultez le guide de développement.

Les fonctions

Un certain nombre de fonctions que vous pouvez définir dans vos fichiers ebuilds permettent de contrôler la construction et le processus d'installation de votre paquet.

Les fonctions utilitaires

Vous pouvez également utiliser les fonctions suivantes dans vos ebuilds.

Fonctions utilitaires proposées par eutils.eclass

Vous pouvez utiliser les fonctions suivantes proposées par l'eclass "eutils" de vos ebuilds. Vous devez vous assurer que inherit eutils est présent dans votre ebuild pour pouvoir utiliser ces fonctions.

Fonctions utilitaires proposées par flag-o-matic.eclass

Vous pouvez utiliser les fonctions suivantes proposées par l'eclass « flag-o-matic » dans vos ebuilds. Vous devez vous assurer que inherit flag-o-matic est présent pour que ces fonctions puissent fonctionner. Vous ne devez pas modifier les configurations des compilateurs directement, à la place, utilisez flag-o-matic pour effectuer toutes les actions, comme par exemple filtrer les paramètres qui posent problèmes.

Les fonctions d'assistance fournies par toolchain-funs.eclass

Vous pouvez aussi utiliser les fonctions suivantes fournies par l'eclass "toolchain-funcs". Vous devez vous assurer que inherit toolchain-funcs est présent pour que ces fonctions puissent fonctionner. Ne spécifiez jamais d'options du compilateur ou de binutils directement, utilisez plutôt les fonctions de toolchain-funcs.

Le but des fonctions ci-dessous est de permettre la compilation croisée et l'utilisation du compilateur icc. Elles devraient être appelées quand un paquet utilise directement gcc, g++, ld, ranlib ou un des outils ci-dessous. En général, les paquets qui utilisent les outils de configuration automatique détectent la compilation croisée.

Règles à utiliser pour écrire un fichier ebuild

Dans la mesure où les fichiers ebuilds ne sont effectivement que des scripts shell, vous devriez pouvoir utiliser le mode d'écriture de scripts shell de votre éditeur pour les créer et modifier. Vous devez utiliser une indentation correcte, en n'utilisant que des tabulations (pas d'espaces). Assurez-vous que votre éditeur affiche les tabulations à moins de quatre espaces. Toujours s'assurer que vous utilisez des accolades pour encadrer les variables d'environnement. Par exemple, ${P} au lieu de simplement $P.

Les longues lignes sont coupées avec des « \ », comme par exemple :

./configure \
--prefix=/usr || die "configure failed"

Pour plus de détails, référez-vous à skel.ebuild (en général il se trouve dans /usr/portage).

Si vous utilisez Vim pour éditer des ebuild ou eclass, le fichier par défaut de vimrc, /etc/vim/vimrc, s'assure déjà de l'indentation correcte et des configurations concernant le type de fichier des ebuild et eclass existent. Pour de meilleurs résultats, comme par exemple avoir une coloration syntaxique spécifique aux mots-clefs des ebuilds, installez app-vim/gentoo-syntax.

Sur les systèmes non Gentoo, vous pouvez obtenir des résultats similaires en utilisant les lignes suivantes dans votre vimrc, ou mieux en installant les scripts « gentoo-syntax » qui peuvent être téléchargés à partir des serveurs mirroirs de Gentoo.

au BufRead,BufNewFile *.e{build,class} let is_bash=1|setfiletype sh
au BufRead,BufNewFile *.e{build,class} set ts=4 sw=4 noexpandtab

Si vous utilisez Emacs, vous pouvez installer par la commande emerge, le paquetage « app-emacs/gentoo-syntax » (pour GNU Emacs ou « app-xemacs/gentoo-syntax » (pour XEmacs). Ces paquetages fournissent des fonctions majeures pour Emacs pour l'indentation automatique et pour la mise en surbrillance des fichiers « ebuild » et des autres types de fichiers spécifiques au système d'exploitation Gentoo.

Si vous utilisez nano, alors vous avez de la chance ! Éditez simplement /etc/nanorc et décommentez la section liée aux ebuilds.

Les paramètres USE

L'objectif des variables USE est de vous permettre de configurer Portage et de généraliser et automatiser l'utilisation ou la non utilisation de certaines options de compilation. Voici un exemple. Imaginons que vous soyez un fan de GNOME et vous voulez que tous les ebuilds qui ont gnome comme option de compilation le supporte effectivement. Alors, vous ajouteriez gnome à votre variable USE dans /etc/make.conf et Portage ajoutera automatiquement les possibilités optionnelles de GNOME dans vos ebuilds si elles sont disponibles. Sinon, si vous ne voulez pas des options GNOME dans vos ebuilds alors qu'elles sont disponibles, éditez tout simplement /etc/make.conf et assurez-vous que gnome n'est pas présent dans la variable USE. Gentoo a un nombre important de paramètres USE vous permettant d'obtenir un système configuré exactement comme vous le souhaiteriez. De plus, vous pouvez désormais utiliser un paramètre USE par paquet, en éditant le fichier /etc/portage/package.use.

Dans vos propres ebuilds, vous pouvez vérifier si une variable USE est présent en utilisant la commande use <variable>. Elle s'utilise comme suit  :

if use X; then
  # Commands specific to X...
fi

Les paramètres USE peuvent également être utilisés pour définir des dépendances. Par exemple, vous voulez qu'un paquet soit nécessaire si un paramètre USE précis est utilisé. Cela se fait en utilisant la syntaxe param? (macategorie/monpaquet) dans la variable DEPEND de votre ebuild. Dans cet exemple, macategorie/monpaquet ne seront requis que si param est présent dans USE. Il est également possible de spécifier une dépendance qui devrait être honorée si un certain paramètre USE est présent et quelle dépendance devrait être utilisée si il n'est pas présent. Cela se fait ainsi : param? ( macat/monpaquet ) et !param? ( autrecat/autrepaquet ). Dans ce cas, si param n'est pas présent, autrecat/autrepaquet sera utilisé à la place de macat/monpaquet. Assurez-vous que vos ebuilds utilisent cette syntaxe et non pas une condition BASH. Les conditions BASH interfèrent avec le cache des dépendances de Portage et l'utilisation de celles-ci casserait votre ebuild.

Voici un point important sur l'utilisation de USE. La plupart du temps, un paquet aura un script ./configure utilisé pour effectuer les diverses étapes de configuration. En général, si votre ebuild utilise ./configure, toutes les fonctionnalités optionnelles seront activées ou désactivées en passant les bons arguments à la commande ./configure. Voici le meilleur moyen de faire cela :

DEPEND="X?       ( >=x11-base/xfree-4.3 )
       mysql?    ( >=dev-db/mysql-3.23.49 )
       apache2?  ( >=net-www/apache-2 )
       !apache2? ( =net-www/apache-1* )"

src_compile() {
  econf \
    $(use_enable X x11) \
    $(use_enable mysql) \
    || die "Error: econf failed!"
  emake || die "Error: emake failed!"
}

Cette méthode produit un très bon résultat. Nous n'avons pas à nous préoccuper de savoir quelles sont les configurations par défaut pour mysql ou X (activé/désactivé), nous indiquons explicitement à econf ce que nous voulons qu'il fasse, d'après les paramètres USE. En plus, vous obtenez un code propre et facile à lire.

Parfois, des options peuvent être conflictuelles. Retourner une erreur dans ce cas n'est pas une solution. Il vaut mieux choisir la meilleure option et ignorer l'autre. Pour cela, consultez les responsables du paquet en amont pour voir ce qu'ils recommandent, voyez quelle solution offre le plus de fonctionnalités ou lancez une pièce et choisissez pile ou face. Par exemple, l'ebuild msmtp peut utiliser SSL avec GnuTLS ou avec OpenSSL, ou pas de SSL du tout. GnuTLS est préféré, car il offre plus beaucoup plus de fonctionnalités que OpenSSL.

src_compile() {
    local myconf
 
    if use gnutls ; then
        myconf="${myconf} --enable-ssl --with-ssl=gnutls"
    elif use ssl ; then
        myconf="${myconf} --enable-ssl --with-ssl=openssl"
    else
        myconf="${myconf} --disable-ssl"
    fi
 
    econf \
        # Other stuff
        ${myconf} \
        || die "configure failed"
 
    emake || die "make failed"
}

Pour avoir une table des paramètres USE mise à jour en permanence, voyez ce lien.

1.c. Emplacements des systèmes de fichiers

Introduction à FHS

Les standards de systèmes de fichiers utilisés dans Gentoo Linux suivent de près le système FHS (pour File system Hierarchy Standard, standard de hiérarchie dans les systèmes de fichiers). Une description simplifiée de ce standard vous est proposée dans ce chapitre ; pour avoir les spécifications complètes, vous pouvez consulter le site pathname.

Comment placer vos paquets dans le système de fichiers

Normalement, si le paquet utilise autoconf et automake, les destinations par défaut de l'installation du paquet sont correctes, à quelques exceptions près :

• Si vous installez un programme dans /bin, /sbin, /usr/bin ou /usr/sbin, alors les pages de manuel correspondant à votre programme devraient être installées dans le répertoire /usr/share/man. Cela peut se faire en général en le spécifiant dans l'ebuild avec la ligne ./configure --mandir=/usr/share/man.
• Les fichiers info GNU doivent toujours être installés dans /usr/share/info, même si les fichiers info sont à propos de programmes et outils spécifiques à X11, GNOME ou KDE. Faites bien attention. /usr/share/info est l'unique emplacement officiel pour les fichiers info GNU. Dans la mesure où plusieurs scripts ./configure installent pas défaut les fichiers info GNU dans /usr/info, il est souvent nécessaire de faire un appel à ./configure avec pour argument --infodir=/usr/share/info.
• Les fichiers de documentation sont installés dans /usr/share/doc dans un sous-répertoire reflétant le nom, la version et la révision d'un programme particulier. Cela s'applique à tous les programmes : GNOME, KDE, X11, etc. Cependant, certains programmes installeront de la documentation supplémentaire et les placeront dans la hiérarchie /usr/share pour leurs propres besoins.
• Les programmes et bibliothèques spécifiques à X11 doivent toujours être installés dans /usr et non directement dans /usr/X11R6. Nous réservons la hiérarchie /usr/X11R6 pour le système X, version 11, sortie R6 en personne. D'autres distributions feront probablement une interprétation différente du FHS concernant cette hiérarchie.
• Les programmes GNOME et KDE, de la même manière, doivent être installés dans /usr.

En général, vos ebuilds doivent installer leurs fichiers dans l'arborescence /usr. Quelques programmes peuvent être compilés et liés avec ou non des bibliothèques de GNOME, KDE, X11, ce qui peut occasionner un peu de confusion. Notre solution consiste à tout installer dans /usr, ce qui empêche les ambiguïtés et évite une complexité inutile pour les auteurs d'ebuilds. L'emplacement dans lequel doivent être installés les fichiers d'un programme ne doit pas dépendre de la présence ou non de paramètres USE. Du coup, les ebuilds dans l'arbre de Portage s'installent presque toujours dans la hiérarchie /usr exclusivement.

1.d. Les scripts et utilitaires de Portage

Scripts publiques

Des scripts permettent à un administrateur système d'installer ou supprimer les paquets et de maintenir à jour la base de données des paquets.

ebuild est l'outil de base du système de Portage : il effectue toutes les tâches principales comme par exemple désarchiver, compiler, installer, fusionner, désinstaller les paquets. Il est appelé en utilisant la commande : ebuild chemin/vers/paquet.ebuild commande. Les commandes disponibles sont :

emerge installe de manière récursive le paquet et toutes ses dépendances dans le système de fichiers. Cette commande a de nombreuses options, faites un emerge --help pour en avoir la liste.

env-update met à jour les fichiers de configuration (entre autres mais pas seulement : /etc/ld.so.conf et /etc/profile.env) pour inclure les changements effectués par les paquets installés.

Scripts et commandes privés

Vous pouvez utiliser certains scripts dans vos fichiers ebuilds pour réaliser des tâches communes.

Si vous voulez un aperçu, jetez un œil aux scripts eux-mêmes dans /usr/lib/portage/bin.

1.e. Les dépendances des paquets

Pourquoi les dépendances sont importantes

Portage est plus qu'un simple script qui vous permet d'unifier la méthode d'installation d'un projet quelconque (programme, bibliothèque) à partir des sources. Il récupère et installe également toutes les dépendances nécessaires si vous les spécifiez correctement dans votre ebuild.

Dans les ebuilds officiels, toutes les dépendances ont été spécifiées de telle manière que si vous exécutez emerge net-www/mozilla/mozilla-1.0, Portage s'assurera que toutes les bibliothèques nécessaires à Mozilla seront construites et installées correctement avant que Mozilla ne soit lui-même construit.

Portage va même jusqu'à distinguer les dépendances dues à la compilation et celles dues au lancement. Cela dit, pour le moment, Portage installe toutes les dépendances de compilation et de lancement, et laisse l'état tel quel. Dans une prochaine version, il est prévu de permettre que seules les dépendances de lancement soient effectivement installées.

Comment préciser les dépendances dans vos ebuild

La variable DEPEND dans votre foo-x.y.z.ebuild indique à Portage les paquets qui sont nécessaires à la construction de foo. La variable RDEPEND indique à Portage les paquets nécessaires au lancement du paquet. La variable RDEPEND doit être explicitement renseignée même si son contenu est le même que la variable DEPEND car prochainement, cette variable dont elle correspond par défaut « DEPEND » ne sera plus utilisé par le système de gestion des paquetages Portage de Gentoo.

DEPEND="virtual/opengl
        dev-libs/libxml2"
RDEPEND="${DEPEND}"

Cela indique à Portage de construire foo-x.y.z, les paquets virtual/opengl (plus de précisions sur les virtuals seront données plus tard) et dev-libs/libxml2 étant nécessaires à la construction. Il ne précise pas la version d'opengl ou de libxml2 dont vous avez besoin, ce qui signifie que n'importe laquelle ira très bien.

La mention de n'importe laquelle fait évidemment un peu peur et ne fonctionnera pas en général. En revanche, pour des bibliothèques centrales qui font tout pour avoir des binaires toujours compatibles, cela fonctionnera. Pour d'autres bibliothèques, on peut évidemment préciser la version des dépendances.

>=sys-apps/bar-1.2
 =sys-apps/baz-1.0

>= et = font bien ce qu'on espère qu'ils feront : toutes les versions plus récentes que sys-apps/bar version 1.2 conviendront (ce qui signifie aussi que sys-apps/bar-2.0 suffira), alors que sys-apps/baz version 1.0 est l'unique version acceptée. Pour plus d'informations sur le schéma de version des paquets voir la section plus haut sur comment nommer des fichiers ebuild.

Voici d'autres méthodes pour spécifier la version des dépendances :

~sys-apps/qux-1.0
=sys-apps/foo-1.2*
!sys-libs/gdbm

~sys-apps/qux-1.0 va sélectionner la révision la plus récente de qux-1.0 dans Portage.

=sys-apps/foo-1.2* va selectionner le membre le plus récent de la série 1.2, mais ignorera la 1.3 et les versions plus récentes/vieilles. Ainsi foo-1.2.3 et foo-1.2.0 sont tous les deux valides, mais foo-1.3.3, foo-1.3.0 et foo-1.1.0 ne le sont pas. Veuillez noter que la version foo-1.22.3 correpond aussi et pourrait très bien provoquer des problèmes dans certains cas.

!sys-libs/gdbm vous empêchera d'installer ce paquet tant que gdbm sera déjà installé.

À noter

De nombreux problèmes peuvent survenir à cause des variables DEPEND et RDEPEND. Les conseils suivants devraient vous aider à éviter ces problèmes :

• Toujours indiquer la catégorie.
  Par exemple, utilisez >=x11-libs/gtk+-2 et pas >=gtk+-2 ;
• Ne pas utiliser d'astérisque (*) pour les dépendances >=.
  Par exemple, utilisez >=x11-libs/gtk+-2 et pas >=x11-libs/gtk+-2* ;
• Ne pas créer de dépendance sur un meta-paquet.
  Ne faites pas dépendre vos ebuilds de gnome-base/gnome, mais utilisez la bibliothèque spécifique ;
• Une seule dépendance par ligne.
  Ne mettez pas plusieurs dépendances sur la même ligne, car elles difficiles à lire ;
• GTK: toujours utiliser =x11-libs/gtk+-1.2* pour des applications GTK+1.

De plus, il est important de vérifier que toutes les dépendances sont mentionnées :

• Regardez dans configure.in ou configure.ac.
  Cherchez y des tests sur la présence de paquets tels que pkg-config ou des fonctions AM_* qui testent des versions spécifiques ;
• Regardez dans les fichiers .spec.
  Ces fichiers donnent de bonnes indications quant aux dépendances, mais ne les considérez pas commme complets ;
• Consultez le site de l'application ou de la bibliothèque.
  Vérifiez les dépendances mentionnées sur les sites concernés ;
• Lisez le fichiers README et INSTALL du paquet.
  Ils contiennent souvent des indications précieuses ;
• N'oubliez pas les dépendances non-relatives au programme même, par exemple pkg-config, la génération de la documentation, etc.
  Généralement, la compilation nécessite des outils tels que intltool, libtool, pkg-config, doxygen, scrollkeeper, gtk-doc, etc. Vérifiez que ces dépendances sont indiquées.

Pour les derniers détails sur les éléments DEPEND, lisez la section 5 de la page man sur les ebuilds : man 5 ebuild.

1.f. Tester et déployer

ChangeLog

Dès que vous mettez à jour un (ou que vous écrivez un nouveau) ebuild, vous devez également mettre à jour (ou créer) le ChangeLog correspondant. Le fichier skel.ChangeLog contient un exemple de ChangeLog que vous pouvez utiliser comme base.

L'objectif du ChangeLog est de documenter ce qui a été fait, pourquoi cela a été fait et par qui. Cela permet à la fois aux développeurs et aux utilisateurs de garder une trace des changements effectués de manière simple.

Le ChangeLog est tout d'abord fait pour les utilisateurs, donc assurez-vous qu'il reste court (jusqu'à un certain point) et évitez de devenir verbeux sur les détails techniques internes.

Sauvegarder vos propres ebuilds localement

Afin de pouvoir tester vos ebuilds et de permettre à Portage de les utiliser, vous devez les placer dans un répertoire connu. Portage utilisera la variable PORTDIR_OVERLAY que vous pouvez définir dans /etc/make.conf. Vous devriez fixer cette variable à votre répertoire local de travail (par exemple, /usr/local/portage).

Dans ce répertoire, vous devez avoir la même structure (et les mêmes catégories) que dans /usr/portage.

En utilisant PORTDIR_OVERLAY, vos ebuilds restent sur votre système, même après un emerge sync et ils restent connus de Portage.

Tester le paquet

Prenez le temps de penser à la façon de tester votre paquet. Parfois, les développeurs ont intégré une routine make check qui permet de tester les fonctionnalités de base du paquet. Dans ce cas, la commande FEATURES=test ebuild foo-x.y.z.ebuild test l'exécutera. Si cela ne fonctionne pas, essayez de résoudre le problème et proposez votre solution aux développeurs du paquet.

Dans le cas contraire, pensez à ajouter une routine src_test à votre ebuild. Elle sera exécutée avant la routine src_install et permet de vérifier que le programme fonctionne sur toutes les architectures. Chaque responsable d'une architecture appréciera cette fonction, car elle leur évite de devoir connaître le paquet en question.

N'oubliez pas les spécifications des ebuilds. La routine src_test ne doit pas être interactive. Si elle dépend d'autres paquets, utilisez l'option USE test pour indiquer qu'il y a des dépendances à la compilation. De plus, remarquez qu'une routine src_test n'est pas recommandée pour des applications graphiques X, car l'utilisateur qui exécute portage ne peut généralement pas lancer ce type d'application.

Outils de tests utiles

Vous disposez de quelques outils pratiques pour vous aider à écrire et maintenir vos ebuilds.

2. Guide pour les eclass

2.a. Introduction aux fichiers eclass

Le principe des fichiers eclass

Les fichiers eclass sont des modules de code partagé. Ils sont écrits en bash et ont la même syntaxe que les ebuilds ordinaires. Ils sont hérités par des ebuilds ou d'autres eclass pour proposer des configurations par défaut et des fonctionnalités qu'on peut retrouver dans de nombreux ebuilds similaires.

Cela permet d'assurer une réutilisation du code entre des ebuilds similaires.

Le premier chapitre montre rapidement comment écrire un eclass en y incorporant des astuces et techniques standards utilisées dans des eclass déjà existants. Le second chapitre offre un tour d'horizon des eclass de KDE. Le troisième explique comment créer un ebuild pour KDE en utilisant le groupe d'eclass de KDE.

Un exemple d'eclass simple

Voici un fichier eclass fictif : sourceforge.eclass, créé pour proposer la page Internet principale et des URI de téléchargement pour des projets hébergés par sourceforge.net.

# Copyright 2004 Gentoo Foundation
# Distributed under the terms of the GNU General Public License, v2 or later
# Author Dan Armak <danarmak@gentoo.org>
# $Header:$
# This eclass sets ${HOMEPAGE} and ${SRC_URI} to the standard values for
# sourceforge.net - hosted projects.

HOMEPAGE="http://${PN}.sourceforge.net/"
SRC_URI="http://download.sourceforge.net/${PN}/${P}.tar.gz"

Les quatre premières lignes forment l'en-tête qu'on peut trouver dans n'importe quel ebuild. Les deux lignes suivantes sont une description rapide de l'eclass. Le reste du code est ce qui fait effectivement le travail : initialiser SRC_URI et HOMEPAGE.

La plupart des eclass proposent des fonctions d'aide ou des déclarations de variables : ils contiennent les versions par défaut des fonctions spéciales d'ebuild (src_unpack, src_compile, etc.) Avant d'écrire une fonction par défaut dans un eclass, vous devriez prendre connaissance des fonctions par défaut déjà contenues dans ebuild.sh. Elles contiennent les fonctions qui seront exécutées si vous n'incluez pas de fonctions dans votre ebuild (même pas en passant par un eclass) : src_unpack(), par exemple, est une fonction par défaut qui est souvent utilisée. Si vous ne l'avez pas encore fait, jetez un œil dans les implémentations par défaut dans ebuild.sh.

C'est tout ce que vous avez besoin de savoir pour écrire des fichiers eclass. Mettez votre nouvel eclass dans ${PORTDIR}/eclass/ et ajoutez cette ligne au début de votre ebuild :

inherit sourceforge

Les contenus de l'eclass seront insérés à cet endroit. Souvenez-vous que toutes les fonctions et variables définies dans l'eclass peuvent être récrites dans l'ebuild dans la mesure où le code de l'ebuild sera exécuté après celui de tous les eclass dont il hérite. De ce fait, vous devez essayer de mettre le plus possible de configuration par défaut et de code mis en commun dans votre eclass. Toutes les modifications et configurations non-standards peuvent être mises dans l'ebuild.

Et vous pouvez bien sûr faire hériter un ebuild de plusieurs eclass en procédant ainsi :

inherit eclass1 eclass2 [...]

Mais faites attention à l'ordre dans lequel ils sont mis ! Souvenez-vous, les eclass peuvent hériter d'autres eclass et remplacer les configurations créées par d'autres, donc vous devez faire attention quand vous utilisez plusieurs eclass à la fois.

Nous allons maintenant donner une liste de petits trucs utiles pour l'écriture d'eclass avant d'aller voir les eclass déjà présents dans Portage.

inherit()

Cette fonction est présente dans ebuild.sh et permet l'héritage des eclass. Elle est appelée avec la liste des noms d'eclass à faire hériter : inherit <eclass1> [eclass2 eclass3...].

En plus de récupérer effectivement les sources des fichiers eclass, elle va mettre à jour les variables ECLASS et INHERITED qui sont utilisées par Portage pour mettre en tampon les dates de dernière modification des eclass. La variable INHERITED peut également être utilisée lors de l'écriture d'un fichier eclass : elle contient la liste des eclass hérités (dont la source a été récupérée) jusqu'au moment de la vérification, dans l'ordre. De ce fait, un eclass peut l'utiliser pour déterminer si oui ou non il a été appelé par d'autres eclass.

EXPORT_FUNCTIONS

Un bon set de fonctions prédéfinies dans un eclass peut souvent être utilisé comme tel. L'ebuild contiendra alors très peu de code (ce qui est une bonne chose). Cependant, les fonctions d'un eclass ne font parfois pas ce que l'on attend d'elles. Vous pouvez écrire une nouvelle fonction dans votre ebuild, en écrasant ainsi la définition proposée par l'eclass. Mais cela diminue l'avantage d'avoir un code réutilisable. Nous essayons donc, à la place, d'étendre les fonctionnalités des eclass.

Supposons que vous vouliez étendre src_compile(). Vous pouvez écrire une définition de src_compile() qui ne contiendra que les parties manquantes de l'eclass src_compile(). Vous pouvez alors appeler l'eclass contenant src_compile() et exploiter le code de votre fonction personnalisée.

Toutefois, si vous créez une nouvelle fonction src_compile(), bash oubliera l'ancienne et ne sera pas capable de l'appeler ! C'est ici que la macro EXPORT_FUNCTIONS entre en jeu.

Observons un autre problème en attendant la solution. Supposons que foo.eclass et bar.eclass définissent tous les deux src_compile(). Si vous héritez à la fois de foo et de bar, vous aurez à votre disposition plusieurs implémentations de src_compile(), selon l'ordre d'héritage que vous avez déclaré. Vous devez donc garder un œil sur l'ordre de l'héritage des eclass. Mais vous pouvez vouloir appeler de manière explicite n'importe lequel des deux src_compile().

Donc, tous les eclass ajoutent aux fonctions qu'ils définissent un préfixe. Du coup, foo.eclass va définir une fonction foo_src_compile() et bar.eclass définira de son côté bar_src_compile(). De cette manière, l'ebuild peut appeler les deux fonctions sans problème.

Cependant, vous voulez également avoir une fonction générique src_compile() ou peut-être même que l'ebuild en a une déjà définie. La macro EXPORT_FUNCTIONS résoud les deux problèmes présentés précédemment.

EXPORT_FUNCTIONS() {
	while [ "$1" ]; do
        eval "$1() { ${ECLASS}_$1 ; }" > /dev/null
        shift
	done
}

La fonction inherit() initialise ${ECLASS} au nom de l'eclass avant de récupérer les sources. L'eclass, à la fin, appelle EXPORT_FUNCTIONS() en lui passant comme paramètres la liste des fonctions par défaut qu'il propose. Par exemple, si vous appelez :

EXPORT_FUNCTIONS src_compile src_install

Alors, EXPORT_FUNCTIONS appellera eval() sur les chaînes de caractères suivantes :

src_unpack() { foo_src_compile() ; }
src_compile() { foo_src_compile() ; }

De plus, n'importe quel eclass hérité définira la fonction par défaut src_compile() à la fin, mais les deux fonctions peuvent également être appelées par l'ebuild si nécessaire.

Vous pouvez également étendre la fonction src_compile() en appelant la fonction de l'eclass à l'intérieur de votre propre fonction. Vous devez alors utiliser le nom complet de la fonction par défaut foo_src_compile. Par exemple :

#dans foo.eclass:
foo_src_compile() {
	[code par défaut ici]
}

EXPORT_FUNCTIONS src_compile
#fin du code de l'eclass

#dans un ebuild:
inherit foo

src_compile() {
	[code personnalisé ici]
	foo_src_compile
	[plus de code personnalisé ici]
}

Les sections de fonction

Parfois, étendre une fonctions en ajoutant du code avant et après n'est pas assez flexible. Avec des fonctions longues et complexes, on veut parfois pouvoir utiliser son propre code au sein des fonctions par défaut.

Les sections de fonction proposent une plus grande flexibilité qui permet de s'affranchir du problème soulevé. Elles cassent les fonctions en sections et vous permettent d'exécuter du code entre deux sections quelconques.

L'implémentation est simple. Prenons par exemple la fonction src_compile() depuis base.eclass (Note : il n'existe plus, mais c'est un assez bon exemple). Cette fonction ressemble à ceci :

base_src_compile() {
    ./configure || die
    emake || die
}

Ici, on trouve une même fonction, divisée en deux sections :

base_src_compile() {
  [ -z "$1" ] && base_src_compile all
  while [ "$1" ]; do
    case $1 in
      configure)
        ./configure || die;;
      make)
         emake || die;;
      all)
        base_src_compile configure make;;
    esac
    shift
  done
}

Ce code a été divisé en deux sections : configure et make. Dans notre exemple, ils correspondent aux deux commandes de la fonction d'origine.

Au centre de notre fonction, on a un bloc while;case...esac;shift;done. Ce bloc vérifie les paramètres passés à la fonction et exécute les lignes de code correspondant aux paramètres passés.

Le cas particulier all appelle la fonction de manière récursive avec une liste de sections dans l'ordre. C'est à l'auteur de l'eclass de maintenir cette liste.

La ligne avant le bloc indique que si on effectue un appel à cette fonction sans lui donner de paramètres, alors il faut agir de la même manière que si on avait pour paramètre all. Comme vous pouvez le constater, cette fonction effectue des appels récursifs. Remarquez également que faire base_src_compile configure all make est tout aussi autorisé. Il exécutera en fait base_src_compile configure configure make make.

Désormais, dans votre ebuild (ou eclass) héritant de base.eclass, vous récupérez une ébauche de fonction src_compile qui appelle base_src_compile sans paramètre. Cela est en fait équivalent à un appel de base_src_compile avec pour paramètre all, c'est-à-dire une exécution de toutes ses sections. Vous pouvez le laisser tel quel. Si vous désirez faire une extension à votre appel de fonction, vous pouvez définir un nouveau src_compile et appeler base_src_compile section après section :

src_compile() {
    run_my_code1
  base_src_compile configure
    run_my_code2
  base_src_compile make
    run_my_code3
}

Comme vous pouvez le remarquer, les sections de la fonction ajoutent une certaine flexibilité dans la mesure où vous pouvez désormais insérer du code entre deux sections, mais vous pouvez aussi les lancer dans un ordre différent, ou lancer seulement certaines sections proposées. Cela permet de mieux réutiliser le code.

Les fonctions debug-print-*

De nombreuses fonctions sont déjà proposées par ebuild.sh. Certaines d'entre elles, les fonctions debug-print-*, donnent accès à des fonctions de retour d'erreur de débogage pour les eclass. Elles vous permettront de faciliter le traçage de l'exécution de ceux-ci sans avoir à lire les (très) longs retour de déboggage de bash en mode debug. Par exemple, tous les eclass que j'ai créés appellent énormément ces fonctions.

debug-print() affiche simplement l'ensemble de ses paramètres avec un préfixe en « debug: ». Elle est utilisée quand un événement intéressant peut être mis dans les fichiers log de déboggage.

debug-print-function() affiche « debug: entering function $1, parameters: $2 [$3 ..] ». Elle est communément appelée au début d'une fonction.

debug-print-section() affiche « debug: now in section $1 ». Elle est habituellement appelée au début d'une section de fonction.

Les retours de déboggage vont normalement dans ${T}/eclass-debug.log. Vous pouvez cependant assigner une valeur dans la variable ECLASS_DEBUG_OUTPUT (dans make.globals/conf ou dans votre environnement tout simplement) et alors le retour y sera envoyé à la place de la valeur par défaut. Vous pouvez également utiliser la valeur spéciale « on » qui permet d'envoyer les messages sur stdout avec les autres messages d'emerge.

Ajoutons un retour de déboggage typique pour récupérer l'état d'avancement de l'exécution dans notre fonction exemple :

base_src_compile() {

  debug-print-function
  [ -z "$1" ] && base_src_compile all
  
  while [ "$1" ]; do
    case $1 in
      configure)
        debug-print-section configure
        ./configure || die;;
      make)
        debug-print-section make
        make || die;;
      all)
        debug-print-section all
        base_src_compile configure make;;
    esac
  shift
  done
  
  debug-print "${FUNCNAME}: result is ${RESULT}"
}

Pour votre information, ${FUNCNAME} est une variable interne de bash qui retourne le nom de la fonction courante.

2.b. Fichiers eclass existants

Introduction

La plupart des eclass sont simples et vous pouvez simplement les lire et repérer un certain nombre d'ebuilds utilisant ceux-ci pour comprendre comment ils marchent. De plus, la plupart des eclass sont bien commentés, donc c'est mieux de les lire directement.

Ce chapitre documente les relations existant entre les eclass kde*.

base.eclass

Cet eclass définit plusieurs variables et fonctions par défaut similairement à celles que l'on aurait dans un ebuild n'héritant pas d'un eclass (et qui sont alors définies dans ebuild.sh). Vous ne les utiliserez probablement pas directement, mais exploiterez des eclass kde qui héritent de base.eclass et utilisent ces fonctions.

Une fonctionnalité intéressante est auto-patch. Si vous initialisez la variable PATCHES à une liste de fichiers dans votre ebuild utilisant base_src_unpack() ou kde_src_unpack(), les sources seront alors corrigées depuis ces fichiers. Les correctifs doivent fonctionner avec l'option -p0 s'ils sont lancés depuis ${S}.

Remarquez que vous pouvez initialiser PATCHES sans définir un src_unpack() personnalisé dans votre ebuild ! C'est là l'astuce.

La récente fonction epatch() dans eutils.eclass est cependant bien plus puissante. Elle supporte les correctifs archivés, les répertoires de correctifs et les séries de correctifs, et détecte automatiquement le niveau de correctif requis. Il est probable que autopatch l'utilise un jour ou l'autre.

Remarquez que la section patch dans base_src_unpack() est désuète et sera bientôt supprimée. Si vous repérez un ebuild l'utilisant il devra être changé pour utiliser autopatch à la place.

cvs.eclass

Cet eclass propose un ensemble de fonctionnalités nécessaires pour créer des ebuilds cvs en « live ». Ce type d'ebuilds récupère les sources sur un serveur cvs spécifique au moment du désarchivage, ce qui permet de toujours avoir les derniers correctifs disponibles.

Cependant, le support nécessaire (exploitation des versions, etc.) pour des ebuilds « live » dans un cvs n'a pas encore été ajouté à Portage. Ils peuvent fonctionner avec cet eclass, mais ce n'est pas très pratique pour plusieurs raisons. Pensez-y à deux fois avant de créer un ebuild de ce type : il est fort probable que récupérer un instantané d'un cvs sera suffisant voire mieux qu'utiliser cvs.eclass. Si vous essayez d'ajouter un tel ebuild à Portage, appliquez à la lettre le guide d'utilisation de cvs dans les guides pour développeurs.

Avant de faire un héritage de cvs.eclass, initialisez toutes les configurations que vous souhaitez (et qui ne sont pas celles par défaut) ou au moins l'adresse du serveur et le nom du module. Voir la liste des possibilités de configuration et les valeurs par défaut au début du fichier cvs.eclass, marqués comme « ebuild-configurable settings ».

Ensuite, tout se passe de manière plus ou moins automatique. Une fonction (sans section) cvs_src_unpack() est proposée. Si vous voulez en savoir plus, lisez directement l'eclass.

kde-functions.eclass

Cet eclass contient toutes les fonctions d'aide relatives à KDE. Parmi elles, il en est certaines que vous n'utiliserez jamais directement dans un ebuild ; elles ne sont pas mentionnées ici et sont suffisamment commentées dans le fichier source.

Par « fonctions d'aide », nous entendons toutes les fonctions qui ne sont pas des fonctions spécifiques aux ebuilds (src_unpack(), etc.) Tous les eclass kde contenant de telles fonctions spéciales héritent de kde-functions.

La seule portion de code qui n'appartienne pas à une fonction dans kde-functions.eclass (qui est donc lancé lors de la récupération des fonctions à l'héritage) est un bloc qui détermine si oui ou non l'ebuild actuel est un ebuild de kde-base. Si c'est le cas, on aura KDEBASE=true. Cette variable est utilisée dans plusieurs tests ailleurs et il est commode d'avoir un test centralisé pour faire cela.

L'arborescence utilisée actuellement pour KDE

Une courte explication sur comment Gentoo gère les multiples versions pour KDE peut être utile :

Une application KDE de kde-base est toujours placée dans /usr/kde/${version-majeure}.${version-mineure}. Donc par exemple, KDE 3.1.x est mis dans /usr/kde/3.1. Cependant, ce schéma a été mis en place après la mise à disposition de KDE 3.0, ce qui fait que les anciennes versions sont situées dans des répertoires non standards : KDE 3.0.x est situé dans /usr/kde/3 (et non dans /usr/kde/3.0) et KDE 2.2.2 (la seule version disponible sous Gentoo pour les versions 2.x) est dans /usr/kde/2. Certains ebuilds sont installés dans /usr/kde/cvs.

De ce fait, tous les KDE ayant un numéro de version mineur différent entre eux peuvent coexister sur un même système. Les paquets kde-base ont un SLOT majeur.mineur (par exemple, 3.0, 3.1).

Depuis que les versions mineures de KDE sont supposées utiliser une version de QT compatible entre les versions mineures, nous n'avons qu'une seule version majeure installée, avec un slot différent : ils sont dans /usr/qt/${major}.

Un ebuild autre que kde-base est toujours installé dans /usr. Le paquet kde-env ajoute KDEDIRS=/usr dans /etc/env.d permettant aux applications concernées de fonctionner correctement. L'application compile et se lie avec la dernière version des bibliothèques KDE trouvées : l'eclass vérifie les emplacements standards dans un ordre décroissant (c'est-à-dire /usr/kde/cvs, puis /usr/kde/3.1, puis /usr/kde/3). Les ebuilds de kde-base se lieront toujours avec la bibliothèque kdelibs de sa propre version. Cela dépend bien sûr du paramètre passé à need-kde() (voir plus bas).

Plusieurs variables spéciales permettent de changer la configuration par défaut du système. Leur première utilité est de compiler un ebuild en utilisant un KDE spécifique que vous avez installé pour faire des tests, mais vous pouvez aussi les utiliser pour installer KDE dans un répertoire non standard, et donc avoir par exemple KDE 3.0.1 et 3.0.2 installés en même temps sur un même système. Encore une fois, c'est plus utile pour les tests et le développement que pour une utilisation normale.

Toutes les applications KDE (base et non-base) seront installées dans ${KDEPREFIX}, s'il est initialisé. Il a priorité sur toutes les actions d'installation dans un répertoire pour tous les eclass.

Une application KDE (même si c'est une application de kde-base) essaiera de se lier au kdelibs installé dans ${KDELIBSDIR} s'il est initialisé. S'il échoue, il utilisera le processus par défaut expliqué plus haut pour identifier la dernière version de kdelibs (ou la bonne version pour kde-base).

need-kde(), need-qt(), set-kdedir(), set-qtdir()

kde-functions.eclass fournit deux paires de fonctions : need-kde(), need-qt() et set-kdedir(), set-qtdir(). Ces fonctions s'occupent de la mise en place de tous les petits détails pour l'installation de multiples KDE et QT.

La fonction need-kde() est appelée avec un paramètre qui est le numéro de version minimal requis pour la bibliothèque kdelibs. Il ajoute les bonnes dépendances à DEPEND et RDEPEND, et appelle la fonction set-kdedir(). Si aucun paramètre n'est donné, le numéro de version 0 sera utilisé, ce qui signifie en fait que toutes les versions satisferont les dépendances requises. need-kde() appelle également need-autoconf() et need-automake() avec les paramètres adaptés à la version de KDE.

La fonction set-kdedir() détermine ensuite le préfixe d'installation et le répertoire pour kdelibs, qui seront utilisés dans votre ebuild. Ils sont ensuite disponibles avec respectivement ${PREFIX} et ${KDEDIR}, et sont gérés automatiquement dans kde.eclass. Remarquez qu'aucun ebuild ne devrait initialiser ${KDEPREFIX} et ${KDELIBSDIR} directement.

need-kde() regarde également la version minimale de QT requise pour cette version de kdelibs dans une table. Il appelle ensuite need-qt() avec cette version. L'ebuild d'une application qt-uniquement (c'est-à-dire non-kde) appelle en général directement need-qt(), sans passer par need-kde().

La fonction need-qt() ajoute la version requise de QT dans DEPEND et RDEPEND, puis appelle set-qtdir() avec celle-ci. La fonction set-qtdir() initialise ${QTDIR} pour qu'il contienne le répertoire par défaut de cette version de QT. Contrairement à set-kdedir(), set-qtdir() ne vérifie en fait pas si QT est bien installé où indiqué.

need-kde() ou need-qt() doit être appelé depuis la partie principale d'un ebuild (c'est-à-dire pas depuis une fonction), afin que tous les changements effectués sur DEPEND et RDEPEND affectent emerge.

need-autoconf(), need-automake()

Ces fonctions initialisent les variables d'environnement nécessaires pour pouvoir exécuter les versions requises de autoconf et automake. Elles suppriment également toutes les variables de ce type initialisées auparavant. Par exemple, appeler « need-automake 1.4 » supprimera toutes les variables WANT_AUTOMAKE* et initialisera NEED_AUTOMAKE_1_4 à 1. Pour plus d'informations, lire le code de ces fonctions et les commentaires au début de /usr/bin/auto{conf,make} (sur un système Gentoo).

kde_sandbox_patch()

Certains Makefile de KDE sont cassés. Ils effectuent des chown et chmod dans PREFIX à l'installation, mais ne respectent pas DESTDIR (${D}). Ainsi, à l'installation, ils copient correctement un fichier dans ${DESTDIR}/${PREFIX}/repertoire/de/foo, mais essaient ensuite de faire un chmod +x sur le fichier ${PREFIX}/repertoire/de/foo sur le système de fichiers, qui n'existent à priori même pas. Et s'il existe, le bac à sable (sandbox) empêche de réaliser cette opération.

Cette fonction lance un sed générique sur les Makefile qui résoud tous les problèmes connus. Elle est appelée avec les répertoires à traiter en paramètres et utilise les fichiers Makefile, Makefile.in et Makefile.am situés dans ces mêmes répertoires. Par exemple :

src_unpack() {
  base_src_unpack
  kde_sandbox_patch ${S}/dir1 ${S}/dir2/dir3
}

kde_remove_flag()

Il sert à ignorer les paramètres passés au compilateur qui sont connus pour casser les paquets générés. Vous devez l'appeler après avoir préparé l'espace de travail (dé-archivage des sources...) en lui donnant comme premier paramètre le sous-répertoire de travail de ${S} et comme second paramètre, le nom d'un paramètre à enlever. Remarquez que la fonction n'est pas récursive. Un exemple d'appel à cette fonction serait donc : kde_remove_flag foodir/barfoo -fomit-frame-pointer.

kde_remove_dir() et ${KDE_REMOVE_DIR}

Cette fonction supprime de la compilation un répertoire spécifique. Elle l'efface et supprime toutes les références à ce répertoire dans les fichiers dansles sous-répertoires, dans les fichiers configure et dans les Makefile. Remarquez que cela ne fonctionne que sur des sous-répertoires de ${S} pour le moment et ne fonctionne pas non plus pour les sous-répertoires de profondeur supérieure à 2. Vous pouvez l'appeler avec une liste des sous-répertoires à enlever ; elle travaille sur tous les répertoires les uns après les autres.

Vous pouvez l'appeler directement, mais pour éviter d'avoir à définir une fonction personnalisée pour src_unpack() juste pour cela, vous pouvez initialiser la variable KDE_REMOVE_DIR à la liste des sous-répertoires à enlever. kde_src_unpack() appellera kde_remove_dir ${KDE_REMOVE_DIR} après avoir fait son travail. Comme vous pouvez le constater, cela vous permet de vous économiser la peine d'avoir à redéfinir une fonction dans un ebuild, ce qui rend les ebuilds bien plus lisibles et propres.

kde.eclass

C'est l'eclass principal et central de KDE. Il contient la plupart du code relatif à KDE. Tous les ebuilds pour KDE en héritent d'une manière ou d'une autre. l'eclass kde hérite lui-même de base et de kde-functions.

Comme pour les autres eclass, lisez-le pour trouver ce qu'il fait. La plupart de ses fonctions sont simples et coulent de source. Voici un petit résumé :

La section globale de l'eclass (c'est-à-dire celle qui est exécutée lors de l'opération d'héritage) ajoute les bonnes dépendances pour kde-env, automake, autoconf, make et perl (ce dernier est utilisé par les scripts standards de configuration « configure » pour générer rapidement les Makefile). Il initialise également SLOT="0" par défaut.

kde_src_unpack() appelle simplement base_src_unpack() en lui passant tous les paramètres nécessaires (par exemple, les sections à exécuter). Ensuite, elle ajoute des petits éléments spécifiques à KDE. Elle touche à tous les fichiers .ui dans les sources non désarchivées pour regénérer tous les fichiers .cpp et .h. Elle appelle également kde_remove_dir() avec ${KDE_REMOVE_DIR} comme paramètre si cette variable est bien initialisée (voir plus haut dans la partie sur kde-functions).

kde_src_compile() effectue également un certain nombre d'opérations. Parmi celles-ci, elle exporte kde_widgetdir="${KDEDIR}/lib/kde3/plugins/designer" pour contourner un problème rencontré avec les anciens fichiers acinclude.m4.in de KDE. Elle initialise également HOME="${T}/fakehome" pour que tous les accès à ${HOME}/.kde et ${HOME}/.qt ne soient pas refusés par le sandbox et pour ne pas affecter directement les répertoires des utilisateurs. C'est une erreur de sa part de toujours vouloir accéder aux fichiers de configuration de ces répertoires.

kde_src_compile() comporte différentes sections. myconf ajoute à ${myconf} les paramètres par défaut du script de configuration de la compilation pour KDE (./configure), comme par exemple --prefix=${PREFIX} (souvenez-vous, ${PREFIX} est initialisé par set-kdedir()). Vous pouvez ajouter vos propres valeurs à ${myconf}, avant ou après cette section d'ailleurs ; souvenez-vous simplement de ne jamais écraser les anciennes valeurs parce que les utilisateurs peuvent eux aussi mettre des paramètres dans ${myconf}, dans le shell, pour pouvoir ajouter des paramètres qui seront utilisés par l'ebuild.

La section configure lance le script de configuration dans ${S} en lui passant ${myconf} en paramètre. Si le script de configuration n'existe pas, il essaiera de le générer en lançant make -f Makefile.cvs ou make -f admin/Makefile.common. Cela dit, cette étape de la compilation (qui est nécessaire pour les instantanés cvs ou pour les ebuilds qui modifient des fichiers comme configure.in) est également faite automatiquement.

La section make lance simplement emake || die. Enfin, une section all lance successivement toutes les sections présentées plus haut.

Finalement, kde_src_install() a une section make qui lance make install et une section dodoc qui lance dodoc sur certains noms de documents dans ${S}, comme par exemple README et COPYING.

kde-base.eclass

Cet eclass est maintenant désuet, les ebuilds doivent utiliser « inherit kde » à la place.

kde-dist.eclass

Cet eclass est utilisé pour les paquets de distribution kde core dans kde-base/*. Il hérite de kde.

Il initialise les variables DESCRIPTION et HOMEPAGE correctement et appelle need-kde ${PV}. Les petis paquets simples de kde-base/ (par exemple, kdetoys) n'ont généralement pas besoin de faire de changement ici.

kde-i18n.eclass

Cet eclass est fait pour les paquets kde-i18n-*. En fait, tous les ebuilds kde-i18n sont rigoureusement identiques et tout ce qu'ils ont à faire est d'hériter de cet eclass. Leurs variables ${P} et ${PV} feront le reste.

kde.org.eclass

Cet eclass est également désuet et tout son code a été déplacé dans kde-dist.eclass.

koffice-i18n.eclass

Cet eclass est fait pour les paquets de koffice-i18n-* et est très similaire à kde-i18n.eclass. Encore une fois, tous les ebuilds koffice-i18n sont identiques et tout ce qu'ils ont à faire est d'hériter de cet eclass.

kde-source.eclass

Cet eclass travaille à un niveau au dessus de cvs.eclass en ajoutant quelques fonctionnalités spécifiques à KDE. Par exemple, il récupère automatiquement le répertoire admin/ dans le module kde-common du cvs pour KDE. Lisez l'eclass directement pour en savoir d'avantage, notamment les configurations spécifiques au cvs pour KDE que vous pouvez lui passer.

2.c. Écrire des ebuilds KDE

Introduction

Ce chapitre explique comment écrire des ebuilds pour KDE. Tout ce qui est dit ici est une récupération et restructuration des informations présentes dans les eclass cités plus haut. Si vous avez un doute quelconque, allez voir d'autres ebuild, lire les eclass ou demandez tout simplement.

Un ebuild typique KDE

Le code ci-dessous devrait être évident pour vous après avoir lu ce HOWTO :

<Les en-têtes viennent ici...>
inherit kde

Certains ebuilds finissent directement ici. D'autres ont besoin d'un peu de personnalisation.

L'étape suivante est l'ajout de toutes les dépendances supplémentaires. Souvenez-vous : toujours ajouter aux variables, jamais les écraser !

Puisque notre objectif est d'éviter de définir des fonctions personnalisées dans nos ebuilds, sauf si c'est vraiment nécessaire, nous initialisons tout ce qu'on peut initialiser et appelons toutes les fonctions d'aide possible directement dans la section principale de l'ebuild. Souvenez-vous cependant qu'il y a des limitations dans le code de la section principale ; par exemple il ne doit pas produire de sortie (à l'exclusion à priori de l'utilisation raisonnable de debug-print()).

DEPEND="foo/bar"
RDEPEND="bar/foo"

Vous pouvez également vouloir ajouter quelques arguments supplémentaires à myconf, qui seront ensuite passés à ./configure (en supposant qu'on utilise la section configure de kde_src_compile()) :

myconf="${myconf} --with-foobar"

Nous devons également ajouter un correctif. S'il peut s'appliquer en utilisant le paramètre -p0 dans ${S}, vous pouvez utiliser la section autopatch de base_src_unpack(). Souvenez-vous, kde_src_unpack() appelle base_src_unpack() en lui passant tous les arguments passés à kde_src_unpack().

PATCHES="${FILESDIR}/${P-myfix}.diff"

Finalement, nous voulons une version étendue de src_install() pour s'occuper également de certaines documentations :

src_unpack() {
  kde_src_install
  dodoc ${S}/doc/*
}

Regardons maintenant l'ebuild que nous avons créé dans notre exemple :

<Les en-têtes viennent ici...>
inherit kde

# add deps
DEPEND="foo/bar"
RDEPEND="bar/foo"

# always enable foobar
myconf="${myconf} --with-foobar"

# fix terrible bug
PATCHES="${FILESDIR}/${P-myfix}.diff"

src_unpack() {
  kde_src_install
  # install some extra docs not included in make install's targets
  dodoc ${S}/doc/*
}

Un ebuild typique avec une fonctionnalité optionnelle KDE

Quand vous ajoutez une fonctionnalité KDE (eclass) à un ebuild existant, vous n'avez qu'à préfixer toutes les lignes spécifiques à KDE avec use kde &&, ou à créer des blocs entiers if [ -n "`use kde`" ]; then; fi.

Dans la section générale, ajoutez les lignes suivantes (seulement si le paramètre USE kde est mis, évidemment) :

inherit kde-functions

# This will add kdelibs, kde-env to your dep strings and set ${KDEDIR}
# to the correct value:

need-kde ${version} # Version minimale de kde requise

# Add anything else you need for kde support:
use kde && myconf="${myconf} --with-my-parameter"

Ensuite, indiquez à votre application de rechercher KDE dans la configuration ${KDEDIR} qui est disponible après un appel de need-kde(). Si vous ne voulez pas ajouter les dépendances à kdelibs, appelez set-kdedir() à la place de need-kde().

3. Erreurs classiques dans les ebuilds

3.a. Erreurs communes dans les ebuilds

Introduction

On peut retrouver un certain nombre d'erreurs communes dans les ebuilds qui sont soumis par les utilisateurs. Assurez-vous que les ebuilds que vous soumettez ne possèdent aucune de ces erreurs. Avant de soumettre un ebuild, assurez-vous que vous avez bien lu la Politique de développement des ebuilds pour Gentoo et le Guide des ebuilds pour Gentoo. Lisez aussi quelques ebuilds (plus d'un ou deux) dans l'arbre de Portage pour connaître le style dans lequel les ebuilds sont écrits.

Ensuite, il pourrait être utile de lire quelques ebuilds qui utilisent des eclass et comprendre comment les utiliser en lisant le Guide eclass. Finalement, vous devez lire le Guide de contribution d'ebuilds soigneusement avant de soumettre vos ebuilds.

En-tête cassé/invalide/manquant

Quand vous soumettez vos ebuilds, l'en-tête doit être exactement le même que celui de /usr/portage/skel.ebuild. Il est important de ne pas le modifier et de s'assurer que la ligne $Header: $ est intacte.

Les trois premières lignes doivent ressembler à celles-ci :

# Copyright 1999-2004 Gentoo Foundation
# Distributed under the terms of the GNU General Public License v2
# $Header: $

Nous n'avez pas besoin de modifier la ligne $Header: $ même si vous soumettez un ebuild pour une nouvelle version ou une correction. La ligne doit être présente. Quand on enregistre l'ebuild dans le CVS, cet en-tête sera modifié avec la version appropriée et la date. Il n'y a donc pas besoin de la modifier manuellement.

Non déclaration de IUSE

L'oubli le plus fréquent, et de loin, est la variable IUSE. Vous devez (selon le Guide des ebuilds pour Gentoo) inclure la variable IUSE, même si aucun paramètre USE n'est utilisé. S'il n'y en a aucun de supporté, ajoutez simplement la ligne suivante :

IUSE=""

P, PV, PN, PF redéfinis

Vous ne devez jamais redéfinir ces variables. Utilisez toujours MY_P, MY_PN, MY_PV, P0, etc. Lisez d'autres ebuilds dans Portage qui utilisent cela pour plus d'informations. La plupart des ebuilds utilisent la fonctionnalité bash des « expansions de paramètres ». Lire la page de manuel de bash pour comprendre comment elles fonctionnent.

Soit dit en passant, si vous trouvez un paquet qui redéfinit une de ces variables, ne le copiez pas. Soumettez un bogue pour cet ebuild.

Inclure les numéros de version dans SRC_URI et S

Vous devez essayer d'éviter d'inclure les numéros de version dans les variables SRC_URI et S. Toujours essayer d'utiliser ${PV} ou ${P}. Cela facilite la maintenance de l'ebuild. Si un numéro de version n'est pas cohérent par rapport à l'archive/source, alors utilisez MY_P. Par exemple, dev-python/pyopenal récupère une archive nommée PyOpenAL, donc nous effectuons une redéfinition comme suit :

MY_P=${P/pyopenal/PyOpenAL}
SRC_URI="http://oomadness.tuxfamily.org/downloads/${MY_P}.tar.gz"
S=${WORKDIR}/${MY_P}

DEPEND comporte des erreurs de syntaxe

Il y a plusieurs choses qui ne vont pas avec les variables DEPEND et RDEPEND soumis par des utilisateurs en général... Voici les points les plus importants à suivre lorsque vous écrivez la partie sur les dépendances.

• Toujours inclure la catégorie
  Par exemple, utilisez >=x11-libs/gtk+-2 et non >=gtk+-2.
• N'utilisez pas d'astérisque (*) pour les dépendances en >=.
  Par exemple, on doit avoir >=x11-libs/gtk+-2 à la place de >=x11-libs/gtk+-2*.
• Spécifique à GTK : toujours utiliser =x11-libs/gtk+-1.2* pour les applications GTK+1.
• Ne jamais dépendre d'un paquet meta
  Du coup, ne pas dépendre de gnome-base/gnome, mais toujours d'une bibliothèque spécifique, comme libgnome.
• Une dépendance par ligne.
  Ne mettez pas plusieurs dépendances sur la même ligne. Cela rend le code plus difficile à lire et à suivre.

DEPEND est incomplet

Voilà encore une erreur assez commune. La personne qui soumet l'ebuild le soumet, et l'ebuild fonctionne tout simplement, sans vérifier si les dépendances sont correctes. Voici quelques trucs pour trouver les bonnes dépendances.

• Lisez les fichiers configure.in ou configure.ac
  Lisez-les pour vérifier les paquets qui y sont inclus. Les éléments à rechercher sont l'utilisation de pkg-config ou les fonctions AM_* qui vérifient une version spécifique.
• Regardez les fichiers .spec inclus
  Un bon indicateur des dépendances est de regarder dans les fichiers .spec pour repérer des dépendances intéressantes. Cependant, ne vous y fiez pas uniquement en pensant que ce sera une liste complète des dépendances.
• Lire le site Internet de l'application/la bibliothèque
  Regardez sur le site de l'application pour repérer les dépendances qu'ils suggèrent comme étant nécessaires.
• Lisez les fichiers README et INSTALL du paquet
  Ils contiennent souvent des informations utiles sur comment construire et installer les paquets.
• Souvenez-vous des dépendances non-binaires comme pkg-config, les programmes de génération de documentation, etc.
  Souvent, le processus de construction nécessite des dépendances comme intltool, libtool, pkg-config, doxygen, scrollkeeper, gtk-doc, etc. Assurez-vous que ces dépendances sont bien respectées.

LICENSE invalide

Une autre erreur commune que les utilisateurs font au moment de soumettre des ebuilds est de proposer une licence invalide. Par exemple, GPL n'est pas une licence valide. Vous devez spécifier GPL-1 ou GPL-2. Même chose pour la LGPL. Assurez-vous que la licence que vous utilisez dans le champ LICENSE est une licence qui existe dans /usr/portage/licenses. Pour connaître la licence, vous pouvez lire le fichier COPYING dans l'archive source, il contient souvent la licence. Si la licence n'est pas spécifiée, utilisez la GPL-1 ou GPL-2 : on est souvent en présence de la GPL-2.

Si la licence du paquet que vous soumettez est unique et n'est pas dans /usr/portage/licenses/, alors vous devez soumettre une nouvelle licence dans un fichier séparé.

Architectures non testées dans les KEYWORDS

Merci de n'ajouter d'architectures dans les KEYWORDS que si l'ebuild a effectivement été testé sur cette architecture. De même, tous les nouveaux ebuilds doivent être en « ~ARCH ». Assurez-vous que quand vous incrémentez une version, toutes les architectures stables sont marquées d'un ~.

SLOT manquant

Assurez-vous que vous avez la variable SLOT déclarée dans l'ebuild. Si vous n'avez pas l'intention de l'utiliser, ne la supprimez pas. Mettez :

SLOT="0"

DESCRIPTION et HOMEPAGE incorrectes

Merci de vérifier si la variable HOMEPAGE est correcte et pointe bien sur la bonne page si les utilisateurs veulent récupérer plus d'informations sur le paquet. Et assurez-vous que la variable DESCRIPTION n'est pas trop longue. Les bonnes descriptions décrivent la fonction principale d'un paquet en une ligne.

Utilisation incorrecte des espaces au lieu de tabulations

Ce n'est pas vraiment un plaisir que de reformatter des lignes d'ebuilds parce que la personne qui l'a soumis ne suit pas les guides pour utiliser des tabulations à la place d'espaces. Donc s'il vous plaît, utilisez des tabulations.

Espaces en fin de lignes

Souvenez-vous que vous pouvez utiliser repoman sur vos ebuilds pour qu'il puisse vous signaler s'il reste des espaces inutiles à la fin de vos lignes, ou dans les lignes vides.

Ajouter des S=${WORKDIR}/${P} redondants

Si S=${WORKDIR}/${P}, alors vous ne devez pas l'ajouter dans votre ebuild. Vous ne devez l'ajouter que si l'on a quelque chose d'autre que ${WORKDIR}/${P}.

Documentation manquante

Si votre paquet a une documentation, assurez-vous que vous l'installez en utilisant dodoc ou en les mettant dans /usr/share/doc/${PF}. N'oubliez pas de vérifier s'il y a des erreurs quand vous lancez dodoc ou doins.

3.b. Erreurs communes de soumission d'ebuilds

Introduction

Merci de soumettre vos ebuilds correctement en suivant le Guide contribuer pour les ebuilds sur la page de documentation Gentoo.

Archiver un ebuild

S'il vous plaît, par pitié, n'attachez pas les ebuilds en archives. De plus attachez les correctifs séparément afin qu'on puisse les examiner facilement.

Proposer des ebuilds

Ne copiez-collez pas un ebuild dans le champ de commentaire du bugzilla.

Aucune description sur ce qu'est le paquet

Merci de nous permettre de savoir ce qu'est le paquet et remplissez le champ URL avec la page Internet de l'application, si elle existe.

Mise à jour d'un paquet sans changer le changelog

Si vous soumettez une mise à jour de paquet, assurez-vous de bien expliquer les changements que vous avez fait sur l'ebuild. Par exemple, si un paquet introduit une nouvelle fonctionnalité ou option et que vous utilisez un paramètre USE, indiquez-le dans votre bogue. Ne nous obligez pas à partir à la chasse aux modifications non expliquées.

C'est toujours mieux de soumettre un diff de mise à jour de paquet plutôt que de soumettre l'ebuild complet. La meilleure méthode pour le générer est celle-ci :

$ diff -u un-paquet-0.1.0.ebuild un-paquet-0.2.0.ebuild > ~/un-paquet-0.2.0.diff

Soumettre des ebuilds non changés pour incrémenter la version d'un ebuild.

Si vous soumettez une nouvelle version d'un paquet dans Portage, assurez-vous que l'ebuild existant fonctionne et que les changements sont inclus dans le nouvel ebuild (comme par exemple des nouveaux guides et manuels). S'il n'y a pas de changements nécessaires à effectuer sur l'ebuild par rapport à l'ancienne version, n'attachez pas l'ebuild. Signalez simplement dans le rapport de bogue que vous avez copié l'ebuild et vérifié que le paquet fonctionne et s'installe correctement.

3.c. Commentaires et suggestions

Merci d'envoyer vos commentaires, corrections et suggestions à Alastair Tse (en anglais).

4. Gentoo Metadata

4.a. L'utilité des fichiers metadada.xml

Le fichier metadata.xml a pour objectif de donner des informations supplémentaires sur les ebuilds. Le fichier metadata.xml devrait être présent dans tout répertoire de paquet. Vous pourrez trouver un fichier skel dans l'arbre de Portage, nommé skel.metadata.xml.

4.b. La structure d'un metadata

Un fichier metadata.xml peut contenir un certain nombre de balises :

Certains attributs peuvent être utilisés avec ces balises. Ils sont tous optionnels :

4.c. Exemples de metadata

Premier exemple

Dans le premier exemple nous vous proposons un fichier metadata.xml pour OpenOffice.org, dans lequel les ebuilds sont complètement gérés par un groupe nommé openoffice :

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE pkgmetadata SYSTEM "http://www.gentoo.org/dtd/metadata.dtd">
<pkgmetadata>
  <herd>openoffice</herd>
  <longdescription>
OpenOffice is the  opensource version of staroffice.
This ebuild allows you to compile it yourself. Unfortunately this
compilation can take up to a day depending on the speed of your
computer. It will however make a snappier openoffice than the binary
version.
  </longdescription>
</pkgmetadata>

Le groupe openoffice est défini dans herds.xml par le Projet de métastructure Gentoo.

<herd>
  <name>openoffice</name>
  <email>openoffice@gentoo.org</email>
  <description>openoffice related packages</description>
  <maintainer><email>pauldv@gentoo.org</email></maintainer>
  <maintainer><email>brad@gentoo.org</email></maintainer>
</herd>

Si vous souhaitez vous ajouter (ou enlever) dans un groupe, éditez herds.xml, qui est situé dans [gentoo]/misc dans le dépôt CVS de Gentoo. Assurez-vous de connaître l'alias mail caractérisant le groupe en question (par exemple le groupe sound a pour alias sound@gentoo.org) et ajoutez-vous à l'alias en question (en éditant /var/mail/alias/misc/<nom de l'alias> sur dev.gentoo.org).

Second exemple

Comme second exemple, nous allons voir le metadata.xml de mirrorselect. Cet ebuild est maintenu par le groupe tools-portage, mais a un mainteneur à part.

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE pkgmetadata SYSTEM "http://www.gentoo.org/dtd/metadata.dtd">
<pkgmetadata>
  <herd>tools-portage</herd>
  <maintainer>
    <email>johnm@gentoo.org</email>
    <name>John Mylchreest</name>
  </maintainer>
  <longdescription>
This utility is used to select the fastest mirror (distfiles) and provide a
nicer front-end for mirror selection (both rsync + distfiles) to a user.
  </longdescription>
</pkgmetadata>

5. Guide de maintenance des ebuilds

5.a. Introduction

Ce guide a pour objectif de présenter les procédures courantes de maintenance des ebuilds ainsi que les procédures de maintenance plus rares avec lesquelles les développeurs ne sont pas forcément très familiers.

5.b. Ajouter un ebuild

Quand vous créez un nouvel ebuild, vous ne devez inclure que les KEYWORDS pour les architectures qui ont été effectivement testées pour cet ebuild, ce qui confirmera qu'il fonctionne effectivement bien comme nous l'espérons et que les paramètres USE sont bien respectés dans le paquet résultant de l'installation à partir de l'ebuild. Dans la mesure du possible, vous devez également préciser les bibliothèques ou applications qui ont été effectivement utilisées lors des tests dans la mesure où vous serez responsable des problèmes inhérents à votre paquet pour les architectures présentées. Un minimum de vérifications doit être effectué comme s'assurer que l'application se lance bien et sans erreurs.

Si vous ajoutez un ebuild proposé par un utilisateur, faites comme si celui-ci n'avait pas fait de vérification sur les différentes architectures : il arrive souvent que les KEYWORDS aient été récupérés sur d'autres paquets ou générés à partir de la documentation proposée avec les sources des paquets. Cela ne signifie en rien que le paquet fonctionnera effectivement sur ces mêmes architectures.

5.c. Stabiliser des ebuilds

Les ebuilds ne peuvent être stabilisés, c'est-à-dire placés de ~arch à arch que si le mainteneur de l'ebuild ou un mainteneur de l'architecture concernée considère l'ebuild comme effectivement stable. Le mainteneur du paquet doit toujours être contacté juste pour le cas où il y ait une raison pour que l'ebuild ne soit pas stabilisé pour cette architecture. Si vous faites partie d'une équipe qui gère une architecture, alors vous pouvez marquer un ebuild pour celle-ci. Si l'architecture qui vous intéresse n'est pas indiquée, veuillez consulter le responsable.

Vous ne devez jamais stabiliser des paquets sur des architectures pour lesquelles vous ne pouvez faire aucun test. À la place, vous devez remplir un formulaire de bogue destiné à l'équipe de l'architecture correspondante, comme par exemple sparc@gentoo.org pour que l'équipe s'occupant de l'architecture SPARC stabilise si possible l'ebuild. Sinon, vous pouvez également chercher des développeurs Gentoo sur IRC qui pourront vous aider dans votre demande.

Il vaut mieux éviter d'utiliser arch-maintainers@gentoo.org et préférer ajouter les équipes d'architecture dans le champ CC d'un rapport de bogue à la place. De cette manière les équipes peuvent s'enlever de la liste une fois qu'ils ont effectué le travail, ce qui permet de savoir de manière précise quelles sont les équipes qui doivent toujours stabiliser le paquet.

5.d. Règles pour stabiliser un ebuild

SPARC : vous devez avoir l'autorisation du responsable (actuellement Weeve). Vous devriez être inscrit dans l'alias sparc pour pouvoir suivre le processus d'assurance-qualité, mais d'autres dispositions peuvent être prises si vous ne travaillez que sur un petit nombre d'ebuilds.

ALPHA : les responsables de paquets peuvent marquer leurs paquets stables pour Alpha, mais il leur est demandé d'en informer l'équipe Alpha pour effectuer des tests supplémentaires et ainsi permettre de corriger les éventuelles erreurs.

MIPS : vous devez avoir l'autorisation d'un développeur MIPS expérimenté. À cause de la grande variété de matériel, vous devez être inscrit dans l'alias mips et avoir accès à des machines MIPS.

5.e. Mettre à jour des ebuilds

Les nouveaux ebuilds sont rarement proposés directement avec un mot-clef arch et, même s'ils le sont, les paquets doivent être testés sur toutes les architectures listées dans la variable KEYWORDS d'un nouvel ebuild.

Les exceptions à la règle qui consiste à ne jamais proposer directement un ebuild en arch sont les correctifs majeurs ou les mises à jour de sécurité. Si la version précédente d'un ebuild contient des mots-clefs KEYWORDS pour lesquels vous ne pouvez pas faire de tests, vous devez les replacer en instable en changeant tous les arch que vous ne pouvez pas tester en ~arch. Si vous pensez que votre paquet ne fonctionnera pas du tout même en le mettant comme ~arch, alors il est préférable d'enlever le mot-clef et de faire une demande de tests à l'équipe concernée : si vous êtes amenés à faire ce genre de chose, vous devez faire un rapport de bogue à destination de l'équipe en question.

Si une nouvelle version introduit de nouvelles dépendances qui ne sont pas disponibles sur certaines architectures, vous devez rapporter un bogue ou demander de l'aide sur IRC avant de mettre à jour le paquet. Si vous avez réellement besoin d'ajouter cet ebuild et que c'est urgent, par exemple, pour une correction de sécurité, alors vous devez enlever tous les KEYWORDS qui posent problème et mettre en CC les architectures en question dans le bogue rapporté. Vous devez pour cela ouvrir un nouveau bogue pour l'architecture en question, sauf si celui-ci existe déjà.

S'il n'y a pas de nouvelles dépendances, n'enlevez pas de mots-clefs. Si la soumission échoue avec repoman, essayez de faire un cvs update complet et si le problème subsiste, alors faites votre soumission avec repoman -I et rapportez un nouveau bogue pour l'architecture qui pose problème en indiquant le problème dans votre message de soumission de CVS.

5.f. Déplacer des ebuilds

Déplacer des ebuilds se fait en deux temps :

Tout d'abord, vous devez déplacer l'ebuild dans le CVS. Pour faire cela, vous devrez copier l'ebuild à sa nouvelle position et soumettre celui-ci comme si vous soumettiez un nouvel ebuild.

Ensuite, vous devez changer tous les ebuilds qui dépendent (via la variable DEPEND) de l'ancien ebuild pour qu'ils pointent vers le nouveau. Alors seulement, vous pourrez enlever l'ensemble des fichiers relatifs à l'ancien ebuild avec cvs remove dans l'ancien répertoire.

Une autre méthode consiste à utiliser epkgmove qui fera le travail pour vous :

# epkgmove net-ancien/paquet net-nouveau/paquet

Une fois que le déplacement a été fait, ajoutez une entrée au dernier fichier dans profiles/updates/ dans l'arbre de Portage, avec la syntaxe suivante :

move net-misc/fwbuilder net-firewall/fwbuilder

Cet exemple devrait déplacer de manière transparente net-misc/fwbuilder vers net-firewall si les utilisateurs l'ont installé. De cette manière, les utilisateurs pourront désormais récupérer les mises à jour sur net-firewall quand elles sont disponibles.

5.g. Enlever des ebuilds

Quand vous supprimez un ebuild, assurez-vous qu'aucune dépendance dans Portage ne se casse à cause de la suppression. De plus, votre message de soumission au CVS devra expliquer clairement pourquoi l'ebuild a été supprimé du CVS.

Si vous avez besoin d'enlever des ebuilds, assurez-vous de ne pas enlever de manière accidentelle des ebuilds nouveaux ou stables uniquement pour certaines architectures. Si vous voulez faire une nouvelle version marquée comme stable, merci de faire un rapport de bogue ou d'en discuter sur IRC.

Vous devez également éviter de diminuer les versions stables des paquets quand vous supprimez des ebuilds. À la place, le mieux est de prendre la plus récente version marquée comme ~arch en premier lieu, puis supprimez les versions redondantes de l'ebuild.

5.h. Collision de fichiers

Si vous trouvez des paquets qui essaient d'installer des fichiers déjà installés par un autre paquet (par exemple en utilisant FEATURES=collision-protect), vous devez résoudre ce problème avant de soumettre l'ebuild. Si l'ebuild est déjà dans l'arbre Portage, remplissez un rapport de bogue sur ce paquet (voir plus bas pour une liste d'exceptions). La raison pour laquelle les collisions de fichiers sont critiques est que si « foo » installe le fichier /usr/bin/exemple et « bar » essaie d'écrire un autre fichier par dessus, puis plus tard « bar » est désinstallé, Portage va supprimer /usr/bin/exemple, avec de grandes chances pour que cela empêche « foo » de fonctionner.

La solution la plus évidente est d'ajouter une dépendance bloquante sur les deux paquets qui veulent installer le même fichier, afin qu'ils ne puissent pas être installés tous les deux en même temps. Mais, à moins qu'il n'y ait d'autres raisons pour que ces paquets se bloquent entre eux, vous devriez éviter ce genre de manipulation et essayer plutôt de modifier les paquets en utilisant l'une des méthodes suivantes (liste non exhaustive) :

• Modifiez le (R)DEPEND de « foo » pour que ce dernier dépende de « bar ».
• Enlevez les fichiers qui engendrent la collision de « foo » dans src_install ou pkg_preinst.
• Déplacez les fichiers en conflit dans un nouveau sous-paquet et faites en sorte que « foo » et « bar » dépendent ((R)DEPEND) tous deux de ce paquet.
• Changez le répertoire dans lequel « foo » ou « bar » installent les fichiers en conflit.

Dans certains cas, les collisions de fichiers ne peuvent pas être résolues ou ne sont pas critiques. Les exceptions connues actuellement sont les pages de manuel des modules Perl (qui écrasent celles de Perl lui-même), ainsi que les fichiers protégés par CONFIG_PROTECT (les collisions sur ces fichiers devraient tout de même être corrigées, mais elles sont moins graves puisque Portage n'écrasera aucun de ces fichiers).

6. Guide pour signer des modifications

6.a. Comment signer des Manifests

Prérequis :

• >=sys-apps/portage-2.0.51_pre10
• >=app-crypt/gnupg-1.2.4

Préparation de la clef :

• Créez une nouvelle clef GnuPG DSA d'une longueur d'au moins 1024 bits, d'une période d'expiration de moins de six mois et avec un bon mot de passe.
• Envoyez la clef au serveur de clefs.

Configuration de Portage :

• Mettez à la variable PORTAGE_GPG_DIR la valeur de votre répertoire gnupg (par exemple ~/.gnupg/ ou le répertoire où le fichier contenant la clef se trouve).
• Mettez à la variable PORTAGE_GPG_KEY la valeur de votre clef d'identification pour la nouvelle clef.
• Ajoutez le paramètre FEATURES="sign" à votre configuration.

Maintenant, vous devriez pouvoir signer vos Manifests lorsque vous effectuez une soumission avec repoman. Repoman va vous demander votre mot de passe avant de soumettre le Manifest. Cette étape se fait après qu'il ait soumis l'ensemble des autres fichiers. Pour le moment, repoman ne vérifie pas encore si le Manifest était déjà signé ou non, ce qui fait que d'autres développeurs peuvent supprimer votre signature du paquet ultérieurement. Cet état de fait changera lorsque la signature des Manifests deviendra obligatoire.

6.b. Comment vérifier des Manifests

Pour le moment Portage n'a pas encore intégré d'outil de vérification. Un premier essai qui permette de vérifier un Manifest est disponible pour tester ici. C'est un code en version alpha, très incomplet, et il n'est là que pour tester. Aucune garantie n'est donnée.

C. Les politiques

1. La politique concernant les ebuilds

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.

2. La politique concernant l'étiquette

2.a. Introduction et quelques suggestions simples

Ces suggestions sont faites pour servir de guide simplifié à ce que les Relations entre Développeurs voient comme étant une bonne étiquette pour les développeurs. Elles devraient couvrir l'ensemble du sujet et devraient être appliquées autant que possible.

Cela ne veut pas dire que nous voulons que vous suiviez ce guide à la lettre : cela ne veut pas non plus dire que vous devez être d'accord sur tous ses points. En revanche on espère que tous les développeurs gardent une sorte de standard dans le comportement vis-à-vis de la communauté. Cela dit, vous pourriez être sanctionné ou suspendu si un tel standard n'est pas atteint.

Par standards raisonnables, nous n'entendons pas que vous agissiez d'une manière la plus formelle possible ou que vous parliez comme un CEO. Nous voulons juste que vous ayez du respect autant envers les développeurs qu'envers les utilisateurs, quelles que soient les opinions de chacun (même si vous pensez qu'ils ont tort).

Vous devez faire votre possible pour écrire avec le moins de fautes d'orthographe et de grammaire, où que vous soyez : que ce soit dans les messages de soumission CVS, dans un ChangeLog ou même sur IRC si vous voulez être bien vu par les autres. Mais ne vous inquiétez pas. Ce n'est pas dramatique si vous n'y arrivez pas. Vous ne le remarquez peut-être pas, mais en essayant de corriger tout ça, le temps passé à essayer de lire vos phrases est largement augmenté si vous ne faites pas un effort. D'un autre côté il ne faut pas non plus perdre trop de temps à essayer d'être d'une éloquence extrême qui sera longue à déchiffrer.

2.b. Ce que vous devez essayer d'éviter

Vous devez essayer de ne pas être brutal, rude, abusif ou impoli, quelles que soient les circonstances. Parfois, un simple commentaire sarcastique peut changer le regard que porte le lecteur vis-à-vis de ce que vous écrivez. Si vous pensez devoir dire quelque chose de désagréable au point de déranger et que vous avez vraiment besoin de le dire, assurez-vous que les gens comprennent que vous n'essayez pas d'être offensant.

Souvenez-vous que vous êtes un représentant officiel de Gentoo. Cette fonction doit vous rappeler que vous devez garder un certain niveau de professionalisme et de courtoisie dans votre vie de tous les jours face aux autres développeurs et aux utilisateurs.

2.c. Trucs et astuces

ChangeLogs

• Rendez vos ChangeLogs lisibles par un utilisateur moyen : essayez de garder les choses simples et courtes autant que possible, mais n'oubliez pas de donner toutes les informations critiques nécessaires. Souvenez-vous que les ChangeLogs doivent être écrits dans un bon anglais, même s'ils sont courts. La ponctuation est, par exemple, essentielle.
• Merci d'éviter de parler dans un langage « gentooifié », sauf pour des termes acceptés classiquement comme « ebuild », « eclass »ou « Portage ». Si vous commencez à écrire beaucoup, utilisez une ponctuation juste et bien placée.

• Tout nom de fonction doit être encapsulé dans des signes de ponctuation.
• Écrire : « version bump. » c'est bien ; écrire « Version bump; see bug #... » c'est beaucoup mieux. Cela n'aide pas seulement l'utilisateur, mais aussi les autres développeurs.
• N'utilisez pas de phrases du genre « Tested for months, should work. », ou « I think this should fix the problems. » pour quelque chose qui fait ou non son boulot. C'est mieux de signaler aux utilisateurs de tester le paquet en profondeur et vous rapporter tous les bogues rencontrés.
• Quand vous faites une référence à des sections d'un ebuild, comme par exemple la variable homepage, utilisez « HOMEPAGE » en n'oubliant pas de mettre des guillemets anglais et d'utiliser la bonne casse (majuscule ou non). Cela rend les choses plus précises et indique au lecteur que vous avez effectivement changé la variable, au lieu par exemple du homepage où votre paquet ira quand il démarrera.
• Quand vous utilisez des acronymes, merci d'utiliser la bonne casse. Par exemple, « ALSA » et non « alsa », « Win4Lin » et non « win4lin ».

Ebuilds

• Essayez de ne pas faire de mises à jour continuelles sauf si c'est réellement une nécessité, par exemple si la mise à jour apporte un plus ou si c'est une correction de sécurité importante. Voici des exemples de mises à jour intempestives à éviter :
  • Vous changez des erreurs d'orthographe dans les commentaires d'un fichier de script, vous modifiez l'indentation du code ou toute autre modification du même ordre ;
  • Vous modifiez un ebuild non lié au noyau pour qu'il supporte une nouvelle version de noyau (ou une nouvelle version d'une bibliothèque) pour permettre à plus d'utilisateurs d'installer votre ebuild, mais sans rien changer pour les utilisateurs de la version courante.
  En règle générale, des corrections qui apportent des changements non triviaux sur un quelconque fichier d'un ebuild justifient une révision. Autrement dit, si votre correctif modifie un comportement pour les utilisateurs courants, vous devez faire votre révision en faisant en sorte qu'ils puissent savoir qu'ils peuvent faire une mise à jour. Veuillez consulter les règles à propos des ebuilds.
• Respectez les préférences des développeurs en matière de code. Modifier de manière inutile la syntaxe d'un ebuild augmente la charge du serveur CVS et peut causer des complications pour les autres. Les modifications de syntaxe doivent toujours être appliquées si elles apportent un réel plus, comme par exemple une compilation plus rapide, des informations supplémentaires pour l'utilisateur ou une conformité aux politiques du projet Gentoo.

IRC

• Soyez courtois et respectez tout le monde, même s'ils vous submergent de messages.
• N'abusez pas de votre position et ne discriminez pas d'utilisateurs, que ce soit pour une blague ou par pur sarcasme.
• Répondez aux questions en utilisant vos connaissances étendues. Il est toujours mieux de ne pas répondre aux questions pour lesquelles vous ne sauriez répondre sans éviter la moindre confusion. Il n'y a pas de politique sur les dommages collatéraux que peuvent causer les développeurs aux utilisateurs, mais si un développeur peut apporter de l'aide et qu'il lui est proposé par exemple un accès SSH sur la machine en panne, le développeur sera tenu responsable de ce qu'il effectuera sur la machine de l'utilisateur. De ce fait, nous ne recommandons clairement pas ce genre de manipulations.
• Si vous êtes un développeur ayant un statut d'opérateur, vous ne devez pas en abuser. Si vous êtes en désaccord avec un utilisateur, vous devez résoudre le problème de la manière la plus pacifique possible et ne pas en venir à les renvoyer ou même les bannir, sauf si la situation est vraiment sans issue et que les autres développeurs approuvent l'usage de ce type de mesure.
• #gentoo et #gentoo-dev sont des canaux de discussion où le langage est poli et courtois. Les autres canaux de type #gentoo- suivent les règles établies par leurs propriétaires respectifs. Puis que la majorité du traffic sur #gentoo-dev est générée par des développeurs Gentoo, les gens perçoivent ce canal comme celui qui représente officiellement Gentoo. Afin de présenter Gentoo de manière la plus professionnelle possible nous demandons que les développeurs gardent #gentoo-dev de manière la plus professionnelle possible.

Forums

• Soyez courtois et respectez tout le monde, même s'il y en a qui posent des questions inimaginables. Soit vous répondez de manière courtoise, soit vous ne donnez pas votre opinion.
• Suivez les règles du forum et essayez de rester dans le fil du sujet au lieu d'en sortir.
• Essayez d'être actif. Si des utilisateurs demandent pourquoi quelque chose a été ajouté, merci de l'expliquer. Si les utilisateurs demandent pourquoi un élément est manquant, expliquez-le. Utilisez vos connaissances et aidez dans la mesure du possible. Cela dit, si vous ne savez pas, ne répondez pas, pour éviter toute confusion.

Courrier électronique

• N'envoyez pas de courrier électronique en HTML (cela peut énerver) et il est recommandé d'utiliser un client mail qui formate le texte (80 caractères par lignes, etc.) avant l'envoi. Certaines personnes bloquent les mails contenant du code HTML, ce qui peut occasionner quelques problèmes dans les correspondances.
• Quand vous répondez à des utilisateurs ou développeurs par mail, soyez courtois et ne renvoyez pas un utilisateur à un autre développeur. Essayez d'expliquer pourquoi les choses sont ce qu'elles sont, dans la mesure du possible. Un exemple à suivre par exemple, serait : « Je transmets votre courrier à <insérer un nom ici> dans la mesure où <personne> est désormais le mainteneur de ce paquet. Toute question se rapportant à ce sujet doit désormais être adressée à <personne>. Veuillez nous excuser du dérangement que cela peut vous occasionner. »

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