# Manuel de JHBuild

## Introduction

JHBuild est un outil conçu pour faciliter la compilation d'ensembles de paquets source, appelés modules. Il utilise des fichiers de « jeux de modules » (moduleset) pour décrire les modules disponibles pour la compilation. Ces fichiers contiennent des informations sur les dépendances, ce qui permet à JHBuild de déterminer les modules à compiler et dans quel ordre.

JHBuild a été d'abord créé pour compiler GNOME, mais il a été complété depuis pour être utilisable par d'autres projets. Un fichier jeux de modules (moduleset) peut se trouver sur un serveur Web, permettant ainsi de fournir des règles de compilation indépendamment du projet JHBuild.

JHBuild can build modules from a variety of sources, including CVS, Subversion, Bazaar, Darcs, Git and Mercurial repositories, as well as Tar and Zip archives hosted on web or FTP sites. JHBuild can build modules using a variety of build systems, including Autotools, CMake, WAF, Python Distutils and Perl Makefiles.

JHBuild n'est pas destiné à remplacer le système de gestion de paquets d'une distribution. Au contraire, il simplifie la compilation de logiciels à l'intérieur d'un préfixe d'installation distinct afin de ne pas interférer avec le reste du système.

## Premiers pas

Quelques manipulations sont nécessaires pour configurer JHBuild avant de pouvoir compiler des logiciels. Certains logiciels sont nécessaires au fonctionnement de JHBuild, et il est aussi nécessaire d'installer des outils indispensables à l'obtention et à la construction des sources de logiciels.

### Installation de JHBuild

JHBuild nécessite un moteur d'exécution Python. Vérifiez que Python >= 2.3 est installé.

La façon recommandée de télécharger JHBuild est d'utiliser le gestionnaire de versions `git`. La commande à utiliser est présentée ci-dessous. Il est recommandé d'exécuter cette commande dans un nouveau répertoire où tout le code source sera téléchargé, par exemple `~/checkout/gnome`).

    $ git clone git://git.gnome.org/jhbuild
    ...
    $

Cela va télécharger JHBuild dans un nouveau dossier nommé `jhbuild` dans le répertoire actuel. Ensuite, pour le construire et l'installer :

    $ cd jhbuild
    $ ./autogen.sh
    ...
    $ make
    ...
    $ make install
    ...
    $

If gnome-common, yelp-tools and autotools are available, `autogen.sh` will configure JHBuild to install via autotools. If gnome-common, yelp-tools and autotools are not available, `autogen.sh` will configure JHBuild to install via a plain Makefile. To always use the plain Makefile method pass `--simple-install` to `autogen.sh`.

Si les étapes ci-dessus se sont déroulées avec succès, un petit script shell sera installé dans `~/.local/bin` pour lancer JHBuild. Ajoutez ce chemin dans votre variable `PATH` :

    $ PATH=$PATH:~/.local/bin
    $

Pour ajouter `~/.local/bin` de façon permanente à la variable `PATH`, exécutez la commande suivante :

    $ echo PATH=$PATH:~/.local/bin >> ~/.bashrc
    $

Avant de lancer JHBuild, il est nécessaire de paramétrer le fichier de configuration `~/.jhbuildrc`.

### Configuration de JHBuild

The `~/.jhbuildrc` file uses Python syntax to set configuration variables for JHBuild. An example is provided with JHBuild, see `examples/sample.jhbuildrc`. Copy `examples/sample.jhbuildrc` to `~/.jhbuildrc` and customize as required.

The sample configuration will make JHBuild build the meta-gnome-core and meta-gnome-apps-tested modules and dependencies from the `gnome-apps` module set. JHBuild will unpack source trees to `~/checkout/gnome` and install all files to subdirectories of `/opt/gnome`. The two directories must be writable.

Les variables de configuration sont documentées dans config-reference. En voici quelques-unes parmi les plus utilisées :

`repos`

- Un dictionnaire pouvant être utilisé pour indiquer un emplacement de dépôt alternatif pour un dépôt spécifique. Cette variable de configuration est utile pour les développeurs de modules. Par défaut, JHBuild extrait le code dans les dépôts par un accès anonyme. Les clés du dictionnaire sont des noms de dépôts courts et les valeurs sont des chaînes d'accès à des emplacements de dépôts alternatifs. Par exemple :

      repos['git.gnome.org'] = 'ssh://nom_utilisateur@git.gnome.org/git/'

`moduleset`

- Une chaîne ou une liste de chaînes indiquant le ou les noms des jeux de modules à utiliser. Cela peut être le nom de fichier d'un jeu de modules inclus dans JHBuild (sans chemin ni extension) ou un URL HTTP complet d'un jeu de modules géré en externe. Les jeux de modules ayant un URL HTTP sont placés dans un cache local. Si le nom d'un module figure dans plus d'un jeu de modules, le dernier jeu de modules dans la liste est prioritaire. Les jeux de modules fournis avec JHBuild sont mis à jour au gré de la progression du développement de GNOME.

`modules`

- A list of strings specifying the modules to build. The list of modules actually built will be recursively expanded to include all the dependencies unless the `buildone` command is used. Defaults to `['meta-gnome-desktop']`.

`checkoutroot`

- A string specifying the directory to unpack source trees to. Unless `buildroot` is set, builds will occur in this directory too. Defaults to `~/checkout/gnome`.

`prefix`

- A string specifying the prefix to install modules to. `prefix` must be an absolute path. This directory must be writable. Defaults to `'/opt/gnome'`.

`autogenargs`

- A string containing arguments passed to the `autogen.sh` script of all modules. Can be overridden for particular modules using the `module_autogenargs` dictionary.

`makeargs`

- Une chaîne énumérant des paramètres supplémentaires à passer à `make`. La valeur par défaut est `''`.

### Prérequis pour la construction

