Syntaxe des fichiers de jeu de modules
JHBuild utilise des fichiers XML pour décrire les dépendances entre modules. Un schéma RELAX-NG et une définition de type de document (DTD : Document Type Definition) sont inclus avec JHBuild dans le répertoire modulesets/. Le schéma RELAX-NG peut être utilisé pour modifier les fichiers de jeux de modules au moyen du mode nxml-mode dans Emacs.
L'élément de premier niveau dans un fichier de jeu de modules est l'élément moduleset. Aucun espace de nom XML n'est utilisé. Les éléments sous le premier niveau sont de trois types : sources de module, commandes d'inclusion et définitions de module.
- VII.I. Sources de module
- VII.II. Inclusion d'autres jeux de modules
- VII.III. Définitions de modules
- VII.IV. Éléments désapprouvés
VII.I. Sources de module
Plutôt que d'énumérer l'emplacement exact de chaque module, plusieurs « sources de modules » sont listées dans le jeu de modules, puis référencées par leur nom dans les définitions de modules. En plus de réduire la quantité d'informations redondantes dans le jeu de modules, cela facilite l'indication d'une source alternative pour ces modules (avec CVS et Subversion, il arrive fréquemment que les développeurs et les utilisateurs utilisent des méthodes différentes pour accéder aux dépôts).
L'élément repository est utilisé pour décrire tout type de dépôt. L'élément branch est utilisé dans une définition de module pour préciser des paramètres supplémentaires.
<repository name="nom" type="type" [ default="valeur_par_défault" ] [ password="mot_de_passe" ] [ cvsroot="racine_cvs" ] [ archive="archive" ] [ href="href" ] [ server="serveur" ] [ database="base_de_données" ] [ defbranch="définition_branche" ] [ trunk-template="modèle_de_tronc" ] [ branches-template="modèle_de_branche" ] [ tags-template="modèle_de_tag" ] [ developer-href-example="exemple_href_pour_développeur" ] />
L'attribut name est un identifiant unique pour le dépôt.
L'attribut default indique si ce dépôt est la source par défaut pour ce jeu de modules.
L'attribut type indique le type de dépôt. Les valeurs possibles sont : arch, bzr, cvs, darcs, fossil, git, hg, mnt, svn, tarball. D'autres attributs dépendent de l'attribut type ainsi que de l'attribut branch utilisé dans les définitions de modules. Ceux-ci sont décrits ci-dessous dans les sous-sections types de dépôts.
L'attribut developer-href-example sert à indiquer le format de l'URL pour le dépôt tel qu'utilisé par les développeurs, à titre informatif.
L'élément branch est employé dans les définitions de modules.
<branch [ repo="dépôt" ] [ module="nom_de_module" ] [ checkoutdir="dossier_extraction" ] [ revision="révision" ] [ tag="tag" ] [ update-new-dirs="mise_à_jour_nouveaux_dossiers" ] [ override-checkoutdir="écraser_dossier_extraction" ] [ subdir="sous-dossier" ] [ branch="branche" ] [ version="version" ] [ size="taille" ] [ source-subdir="sous-dossier_source" ] [ hash="hâchage" ]/>
Tous les attributs possèdent des valeurs par défaut convenables et dépendent des définitions de modules et de dépôts. Les attributs courants sont décrits ici.
L'attribut repo permet d'indiquer un nom de dépôt différent de la valeur par défaut.
L'attribut module permet d'indiquer un nom de module pour l'extraction du dépôt. Par défaut, c'est l'identifiant du module.
L'attribut checkoutdir permet d'indiquer le nom du dossier d'extraction. Par défaut, c'est l'identifiant du module.
D'autres attributs sont décrits ci-dessous
- VII.I.I. Arch
- VII.I.II. Bazaar
- VII.I.III. CVS
- VII.I.IV. Darcs
- VII.I.V. Git
- VII.I.VI. Mercurial
- VII.I.VII. Monotone
- VII.I.VIII. Subversion
- VII.I.IX. Tarballs (archives tar)
VII.I.I. Arch
Ce type de dépôt permet de définir un dépôt Arch.
L'attribut archive permet d'indiquer l'archive à utiliser.
L'attribut href permet d'indiquer l'URL du dépôt.
<repository type="arch" name="rhythmbox" archive="rhythmbox-devel@gnome.org--2004" href="http://web.rhythmbox.org/arch/2004"/>
VII.I.II. Bazaar
This repository type is used to define a Bazaar repository. It is recommended to have Bazaar 1.16 or higher.
<repository type="bzr" name="launchpad.net" href="lp:"/>
Additional attributes are: trunk-template (defaults to "%(module)s") and branches-template (defaults to "%(module)s/%(branch)s"). These attributes are used to specify templates for constructing URL. A branch element in the module definitions can specify branch and user attributes. These values will be substitued in the templates. If either of those are defined branches-template is used, otherwise trunk-template is used. This way you can ovveride repository to build modules from your personal branch or build many modules fron a repository with non-standard layout.
An addition branch element accepts revspec attibute to anchor on a particular revision. Any valid bzr revspec is accepted, for example date:yesterday, -5, tag:0.1 to get first revision since yesterday, 5 commits behind the tip or tag "0.1". See bzr help revisionspec for all possible values.
Par exemple, un dépôt avec des attributs template :
<repository type="bzr" name="launchpad.net" href="lp:" trunk-template="~bzr-pqm/%(module)s/bzr.dev" branches-template="~bzr-pqm/%(module)s/%(branch)s"/>
Des exemples d'éléments branch pour le dépôt ci-dessus :
<branch repo="launchpad.net" module="bzr" checkoutdir="bzr-next"/>
<branch repo="launchpad.net" module="bzr" branch="2.2" checkoutdir="bzr-beta"/>
VII.I.III. CVS
Ce type de dépôt permet de définir un dépôt CVS.
L'attribut password permet d'indiquer le mot de passe pour accéder au dépôt.
L'attribut cvsroot permet d'indiquer la racine du dépôt.
<repository type="cvs" name="tango.freedesktop.org" cvsroot=":pserver:anoncvs@anoncvs.freedesktop.org:/cvs/tango" password=""/>
Attributs supplémentaires : revision, update-new-dirs et override-checkoutdir.
VII.I.IV. Darcs
Ce type de dépôt permet de définir un dépôt Darcs.
<repository type="darcs" name="telepathy.freedesktop.org" href="http://projects.collabora.co.uk/darcs/telepathy/"/>
VII.I.V. Git
Ce type de dépôt permet de définir un dépôt Git.
<repository type="git" name="git.freedesktop.org" href="git://anongit.freedesktop.org/git/"/>
Il autorise les attributs suivants sur l'élément branch :
The revision attribute is used to specify a local or remote-tracking branch to switch to in the update phase. It defaults to 'master'. It is possible to override this attribute with the branches configuration variable. The switch will only be performed, if the current branch is tracking a remote branch, to not disturb your own work.
The tag attribute is used to specify a revision to unconditionally check out in the update phase. It overrides the revision attribute.
<branch repo="git.freedesktop.org" module="swfdec/swfdec" checkoutdir="swfdec" revision="local-or-remote-branch" tag="tree-ish"/>
VII.I.VI. Mercurial
Ce type de dépôt permet de définir un dépôt Mercurial.
<repository type="hg" name="hg.gtk-vnc" href="http://gtk-vnc.codemonkey.ws/hg/" />
<branch repo="hg.gtk-vnc" module="outgoing.hg" checkoutdir="gtk-vnc"/>
VII.I.VII. Monotone
Ce type de dépôt permet de définir un dépôt Monotone.
L'attribut server permet d'indiquer le serveur du dépôt.
L'attribut database permet d'indiquer la base de données à utiliser pour le dépôt.
L'attribut defbranch permet d'indiquer la branche à utiliser dans le dépôt.
<repository type="mtn" name="pidgin.im" server="pidgin.im" database="pidgin.im.mtn" defbranch="im.pidgin.pidgin"/>
VII.I.VIII. Subversion
Ce type de dépôt permet de définir un dépôt Subversion.
<repository type="svn" name="svn.gnome.org" default="yes" href="http://svn.gnome.org/svn/"/>
Il autorise un attribut revision sur l'élément branch. Cet attribut définit la branche à extraire ou, si c'est un nombre, une révision spécifique à extraire.
<branch revision="gnome-2-20"/>
Il est possible de définir un agencement svn personnalisé en utilisant trunk-template (qui vaut par défaut « %(module)s/trunk »), branches-template (qui vaut par défaut « %(module)s/branches/%(branch)s ») et tags-template (qui vaut par défaut « %(module)s/tags/%(tag)s »).
VII.I.IX. Tarballs (archives tar)
Ce type de dépôt permet de définir un dépôt tarball.
<repository type="tarball" name="dbus/dbus-python" href="http://dbus.freedesktop.org/releases/dbus-python/"/>
Il autorise les attributs suivants sur l'élément branch :
L'attribut module indique le fichier à télécharger et compiler. L'attribut version indique la version du module.
Les attributs size et hash, ainsi que l'ancien attribut md5sum sont facultatifs. Si ces attributs existent, ils sont utilisés pour vérifier que le paquet source a été correctement téléchargé.
L'élément patches sert à indiquer un ou plusieurs correctifs à appliquer à l'arborescence source après décompression. L'attribut file indique le nom de fichier du correctif et l'attribut strip précise le nombre de niveaux de répertoires à retirer dans les chemins en appliquant le correctif.
Pour les jeux de modules livrés avec JHBuild, les fichiers de correctifs sont situés dans le répertoire jhbuild/patches/ ; pour les jeux de modules référencés par URI, les fichiers de correctifs doivent se trouver dans le même répertoire que le jeu de modules ou dans le sous-répertoire patches/. Il est aussi possible que l'attribut file indique un URI, auquel cas il sera téléchargé à cet emplacement.
<branch module="dbus-python-0.80.2.tar.gz" version="0.80.2" repo="dbus/dbus-python" hash="md5:2807bc85215c995bd595e01edd9d2077" size="453499"> <patches> <patch file="dbus-glib-build.patch" strip="1" /> </patches> <branch>
VII.II. Inclusion d'autres jeux de modules
JHBuild autorise un jeu de modules à inclure le contenu d'un autre jeu de modules en le référençant au moyen de l'élément include.
<include href="uri"/>
L'attribut href est une référence sous forme d'URI vers le jeu de modules à inclure, relatif au fichier contenant l'élément include.
Seules les définitions de modules sont importées à partir du jeu de modules référencé, et non pas les sources de modules. Plusieurs niveaux d'imbrication sont autorisés, mais pas les inclusions en boucle (il n'y a pas de code de détection de boucle pour l'instant).
VII.III. Définitions de modules
Il existe plusieurs types de définitions de modules utilisables dans un fichier de jeu de modules, et la liste peut facilement être augmentée. Seuls les types les plus courants sont mentionnés ici.
À la base, ils sont tous formés d'un élément branch décrivant la manière d'obtenir le module et d'éléments dependencies, suggests et after pour déclarer les dépendances du module.
Tout module mentionné dans l'élément dependencies est ajouté à la liste des modules lors de la commande jhbuild build (s'il n'y est pas déjà) ; JHBuild s'assure que les modules dépendants soient construits en premier.
Après avoir généré la liste des modules, les modules mentionnés dans l'élément suggests sont utilisés pour trier la liste des modules (sans y ajouter de module supplémentaire). Ceci est prévu pour les cas où un module possède une dépendance facultative sur un autre module.
- VII.III.I. autotools
- VII.III.II. cmake
- VII.III.III. distutils
- VII.III.IV. linux
- VII.III.V. perl
- VII.III.VI. waf
- VII.III.VII. Ant
- VII.III.VIII. testmodule
- VII.III.IX. metamodule
VII.III.I. autotools
L'élément autotools sert à définir un module qui doit être compilé à l'aide du système de construction GNU Autotools.
<autotools id="id" [ autogenargs="paramètres_autogen" ] [ makeargs="paramètres_make" ] [ makeinstallargs="paramètres_make_install" ] [ autogen-sh="autogen-sh" ] [ makefile="makefile" ] [ skip-autogen="ignorer-autogen" ] [ autogen-template="modèle_autogen" ] [ check-target="cible_contrôle" ] [ supports-non-srcdir-builds="gère_construction_non_srcdir" ]> <branch [ ... ] > [...] </branch> <dependencies> <dep package="nom_module"/> ... </dependencies> <after> <dep package="nom_module"/> ... </after> </autotools>
Les attributs autogenargs, makeargs et makeinstallargs servent à indiquer des paramètres supplémentaires à transmettre respectivement à autogen.sh, make et make install.
L'attribut autogen-sh indique le nom du script autogen.sh à exécuter. La valeur autoreconf peut être utilisée si le module n'a pas d'équivalent du script autogen.sh. Dans ce cas, JHBuild exécutera autoreconf -i, suivi par la phase configure. L'attribut skip-autogen indique s'il faut exécuter autogen.sh, il s'agit d'une valeur booléenne admettant également la valeur never pour signifier à JHBuild de ne jamais ignorer le lancement de autogen.sh. L'attribut makefile indique le nom du fichier makefile à utiliser.
L'attribut supports-non-srcdir-builds sert à marquer les modules qui ne peuvent être proprement construits en utilisant un répertoire source séparé.
L'attribut autogen-template peut être utilisé en cas de besoin de contrôle fin sur la ligne de commande autogen. C'est une chaîne de formatage Python, qui sera substituée par les variables suivantes : srcdir, autogen-sh, prefix, libdir, et autogenargs. Par exemple, voici la valeur par défaut de autogen-template :
%(srcdir)s/%(autogen-sh)s --prefix %(prefix)s --libdir %(libdir)s %(autogenargs)s
L'attribut check-target doit être indiqué (avec la valeur « false ») pour les modules qui n'ont pas de cible make check.
VII.III.II. cmake
L'élément cmake permet de définir un module construit à l'aide du système de construction CMake.
<cmake id="nom_module"> <branch [ ... ] > [...] </branch> <dependencies> <dep package="nom_module"/> ... </dependencies> <after> <dep package="nom_module"/> ... </after> </cmake>
VII.III.III. distutils
L'élément distutils permet de définir un module construit à l'aide de Python distutils.
<distutils id="nom_module" [ supports-non-srcdir-builds="yes|no" ]> <branch [ ... ] > [...] </branch> <dependencies> <dep package="nom_module"/> ... </dependencies> <after> <dep package="nom_module"/> ... </after> </distutils>
VII.III.IV. linux
L'élément linux permet de définir un module utilisé pour construire un noyau linux. De plus, une configuration de noyau séparée peut être choisie en utilisant le sous-élément kconfig.
<linux id="id" [ makeargs="paramètres_make" ]> <branch [ ... ] > [...] </branch> <dependencies> <dep package="nom_module"/> ... </dependencies> <after> <dep package="nom_module"/> ... </after> <kconfig [ repo="dépôt" ] version="version" [ module="module" ] [ config="config" ] /> </linux>
VII.III.V. perl
L'élément perl permet de construire des modules Perl.
L'attribut makeargs permet de définir des paramètres supplémentaires à passer à make.
<perl id="nom_module" [ makeargs="paramètres_make" ]> <branch [ ... ] > [...] </branch> <dependencies> <dep package="nom_module"/> ... </dependencies> <after> <dep package="nom_module"/> ... </after> </perl>
VII.III.VI. waf
L'élément waf permet de définir un module construit à l'aide du système de construction Waf.
L'attribut waf-command permet de définir le script de commande waf à utiliser ; la valeur par défaut est waf.
<waf id="nom_module"> [ waf-command="commande_waf" ]> <branch [ ... ] > [...] </branch> <dependencies> <dep package="nom_module"/> ... </dependencies> <after> <dep package="nom_module"/> ... </after> </waf>
VII.III.VII. Ant
L'élément ant permet de définir un module construit à l'aide de Ant, l'outil de construction basé sur Java.
<ant id="nom_module"> <branch [ ... ] > [...] </branch> <dependencies> <dep package="nom_module"/> ... </dependencies> <after> <dep package="nom_module"/> ... </after> </ant>
VII.III.VIII. testmodule
L'élément testmodule permet de créer un module qui exécute une suite de tests en utilisant LDTP ou Dogtail.
<testmodule id="id" type="type"> <branch [ ... ] > [...] </branch> <dependencies> <dep package="nom_module"/> ... </dependencies> <after> <dep package="nom_module"/> ... </after> <testedmodules> <tested package="paquet" /> </testedmodules> </testmodule>
L'attribut type indique le type de tests à exécuter dans le module. « dogtail » utilise Python pour appeler tous les fichiers .py. « ldtp » fait appel à « ldtprunner run.xml ».
Tant que l'option de configuration noxvfb n'est pas définie, un serveur Xvfb est démarré pour y lancer les tests.
VII.III.IX. metamodule
L'élément metamodule permet de définir un module qui ne fait vraiment rien. Le seul but d'un tel module est de définir des dépendances.
Par exemple, meta-gnome-desktop dépend de tous les éléments clés du bureau GNOME. En conséquence, demander à JHBuild de l'installer revient à installer le bureau complet.
<metamodule id="nom_module"> <dependencies> <dep package="nom_module"/> ... </dependencies> <suggests> <dep package="nom_module"/> ... </suggests> </metamodule>
L'attribut id donne le nom du module. Les éléments enfants sont traités de la même manière que autotools.
VII.IV. Éléments désapprouvés
- VII.IV.I. Sources de module
- VII.IV.II. Types de modules désapprouvés
VII.IV.I. Sources de module
- VII.IV.I.I. cvsroot
- VII.IV.I.II. svnroot
- VII.IV.I.III. arch-archive
VII.IV.I.I. cvsroot
L'élément cvsroot est maintenant désapprouvé. Il faut utiliser l'élément repository à la place.
L'élément cvsroot permet de décrire un dépôt CVS.
<cvsroot name="nom_racine" [ default="yes|no" ] root="cvsroot_anon" password="mot_de_passe_anon"/>
L'attribut name doit être un identifiant unique pour le dépôt CVS.
L'attribut default indique si cette source de module est la source par défaut pour ce fichier de jeu de modules.
L'attribut root contient la racine CVS utilisée pour l'accès anonyme à ce dépôt, et l'attribut password précise le mot de passe utilisé pour l'accès anonyme.
VII.IV.I.II. svnroot
L'élément svnroot est maintenant désapprouvé. Il faut utiliser l'élément repository à la place.
L'élément svnroot permet de décrire un dépôt Subversion.
<svnroot name="nom_racine" [ default="yes|no" ] href="svnroot_anonyme"/>
L'attribut name doit être un identifiant unique pour le dépôt Subversion.
L'attribut default indique si cette source de module est la source par défaut pour ce fichier de jeu de modules.
L'attribut href contient l'URL de base du dépôt. En général, c'est un URL http, https ou svn.
VII.IV.I.III. arch-archive
L'élément arch-archive est maintenant désapprouvé. Il faut utiliser l'élément repository à la place.
L'élément arch-archive permet de décrire une archive GNU Arch.
<arch-archive name="nom_archive" [ default="yes|no" ] href="url_miroir"/>
L'attribut name doit correspondre au nom de l'archive Arch.
L'attribut default indique si cette source de module est la source par défaut pour ce fichier de jeu de modules.
L'attribut href contient l'URL d'un miroir public de l'archive.
VII.IV.II. Types de modules désapprouvés
Cette section présente des éléments désapprouvés. Il se peut qu'ils soient encore utilisés dans des jeux de modules existants, mais il est conseillé de ne plus les utiliser.
- VII.IV.II.I. tarball
VII.IV.II.I. tarball
Cet élément désapprouvé est une simple couche fine autour du type de module autotools et du type de dépôt tarball.
L'élément tarball permet de définir un module à construire à partir d'une archive tar.
<tarball id="nom_de_module" [ version="version" ] [ checkourdir="répertoire_extraction" ] [ autogenargs="paramètres_autogen" ] [ makeargs="paramètres_make" ] [ autogen-sh="autogen-sh" ] [ supports-non-srcdir-builds="yes|no" ]> <source href="url_source" [ size="taille_source" ] [ hash="algorithme_source:hash_source" ] [ md5sum="somme_md5_source" ]/> <patches> <patch file="nom_de_fichier" strip="niveau"/> ... </patches> <dependencies> <dep package="nom_de_module"/> ... </dependencies> <suggests> <dep package="nom_de_module"/> ... </suggests> </tarball>
Les attributs id et version sont utilisés pour identifier le module.
L'élément source indique le fichier à télécharger et compiler. L'attribut href est obligatoire, alors que les attributs size et hash, comme l'attribut obsolète md5sum, sont facultatifs. Si ces deux derniers attributs sont présents, ils sont utilisés pour vérifier que le paquet source a été correctement téléchargé.
L'élément patches sert à indiquer un ou plusieurs correctifs à appliquer à l'arborescence source après décompression. L'attribut file indique le nom de fichier du correctif et l'attribut strip précise le nombre de niveaux de répertoires à retirer dans les chemins en appliquant le correctif.
Pour les jeux de modules livrés avec JHBuild, les fichiers de correctifs sont situés dans le répertoire jhbuild/patches/ ; pour les jeux de modules référencés par URI, les fichiers de correctifs doivent se trouver dans le même répertoire que le jeu de modules ou dans le sous-répertoire patches/. Il est aussi possible que l'attribut file indique un URI, auquel cas il sera téléchargé à cet emplacement.
Les autres attributs et les éléments dependencies, suggests et after sont traités de la même manière que pour autotools.