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 (quelque soit la version) partagent le
même répertoire ma_categorie/mon_paquet dans
/usr/portage.
Récupérer une version de l'arbre de Portage avec CVS
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.
Ce qu'on (ne) peut (pas) mettre dans l'arbre de Portage
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é.
Politique de soumission au CVS
- 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...
Le répertoire 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 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.
Scripts ebuild
Introduction
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.
Nommer les fichiers 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.
Si vous pensez utiliser une lettre en queue 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
alphas et betas 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 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.
Un paquet _rc est plus vieux qu'un paquet sans suffixe avec
soulignement (par exemple linux-2.4.0), et linux-2.4.0
est plus vieux qu'un paquet avec un suffixe à une seule lettre, par
exemple linux-2.4.0b. Comme vous vous y attendez, le paquet
linux-2.4.0b est considéré comme plus vieux que linux-2.4.0c
. Encore une fois, les informations sur la version sont importantes,
car Portage les utilise de manière interne pour déterminer si un paquet
ou un ebuild est plus récent qu'un autre, pour une catégorie et un nom
donnés.
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.
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.
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.
Variable |
Utilisation |
Description |
P
READ
Le nom et la version du paquet.
PN
READ
Le nom du paquet.
PV
READ
La version du paquet.
PR
READ
Contient le numéro de révision ou r0 si aucun numéro de
révision n'existe.
PVR
READ
Contient le numéro de version avec la révision.
PF
READ
Contient le nom complet du paquet ${PN}-${PVR}.
A
READ
Liste séparée par des espaces, des fichiers dans SRC_URI.
Elle ne contient pas les directions URL, juste le nom de fichier.
DISTDIR
READ
Contient la direction du répertoire distfiles où tous
les fichiers récupérés pour un paquet sont mis. C'est en général
/usr/portage/distfiles.
FILESDIR
READ
Contient la direction vers le sous-répertoire files/
dans l'emplacement spécifique du paquet dans l'arbre de Portage.
Ne modifiez pas cette variable.
WORKDIR
READ
Base de la racine de travail pour un ebuild. Rien ne doit être
construit hors de ce répertoire.
S
OPT
Le répertoire source pour votre paquet : en général,
${WORKDIR}/${P}. Portage va prendre cette valeur par défaut
donc vous n'avez probablement pas besoin de l'initialiser.
T
READ
Le répertoire temporaire pour votre paquet. Il est utilisé comme
un répertoire /tmp virtuel lors de l'exécution de
l'ebuild.
D
READ
Le répertoire racine où le paquet devra être installé.
Considérez-le comme un / virtuel.
SLOT
MUST
Portage manipule souvent plusieurs versions d'un même programme
installé. Par exemple vous pouvez avoie GCC 2.95 et GCC 3.2
installés en même temps sur votre machine. Vous devez alors
spécifier le SLOT dans chaque ebuild. Ici nous prendrions
pour le SLOT de GCC 2.95 un 2 alors que nous aurions
un 3 pour le SLOT de GCC 3.2.
Note : utiliser 0 comme valeur du SLOT
signifie que le paquet n'a qu'un seul SLOT possible (en
d'autres termes, ce paquet n'est pas "SLOTable").
LICENSE
MUST
Cette variable spécifie sous quelle licence est le programme,
c'est à dire GPL-2, BSD, etc. Ce champ doit être initialisé à une
valeur de licence valide (qui peut être n'importe quelle licence
dans le répertoire /usr/portage/license/). Si la
licence n'y est pas encore répertoriée, elle doit être ajoutée
avant que l'ebuild ne soit ajoutée à l'arbre de Portage.
KEYWORDS
MUST
Cette variable remplie désormais un certain nombre de fonctions.
Tout d'abord, elle spécifie la cibles de l'ebuild en matière
d'architecture. Les mots-clefs incluent : x86, ppc, sparc,
mips, alpha, arm, hppa, amd64, ia64 (NdT : cette liste
n'est plus complète actuellement, de nouveaux mots-clefs ont été
ajoutés récemment). Évidemment, vous utiliserez ceci pour indiquer
l'architecture de la machine cible. Portage n'autorisera pas une
machine x86 à construire autre chose que des ebuilds dont le
mot-clef x86 est spécifié dans la variable KEYWORDS. Les
paquets qui ne supportent pas une architecture nativement, sont
automatiquement masqués par Portage. Si le paramètre
KEYWORDS est précédé d'un ~, alors cela indique que
l'ebuild fonctionne, mais nécessite encore plusieurs tests dans
différents environnements avant d'être placé dans un profile
stable avec le mot-clef associé. Si rien ne précède le
KEYWORDS alors le paquet est considéré comme stable.
Vous pouvez autoriser l'installation de ces différents types
de paquets à travers l'utilisation de la variable
ACCEPT_KEYWORDS dans make.conf, ou dans le
fichier /etc/portage/package.keywords.
DESCRIPTION
MUST
Une courte et unique ligne de description de votre paquet.
SRC_URI
MUST
Les URLs pour chaque fichier source de votre paquet, en les
séparant d'un espace. Normalement, le premier devrait ressembler à
"ftp://ftp.compagnie.com/pub/unpaquet/${P}.tar.bz2"
HOMEPAGE
MUST
La page Internet dédiée au paquet. Si vous n'arrivez pas à trouver
la page officielle, essayez de trouver un lien depuis le site freshmeat.net ou un site de
traçage de paquet similaire.
IUSE
MUST
Cette variable contient les paramètres USE que votre paquet
utilise. Souvenez-vous que KEYWORDS ne doit pas y être
listé !
DEPEND
OPT
Les dépendances de construction du paquet sont listées ici. Lire
la section sur les dépendances de paquets
pour plus de détails sur la syntaxe.
RDEPEND
OPT
Les dépendances d'exécution du paquet sont listées ici. Encore une
fois lire la section sur les dépendances de
paquets pour plus de détails sur la syntaxe.
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.
Fonction |
Objectif |
pkg_setup
Utilisez cette fonction pour effectuer n'importe quel type de
tache qui sont des prérequis à la construction. Cela inclue la
vérification de l'existence d'un fichier de configuration par
exemple. S'il est nécessaire de créer des utilisateurs ici, vous
devez également faire une vérification dans la fonction
pkg_preinst() avant que le paquet ne s'installe.
pkg_nofetch
Informe l'utilisateur des actions requises si pour une raison ou
pour une autre (comme par exemple des conditions liées à la
licence) les sources ne serait pas téléchargeable automatiquement
par Portage lors du processus normal d'installation. Utilisez-le
en conjonction avec RESTRICT="fetch". Vous ne
devez que faire un affichage de messages avec cette fonction,
jamais d'appel à la fonction die.
src_unpack
Utilisez cette fonction pour désarchiver les sources, 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éfini 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 make DESTDIR=${D} install.
Assurez-vous que votre paquet installe tous ses fichiers en
utilisans D comme racine ! Le répertoire initial
de travail est S.
src_test
Exécuté uniquement quand vous avez fait un FEATURES="maketest"
et que RESTRICT="maketest" n'est pas mis, la fonction
par défaut exécutera une fonction de test disponible dans
n'importe quel 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 fichier.
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 fichier.
pkg_prerm
Les commandes dans cette fonction sont lancées juste avant la
suppression d'un paquet du système de fichier.
pkg_postrm
Les commandes dans cette fonction sont lancées juste après la
suppression d'un paquet du système de fichier.
pkg_config
Vous utiliserez cette fonction pour mettre en oeuvre une
configuration initiale d'un paquet après qu'il ait été installé.
Toutes les directions de répertoire dans cette fonction doivent
être préfixées de ROOT. Cette fonction n'est uniquement
exécutée que si l'utilisateur lance : ebuild
/var/db/pkg/${CATEGORY}/${PF}/${PF}.ebuild config.
Les fonctions d'aide
Vous pouvez également utiliser les fonctions d'aide suivantes dans vos
ebuilds.
Fonction |
Objectif |
use
Vérifier si un ou plus des paramètres USE sont définis. Si c'est
le cas, la fonction retournera les paramètres qui existent dans
USE. Cette possibilité va bientôt être modifiée, et
use ne retournera rien, mais usev continuera à
retourner les paramètres. Pour vérifier l'existence d'un paramètre
USE, vous pouvez utiliser use foorbar.
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
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 USE.
use_enable
La même chose que use_with, mais retourne
"--enable-foobar" ou "--disable-foobar" selon
le cas.
check_KV
Vérifie si Portage connait la version du noyau. Si non, cette
fonction retourne une erreur et meurt. Si vous avez besoin d'une
version de noyau dans votre script, utilisez la variableKV
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 le 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, alors créer un
tel fichier vous-même pourrait casser le paquet.
econf
Effectue ./configure avec les changements de répertoires
nécessaires (prefix, host, mandir, infodir, datadir, sysconfdir,
localstatedir). Vous pouvez optionnellement lui passer des
arguments supplémentaires pour ./configure en les donnant
lors de l'appel d'econf, et les utilisateurs peuvent
utiliser également la variable EXTRA_ECONF si ils en ont
besoin. Les options passées à configure sont passées dans l'ordre
inverse à celui dans lequel elles ont été données. En d'autres
termes, le premier argument passé sera toujours remplacé par le
dernier.
einstall
Effectue un 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 manière utilisée
de manière préférentielle pour installer un paquet est d'utiliser
la commande make install DESTDIR=${D} et non einstall
. Cette commande n'est qu'un moyen pour écrire par dessus un
fichier make cassé.
die
Avorte le processus en cours. Il indiquera à l'utilisateur
les données passées en argument, comme une raison d'avortement.
Ne pas négliger l'utilisation de message à die si vous
faites plusieurs appels à die dans une même fonction.
Il sera plus dur de rechercher une erreur si vous n'êtes pas sûr
de savoir où le paquet a échoué.
einfo
Informe l'utilisateur d'un événement important. L'argument passé à
einfo est le message qui sera passé à l'utilisateur.
N'utilisez pas einfo pour afficher des bannières comme
"*************************************". Le fait même
d'utiliser einfo est suffisant pour attirer l'attention de
l'utilisateur.
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.
Fonction |
Objectif |
draw_line
Cette fonction affiche une liste de '=' ayant la longueur de
l'entrée de la fonction.
epatch
Cette fonction ressemble un peu à la commande patchmais a
l'avantage de fonctionner avec des correctifs aux formats .bz2,
.gz, .zip et fichier 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.
have_NPTL
Retourne 0 si le système utilise l'implémentation des pthreads
NPTL.
get_number_of_jobs
Cette fonction vérifie le nombre de CPUs présents et ajoute dans
MAKEOPTS l'option correcte -jX correspondante.
mymktemp
Cette fonction agit comme un "wrapper" à mktemp quand il existe,
ou agit comme un remplacement à cette fonction quand elle n'existe
pas.
edos2unix
Cette fonction effectue le même travail que le binaire
dos2unix.
egetent
egetent agit comme un wrapper pour getent pour Linux, ou
nidump pour Mac OS X (R).
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 qu'il prenne la prochaine ID disponible.
$3 contient un shell, avec /bin/false comme
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 un commentaire. Par défaut,
le commentaire sera "added by portage for ${PN}".
enewgroup
Ajoute un nouveau groupe. Cette fonction prend pour paramètre
obligatoirement le nom du groupe, et comme paramètre optionnel, on
peut lui indiquer 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 la direction d'une
icône à partir de /usr/share/pixmaps ou en donnant la
direction complète à 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 contient la
direction (optionnel) 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
Essaye 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 contienne 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 en premier
argument est donné -u, alors la liste des fichiers .po des
répertoires spécifiés est construite et l'union des listes est
utilisée.
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ème.
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
Celle-ci 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
Remplace tous les paramètres -march=... ou -mcpu=... qui
contiennent le second argument, par le premier.
replace-sparc64-flags
Cette fonction établi le paramètre -mcpu=... pour les SPARC v8 et
utilise la valeur d'origine pour -mtune, si aucune valeur n'est
encore spécifiée ici.
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 ; ne fait que des
vérifications de paramètres complètes.
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
les paramètres complets.
fstack-flags
Utilise -fno-stack-protector, ce qui supprime -fstack-protector et
-fstack-protector-all.
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 éditer. 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/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, on
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
siminaires 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.
Les variables 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 que 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 alors
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 d'options USE, vous permettant
d'obtenir un système configuré exactement comme vous le souhaiteriez.
De plus vous pouvez désormais n'utiliser un paramètre USE que
pour certains paquets, en éditant le fichier
/etc/portage/package.use.
Si vous enlevez un paramètre USE (par exemple, enlever gnome de
USE), cela ne fera que préciser à Portage de ne pas activer le
support optionnel de GNOME dans vos paquets. Cela dit, si vous
installez un ebuild qui nécessite GNOME, alors le paquet aura
evidemment le support de GNOME activé, comme vous pouviez vous en
douter. Cela signifie également que GNOME sera installé automatiquement
(en tant que dépendance) s'il ne l'était pas encore. C'est pourquoi
c'est toujours une bonne idée de faire un emerge --pretend (ou
mieux, un emerge --ask) avant de procéder à l'installation
effective. De cette manière, vous saurez exactement ce qui sera installé
par emerge.
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 qus 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 truc 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 disons explicitement à econf ce que
nous voulons qu'il fasse, d'après ce que l'on a dans les paramètres
USE. En plus, ça produit un code propre et facile à lire :).
Pour avoir une table mise à jour en permanence des paramètres USE, voyez
ce lien.
Les dépendances de paquet
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 faites un
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'à distinquer 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 rentre possible
de faire en sorte que seules les dépendances de lancement soient
effectivement installées.
Comment préciser les dépendances à vos fichiers 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 à 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 loin) 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, dans ce cas-là, ç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 pense qu'ils feront : Toutes les
versions plus récentes que sys-apps/bar version 1.2 iront (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émar 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évicion 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 est
déjà installé.
Pour les derniers détails sur les éléments DEPEND, lisez la section 5 de
la page de manuel sur les ebuilds : man 5 ebuild.