Before any modules can be built, it is necessary to have certain build tools installed. Common build tools include the GNU Autotools (autoconf, automake, libtool and gettext), The GNU Toolchain (binutils, gcc, g++), make, pkg-config and Python, depending on which modules will be built.

JHBuild peut vérifier si ces outils sont installés sur votre système à l'aide de la commande `sanitycheck` :

    $ jhbuild sanitycheck

Si cette commande affiche un message, il est possible de corriger les erreurs de deux manières :

1. Installez le paquet requis à partir du dépôt de votre distribution. Une liste de noms de paquets de différentes distributions est disponible sur le wiki de GNOME. Exécutez à nouveau la commande `sanitycheck` après avoir installé les paquets de la distribution pour s'assurer que les outils requis sont maintenant présents.

2. Lancez la commande `bootstrap` pour télécharger, compiler et installer les prérequis de construction :

       $ jhbuild bootstrap

   Lorsque l'opération est terminée, lancez la commande `sanitycheck` pour vérifier que les outils requis sont présents.

   La commande `bootstrap` ne construit pas toutes les dépendances des paquets requis par les outils de construction. Si votre distribution ne fournit pas ces paquets, ils devront alors être construits en dehors de l'environnement JHBuild.

   Les dépendances des outils de construction comprennent notamment m4, perl et un compilateur C (par exemple gcc).

### Utilisation de JHBuild

Après que tout a été configuré, JHBuild peut se mettre à construire des logiciels. Pour construire tous les modules indiqués dans le fichier `~/.jhbuildrc`, exécutez la commande suivante :

    $ jhbuild build

JHBuild va télécharger, configurer, compiler et installer chaque module. Si une erreur se produit à n'importe quelle étape, JHBuild présente un menu pour savoir ce qu'il doit faire. Les choix possibles comprennent le passage dans un shell pour corriger l'erreur, une nouvelle passe de construction à différentes étapes, l'abandon de la construction du module ou la non prise en compte de l'erreur en continuant le processus.

L'abandon d'un module provoque l'échec de construction de tout module dépendant de ce module.

Voici un exemple de menu qui est affiché :

      [1] Rerun phase build
      [2] Ignore error and continue to install
      [3] Give up on module
      [4] Start shell
      [5] Reload configuration
      [6] Go to phase "wipe directory and start over"
      [7] Go to phase "configure"
      [8] Go to phase "clean"
      [9] Go to phase "distclean"
    choice:

Il est aussi possible de construire un jeu différent de modules (et leurs dépendances) en passant les noms des modules en paramètre de la commande `build`. Par exemple, pour construire gtk+ :

    $ jhbuild build gtk+

Si JHBuild est interrompu en cours de construction d'un module, quelle qu'en soit la raison, il est possible de reprendre la construction à partir d'un module précis en utilisant l'option `--start-at` :

    $ jhbuild build --start-at=pango

Pour construire un ou plusieurs modules en ignorant leurs dépendances, JHBuild fournit la commande `buildone`. Pour que cette commande se déroule correctement, toutes les dépendances du module indiqué doivent être préalablement construites et installées, ou fournies par des paquets de votre distribution.

    $ jhbuild buildone gtk+

When actively developing a module, you are likely in a source working directory. The `make` will invoke the build system and install the module. This will be a key part of your edit-compile-install-test cycle.

    $ jhbuild make

Si JHBuild est interrompu en cours de construction d'un module, quelle qu'en soit la raison, il est possible de reprendre la construction à partir d'un module précis en utilisant l'option `--start-at` :

Pour obtenir une liste ordonnancée des modules et des dépendances que JHBuild va construire, utilisez la commande `list` :

    $ jhbuild list

Pour obtenir des informations sur un module particulier, utilisez la commande `info` :

    $ jhbuild info gtk+

Pour télécharger ou mettre à jour toutes les sources de logiciels sans rien compiler, utilisez la commande `update`. Cette commande donne l'occasion de modifier les sources avant la compilation et peut se révéler utile quand la disponibilité de bande passante Internet est instable.

    $ jhbuild update

Plus tard, JHBuild peut tout construire sans télécharger ni mettre à jour les sources :

    $ jhbuild build --no-network

Pour lancer une commande précise dans le même environnement utilisé par JHBuild, utilisez la commande `run` :

    $ jhbuild run program

Pour lancer un shell avec l'environnement utilisé par JHBuild, utilisez la commande `shell` :

    $ jhbuild shell

## JHBuild et GNOME

Cette section fournit des indications sur la compilation, l'installation et le fonctionnement de GNOME.

### Construction de GNOME

Pour compiler GNOME, certains paquets de développement sont nécessaires, notamment :

- La DTD DocBook XML et les feuilles de styles XSLT. Elles doivent être enregistrées dans le catalogue XML (`/etc/xml/catalog`).

- Les bibliothèques X

- `libsmbclient` de Samba (utilisé pour parcourir les réseaux Windows).

- `libbz2` de bzip2.

