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

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

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

Ce type de dépôt permet de définir un dépôt Bazaar. Il est recommandé de posséder une version de Bazaar 1.16 ou plus élevée.

<repository type="bzr" name="launchpad.net"
      href="lp:"/>
        

Voici des attributs supplémentaires : trunk-template (égal à « %(module)s » par défaut) et branches-template (égal à « %(branch)s » par défaut). Ces attributs sont utilisés pour indiquer des modèles dans la construction des URL. Un élément branch dans les définitions de modules peut préciser des attributs branch et user. Ces valeurs sont substituées dans les modèles. Si l'un des deux est défini, c'est branches-template qui est utilisé, sinon c'est trunk-template. Ainsi, vous pouvez redéfinir un dépôt pour construire des modules à partir de votre branche personnelle ou construire plusieurs modules à partir d'un dépôt qui n'est pas structuré de manière standard.

Un élément branch supplémentaire accepte un attribut revspec pour se fixer sur une révision particulière. N'importe quelle bzr revspec valide est acceptée, par exemple date:yesterday, -5, tag:0.1 pour obtenir la première révision depuis hier, 5 commits derrière la tête (tip) ou l'étiquette « 0.1 ». Consultez bzr help revisionspec pour connaître toutes les valeurs possibles.

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 :

L'attribut revision est utilisé pour indiquer une branche locale ou qui suit une branche distante vers laquelle basculer lors de la phase de mise à jour. Par défaut, il contient « master ». Il est possible de redéfinir cet attribut avec la variable de configuration branches. Ce basculement ne se produit que si la branche actuelle suit une branche distante, afin de ne pas interférer avec votre propre développement.

L'attribut tag indique la révision à extraire absolument durant la phase de mise à jour. Il surcharge l'attribut revision.

<branch repo="git.freedesktop.org" module="swfdec/swfdec"
        checkoutdir="swfdec"
        revision="branche-locale-ou-distante"
        tag="étiquette"/>
        

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

Any number of patch elements may be nested inside the branch element. These patches are applied, in order, to the source tree after unpacking. The file attribute gives the patch filename, and the strip attribute says how many levels of directories to prune when applying the patch.

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">
  <patch file="dbus-glib-build.patch" strip="1" />
</branch>

A tarball branch element may also contain quilt elements which specify nested branch to import.

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

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

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.