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 (quelque soit la version) partagent le même répertoire ma_categorie/mon_paquet dans /usr/portage.

Si vous n'êtes pas familié au 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 350Mo), 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.

Avant d'écrire un ebuild, vérifiez sur bugs.gentoo.org s'il existe déjà ebuild pour ce que vous voulez faire, mais qui n'aurait pas encore été mis dans Portage. Allez sur bugs.gentoo.org, choisissez query. 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 rangé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 ce n'est en général pas une bonne idée d'ajouter des fichiers binaires (non-ASCII) au CVS. 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 adjoindre 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 devront ne 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 paquet est cassé, et que vous n'êtes pas sûr de comment faire pour le faire fonctionner, regardez ce qu'ont fait d'autres distributions qui ont effectué leur propres versions de ce paquet. Vous pouvez regarder chez Mandrake ou Debian pour avoir de bons exemples.

Vérifiez de nouveau votre ebuild pour vous assurer de sa bonne correction en consultant la section concernant les Erreurs fréquentes dans les ebuilds Gentoo.

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

• 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 la licence, d'une traite. Sauf si vous souhaitez corrompre les installations des utilisateurs...

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 poser la question de 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.

S'il y a plusieurs fichiers qui 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.

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 un invite de commande. Un des principes importants dans la conception que l'on retrouve derrière les scripts ebuild 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 si elles sont 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.

Les noms de fichiers ebuild sont constitués de quatre parties logiques :

La première partie est le nom du paquet, qui ne doit contenir que des lettres minuscules, des nombres entre 0 et 9, et les caractères trait d'union « - », blanc souligné « _ », ou plus « + ». Par exemple, util-linux, sysklogd, mod_php et gtk+.

La seconde partie est la version du paquet, qui est en général la même que la version de l'archive source principale. La version est en général composée de deux ou trois nombres séparés par un point comme 1.2 ou 4.5.2 (cependant des séquences plus longues sont supportées) et peut avoir une lettre seule, qui suit le dernier chiffre ; par exemple 1.4b ou 2.6h. La version du paquet est liée au nom du paquet par un trait d'union. Par exemple foo-1.0, bar-2.4.6, etc.

La troisième partie (optionnelle) contient un suffixe spécial : au choix _alpha, _beta, _pre (pré-sortie), _rc (candidat à une sortie) ou _p (correctif). Ils sont toujours suivi directement d'un nombre. Par exemple linux-2.4.0_pre10. Pour une version identique (voir la deuxième partie du nom d'un ebuild) un paquet _alpha est plus vieux qu'un paquet _beta, un _beta est plus vieux qu'un _pre, un _pre est plus vieux qu'un _rc, et un _rc est plus vieux que le même paquet sans suffixe. Un paquet sans suffixe est plus vieux qu'un paquet avec _p. Cette partie est utilisée uniquement pour signaler une mise à jour dans une même version.

La quatrième partie (encore optionnelle) d'un nom de paquet est le numéro de révision spécifique à Gentoo, qui est spécifié par un -r#, où # est un entier, par exemple paquet-4.5.3-r3. Ce numéro de révision est indépendant de la version de l'archive source, et est utilisé pour informer les utilisateurs qu'une nouvelle révision ou amélioration de la part de Gentoo est disponible pour un certain paquet.

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. Les sorties initiales n'ont en général pas de numéro de révision, par exemple paquet-4.5.3 et sont considérés par Portage comme ayant un numéro de révision de 0. Cela signifie que le décompte se fait comme suit : 1.0 (version initiale), 1.0-r1, 1.0-r2, etc. 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.

Les variables

La première partie de tous les fichiers ebuild est constituée d'un certain nombre de variables. Elles sont placées dans trois catégories qui sont :

• READ : les variables que vous pouvez utiliser mais qui ne sont jamais déclarées ;
• MUST : les variables que vous devez toujours déclarer ;
• OPT : les variables que vous pouvez déclarer.

Les fonctions

Il existe un certain nombre de fonctions que vous pouvez définir dans vos fichiers ebuilds, qui contrôlent la construction et le processus d'installation de votre paquet.

Les fonctions d'aide

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

Fonctions d'aide proposées par eutils.eclass

Vous pouvez utiliser les fonctions d'aide suivantes, qui sont 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 d'aide proposées par flag-o-matic.eclass

Vous pouvez utiliser les fonctions d'aide suivantes, qui sont 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.

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 crochets 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 la correcte indentation, et des configurations concernant le type de fichier des ebuild et eclass existe. 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.

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 ajouter les lignes suivantes à la fin de votre fichier .emacsrc (pour GNU Emacs) ou init.el (pour XEmacs) pour vous assurer d'utiliser une configuration correcte lors de l'édition de tout ce qui est lité à Gentoo :

(defun ebuild-mode ()
  (shell-script-mode)
  (sh-set-shell "bash")
  (make-local-variable 'tab-width)
  (setq tab-width 4))
(setq auto-mode-alist (cons '("\\.ebuild$" . ebuild-mode) auto-mode-alist))
(setq auto-mode-alist (cons '("\\.eclass$" . ebuild-mode) auto-mode-alist))

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

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 comme option de compilation (optionnel) GNOME 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 conséquent 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 que pour certains paquets, en éditant le fichier /etc/portage/package.use.

Dans vos propres ebuilds, vous pouvez vérifier si un paramètre USE est présent ou non en utilisant la commande use <variable>. La commande use affiche <variable> si celle-ci est présente dans les USE de l'utilisateur. Vous pouvez l'utiliser 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 boucle conditionnelle 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 petit point important sur comment utiliser 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 se débarrasser de ce problème :

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 quels 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 ce que l'on a dans les paramètres USE. En plus, vous obtenez un code propre et facile à lire :).

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

Les standards de couche 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.

Normalement, si le paquet utilise autoconf et automake, les destinations par défaut de l'installation du paquet sont en général 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 de fenêtre 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 évitent 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.

Il existe des scripts permettant à 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 dir/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.

Il existe des scripts que vous pouvez utiliser dans vos fichiers ebuilds pour réaliser des taches communes.

Si vous voulez un aperçu, jetez un oeil aux scripts en eux-même dans /usr/lib/portage/bin.

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 dûes à la compilation et celles dûes 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.

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 à son lancement.

DEPEND="virtual/glibc
        sys-libs/zlib"
RDEPEND="virtual/glibc"

Cela indique à Portage de construire foo-x.y.z, les paquets virtual/glibc (plus de précisions sur les virtuals seront données plus tard) et sys-libs/zlib étant nécessaires à la construction. Il ne précise pas la version de glibc ou zlib 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 en général pas. En revanche pour des bibliothèques centrales comme glibc, qui fait tout pour avoir des binaires toujours compatibles ça 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 plus récente révision 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.

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

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.

Afin de pouvoir tester vos ebuilds et de les laisser à la connaissance de Portage, 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.

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