- `libpng`, `libjpeg` et `libtiff` (utilisés pour le chargement d'images).

Si vous installez des paquets de votre distribution et si cela s'applique à votre distribution, installez les paquets dev ou devel correspondants. Une liste de noms de paquets de différentes distributions est disponible sur le wiki de GNOME.

### Lancement d'une application GNOME unique

Cette section décrit comment lancer une seule application GNOME. L'application se lance dans l'environnement de bureau actuel. Pour lancer une application dans le contexte d'un GNOME JHBuild complet, consultez running-gnome.

Exécutez un shell JHBuild. Ce shell dispose de toutes les variables d'environnement nécessaires déjà configurées.

    $ jhbuild shell

Vérifiez que la bonne application va être lancée. Par exemple :

    $ which gedit
    /opt/gnome/bin/gedit

lancez l'application :

    $ gedit &

Il est aussi possible de lancer l'application en utilisant la commande `run` :

    $ jhbuild run gedit

### Lancement de l'environnement de bureau GNOME

Créez un nouveau compte utilisateur pour faire fonctionner le GNOME JHBuild. Il est recommandé d'utiliser un compte utilisateur différent pour GNOME JHBuild, afin d'éviter des problèmes liés aux paramètres utilisateur stockés dans le dossier personnel. Ce manuel fait référence à ce nouveau compte par le nom `gnomedev`.

Configurez JHBuild dans le nouveau compte `gnomedev`. Copiez ou créez un lien symbolique pour `~/.jhbuildrc` et `~/.local/bin/jhbuild` dans le dossier personnel de `gnomedev`.

Ouvrez un terminal en tant qu'utilisateur `gnomedev`. Ajoutez `~/.local/bin` de façon permanente à la variable `PATH` en exécutant la commande suivante :

    $ echo PATH=$PATH:~/.local/bin >> ~/.bashrc

Testez que JHBuild fonctionne :

    $ jhbuild run pkg-config gtk+-2.0 --modversion
    2.20.1

#### Configuration de GNOME en mode « gestionnaire d'affichage »

Compilez et installez GNOME JHBuild.

Activez les services système. GNOME JHBuild utilise le démon D-Bus système `/usr/bin` et les services système dans `/usr/share/dbus-1/system-services/`. GNOME JHBuild utilise le démon D-Bus de session et les services dans ``/opt/gnome/`share/dbus-1/services/`. Remplacez `/opt/gnome` par le préfixe d'installation de GNOME dans la commande ci-après :

    $ rm -rf /opt/gnome/var/run/dbus
    $ ln -s /var/run/dbus /opt/gnome/var/run/dbus
    $ rm -rf /opt/gnome/var/lib/dbus/machine-id
    $ ln -s /var/lib/dbus/machine-id /opt/gnome/var/lib/dbus/machine-id

Créez un script de démarrage GNOME dans `/usr/bin/gnome-jhbuild-session` contenant le texte suivant, en remplaçant `/opt/gnome` par le préfixe d'installation de GNOME :

    #!/bin/sh

    GNOME=/opt/gnome

    GDK_USE_XFT=1
    XDG_DATA_DIRS=$XDG_DATA_DIRS:$GNOME/share
    XDG_CONFIG_DIRS=$XDG_CONFIG_DIRS:$GNOME/etc/xdg

    jhbuild run gnome-session

Rendez exécutable le fichier `/usr/bin/gnome-jhbuild-session` :

    $ chmod a+x /usr/bin/gnome-jhbuild-session

Pour ajouter une nouvelle entrée de session dans le gestionnaire d'affichage, créez le fichier `/usr/share/xsessions/gnome-jhbuild.desktop` avec un contenu semblable à ceci :

    [Desktop Entry]
    Name=GNOME (JHBuild)
    Comment=Cette session vous connecte dans une session GNOME de test
    Exec=/usr/bin/gnome-jhbuild-session
    Icon=
    Type=Application

Redémarrez `gdm`.

#### Lancement de GNOME depuis le gestionnaire d'affichage

Pour lancer GNOME JHBuild, sélectionnez la session GNOME (JHBuild) dans l'écran de bienvenue du gestionnaire d'affichage, avant de saisir les informations de connexion du compte `gnomedev`. Si tout fonctionne correctement, GNOME JHBuild va apparaître. Sinon, inspectez le journal dans le fichier `~gnomedev/.xsession-errors`.

## Intégration à un robot de compilation (buildbot)

Associé au projet Buildbot, JHBuild peut aussi fonctionner comme outil d'intégration continue. Le projet GNOME utilise une configuration Buildbot sur build.gnome.org.

### Configuration d'un esclave de robot de compilation

Un esclave de robot de compilation est une variante d'une installation JHBuild normale qui va servir les requêtes d'un maître de compilation. Il est conseillé de d'abord faire fonctionner JHBuild correctement en effectuant une compilation complète et réussie de la majorité des modules avant de le configurer en tant que robot de compilation.

Les commandes des robots de compilation sont des options de la commande `bot`. Pour télécharger et installer les logiciels supplémentaires requis, exécutez la commande suivante :

    $ jhbuild bot --setup

Après l'exécution réussie de cette étape, trois nouvelles variables de configuration sont nécessaires dans `~/.jhbuildrc`.

Il n'est pas possible d'utiliser un fichier de configuration différent, l'option `--file` ne produira pas l'effet désiré.

    jhbuildbot_master = 'build.gnome.org:9070'
    jhbuildbot_slavename = 'nom_esclave'
    jhbuildbot_password = 'mot_de_passe'

`jhbuildbot_master` est une chaîne indiquant le serveur maître du robot de compilation. Par défaut, c'est `'build.gnome.org:9070'`. `jhbuildbot_slavename` et `jhbuildbot_password` permettent d'identifier l'esclave sur le serveur maître. Contactez les administrateurs du robot maître pour obtenir les nom d'utilisateur et mot de passe de l'esclave.

Les administrateurs de build.gnome.org peuvent être contactés via la liste de diffusion de l'équipe de compilation.

## Référence des commandes

JHBuild utilise une syntaxe de ligne de commande similaire aux outils du style CVS :

    jhbuild
          global-options
          command
          command-arguments

Les options globales de JHBuild sont :

`-f`, `--file` `config`

- Utilise un fichier de configuration alternatif au lieu du fichier `~/.jhbuildrc` par défaut.

`-m`, `--moduleset` `moduleset`

- Utilise un autre jeu de modules que celui qui est indiqué dans le fichier de configuration. Cette option peut être un chemin relatif si le jeu de modules se trouve dans le dossier des jeux de modules de JHBuild, ou un chemin absolu s'il se trouve ailleurs.

`--no-interact`

- N'interroge jamais l'utilisateur quant à un choix à faire. Cette option est utile pour effectuer une construction sans intervention humaine, afin de s'assurer que la construction ne soit pas interrompue.

Les options particulières à certaines commandes sont énumérées ci-dessous.

### autobuild

La commande `autobuild` construit automatiquement les modules indiqués dans le fichier de configuration, puis envoie les résultats vers JHAutobuild.

    jhbuild autobuild
            --autogen
            --clean
            --distcheck
            --skip=module
            --start-at=module
            --report-url=reporturl
            --verbose

The `--autogen`, `--clean`, `--distcheck`, `--skip` and `--start-at` options are processed as per the `build` command.

`--report-url=`url-de-rapport``, `-r `url-de-rapport``

- Cette option indique l'URL de JhAutobuild où envoyer le rapport.

`--verbose`, `-v`

- Si indiquée, cette option produit des messages de JHBuild plus verbeux.

### bootstrap

La commande `bootstrap` installe un ensemble d'utilitaires de construction requis pour la plupart des modules (par ex. autoconf, automake, etc).

    jhbuild bootstrap

La commande `bootstrap` construit les modules avec la même méthode que la commande `build`, mais en utilisant le jeu de modules `bootstrap.modules`.

Consultez la documentation de la commande `build` pour connaître les options disponibles.

### build

La commande `build` construit un ou plusieurs paquets ainsi que leurs dépendances.

    jhbuild build
            --autogen
            --clean
            --check
            --dist
            --distcheck
            --ignore-suggests
            --no-network
            --skip=module
            --start-at=module
            --tags=tags
            -D date
            --no-xvfb
            --try-checkout
            --no-poison
            --force
            --build-optional-modules
            --min-age=time
            module

Si aucun nom de module n'est indiqué dans la ligne de commande, c'est la liste des modules du fichier de configuration qui est utilisée.

`-c`, `--clean`

- Exécute `make clean` avant de construire les modules.

`--check`

- Exécute `make check` après la construction des modules.

`-d`, `--dist`

- Exécute `make dist` après la construction des modules.

`--distcheck`

- Exécute `make distcheck` après la construction des modules.

`--ignore-suggests`

- Ne compile pas les dépendances faibles.

`-n`, `--no-network`

- N'accède pas au réseau lors de la construction des modules. Cette option évite les étapes de téléchargement ou de mise à jour lors des constructions. Si un module ne peut pas être construit sans accès réseau, sa construction échouera.

`-s`, `--skip`=`module,...`

- Ne compile pas les modules de la liste. Utilisé pour éviter la construction de dépendances spécifiques.

`--tags`=`étiquette,...`

- Ignore les modules qui ne correspondent pas à `étiquette`. Une étiquette correspondant au nom du jeu de modules conteneur est automatiquement attribuée à chaque module.

`-t`, `--start-at`=`module`

- Commence par le module indiqué plutôt qu'au début de la liste des dépendances. Cette option est utile quand la construction précédente a échoué.

`-D` `date`

- Si le système de gestion de version sous-jacent le prend en charge, met à jour l'arborescence source selon son état à la date indiquée, avant de commencer la construction. La date doit être indiquée au format ISO, par exemple `"2009-09-18 02:32Z"`.

`-x`, `--no-xvfb`

- Effectue les tests graphiques avec le serveur X réel au lieu d'utiliser une simulation Xvfb.

`-C`, `--try-checkout`

- Si la construction échoue et que le système de gestion de version le prend en charge, force une extraction et exécute `autogen.sh` avant de recommencer la construction.

`-N`, `--no-poison`

- Si l'une ou plusieurs des dépendances du module échouent, cette option force JHBuild à essayer tout de même de construire le module.

`-f`, `--force`

- Construit les modules même si la stratégie habituelle indique que ce n'est pas nécessaire.

`--build-optional-modules`

- Certains modules énumérés comme dépendances facultatives ne sont pas absolument nécessaires pour construire le module. Cette option force JHBuild à construire aussi les dépendances facultatives.

`--min-age`=`time`

- Skip modules installed more recently than the specified relative time. The `time` string format is a number followed by a unit. The following units are supported: seconds (s), minutes (m), hours (h) and days (d). For example, `--min-age=2h` will skip modules built less than two hours ago.

### make

The `make` command is for actively developing on a particular module. It requires the current directory be a source checkout, and does the equivalent of `buildone -nf $(basename $(pwd))`.

    jhbuild make
            --clean
            --check
            --distcheck
            --quiet

The options are the same as those available for the `buildone` command.

### buildone

La commande `buildone` est semblable à `build`, mais elle ne construit pas les dépendances du module. Elle est utile pour reconstruire un ou plusieurs modules.

    jhbuild buildone
            --clean
            --check
            --distcheck
            --no-network
            -D date
            --no-xvfb
            --force
            --min-age=time
            module

The `--check`, `--clean`, `-d`, `--distcheck`, `--no-network`, `-D` and `-x` options are processed as per the `build` command.

Cette commande nécessite au minimum un module dans la ligne de commande.

### checkbranches

La commande `checkbranches` vérifie si les branches des modules sont définies correctement dans le gestionnaire de version et si les branches sont cohérentes avec le jeu de modules.

    jhbuild checkbranches
            --branch=branch

`--branch`=`branch`, `-b` `branch`

- La branche à vérifier

    $ jhbuild -m gnome-2.20 checkbranches
    libgnomecanvas is missing branch definition for gnome-2-20
    $

### clean

La commande `clean` nettoie les répertoires de compilation d'un ou de plusieurs modules.

    jhbuild clean
            --skip=module
            --start-at=module

Si aucun nom de module n'est indiqué dans la ligne de commande, c'est la liste des modules du fichier de configuration qui est utilisée.

Consultez la documentation de la commande `build` pour une description des options disponibles.

### dot

La commande `dot` génère un fichier décrivant le graphe directionnel formé par les dépendances dans un jeu de modules. Ce fichier peut ensuite être traité par le logiciel GraphViz pour produire un diagramme.

    jhbuild dot
            --soft-deps
            --clusters
            module

Si aucun nom de module n'est indiqué dans la ligne de commande, c'est la liste des modules du fichier de configuration qui est utilisée.

L'option `--soft-deps` ajoute des lignes pointillées depuis les modules vers leurs dépendances faibles. L'option `--clusters` groupe les modules selon les métamodules.

La sortie de la commande dot peut être redirigée vers l'utilitaire dot pour générer un fichier PostScript :

    $ jhbuild dot modules | dot -Tps > dependencies.ps

Ou une image PNG :

    $ jhbuild dot modules | dot -Tpng > dependencies.png

#### Exemple de sortie dot de JHBuild

### gui

La commande `gui` lance une interface graphique de JHBuild qui permet de sélectionner des modules à construire et de modifier certaines options.

    jhbuild gui

L'interface graphique est basée sur GTK, ce qui requiert des bibliothèques supplémentaires.

### info

La commande `info` affiche des informations sur un ou plusieurs modules.

    jhbuild info
            module

Cette commande affiche le nom du module, son type, ses dépendances, les paquets qui en dépendent, le répertoire source et la date de sa dernière installation avec JHBuild. Le cas échéant, elle affiche également certaines informations spécifiques au type de module, telles que le dépôt CVS ou l'URL de téléchargement.

Si aucun module n'est précisé dans la commande, des informations sont affichées au sujet de tous les modules définis dans le jeu de modules.

### list

La commande `list` affiche la liste complète des modules que la commande `build` construirait.

    jhbuild list
            -a
            -r
            -s
            --start-at=module
            --tags=tags
            --ignore-suggests
            --list-optional-modules
            module

Si aucun nom de module n'est indiqué dans la ligne de commande, c'est la liste des modules du fichier de configuration qui est utilisée.

Les options `--skip`, `--start-at`, `--tags` et `--ignore-suggests` sont traitées de la même manière que pour la commande `build`.

`-a`, `--all-modules`

- Énumère tous les modules du jeu de modules, sans tenir compte des dépendances de construction.

`-r`, `--show-revision`

- Si un module est défini par une de ses branches, affiche le nom de la branche avec le nom de module.

`--list-optional-modules`

- Cette option force JHBuild à énumérer les dépendances facultatives.

### rdepends

La commande `rdepends` affiche les dépendances inverses d'un module.

    jhbuild rdepends
            module

`--dependencies`

- Affiche le chemin de dépendance à la suite des modules.

`--direct`

- Limite l'affichage aux modules dépendant directement du module indiqué.

### run

La commande `run` exécute la commande indiquée dans le même environnement que JHBuild utilise lors de la construction de modules.

    jhbuild run
            --in-builddir
            --in-checkoutdir
            program
            argument

En cas d'utilisation de JHBuild pour construire GNOME, cette commande est utile dans les scripts de démarrage de X.

`--in-builddir`=`module`

- Exécute la commande dans le répertoire de construction du module indiqué.

`--in-checkoutdir`=`module`

- Exécute la commande dans le répertoire source du module indiqué.

### sanitycheck

La commande `sanitycheck` effectue un certain nombre de contrôles pour vérifier que l'environnement de construction est correct.

    jhbuild sanitycheck

Ces contrôles vérifient notamment que :

- les préfixes d'extraction et d'installation sont accessibles en écriture ;

- les outils de construction indispensables sont installés ;

- certaines macros couramment utilisées sont disponibles dans les chemins de recherche des commandes `aclocal` associées aux différentes versions de `automake` ;

- le catalogue XML contient les DTD et feuilles de style DocBook.

### shell

La commande `shell` lance un shell utilisateur dans le même environnement que JHBuild lorsqu'il construit des modules.

    jhbuild shell

Cette commande est équivalente à ceci :

    $ jhbuild run $SHELL

La variable d'environnement `UNDER_JHBUILD` est définie à « true » (vrai) lorsque ce shell est actif. Vous pouvez utiliser la présence de cette variable pour personnaliser votre invite de commande afin d'indiquer que vous êtes dans un shell contrôlé par JHBuild. Par exemple, il est possible d'indiquer cela dans votre `.bashrc` :

    	if [ -n "$UNDER_JHBUILD" ]; then
    	    PS1="[jhbuild] $PS1"
    	fi

En conséquence, vous verrez apparaître la séquence `[jhbuild]` au début de votre invite de commande habituelle, ce qui rend plus évident la distinction entre un shell normal et un shell contrôlé par JHBuild.

### sysdeps

The `sysdeps` command displays a list of dependency modules that are provided by installed system packages. JHBuild will not build the modules from source if the configuration variable `partial_build` is `True`.

The `sysdeps` command also displays a list of dependency modules where the installed system packages are too old. JHBuild will build newer modules from source.

The `sysdeps` command also displays a list of dependency modules with no matching system package installed.

    jhbuild sysdeps
            --install

`--install`

- This option installs system packages which are dependencies of the moduleset. The system packages are installed using PackageKit.

#### `sysdeps` example

    $ jhbuild sysdeps
    System installed packages which are new enough:
      speex (required=1.2rc1, installed=1.2rc1)
      libdiscid (required=0.2.2, installed=0.2.2)
      telepathy-farsight (required=0.0.14, installed=0.0.16)
      lcms2 (required=2.2, installed=2.2)
    ...
    System installed packages which are too old:
      webkitgtk-3.0 (required=1.5.1, installed=1.4.0)
      ...
    No matching system package installed:
      libvala-0.14 (required=0.13.1)
      ...

### tinderbox

La commande `tinderbox` est semblable à la commande `build`, mais écrit toutes les sorties de terminal dans des fichiers HTML prêts à être publiés sur un site Web. Elle permet de mettre en place des systèmes tels que Mozilla Tinderbox ou Debian Buildd.

    jhbuild tinderbox
            --clean
            --no-network
            --output=directory
            --skip=module
            --start-at=module
            -D date
            -C
            -N
            -f
            module

The `--clean`, `--no-network`, `--skip`, `--start-at`, `-D`, `-C`, `-N` and `-f` options are processed as per the `build` command.

`-o`, `--output`=`répertoire`

- Le répertoire dans lequel écrire les fichiers HTML.

### uninstall

La commande `uninstall` désinstalle un ou plusieurs modules.

    jhbuild uninstall
            module

### update

La commande `update` est semblable à `build`, mais n'effectue que les étapes de téléchargement et de mise à jour des modules, sans les construire.

    jhbuild update
            --skip=module
            --start-at=module
            --tags=tags
            --ignore-suggests
            -D date
            module

Les options `--skip`, `--start-at`, `--tags`, `--ignore-suggests` et `-D` sont traitées de la même manière que pour la commande `build`.

### updateone

La commande `updateone` est semblable à `update`, mais elle ne met pas à jour les modules dépendants. Elle est utile pour mettre à jour un ou plusieurs modules.

    jhbuild updateone
            -D date
            module

L'option `-D` est traitée de la même manière que pour `build`.

Cette commande nécessite au minimum un module dans la ligne de commande.

## Référence du fichier de configuration

Le fichier `~/.jhbuildrc` utilise la syntaxe Python standard. Le fichier est exécuté et les variables résultantes définies dans l'espace de noms sont utilisées pour contrôler le comportement de JHBuild. Un ensemble de valeurs par défaut sont insérées dans l'espace de noms avant d'exécuter le fichier de configuration de l'utilisateur.

Les variables de configuration booléennes sont définies avec une syntaxe correspondant à l'exemple suivant :

    use_local_modulesets = True

Les variables de configuration « chaînes de caractères » sont définies avec une syntaxe correspondant à l'exemple suivant :

    autogenargs = '--disable-static --disable-gtk-doc'

Les variables de configuration contenant des listes sont définies avec une syntaxe correspondant à l'exemple suivant :

    skip = ['mozilla', 'pulseaudio']

Les variables de configuration contenant des dictionnaires sont définies avec une syntaxe correspondant à l'exemple suivant :

    repos['git.gnome.org'] = 'ssh://username@git.gnome.org/git/'

### Variables de configuration

`autogenargs`

- Une chaîne contenant des paramètres passés au script `autogen.sh` de tous les modules. Peut être surchargée par des modules précis en utilisant le dictionnaire `module_autogenargs`.

`branches`

- A dictionary specifying which branch to use for specific modules. This is useful if you are making some changes on a branch of a module and want JHBuild to build that branch instead of the one listed in the module set.

  La définition des branches dépend du gestionnaire de version du module :

  - CVS : révision. Par ex. `'BRANCH-PROJECT-0_8'`

  - Bazaar : URI de la branche du module. Par ex. `'http://bzr.example.net/project/gnome-2-28'`

  - Git : tuple dont la première partie est un dépôt (facultatif, peut contenir la valeur None) et la seconde partie le nom de la branche. Par ex. `('git://git.example.net/project', 'gnome-2-28')`

    #### Simple example

        branches['modulename'] = (None, 'branchname')

  - Subversion : URI de la branche du module. Par ex. `'svn://svn.example.net/project/gnome-2-28'`

`builddir_pattern`

- A `printf` style formatting pattern used to generate build directory names. This is only used when using separate source and build trees. The `%s` in the format string will be replaced with `checkoutdir`. Defaults to `'%s'`.

`buildroot`

- Une chaîne indiquant le répertoire parent contenant les arborescences de construction. La valeur par défaut est `None`, ce qui signifie que la construction s'effectue dans les arborescences source.

`buildscript`

- Une chaîne indiquant le script de construction à utiliser. La valeur recommandée est la valeur par défaut, `terminal`. En particulier, n'indiquez pas `gtk`.

`build_policy`

- A string specifying which modules to build. The three possible options are `all`, to build all modules requested, `updated` to build only modules which have changed, or `updated-deps` to build modules which have changed or which have dependencies which have changed. Defaults to `updated-deps`.

`checkoutroot`

- Une chaîne indiquant le répertoire dans lequel décompresser les arborescences source. À moins que `buildroot` ne soit défini, la construction s'opère également dans ce répertoire. La valeur par défaut est `~/checkout/gnome`.

`checkout_mode`

- Une chaîne indiquant la méthode d'extraction des répertoires dans la gestion de versions. La valeur par défaut est `update` (mise à jour). Cette valeur peut être définie pour chaque module avec `module_checkout_mode`. Les valeurs possibles sont : `update` (mettre à jour le répertoire extrait), `clobber` (effacer le répertoire avant d'extraire les sources), `export` (effacer le répertoire puis créer une copie non versionnée des sources) et `copy` (extraire dans un répertoire différent de celui où il sera construit).

