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 peut être trouvé 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 dit 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 un ebuild pour ce que vous voulez faire, mais qui n'a 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 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 inutile et d'espace disque 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 les développeurs de conflits de manière correcte.

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

Re-vérifiez votre ebuild et vérifiez qu'il est bon 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 lancer un repoman full pour vous assurer que vous n'avez rien oublié.

• Toujours lancer repoman scan avant de soumettre son travail.
• Lancez 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 ne 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 nous, 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 différenciable les uns des autres, 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 ce qui se fait en général, c'est plus commode.

Les scripts d'ebuild sont la base de l'intégralité du système de Portage. Ils contiennent toutes les informations nécessaires pour télécharger, désarchiver, compiler et installer un ensemble de sources, ainsi que les informations nécessaires pour réaliser n'importe quelle tache de pre/post installation/suppression ou de configuration. Si la majeure 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, c'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 pour ebuild, et il a la capacité d'installer automatiquement les dépendances si elles sont nécessaires, 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'erreur précieux, car il vous permettra d'isoler les problèmes d'un ebuild par parties spécifiques dans l'ebuild.

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 ('-'), soulignement ('_'), 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 ou 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 _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élioratons 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évirion incrémenté 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'outliez jamais de laisser une mention de vos modifications dans le 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ète 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 variablesque 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 différentes 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 pour que vous puissiez utiliser ces fonctions.

Helper Functions provided by flag-o-matic.eclass

You can use the following helper functions that are provided by the "flag-o-matic" eclass in your ebuilds. You must make sure that inherit flag-o-matic is present for these functions to work. You should never modify any compiler settings directly, instead please use flag-o-matic to perform any actions such as filtering flags that cause trouble.

Since ebuild files are really just shell scripts, you should use your editor's shell-script mode for editing them. You should use proper indentation, using only tab characters -- no spaces. Make sure you set up your editor to put tab stops at 4 spaces. Always make sure you use braces around your environment variables; e.g. ${P} instead of just $P.

Long lines are wrapped with ' \', thus:

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

For further details, refer to skel.ebuild (usually residing in /usr/portage).

If you use Vim for ebuild/eclass editing, the default Gentoo vimrc file, /etc/vim/vimrc, already ensures that correct indentation and filetype settings are used for ebuild and eclass files. For better results, including special syntax highlighting for ebuild keywords, emerge app-vim/gentoo-syntax.

On non-Gentoo systems, you can obtain similar results by using the following lines in your vimrc, or better yet by installing the gentoo-syntax scripts.

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

If you're using Emacs, you can put the following snippet at the bottom of .emacsrc file (for GNU Emacs) or init.el (for XEmacs) to make sure your using the correct settings when editing anything Gentoo-related.

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

If you're using nano, then you're in luck! Just edit /etc/nanorc and uncomment the section referring to ebuild's.

The purpose of USE variables is to allow you to configure Portage to globally and automatically enable or disable certain optional build-time features. Here's an example. Let's say you're a GNOME fan, and you'd like any ebuild that has the option of compiling-in optional GNOME support to do so. In this case, you'd add gnome to the USE variable in /etc/make.conf, and then Portage will automatically add optional GNOME functionality to packages if it is available. Likewise, if you don't want optional GNOME features to be added to your ebuilds if they are available, simply edit /etc/make.conf and make sure that gnome is not set in the USE variable. Gentoo Linux has an almost overwhelming number of USE options, allowing you to have your system configured exactly the way you want it.

In your own ebuilds, you can check whether a USE variable is set by using the use <variable> command. The use command prints out <variable> if it is present in the user's USE. You would normally use this command as follows:

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

USE variables can also be used to set dependencies. For example, you may only want to require a package if a certain USE variable is set. This is done by using the syntax flag? ( mycat/mypackage ) in the DEPEND variable for your ebuild. In this example, mycat/mypackage will only be required if flag is present in USE. It is also possible to specify what dependency should be used if some USE flag is set, and what dependency to use if it is not set: flag? ( mycat/mypackage) and !flag? ( othercat/otherpackage ). In this case, if flag is not set, othercat/otherpackage is used instead of mycat/mypackage. Make sure that your ebuilds use this syntax and not Bash IFS. Bash conditionals interfere with Portage's dependency caching, and the use of them will break your ebuild.

Here's an important tip about how to use USE. Most of the time, a package will have a ./configure script used to perform configuration steps. Generally, if your ebuild uses ./configure, any optional build-time functionality will be enabled or disabled by passing the appropriate arguments to the ./configure command. Here's the best way to handle this:

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!"
}

This approach has a very nice result. We don't have to worry about what the default setting is for mysql or X (enable/disabled), we explicitly tell econf what we want it to do based upon the USE variable. Not to mention it's quite clean in terms of readability :).

To view a continuously updated table of USE variables, please go here.

The file system layout standards used in Gentoo Linux closely follow the FHS, short for File system Hierarchy Standard. A simplified description of the standard is given here; for a complete specification go to http://www.pathname.com/fhs/.

Usually, if the package uses autoconf and automake, the default installation destinations are mostly correct, with a few exceptions:

