3.10 Scripts ebuild¶

• 3.10 Scripts ebuild
• Introduction
• Nommer les fichiers ebuild
• Le contenu d'un fichier ebuild
• Entêtes
• Variables
• Fonctions
• Fonctions utilitaires
• Fonctions utilitaires proposées par eutils.eclass
• Fonctions utilitaires proposées par flag-o-matic.eclass
• Fonctions d'assistance fournies par toolchain-funs.eclass
• Règles à utiliser pour écrire un fichier ebuild
• Les paramètres USE

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

Note : Les crochets ({}) délimitent des champs optionnels et n'apparaissent pas dans le nom final pour le paquet. # représente un entier positif différent de zéro.

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.

Important : Si vous pensez utiliser une lettre à la fin de la version du paquet, n'oubliez pas que ce caractère ne doit pas être utilisé pour signifier le statut alpha ou beta d'un paquet, dans la mesure ou les alpha et beta sont des pré-sorties et les révisions ultérieures sont des nouvelles versions. C'est une distinction importante, car Portage utilise le numéro de version des ebuilds pour déterminer si il est plus récent ou plus vieux que les autres paquets d'une même catégorie et d'un même nom. C'est très important d'avoir des noms de version représentant fidèlement la version du paquet, afin que Portage puisse vérifier correctement les dépendances entre les paquets.

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 :