`copy_dir`

- A string specifying the directory to copy to, if the copy `checkout_mode` is in use. Defaults to the checkout directory.

`cvs_program`

- Une chaîne indiquant le programme à utiliser pour la prise en charge de CVS. Cela peut être `git-cvsimport` ou `cvs`. La valeur par défaut est `cvs`.

`dvcs_mirror_dir`

- A string specifying a local mirror directory. JHBuild will create local mirrors of repositories at the specified directory. The mirrors can be shared by multiple repository groups, saving space and time because hard-links will be used for local clones. The commands `update` and `updateone` will create the mirrors and fetch new commits from the online repositories. This option is only supported by Git and Bazaar repositories.

`installprog`

- Une chaîne indiquant un programme à utiliser en remplacement de `/usr/bin/install`. Si présente, sa valeur par défaut correspond au script d'encapsulation `install-check` fourni par JHBuild. Ce script optimise l'installation des en-têtes afin de réduire le temps nécessaire aux recompilations.

`ignore_suggests`

- Une valeur booléenne indiquant s'il faut ignorer les dépendances faibles lors de la génération de l'arbre des dépendances. La valeur par défaut est `False`.

`interact`

- Une valeur booléenne indiquant si l'interaction avec l'utilisateur est autorisée. La définition de cette valeur à `False` équivaut à passer l'option `--no-interact` à JHBuild. La valeur par défaut est `True`.