• If you're installing a program into /bin, /sbin, /usr/bin, or /usr/sbin, then the program's corresponding man page should be installed into the /usr/share/man tree. This can often be accomplished by specifying a ./configure --mandir=/usr/share/man in the ebuild.
• GNU info files should always be installed to /usr/share/info, even if the info files are about X11, GNOME or KDE-specific programs or tools. Make a note: /usr/share/info is the only official location for GNU info files. Since many ./configure scripts default to installing GNU info files in /usr/info, it's often necessary to call ./configure with the --infodir=/usr/share/info argument.
• Documentation files are installed in /usr/share/doc, into a subdirectory reflecting the name, version, and revision of the particular program. This applies to all programs: GNOME, KDE, X11 and console alike. However, some programs may install additional documentation and support files into a /usr/share hierarchy for their own purposes.
• X11-specific programs and libraries should always be installed into /usr, not directly into /usr/X11R6. We reserve the /usr/X11R6 hierarchy for the X Window System, Version 11 Release 6 itself. This is perhaps a more to-the-letter interpretation of the FHS than some other distributions have made.
• GNOME and KDE programs, similarly, should always be installed into /usr.

In general, you should have ebuilds install their files into the /usr tree. Some programs can be compiled and linked with or without GNOME, KDE, and X11 libraries, which can cause confusion. Our solution is to install everything into /usr which avoids ambiguity and needless complexity for ebuild authors. The location in which to install a program's files should not depend on the presence or absence of specific USE variables. Therefore, the ebuilds in the portage tree almost always install into the /usr hierarchy exclusively.

These are scripts used by the system-administrator to install and remove packages, and maintain the package database.

ebuild is the main engine of the Portage system; it performs all major tasks such as unpacking, compiling, installing, merging, and unmerging packages. It is called using the command: ebuild path/to/package.ebuild command. The commands available are:

emerge recursively merges a package and all of its dependencies into your file system. This command has many options, try emerge --help for a list of them.

env-update updates the configuration files (including, but not limited to /etc/ld.so.conf and /etc/profile.env) to include changes made by installed packages.

These are scripts you can use in your ebuild files to perform common tasks.

For you down and dirty people, look at the scripts themselves in /usr/lib/portage/bin.

Portage is more than just a convenience script that gives you a unified way to build any one project (program, library) from source. It will also fetch and install any necessary dependencies if you take care to specify these in your ebuild.

In the official ebuilds, all dependencies have already been specified, so when you issue emerge net-www/mozilla/mozilla-1.0, Portage will insure that all libraries necessary for Mozilla to build and run are properly installed before Mozilla itself is built.

Portage even distinguishes between build-time dependencies and run-time dependencies. (Caveat: Currently, Portage installs all build-time and run-time dependencies and leaves it at that. At a later stage, it will be possible to trim your installation so that only the run-time dependencies are left installed).

The DEPEND variable inside your foo-x.y.z.ebuild tells Portage about which packages are needed to build foo. The RDEPEND variable specifies which packages are needed for foo to run.

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

This tells Portage that to build foo-x.y.z, the packages virtual/glibc (more on virtuals in a bit) and sys-libs/zlib are needed. It does not say anything about which version of glibc or zlib that are needed, which means "anything goes".

The "anything goes" is of course a bit scary, and will not work in the general case. But for central libraries like glibc, which strives very hard to be 100% binary compatible all the time, it actually works. For other libraries, we can of course specify version dependencies.

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

>= and = do what you would expect; sys-apps/bar version 1.2 or newer is okay (this means that sys-apps/bar-2.0 is okay), while sys-apps/baz version 1.0 is the only version that is accepted. For more information on the version schema of packages, see the section above on Naming ebuild Files.

Other methods of specifying version dependencies are as follows:

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

~sys-apps/qux-1.0 will select the newest portage revision of qux-1.0.

=sys-apps/foo-1.2* will select the newest member of the 1.2 series, but will ignore 1.3 and later/earlier series. That is, foo-1.2.3 and foo-1.2.0 are both valid, while foo-1.3.3, foo-1.3.0, and foo-1.1.0 are not.

!sys-libs/gdbm will prevent this package from being emerged while gdbm is already emerged.

Whenever you update a (or write a new) ebuild, you must also update its (or create a new) ChangeLog. The skel.ChangeLog contains a sample ChangeLog that you can use as a basis.

The purpose of the ChangeLog is to document what is being done, why it is being done, and by whom. This allows both developers and users to trace the changes made in an easy way.

The ChangeLog is primarily targeted at users, so be sure to keep your writing short, to the point, and avoid getting verbose about the internal technical details.

In order to be able to test your ebuilds and let Portage know about them, you must place those in a known directory. Portage will use the PORTDIR_OVERLAY variable which you can define in /etc/make.conf. You should set this variable to your directory (e.g. /usr/local/portage).

In that directory, you must use the same structure (and categories) as in /usr/portage.

Using this PORTDIR_OVERLAY, your ebuilds remain on your system, even after an emerge sync, and they are still known to Portage.

We have a few useful tools to help you with writing and maintaining your ebuilds.