Suffixe	Sens
_alpha	Sortie de type alpha
_beta	Sortie de type beta
_pre	Pré-sortie
_rc	Candidat à la sortie
(none)	Sortie officielle
_p	Niveau de correctif (normalement suivi d'un entier)

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

Entêtes¶

Quand vous soumettez vos ebuilds, les entê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: $

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.

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.

Fonction	Objectif
pkg_setup	Utilisez cette fonction pour effectuer n'importe quel type de tâche qui soit un pré-requis à la construction. Cela inclut la vérification de l'existence d'un fichier de configuration par exemple.
pkg_nofetch	Informe l'utilisateur des actions manuelles nécessaires si pour une raison ou pour une autre (comme par exemple des conditions liées à la licence) les sources ne seraient pas récupérables automatiquement par Portage lors du processus normal d'installation. Utilisez-le en conjonction avec RESTRICT="fetch". Vous pouvez uniquement afficher des messages avec cette fonction, jamais d'appel à la fonction die.
src_unpack	Utilisez cette fonction pour désarchiver les sources et les correctifs, et pour lancer des programmes auxiliaires, comme par exemple autotools. Par défaut, cette fonction désarchive les paquets listés dans A. Le répertoire de travail initial est définit par WORKDIR.
src_compile	Utilisez cette fonction pour configurer et construire le paquet. Le répertoire initial de travail est S.
src_install	Utilisez cette fonction pour installer le paquet dans une image dans D. Si le paquet utilise automake, vous pouvez simplement effectuer un emake DESTDIR=${D} install. Assurez-vous que votre paquet installe tous ses fichiers en utilisant D comme racine ! Le répertoire initial de travail est S.
src_test	Cette fonction n'est exécutée que si vous avez initialisé la variable FEATURES="test" et si RESTRICT="test" n'est pas mis. La fonction par défaut exécutera une fonction de test disponible dans n'importe quel fichier Makefiles dans le répertoire ${C} en lançant au choix make test ou make check, selon la fonction disponible. Ce comportement par défaut peut être remplacé par une fonction de test faite sur mesure.
pkg_preinst	Les commandes dans cette fonction sont lancées juste avant la fusion de l'image du paquet dans le système de fichiers.
pkg_postinst	Les commandes dans cette fonction sont lancées juste après la fusion de votre image de paquet dans le système de fichiers.
pkg_prerm	Les commandes dans cette fonction sont lancées juste avant la suppression d'un paquet du système de fichiers.
pkg_postrm	Les commandes dans cette fonction sont lancées juste après la suppression d'un paquet du système de fichiers.
pkg_config	Vous utiliserez cette fonction pour mettre en œuvre une configuration initiale d'un paquet après qu'il ait été installé. Toutes les chemins des répertoires dans cette fonction doivent être préfixés de ROOT qui indique le répertoire racine (il se peut que ce ne soit pas /.) Cette fonction est uniquement exécutée si l'utilisateur lance : emerge --config =${PF}.

Fonctions utilitaires¶

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

Fonction	Objectif
use	Vérifier si une ou plusieurs variables USE sont sélectionnées. Pour les variables sélectionnées, la fonction renverra « vrai ». Dans tous les cas, rien ne sera affiché sur la sortie standard. Pour une sortie plus verbeuse, utilisez usev qui affichera les options USE qui ont été sélectionnées.
has_version	Retourne 1 si le système a la version requise d'un certain paquet. Utilisez-le ainsi : has_version >=sys-libs/glibc-2.3.0.
best_version	Retourne le couple categorie/paquet-version d'un couple categorie/paquet demandé. Utilisez-le ainsi : best_version x11-libs/gtk+extra.
use_with	Cette fonction vérifie si un paramètre USE a été défini et retourne --with-foobar ou --without-foobar selon le cas. Si vous ne donnez qu'un seul argument, cet argument sera à la fois paramètre USE et with(out)-string. Sinon le premier argument sera le paramètre USE, et le second sera le with(out)-string. Par exemple, use_with truetype freetype retournera --with-freetype si truetype est dans les paramètres USE.
use_enable	Même fonction que use_with, mais retourne --enable-foobar ou --disable-foobar selon le cas.
check_KV	Vérifie si Portage connaît la version du noyau. Si non, cette fonction retourne une erreur et se termine immédiatement. Si vous avez besoin d'une version de noyau dans votre script, utilisez la variable KV qui est automatiquement définie par Portage. Sur un système utilisant gentoo-sources-2.4.20-r6, KV devra avoir la valeur 2.4.20.
keepdir	Crée (si besoin) un fichier .keep dans un répertoire donné afin qu'il ne soit pas supprimé automatiquement. Ne jamais créer de fichier .keep soi-même. Si Portage change le fonctionnement de keepdir, créer un tel fichier soi-même pourrait casser le paquet.
econf	Exécute ./configure avec les changements de répertoires nécessaires (prefix, host, mandir, infodir, datadir, sysconfdir, localstatedir). Vous pouvez éventuellement lui passer des arguments supplémentaires pour ./configure en les donnant lors de l'appel d'econf et les utilisateurs peuvent également utiliser la variable EXTRA_ECONF s'ils en ont besoin. Les options passées à configure sont passées dans l'ordre inverse à celui dans lequel elles ont été données à econf. En d'autres termes, le premier argument passé sera toujours remplacé par le dernier.
einstall	Exécute make install avec les bons changements de répertoires (prefix, host, mandir, infodir, datadir, sysconfdir, localstatedir). Encore une fois, vous pouvez donner des arguments supplémentaires à la commande make en les donnant directement comme paramètres à einstall. Notez que la méthode utilisée de manière préférentielle pour installer un paquet est d'utiliser la commande emake install DESTDIR="${D}" et non einstall. Cette commande n'est en fait qu'une alternative aux fichiers make défectueux.
die	Avorte le processus en cours. Il indiquera à l'utilisateur les données passées en argument. Ne pas négliger l'utilisation de message passés en arguments à die si vous faites plusieurs appels à die dans une même fonction par exemple. Si vous n'en utilisez pas, il sera plus dur de rechercher une erreur, car vous ne pourrez pas être sûr de savoir où le paquet a échoué.
elog
einfo	Affiche des informations moins importantes qui ne seront pas sauvegardés dans un log.

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.

Fonction	Objectif
epatch	Cette fonction ressemble un peu à la commande patch mais a l'avantage de fonctionner avec des correctifs aux formats .bz2, .gz, .zip et fichiers texte. Vous n'avez pas besoin de lui spécifier une option -p, toutes les options qui ont besoin d'être passées de manière explicite à la fonction doivent être mises dans EPATCH_OPTS.La fonction prend pour argument soit un fichier, soit un répertoire. Si vous lui donnez un répertoire, tous les correctifs de la forme « ??_${ARCH}_... » seront appliqués. Pour qu'un correctif soit appliqué, il doit correspondre à l'architecture spécifiée ou avoir « _all_ » dans son nom (pour toutes les supporter) ou initialiser EPATCH_FORCE à « yes ».
gen_usr_ldscript	Cette fonction génère des scripts de liens dans /usr/lib pour les bibliothèques dynamiques dans /lib. Cela résoud les problèmes de liens lorsqu'un .so est dans /lib alors qu'un .a est dans /usr/lib.
edos2unix	Cette fonction effectue la même tâche que le binaire dos2unix.
egetent	egetent est une abstraction de getent sous Linux ou nidump sous Mac OS X.
enewuser	Crée un nouvel utilisateur. Cette fonction prend pour argument obligatoire le nom d'utilisateur et un certain nombre d'arguments optionnels peuvent lui être spécifiés : $2 contient un UID. Mettre -1 pour que l'UID prenne le prochain ID disponible. $3 contient un shell. Mettre -1 pour que prendre le shell par défaut. $4 contient le répertoire utilisateur avec /dev/null comme répertoire par défaut. $5 contient tous les groupes auquel l'utilisateur doit être ajouté, vide par défaut et $6 contient les éventuels paramètres à passer à la commande useradd lors de la création de l'utilisateur.
enewgroup	Ajoute un nouveau groupe. Cette fonction prend pour paramètre obligatoire le nom du groupe et comme paramètre optionnel le GID souhaité pour ce groupe.
make_desktop_entry	Crée une entrée de bureau : le premier argument contient le répertoire qui mène au binaire. De manière optionnelle, le second argument contient le nom pour l'icône, par défaut ${PN} ; le troisième argument peut contenir le chemin vers une icône relatif à /usr/share/pixmaps ou en donnant le chemin complet à partir de la racine, par défaut, ${PN}.png ; le quatrième peut contenir une catégorie d'application et enfin le cinquième argument (optionnel) contient le chemin de lancement de l'application.
check_license	Affiche une licence que l'utilisateur devra accepter. Si aucun argument n'est donné à la fonction, la licence spécifiée sera celle donnée par ${LICENSE}.
unpack_pdv	Désarchive une archive générée avec pdv. Le premier argument doit contenir le fichier à désarchiver et le second devrait contenir « off_t » qui doit être généré manuellement : strace -elseek${file} et pour obtenir quelque chose du genre « lseek(3, -4, SEEK_END) » vous devriez lui passer comme valeur « 4 ».
unpack_makeself	Désarchive une archive créée avec makeself. L'argument nécessaire sera le nom du fichier à désarchiver.
cdrom_get_cds	Essaie d'obtenir un CD qui possède les fichiers spécifiés en argument et qui est monté sur ${CDROM_ROOT}.
cdrom_load_next_cd	Charge le CD suivant une fois que vous en avez fini avec le premier CD. Si la fonction est lancée, ${CDROM_ROOT} devra pointer vers le CD suivant.
strip-linguas	Cette fonction s'assure que LINGUAS contient uniquement les langues que le paquet peut supporter spécifées en arguments à la fonction. Si le premier argument est -i, alors la liste des fichiers .po dans les répertoires spécifiés est construite et la conjonction des deux listes présentes est utilisée. Si -u est passé en premier argument, alors la liste des fichiers .po des répertoires spécifiés est construite et l'union des listes est utilisée.

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.

Fonction	Objectif
filter-flags	Cette fonction supprime un paramètre particulier de C[XX]FLAGS. Seuls les paramètres complets sont vérifiés.
append-flags	Cette fonction ajoute un paramètre supplémentaire à ceux définis dans les variables C[XX]FLAGS.
replace-flags	Cette fonction remplace un paramètre spécifié en premier argument par un autre donné en second argument, dans les variables actuelles de C[XX]FLAGS.
replace-cpu-flags	Cette fonction nécessite deux arguments. Il remplace une valeur de type mtune/march/mcpu par une autre (Par exemple, « replace-cpu-flags 'i686' 'i586' » remplacera -mtune/-march/-mcpu=i686 par -mtune/-march/-mcpu=i586).
strip-flags	Enlève tous les paramètres sauf ceux spécifiés dans ALLOWED_FLAGS.
strip-unsupported-flags	Enlève de C[XX]FLAGS tous les paramètres non supportés par la version utilisée de GCC.
get-flag	Trouve un paramètre et retourne sa valeur.
is-flag	Retourne « vrai » si le paramètre est déclaré dans les variables actuelles C[XX]FLAGS. Cette fonction ne fait que des vérifications de paramètres complets.
append-ldflags	Cette fonction ajoute des paramètres supplémentaires à la variable LDFLAGS.
filter-ldflags	Enlève les paramètres spécifiés de LDFLAGS et ne vérifie que les paramètres complets.
fstack-flags	Utilise -fno-stack-protector, ce qui supprime -fstack-protector et -fstack-protector-all.

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.

Fonction	Objectif
tc-getAR	Retourne le nom du programme archiveur.
tc-getAS	Retourne le nom de l'assembleur.
tc-getCC	Retourne le nom du compilateur C.
tc-getCXX	Retourne le nom du compilateur C++.
tc-getLD	Retourne le nom de l'éditeur de liens.
tc-getNM	Retourne le nom de l'inspecteur de symboles.
tc-getRANLIB	Retourne le nom de l'indexeur d'archive.
tc-getF77	Retourne le nom du compilateur Fortran.
tc-getGCJ	Retourne le nom du compilateur Java.
tc-getBUILD_CC	Retourne le nom du compilateur C pour la compilation.
tc-is-cross-compiler	Indique si on fait une compilation croisée.
gcc-fullversion	Retourne la version telle que reçue par la commande $($CC -dumpversion).
gcc-version	Retourne la version, uniquement <major>.<minor>
gcc-major-version	Retourne le numéro de version majeur.
gcc-minor-version	Retourne le numéro de version mineur.
gcc-micro-version	Retourne le numéro de version micro.

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

Les paramètres USE¶

Dans vos propres ebuilds, vous pouvez vérifier si une variable USE est présente 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!" 
}