`makeargs`

- Une chaîne énumérant des paramètres supplémentaires à passer à `make`. La valeur par défaut est `''`.

`makecheck`

- Une valeur booléenne indiquant s'il faut exécuter `make check` après `make`. La valeur par défaut est `False`.

`makecheck_advisory`

- Une valeur booléenne indiquant si les échecs d'exécution de la commande `make check` doivent être considérés comme des avertissements ou s'ils produisent un échec de la construction. La valeur par défaut est `False`.

`makeclean`

- Une valeur booléenne indiquant s'il faut exécuter `make clean` après `make`. La valeur par défaut est `False`.

`makedist`

- Une valeur booléenne indiquant s'il faut exécuter `make dist` après `make`. La valeur par défaut est `False`. Ce réglage équivaut à passer l'option `--dist` à JHBuild.

`makedistcheck`

- Une valeur booléenne indiquant s'il faut exécuter `make distcheck` après `make`. La valeur par défaut est `False`. Ce réglage équivaut à passer l'option `--distcheck` à JHBuild.

`module_autogenargs`

- Un dictionnaire faisant correspondre les noms de modules à des chaînes donnant des paramètres à passer à `autogen.sh`. Le paramètre dans `module_autogenargs` est utilisé à la place du paramètre global `autogenargs`. Si un module particulier n'est pas dans le dictionnaire, c'est le paramètre global `autogenargs` qui est utilisé.

