Gentoo Logo

[ << ] [ < ] [ Sommaire ] [ > ] [ >> ]


2. Guide pour les eclass

Table des matières :

2.a. Introduction aux fichiers eclass

Le principe des fichiers eclass

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

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

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

Un exemple d'eclass simple

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

Exemple de code 1.1 : Exemple : sourceforge.eclass

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

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

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

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

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

Exemple de code 1.2 : Comment hériter d'un eclass

inherit sourceforge

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

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

Exemple de code 1.3 : Héritage multiple

inherit eclass1 eclass2 [...]

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

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

inherit()

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

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

EXPORT_FUNCTIONS

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

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

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

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

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

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

Exemple de code 1.4 : EXPORT_FUNCTIONS() (depuis ebuild.sh)

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

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

Exemple de code 1.5 : Exemple d'utilisation de EXPORT_FUNCTIONS

EXPORT_FUNCTIONS src_compile src_install

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

Exemple de code 1.6 : Résultat d'utilisation de EXPORT_FUNCTIONS

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

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

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

Exemple de code 1.7 : Étendre une fonction définie par défaut dans un eclass dans votre ebuild

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

EXPORT_FUNCTIONS src_compile
#fin du code de l'eclass

#dans un ebuild:
inherit foo

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

Les sections de fonction

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

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

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

Exemple de code 1.8 : Exemple pris sur le fichier base.eclass d'origine

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

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

Exemple de code 1.9 : La même fonction, divisée en sections

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

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

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

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

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

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

Exemple de code 1.10 : Utiliser src_compile() sectionné

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

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

Les fonctions debug-print-*

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

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

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

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

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

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

Exemple de code 1.11 : Ajouter des retours de déboggage

base_src_compile() {

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

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

2.b. Fichiers eclass existants

Introduction

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

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

base.eclass

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

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

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

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

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

cvs.eclass

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

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

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

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

kde-functions.eclass

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

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

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

L'arborescence utilisée actuellement pour KDE

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

need-autoconf(), need-automake()

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

kde_sandbox_patch()

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

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

Exemple de code 2.1 : Utilisation de kde_sandbox_patch

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

kde_remove_flag()

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

kde_remove_dir() et ${KDE_REMOVE_DIR}

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

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

kde.eclass

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

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

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

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

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

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

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

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

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

kde-base.eclass

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

kde-dist.eclass

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

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

kde-i18n.eclass

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

kde.org.eclass

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

koffice-i18n.eclass

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

kde-source.eclass

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

2.c. Écrire des ebuilds KDE

Introduction

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

Un ebuild typique KDE

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

Exemple de code 3.1 : Un ebuild simple pour KDE, #1

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

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

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

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

Exemple de code 3.2 : Un ebuild simple pour KDE, #2 : ajouter des dépendances supplémentaires

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

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

Exemple de code 3.3 : Un ebuild simple pour KDE, #3 : passer des arguments à configure

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

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

Exemple de code 3.4 : Un ebuild simple pour KDE, #4 : correctifs automatiques

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

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

Exemple de code 3.5 : Un ebuild simple pour KDE, #5 : étendre src_install()

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

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

Exemple de code 3.6 : Un ebuild simple pour KDE - complet

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

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

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

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

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

Un ebuild typique avec une fonctionnalité optionnelle KDE

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

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

Exemple de code 3.7 : Support optionnel KDE - section principale de l'ebuild

inherit kde-functions

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

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

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

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


[ << ] [ < ] [ Sommaire ] [ > ] [ >> ]


Imprimer

Voir tout

Dernière mise à jour le 5 décembre 2004

Résumé : Cette section propose aux développeurs un guide qui détaille le fonctionnement des eclass et comment ils peuvent être appliqués aux ebuilds.

Donny Davies
HOWTO Ebuilds - Auteur

Peter Gavin
Auteur

Karl Trygve Kalleberg
Auteur

Mike Frysinger
Auteur

Daniel Robbins
Auteur/Relecteur

John P. Davis
Auteur/Relecteur

Jorge Paulo
Relecteur

Sven Vermeulen
Relecteur

Zack Gilburd
Relecteur

Benny Chuang
Relecteur

Erwin
Relecteur

Dan Armak
HOWTO Eclass - Autheur

Alastair Tse
Erreurs Classiques pour les ebuilds - Auteur

Paul De Vrieze
Documentation Metadata - Auteur

Owen Stampflee
Politique générale concernant les ebuilds - Auteur

Seemant Kulleen
Relecteur

Jon Portnoy
Relecteur

Carl Anderson
Relecteur

Ciaran McCreesh
Correcteur

Nicholas D. Wolfwood
Correcteur

Marius Mauch
Correcteur

Daniel Black
Correcteur

Tim Yamin
Auteur/Relecteur

Wernfried Haas
Correcteur

Shyam Mani
Relecteur

L'équipe relationnelle des développeurs Gentoo
Relecteurs

Clément Varaldi
Traducteur

Xavier Neys
Traducteur

Donate to support our development efforts.

Copyright 2001-2014 Gentoo Foundation, Inc. Questions, Comments? Contact us.