`module_checkout_mode`

- Un dictionnaire indiquant le mode d'extraction à employer pour les modules. Ce paramètre écrase le paramètre global `checkout_mode`.

`module_makeargs`

- Un dictionnaire faisant correspondre les noms de modules à des chaînes indiquant les paramètres à passer à `make`. Le paramètre dans `module_makeargs` est utilisé à la place du paramètre global `makeargs`. Si un module particulier n'est pas dans le dictionnaire, c'est le paramètre global `makeargs` qui est utilisé.

`module_makecheck`

- Un dictionnaire faisant correspondre les noms de modules à des valeurs booléennes indiquant s'il faut exécuter `make check` après `make`. Le paramètre dans `module_makecheck` remplace la valeur de `makecheck`. Si un module particulier n'est pas dans le dictionnaire, c'est le paramètre global `makecheck` qui est utilisé.

`module_nopoison`

- Un dictionnaire faisant correspondre les noms de modules à des valeurs booléennes. Si la valeur pour un module vaut `True`, JHBuild essaye de construire les modules dépendants même si le module indiqué échoue. Le paramètre dans `module_nopoison` remplace la valeur de `nopoison`. Si un module particulier n'est pas dans le dictionnaire, c'est le paramètre global `nopoisons` qui est utilisé.

`module_extra_env`

- Un dictionnaire faisant correspondre les noms de modules à des dictionnaires contenant des variables d'environnement supplémentaires à passer lors de l'exécution de commandes pour le module.

`modules`

- A list of strings specifying the modules to build. The list of modules actually built will be recursively expanded to include all the dependencies unless the `buildone` command is used. Defaults to `['meta-gnome-desktop']`.

`moduleset`

- Une chaîne ou une liste de chaînes indiquant le ou les noms des jeux de modules à utiliser. Cela peut être le nom de fichier d'un jeu de modules inclus dans JHBuild (sans chemin ni extension) ou un URL HTTP complet d'un jeu de modules géré en externe. Les jeux de modules ayant un URL HTTP sont placés dans un cache local. Si le nom d'un module figure dans plus d'un jeu de modules, le dernier jeu de modules dans la liste est prioritaire. Les jeux de modules fournis avec JHBuild sont mis à jour au gré de la progression du développement de GNOME.

`modulesets_dir`

- Une chaîne indiquant le répertoire contenant les jeux de modules à utiliser. Par défaut, c'est le répertoire `modulesets/` dans les sources de JHBuild.

`nice_build`

- Run builds under the `SCHED_IDLE` priority on Linux, `nice` on other Unix. This can dramatically improve desktop interactivity for parallel builds while having only a negligible impact on build throughput.

`nobuild`

- Une valeur booléenne qui si elle est définie à `True` indique à JHBuild de ne pas construire les modules, mais uniquement de les télécharger et de décompresser les sources. La valeur par défaut est `False`.

`nonetwork`

- Une valeur booléenne indiquant si l'accès au réseau est autorisé. Cela affecte l'extraction ou la mise à jour de modules CVS, le téléchargement d'archives tar et la mise à jour des jeux de modules. Définir cette valeur à `True` équivaut à passer l'option `--no-network`. La valeur par défaut est `False`.

`nonotify`

- A boolean value specifying whether to emit notifications using the notification daemon. If set to `False`, notifications are emitted. Defaults to `True`.

`nopoison`

- Une valeur booléenne qui, si elle est définie à `True`, indique à JHBuild d'essayer la construction des modules même si la construction d'une ou de plusieurs dépendances a échoué. Cette option est équivalente au paramètre `--no-poison`. La valeur par défaut est `False`.

`notrayicon`

- A boolean value specifying whether to show an icon in the system tray using Zenity. If set to `False`, notifications are emitted. Defaults to `True`.

`noxvfb`

- Une valeur booléenne qui, si elle est définie à `True`, indique à JHBuild d'exécuter tout test graphique avec le serveur X réel au lieu d'utiliser `Xvfb`. Cette option est équivalente au paramètre `--no-xfvb`. La valeur par défaut est `False`.

`partial_build`

- A boolean value, if set to `True` JHBuild will not build dependency modules if corresponding system packages are installed and sufficient version. Defaults to `True`.

`prefix`

- A string specifying the prefix to install modules to. `prefix` must be an absolute path. This directory must be writable. Defaults to `'/opt/gnome'`.

`pretty_print`

- Une valeur booléenne indiquant s'il s'agit d'améliorer la mise en forme de la sortie des sous-processus. Seules les sorties CVS gèrent la mise en forme améliorée. Cette option peut être désactivée si la mise en forme améliorée pose des problèmes. La valeur par défaut est `True`.

`print_command_pattern`

- A string displayed before JHBuild executes a command. `%(command)s` in the string will be replaced with the command about to be executed. `%(cwd)s` in the string will be replaced with the current working directory. Defaults to `'%(command)s'`.

`progress_bar`

- Une valeur booléenne indiquant s'il faut afficher une barre de progression lorsque JHBuild fonctionne en mode silencieux. La valeur par défaut est `True`.

`quiet_mode`

- Une valeur booléenne. Si définie à `True`, elle désactive la sortie des commandes qui s'exécutent. La valeur par défaut est `False`.

`repos`

- Un dictionnaire indiquant un emplacement de dépôt alternatif pour un dépôt spécifique. Cette variable de configuration est utile aux développeurs de modules. Par défaut, JHBuild extrait le code à partir des dépôts en utilisant des emplacements anonymes. Les clés du dictionnaire sont des noms de dépôts courts et les valeurs sont des chaînes d'emplacement des dépôts alternatifs. Par exemple :

      repos['git.gnome.org'] = 'ssh://username@git.gnome.org/git/'

`skip`

- Une liste de modules à ignorer. L'option de ligne de commande `--skip` étend cette liste. Par défaut, cette liste est vide.

`sticky_date`

- Une chaîne de caractères. Si définie et si le gestionnaire de versions sous-jacent le prend en charge, JHBuild met à jour l'arborescence source selon son état à la date indiquée. La date doit être fournie au format ISO, par ex. `'`aaaa`-`mm`-`jj`'`. La valeur par défaut est `None`.

`svn_program`

- Une chaîne indiquant le programme à utiliser pour la prise en charge de Subversion. Cela peut être `svn`, `git-svn` ou `bzr`. La valeur par défaut est `svn`.

`tarballdir`

- Une chaîne de caractères ; si définie, les archives tar sont téléchargées dans ce répertoire au lieu de `checkoutroot`. C'est utile si vous avez plusieurs environnements JHBuild ou que vous nettoyez régulièrement `checkoutroot` et que vous souhaitez restreindre la consommation de bande passante.

`tinderbox_outputdir`

- Une chaîne indiquant le répertoire de stockage de la sortie de `jhbuild tinderbox`. Cette chaîne peut être remplacée par l'option `--output`. La valeur par défaut est `None`, ce qui signifie qu'il faut obligatoirement définir cette option soit dans la ligne de commande, soit dans le fichier de configuration.

`trycheckout`

- Une option booléenne qui, si elle est définie à `True`, indique à JHBuild d'essayer de résoudre automatiquement les échecs en 1) exécutant une nouvelle fois `autogen.sh` et 2) extrayant une nouvelle version du module à partir du contrôle de version. Ce paramètre équivaut à passer l'option `--try-checkout`.

`use_lib64`

- Une valeur booléenne qui indique s'il faut installer les bibliothèques dans les répertoires `lib64`. Lorsque c'est le cas, `--libdir=\${exec_prefix}/lib64` est transmis à « configure ». Lorsque JHBuild fonctionne sur un système Linux `x86_64`, `ppc64` ou `s390x`, cette valeur vaut `True` par défaut, sinon elle est définie à `False`.

`use_local_modulesets`

- Une valeur booléenne indiquant d'utiliser des jeux de modules qui ont été extraits parallèlement au code source de JHBuild, au lieu de les télécharger au fur et à mesure, à partir du dépôt du gestionnaire de versions de GNOME. La valeur par défaut est `False`.

`xvfbargs`

- Une chaîne contenant des paramètres à passer à `Xvfb` si des tests graphiques sont effectués.

### Autres structures du fichier de configuration

En plus des variables ci-dessus, d'autres paramètres peuvent être définis dans le fichier de configuration :

`os.environ`

- Un dictionnaire représentant l'environnement. Cet environnement est transmis aux processus générés par JHBuild.

  Certaines variables d'environnement ont un impact certain, comme `CPPFLAGS`, `CFLAGS`, `INSTALL` et `LDFLAGS`. Par exemple :

      os.environ['CFLAGS'] = '-O0 -g'

`addpath`(`var_env`, `chemin`)

- Cela ajoute un répertoire à la variable d'environnement `PATH` (chemin). `addpath` gère correctement le cas où la variable d'environnement est initialement vide (un deux-points isolé au début ou à la fin d'une variable d'environnement peut avoir des conséquences inattendues).

  `addpath` prend en charge de manière particulière la variable d'environnement `ACLOCAL_FLAGS` dont la liste de chemins doit être de la forme `-I `chemin``.

`prependpath`(`var_env`, `chemin`)

- Après le traitement du fichier de configuration, JHBuild modifie certains chemins sur la base de variables telles que `prefix` (par ex. en ajoutant `$prefix/bin` au début de la variable `PATH`).

  La fonction `prependpath` fonctionne comme `addpath`, sauf que la variable d'environnement est modifiée après que JHBuild ait modifié l'environnement.

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

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

The `type` attribute specifies the type of repository. It can be one of: `bzr`, `cvs`, `darcs`, `fossil`, `git`, `hg`, `mnt`, `svn`, `tarball`. Other attributes depend on the `type`, as well as the `branch` used inside module definitions. Those are described below in the repository type sub-sections.

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

#### 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"/>

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

#### 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/"/>

#### 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"/>

#### 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"/>

#### 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"/>

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

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

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

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

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

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

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

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

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

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

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

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

### Éléments désapprouvés

#### Sources de module

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

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

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

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