# JHBuild-Handbuch

## Einführung

JHBuild ist ein Werkzeug zur Vereinfachung der Erstellung aus einer Sammlung von Quellpaketen (auch als »Module« bekannt). Es kommt ein »Modulsatz« zum Einsatz, in welchem die zu erstellenden Module beschrieben werden. Diese Dateien enthalten Abhängigkeitsinformationen, aus welchen JHBuild erfährt, was und in welcher Reihenfolge der Benutzer erstellen will.

JHBuild wurde ursprünglich zur Erstellung von GNOME entwickelt, aber im Laufe der Zeit erweitert, um es für andere Projekte nutzbar zu machen. Eine »Modulsatz-Datei« kann auf einem Webserver abrufbar gehalten werden, wodurch es möglich ist, unabhängig von JHBuild den Benutzern Erstellungsregeln bereitzustellen.

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, Meson, WAF, Python Distutils and Perl Makefiles.

JHBuild ist nicht dazu bestimmt, das Paketverwaltungssystem Ihrer Distribution zu ersetzen. Es vereinfacht lediglich, alles in einem separaten Installationspräfix zu erstellen, so dass das übrige System nicht beeinflusst wird.

## Erste Schritte

JHBuild erfordert einige Konfigurationsschritte, bevor Software erstellt werden kann. JHBuild hat einige Abhängigkeiten, und es ist nötig, einige Werkzeuge zu installieren, um Softwaremodule zu erhalten und zu erstellen.

### Installieren von JHBuild

JHBuild benötigt eine Python-Laufzeitumgebung. Stellen Sie sicher, dass Python >= 2.3 installiert ist.

Der empfohlene Weg zum Herunterladen von JHBuild führt über das Versionsverwaltungssystem `git`. Dieses erreichen Sie mit dem folgenden Befehl. Es ist empfehlenswert, den Befehl in einem neuen Ordner auszuführen, in welchem der Quellcode installiert wird, beispielsweise `~/jhbuild/checkout`.

    $ git clone https://gitlab.gnome.org/GNOME/jhbuild.git
    ...
    $

Dadurch wird JHBuild in einen neuen Ordner namens `jhbuild` unterhalb des aktuellen Ordners heruntergeladen. Nun können Sie JHBuild erstellen und installieren:

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

Wenn gnome-common, yelp-tools und autotools verfügbar sind, so wird `autogen.sh` JHBuild anweisen mit autotools zu installieren. Wenn gnome-common, yelp-tools und autotools nicht verfügbar sind, so wird `autogen.sh` JHBuild anweisen, mit einem Makefile zu installieren. Um immer die Methode mit Makefile zu verwenden, verwenden Sie die Option `--simple-install` für `autogen.sh`.

Falls die oben genannten Schritte erfolgreich verlaufen, wird in `~/.local/bin` ein kleines Shell-Skript installiert, welches JHBuild startet. Fügen Sie `~/.local/bin` zur Variable `PATH` hinzu:

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

Um `~/.local/bin` dauerhaft zur Variable `PATH` hinzuzufügen, führen Sie folgenden Befehl aus:

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

### Konfigurieren von JHBuild

JHBuild wird über eine Konfigurationsdatei eingerichtet. Die Datei befindet sich normalerweise unter `~/config/.jhbuildrc`. Wenn keine Datei vorhanden ist, so werden die Voreinstellungen verwendet. Die Datei nutzt die Python-Syntax zum Festlegen der Konfigurationsvariablen. Ein Beispiel ist im Ordner `examples/sample.jhbuildrc`. Kopieren Sie `examples/sample.jhbuildrc` nach `~/.config/.jhbuildrc` und passen Sie die Datei nach Ihren Wünschen an.

Mit der Beispielkonfiguration erstellt JHBuild die Module meta-gnome-desktop und meta-gnome-apps-tested sowie deren Abhängigkeiten aus dem Modulsatz `gnome-apps`. JHBuild entpackt die Quellbäume nach `~/jhbuild/checkout/` und installiert alle Dateien in Unterordner von `~/jhbuild/install/`. Für diese zwei Ordner müssen Schreibrechte vorhanden sein.

Konfigurationsvariablen sind in config-reference dokumentiert. Einige der am häufigsten verwendeten Variablen sind:

`repos`

- A dictionary that can be used to specify an alternative repository location for a particular repository. This configuration variable is useful to a module developer. By default, JHBuild will check out code from repositories using an anonymous repository location. The dictionary keys are short repository names and the values are alternative repository location strings. For example:

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

`moduleset`

- A string or list of strings specifying the name(s) of the module set(s) to use. This can either be the filename of a moduleset included with JHBuild (excluding the path and extension), or a full HTTP URL to an externally managed moduleset. HTTP URL modulesets are cached locally. If a module with the same name is present in more than one moduleset, the last set listed takes priority. Modulesets provided with JHBuild are updated to match the current GNOME development release.

`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. If `buildroot` is set to `None`, builds will occur in this directory too. Defaults to `~/jhbuild/checkout`.

`prefix`

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

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

`cmakeargs`

- A string containing arguments passed to the `cmake` invocation of all modules. Can be overridden for particular modules using the `module_cmakeargs` dictionary.

`makeargs`

- A string listing additional arguments to be passed to `make`. JHBuild will automatically append the parallel execution option (`-j`) based upon available CPU cores. Defaults to `''`.

`mesonargs`

- A string containing arguments passed to the `meson` invocation of all modules. Can be overridden for particular modules using the `module_mesonargs` dictionary.

`ninjaargs`

- A string listing additional arguments to be passed to `ninja`. Defaults to `''`.

### Voraussetzungen zur Erstellung

Bevor irgendwelche Module erstellt werden können, müssen zunächst verschiedenen Erstellungswerkzeuge installiert sein. Diese umfassen die GNU Autotools (autoconf, automake, libtool und gettext), die GNU Toolchain (binutils, gcc, g++), make, pkg-config und Python, je nachdem, welche Module erstellt werden sollen.

JHBuild kann das Vorhandensein dieser Werkzeuge mit dem Befehl `sanitycheck` überprüfen:

    $ jhbuild sanitycheck

Wenn dieser Befehl eine Meldung ausgibt, dann installieren Sie bitte das benötigte Paket aus dem Softwarebestand Ihrer Distribution. Eine Liste von Paketnamen für verschiedene Distributionen finden Sie im GNOME-Wiki. Führen Sie den Befehl `sanitycheck` nach der Installation der Distributionspakete erneut aus, um sicherzustellen, dass die benötigten Werkzeuge vorhanden sind.

### Verwendung von JHBuild

Nachdem die Einrichtung abgeschlossen ist, kann JHBuild zum Erstellen von Software verwendet werden. Führen Sie zum Erstellen aller in der Datei `~/.config/jhbuildrc` ausgewählten Module den folgenden Befehl aus:

    $ jhbuild build

JHBuild lädt jedes der Module herunter, konfiguriert, kompiliert und installiert es. Falls in einer der Stufen Fehler auftreten, öffnet JHBuild ein Menü, um nach der weiteren Vorgehensweise zu fragen. Die Auswahl umfasst die Weiterleitung in eine Shell zum Beheben des Fehlers, die erneute Ausführung aus verschiedenen Stufen, Aufgeben oder Ignorieren des Fehlers und Fortsetzen.

Das Aufgeben eines Moduls wirkt sich auf die davon abhängigen Module aus, wodurch deren Erstellung scheitert.

Es folgt ein Beispiel des angezeigten Menüs:

      [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:

Es ist auch möglich, einen Modulsatz und dessen Abhängigkeiten zu erstellen, indem Sie die Modulnamen als Argumente an den `build`-Befehl übergeben. So erstellen Sie beispielsweise gtk+:

    $ jhbuild build gtk+

If JHBuild is cancelled part way through a build, it is possible to resume the build at a particular module using the `--start-at` option:

    $ jhbuild build --start-at=pango

To build one or more modules, ignoring their dependencies, JHBuild provides the `buildone` command. For the `buildone` command to complete successfully, all dependencies must be previously built and installed or provided by distribution packages.

    $ 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

To get a list of the modules and dependencies JHBuild will build, and the order they will be built, use the `list` command:

    $ jhbuild list

Um Informationen über ein bestimmtes Modul anzuzeigen, verwenden Sie den Befehl `info`:

    $ jhbuild info gtk+

To download or update all the software sources without building, use the `update` command. The `update` command provides an opportunity to modify the sources before building and can be useful if internet bandwidth varies.

    $ jhbuild update

Später kann JHBuild alles ohne Herunterladen oder Aktualisieren der Quellen erstellen:

    $ jhbuild build --no-network

Um einen Befehl in der auch von JHBuild genutzten Umgebung auszuführen, benutzen Sie den `run`-Befehl:

    $ jhbuild run program

Um eine Shell in der auch von JHBuild genutzten Umgebung auszuführen, benutzen Sie den `shell`-Befehl:

    $ jhbuild shell

## JHBuild und GNOME

This section provides guidance on building, installing and running GNOME.

### GNOME erstellen

Um GNOME zu erstellen, werden einige Entwicklerpakete benötigt. Diese sind:

- XML-DTD und XSLT-Stilvorlagen von DocBook. Diese müssen im XML-Katalog registriert sein (`/etc/xml/catalog`).

- X libraries.

- `libsmbclient` aus Samba (wird zum Durchsuchen von Windows-Netzwerken verwendet).

- `libbz2` aus bzip2.

- `libpng`, `libjpeg` und `libtiff` (verwendet zum Laden von Bildern).

If installing distribution packages, and if applicable for your distribution, install the corresponding dev or devel packages. A list of package names for different distributions is maintained on the GNOME wiki.

### Ausführung einer einzelnen GNOME-Anwendung

This section details how to run a single GNOME application. The application will run within the current desktop environment. To run the application within the complete JHBuild GNOME see running-gnome.

Starten Sie eine JHBuild-Shell. In der JHBuild-Shell sind bereits alle nötigen Umgebungsvariablen gesetzt.

    $ jhbuild shell

Überprüfen Sie, ob die richtige Anwendung ausgeführt wird. Zum Beispiel:

    $ which gedit
    /home/wanda/jhbuild/install/bin/gedit

Die Anwendung ausführen:

    $ gedit &

Alternativ rufen Sie die Anwendung dem Befehl `run` auf:

    $ jhbuild run gedit

### Ausführung der GNOME-Arbeitsumgebung

Create a new user account to run the JHBuild GNOME. Running JHBuild GNOME using a different user account is recommended to avoid problems caused by user settings stored in the home directory. This manual refers to the new account as `gnomedev`.

Setup JHBuild on the new `gnomedev` account. Copy or soft-link `~/.config/jhbuildrc` and `~/.local/bin/jhbuild` to `gnomedev` home directory.

Öffnen Sie ein Terminal als Benutzer `gnomedev`. Fügen Sie `~/.local/bin` dauerhaft zur Variable `PATH` hinzu, führen Sie folgenden Befehl aus:

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

Testen Sie, ob JHBuild funktioniert:

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

#### GNOME für den Start über das Anmeldefenster einrichten

Erstellen und installieren Sie JHBuild GNOME.

Enable system services. JHBuild GNOME will use the `/usr/bin` system D-Bus daemon and the system services within `/usr/share/dbus-1/system-services/`. JHBuild GNOME will use the JHBuild session D-Bus daemon and the services within ``~/jhbuild/install/`/share/dbus-1/services/`. Replace `~/jhbuild/install` with GNOME install `prefix` in the command below:

    $ rm -rf ~/jhbuild/install/var/run/dbus
    $ ln -s /var/run/dbus ~/jhbuild/install/var/run/dbus
    $ rm -rf ~/jhbuild/install/var/lib/dbus/machine-id
    $ ln -s /var/lib/dbus/machine-id ~/jhbuild/install/var/lib/dbus/machine-id

Create a GNOME startup script at `/usr/bin/gnome-jhbuild-session` with the following, replacing `~/jhbuild/install` with GNOME install `prefix`:

    #!/bin/sh

    GNOME=~/jhbuild/install

    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

Machen Sie die Datei `/usr/bin/gnome-jhbuild-session` ausführbar:

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

Um einen neuen Sitzungseintrag für das Anmeldefenster anzulegen, erstellen Sie die Datei `/usr/share/xsessions/gnome-jhbuild.desktop` und geben Sie ein:

    [Desktop Entry]
    Name=GNOME (JHBuild)
    Comment=This session logs you into GNOME testing session
    TryExec=/usr/bin/gnome-jhbuild-session
    Exec=/usr/bin/gnome-jhbuild-session
    Icon=
    Type=Application

Starten Sie `gdm` neu.

#### GNOME über das Anmeldefenster ausführen

To run the JHBuild GNOME, select the GNOME (JHBuild) session at the display manager before entering `gnomedev` login credentials. If successful, JHBuild GNOME will be displayed. If unsuccessful, check the log file. The log file will be located at `~gnomedev/.cache/gdm/session.log` or `~gnomedev/.xsession-errors`.

### Statische Analysen

JHBuild supports running static analysis tools on the code in modules as they’re built. To enable this, set the `static_analyzer` configuration variable to `True` in the `.jhbuildrc` configuration file.

If enabled, every time a module is built using JHBuild, the build process will be wrapped in a static analyzer, which will generate a report of any problems it finds with the code. These reports are saved as HTML files in subdirectories of `/tmp/jhbuild_static_analyzer` (by default; the path can be changed using the `static_analyzer_outputdir` configuration variable).

Static analysis currently only works for modules which use autotools as their build system. It requires the `scan-build` program to be installed, although the command it uses can be changed by modifying the `static_analyzer_template` configuration variable.

## Integration von Buildbot

Coupled with the Buildbot project, JHBuild can also function as a continuous integration tool. The Buildbot configuration is used by the GNOME project at build.gnome.org.

### Konfigurieren eines Buildbot-Slaves

A Buildbot slave is a variation of a normal JHBuild installation that serves the requests of a Buildbot master. It is recommended to set up JHBuild and complete a build with most modules building successfully before adding the Buildbot customizations.

Buildbot-Befehle sind Optionen des `bot`-Befehls. Um die zusätzlich benötigte Software herunterzuladen und zu installieren, führen Sie den folgenden Befehl aus:

    $ jhbuild bot --setup

Sobald dieser Schritt erfolgreich abgeschlossen ist, sind drei neue Konfigurationsvariablen in der Datei `~/.config/jhbuildrc` erforderlich.

Es ist nicht möglich, eine alternative Konfigurationsdatei zu verwenden, die Option `--file` wird nicht die gewünschten Effekte erzielen.

    jhbuildbot_master = 'build.gnome.org:9070'
    jhbuildbot_slavename = 'slavename'
    jhbuildbot_password = 'password'

`jhbuildbot_master` is a string specifying the Buildbot master server; it defaults to `'build.gnome.org:9070'`. `jhbuildbot_slavename` and `jhbuildbot_password` identify the slave on the master server. Contact the Buildbot master administrators to obtain the slave name and password.

Die Verwalter von build.gnome.org sind über die Mailingliste der Build Brigade erreichbar.

## Befehlsreferenz

JHBuild verwendet eine Befehlszeilensyntax ähnlich wie in Werkzeugen wie CVS:

    jhbuild global-options command command-arguments

Folgende globale Optionen stehen für JHBuild zur Verfügung:

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

- Eine alternative Konfiguration anstelle der vorgegebenen `~/.config/jhbuildrc` verwenden.

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

- Use a module set other than the module set listed in the configuration file. This option can be a relative path if the module set is located in the JHBuild moduleset folder, or an absolute path if located elsewhere.

`--no-interact`

- Do not prompt the user for any input. This option is useful if leaving a build unattended, in order to ensure the build is not interrupted.

`--exit-on-error`

- Exit immediately if a module fails to build. This option is primarily useful in noninteractive mode, in order to ensure jhbuild does not continue to build any additional modules.

`--conditions`

- Modify the condition flags to be different than those determined on the basis of the OS and those specified in jhbuildrc. Modifications are specified like `-wayland` or `+docs` in order to remove or add conditions. Multiple modifications can be separated by a comma like `--conditions=+docs,-wayland` or you can split them across multiple `--conditions` arguments.

Additionally, JHBuild checks the presence, and value, of the following environment variables:

`JHBUILD_RUN_AS_ROOT`

- By default, JHBuild does not run when using the root user, to avoid destructive operations that may affect the whole system. In certain cases, though, it's acceptable to run JHBuild as root; for instance, inside a container, or in a continuous integration environment. Exporting the `JHBUILD_RUN_AS_ROOT` will disable the user id check at startup.

Befehlsspezifische Optionen werden nachstehend aufgelistet.

### autobuild

Der Befehl `autobuild` erstellt automatisch die in der Konfigurationsdatei angegebenen Module und überträgt die Ergebnisse zu JHAutobuild.

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

Die Optionen `--autogen`, `--clean`, `--distcheck`, `--skip` und `--start-at` werden ebenso wie der Befehl `build` verarbeitet.

`--report-url=`reporturl``, `-r `Berichtsadresse``

- Diese Option legt die Adresse für Berichte an JHAutobuild fest.

`--verbose`, `-v`

- Falls angegeben, sind die Ausgaben von JHBuild ausführlicher.

### bootstrap

The `bootstrap` command installs a set of build utilities. The build utilities include autoconf, automake and similar utilities. The recommended method to install the build utilities is via your distribution's package management system. The `bootstrap` should only be used if the build utilities are not provided by your distribution's package management system, for example on `Mac OS`.

    jhbuild bootstrap

The `bootstrap` command builds modules using the same method as the `build` command, but uses the `bootstrap.modules` moduleset.

Die verfügbaren Optionen finden Sie in der Dokumentation zu `build`.

### build

Der Befehl `build` erstellt ein oder mehrere Pakete einschließlich deren Abhängigkeiten.

    jhbuild build --autogen --clean --check --dist --distcheck --distclean --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 --nodeps module

Falls keine Modulnamen auf der Befehlszeile übergeben werden, wird die Modulliste aus der Konfigurationsdatei verwendet.

`-a`, `--autogen`

- `autogen.sh` immer vor der Erstellung von Modulen ausführen.

`-c`, `--clean`

- `make clean` vor der Erstellung von Modulen ausführen.

`--check`

- `make check` nach der Erstellung von Modulen ausführen.

`-d`, `--dist`

- `make dist` nach der Erstellung von Modulen ausführen.

`--distcheck`

- `make distcheck` nach der Erstellung von Modulen ausführen.

`--distclean`

- For git modules, run `git clean -dfx` before building modules. For other modules, run `make distclean` before building modules.

  This option will delete any uncommitted changes.

`--ignore-suggests`

- Keine weichen Abhängigkeiten erstellen.

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

- Beim Erstellen von Modulen nicht auf das Netzwerk zugreifen. Dadurch werden Download- oder Aktualisierungsschritte in einer Erstellung übersprungen. Falls das Modul ohne Netzwerkzugriff nicht erstellt werden kann, wird die Erstellung des Moduls scheitern.

`-s`, `--skip`=`Modul,…`

- Die aufgelisteten Module nicht erstellen. Wird benutzt, um die Erstellung spezifischer Abhängigkeiten zu überspringen.

`--tags`=`Tag, …`

- Ignore modules that do not match `tag`. Modules are automatically attributed a tag matching the name of the module's module set.

`-t`, `--start-at`=`Modul`

- Beim genannten Modul anstatt am Beginn der Liste starten. Diese Option ist sinnvoll, wenn die Erstellung zuvor unterbrochen wurde.

`-D` `Datum`

- If supported by the underlying version control system, update the source tree to the specified date before building. An ISO date format is required, e.g. `"2009-09-18 02:32Z"`.

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

- Grafiktests im eigentlichen X-Server anstelle des simulierten Xvfb ausführen.

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

- If the build fails, and if supported by the version control system, force a checkout and run `autogen.sh` before retrying the build.

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

- Falls die Abhängigkeiten eines oder mehrerer Module scheitern, erzwingt dies die Erstellung des Moduls durch JHBuild.

`-f`, `--force`

- Das Modul erstellen, auch wenn die Regeln es als nicht erforderlich ansehen.

`--build-optional-modules`

- Einige als optionale Abhängigkeiten aufgelistete Module sind nicht für die Erstellung des Zielmoduls notwendig. Diese Option zwingt JHBuild, diese Module trotzdem einzuschließen.

`--min-age`=`Zeit`

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

`--nodeps`

- Ignore missing system dependencies. To ignore a single system dependency add the module to `skip`.

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

Die verfügbaren Optionen sind die gleichen wie für den Befehl `buildone`.

### buildone

Der Befehl `buildone` arbeitet ähnlich wie `build`, erstellt jedoch keine abhängigen Module. Dies ist nützlich für das erneute Erstellen eines oder mehrerer Module.

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

Die Optionen `--autogen`, `--check`, `--clean`, `-d`, `--distcheck`, `--distclean`, `--no-network` `-D`, `-x` und `--nodeps` werden ebenso wie für `build` verarbeitet.

In der Befehlszeile muss mindestens ein Modul angegeben werden.

### checkbranches

The `checkbranches` checks the module's branches are defined correctly within the version control system and the branches are consistent with the module set.

    jhbuild checkbranches --branch=branch

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

- Der auszucheckende Zweig.

    $ jhbuild -m gnome-2.20 checkbranches
    libgnomecanvas fehlen Zweigdefinitionen für gnome-2-20
    $

### clean

Der Befehl `clean` leert die Erstellungsordner von einem oder mehreren Modulen.

    jhbuild clean --skip=Modul --start-at=Modul

Falls keine Modulnamen auf der Befehlszeile übergeben werden, wird die Modulliste aus der Konfigurationsdatei verwendet.

In der Dokumentation zum Befehl `build` finden Sie eine Beschreibung der verfügbaren Optionen.

### dot

The `dot` command generates a file describing the directed graph formed by the dependencies between a set of modules. This file can then be processed using the GraphViz software to produce a diagram.

    jhbuild dot --soft-deps --clusters module

Falls keine Modulnamen auf der Befehlszeile übergeben werden, wird die Modulliste aus der Konfigurationsdatei verwendet.

The `--soft-deps` option adds dotted lines from the modules to the soft dependencies. The `--clusters` option groups modules from metamodules together.

Die Ausgabe dieses Befehls kann leicht zum Befehl `dot` weitergeleitet werden, um eine PostScript-Datei zu erstellen:

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

Oder ein PNG-Bild:

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

#### Beispielausgabe von dot in JHBuild

### gui

Der Befehl `gui` startet eine grafische Oberfläche für JHBuild, in welcher Module ausgewählt und einige Optionen angepasst werden können.

    jhbuild gui

Die erzeugte grafische Oberfläche benötigt GTK zur Darstellung, so dass einige unterstützende Bibliotheken erforderlich sein werden.

### info

Der Befehl `info` wird dazu verwendet, um Informationen über ein oder mehrere Module anzuzeigen.

    jhbuild info --installed module

Der Befehl gibt den Modulnamen, den Typ, die Abhängigkeiten, die davon abhängenden Pakete, den Quellordner und die Zeit der letzten Erstellung mit JHBuild aus. Falls verfügbar, können außerdem Informationen bezüglich des Modultyps ausgegeben werden, wie den CVS-Softwarebestand oder die Downloadadresse.

Falls kein Modul angegeben wird, dann werden Informationen über alle im Modulsatz definierten Module ausgegeben.

If the `--installed` option is specified, the output will be filtered to include only installed packages. This resulting output only contains modules that were actually built and installed by jhbuild. The output does not include system dependencies.

If the `--installed` option is specified together with one or more module names, then only the installed modules (not including system dependencies) are printed out. If at least one module is not installed, then the command will exit with a return value of 1.

### list

The `list` command displays the expanded list of modules the `build` command would build.

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

Falls keine Modulnamen auf der Befehlszeile übergeben werden, wird die Modulliste aus der Konfigurationsdatei verwendet.

Die Optionen `--skip`, `--start-at`, `--tags` und `--ignore-suggests` werden ebenso wie für `build` verarbeitet.

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

- List all the modules from the module set regardless of the build dependencies.

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

- If a module is set to a branch, show the branch name with the module name.

`--list-optional-modules`

- Diese Option zwingt JHBuild, optionale Abhängigkeiten aufzulisten.

### rdepends

Der Befehl `rdepends` zeigt die rekursiven Abhängigkeiten eines Moduls an.

    jhbuild rdepends Modul

`--dependencies`

- Zeigt den Abhängigkeitspfad neben den Modulen an.

`--direct`

- Limit display to modules directly depending on specified module.

### run

The `run` command runs the specified command using the same environment that JHBuild uses when building modules.

    jhbuild run --in-builddir --in-checkoutdir Program Argument

Falls Sie JHBuild zur Erstellung von GNOME verwenden, kann dieser Befehl in X-Startskripten nützlich sein.

`--in-builddir`=`Modul`

- Führen Sie den Befehl im Erstellungesordner des angegebenen Moduls aus.

`--in-checkoutdir`=`Modul`

- Führen Sie den Befehl im Quellordner des angegebenen Moduls aus.

### sanitycheck

Der Befehl `sanitycheck` nimmt eine Reihe von Überprüfungen vor, um die Vollständigkeit der Erstellungsumgebung zu gewährleisten.

    jhbuild sanitycheck

Beispielsweise wird Folgendes überprüft:

- Ob die Präfixes für Checkout und Installation schreibbar sind.

- Ob die benötigten Erstellungswerkzeuge installiert sind.

- Ob einige häufig verwendete Makros in den Suchpfaden der den verschiedenen Versionen von `automake` zugeordneten `aclocal`-Befehle vorhanden sind.

- Ob der XML-Katalog die DocBook-DTD und die Stilvorlagen enthält.

### shell

The `shell` command starts the user's shell with the same environment as JHBuild uses when building modules.

    jhbuild shell

Dieser Befehl entspricht dem Folgenden:

    $ jhbuild run $SHELL

The `UNDER_JHBUILD` environment variable will be set to "true" when this shell is active. You can use the presence of that variable to customize your shell's prompt to indicate that you indeed are under a jhbuild-controlled shell. For example, you may want to put this in your `.bashrc`:

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

This will make your bash shell display `[jhbuild]` before your normal prompt, making it easier to see which shells are under a jhbuild environment.

### sysdeps

Der Befehl `sysdeps` zeigt Folgendes an:

1. a list of installed system packages which will be used during the build. JHBuild will not build these modules and opt to use the system package instead.

2. a list of required packages. To begin a build the packages must be provided by your system.

3. a list of optional packages. The corresponding system package was not found or too old. JHBuild will build the module. Optional packages will not be displayed if `partial_build` is `False`.

    jhbuild sysdeps --install

`--install`

- This option installs system packages which are dependencies of the moduleset. The installation method depends on your distribution. System packages are installed using PackageKit, if available. For distributions using APT such as `Debian` and `Ubuntu`, this option requires apt-file to be installed.

#### `sysdeps` example

    $ jhbuild sysdeps
    System installed packages which are new enough:
      speex (speex.pc required=1.2rc1, installed=1.2rc1)
      lcms2 (lcms2.pc required=2.2, installed=2.2)
    ...
    Required packages:
      System installed packages which are too old:
        (none)
      No matching system package installed:
        zlib (zlib.pc required=1.2)
    Optional packages: (JHBuild will build the missing packages)
      System installed packages which are too old:
        WebKit (webkitgtk-3.0.pc required=1.5.1, installed=1.4.0)
        ...
      No matching system package installed:
        pulseaudio (libpulse.pc required=2.0)
        ...

### tinderbox

The `tinderbox` command is similar to `build`, but writes all terminal output to HTML files suitable for publishing on a website. It can be used to set up systems similar to Mozilla's Tinderbox, or Debian's Buildd.

    jhbuild tinderbox --autogen --clean --distclean --no-network --output=Ordner --skip=module --start-at=module -D Datum -C -N -f --nodeps Modul

Die Optionen `--autogen`, `--clean`, `--distclean`, `--no-network`, `--skip`, `--start-at`, `-D`, `-C` `-N` und `-f` und `--nodeps` werden ebenso wie der Befehl `build` verarbeitet.

`-o`, `--output`=`Ordner`

- The directory to write the HTML files. JHBuild will create an index (`index.html`) and a HTML file for each module.

### uninstall

Der Befehl `uninstall` deinstalliert ein oder mehrere Module.

    jhbuild uninstall Modul

### update

The `update` command is similar to `build`, but only performs the download or update stage for modules without building them.

    jhbuild update --skip=Modul --start-at=Modul --tags=Tags --ignore-suggests -D Datum Modul

Die Optionen `--skip`, `--start-at`, `--tags` `--ignore-suggests` und `-D` werden ebenso wie für `build` verarbeitet.

### updateone

The `updateone` command is similar to `update`, but it does not update the dependent modules. It is useful for updating one or more modules.

    jhbuild updateone -D Datum Modul

The `-D` option is processed as per the `build` command.

In der Befehlszeile muss mindestens ein Modul angegeben werden.

## Referenz der Konfigurationsdatei

The `~/.config/jhbuildrc` file uses standard Python syntax. The file is run, and the resulting variables defined in the namespace are used to control how JHBuild acts. A set of default values are inserted into the namespace before running the user's configuration file.

Boolean configuration variables are set using syntax as demonstrated in the following example:

    use_local_modulesets = True

String configuration variables are set using syntax as demonstrated in the following example:

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

List configuration variables are set using syntax as demonstrated in the following example:

    skip = ['mozilla', 'pulseaudio']

Dictionary configuration variables are set using syntax as demonstrated in the following example:

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

### Konfigurationsvariablen

`alwaysautogen`

- A boolean value if set to `True`, always run `autogen.sh`. This is equivalent to passing `--autogen` option to JHBuild. Defaults to `False`.

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

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

  Die Definition der Zweige hängt von der Art der Versionsverwaltung des Moduls ab:

  - CVS: Revision. Beispielsweise `'BRANCH-PROJECT-0_8'`

  - Bazaar: Adresse des Modulzweiges. Beispielsweise `'http://bzr.example.net/project/gnome-2-28'`

  - Git: tuple, with first part being an optional repository (or the None value) and the second part the name of the branch. E.g. `('git://git.example.net/project', 'gnome-2-28')`

    #### Einfaches Beispiel

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

  - Subversion: URI of module branch. E.g. `'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`

- A string specifying the parent directory to place build trees. Defaults to `~/.cache/jhbuild/build`. Setting the value to `None` causes builds to be performed within the source trees.

`buildscript`

- A string specifying which buildscript to use. The recommended setting is the default, `terminal`. In particular, do not set to `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`

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

`checkout_mode`

- A string specifying how the checkout is performed for directories in version control. Defaults to `update`. This can be set per module using `module_checkout_mode`. Possible values are `update` (update checkout directory), `clobber` (wipe out directory before checking out the sources), `export` (wipe out directory then create a tarball of the sources containing any patches) and `copy` (checkout in a directory different from the one it will build).

`cmakeargs`

- A string containing arguments passed to the `cmake` invocation of all modules. Can be overridden for particular modules using the `module_cmakeargs` dictionary. Defaults to `''`.

`copy_dir`

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

`export_dir`

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

`cvs_program`

- A string specifying which program to use for CVS support. This can be `git-cvsimport`, or `cvs`. Defaults to `cvs`.

`disable_Werror`

- A boolean value (default `True`) which controls if `--disable-Werror` will be passed to automake builds. Many packages use this flag as a way to disable fatal compiler warnings. The value of `True` is selected as a reasonable default for those using jhbuild as a means to get an up-to-date version of software packages without being side-tracked by build failures in other people's modules. Setting this value to `False` may make sense for those using jhbuild as part of a continuous integration or testing system.

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

`exit_on_error`

- A boolean value specifying whether to exit immediately when a module fails to build. This is primarily useful in noninteractive mode, in order to prevent additional modules from building after one fails. Setting this value to `True` is equivalent to passing the `--exit-on-error` option. Defaults to `False`.

`extra_prefixes`

- A list of strings specifying, in precedence order, the list of extra prefixes. JHBuild sets many environment variables (such as `LD_LIBRARY_PATH`, `PKG_CONFIG_PATH` and `XDG_DATA_DIRS`) based on the `prefix` variable. Adding directories to `extra_prefixes` will cause these prefixes to be included as well, at a lower precedence than the JHBuild `prefix`, but at a higher precedence than system directories. This variable is empty by default except on systems that install software in `/usr/local`, in which case it contains this directory.

`help_website`

- A tuple specifying a help website name and URL. The website is displayed in the tinderbox html for failed modules. `%(module)s` in the URL will be replaced with the module name. To disable, set `help_website` to `None`. Defaults to `('Gnome Live!', 'http://live.gnome.org/JhbuildIssues/%(module)s')`.

`installprog`

- A string specifying a program to use as replacement for `/usr/bin/install`.

`ignore_suggests`

- A boolean value specifying whether to ignore soft dependencies when calculating the dependency tree. Defaults to `False`.

`interact`

- A boolean value specifying whether to interact with the user. Setting this value to `False` is equivalent to passing the `--no-interact` option. Defaults to `True`.

`makeargs`

- A string listing additional arguments to be passed to `make`. JHBuild will automatically append the parallel execution option (`-j`) based upon available CPU cores. Defaults to `''`.

`makecheck`

- A boolean value specifying whether to run `make check` after `make`. Defaults to `False`.

`makecheck_advisory`

- A boolean value specifying whether failures when running `make check` should be advisory only and not cause a build failure. Defaults to `False`.

`makeclean`

- A boolean value specifying whether to run `make clean` before `make`. Defaults to `False`.

`makedist`

- A boolean value specifying whether to run `make dist` after `make`. Defaults to `False`. This setting is equivalent to passing the `--dist` option.

`makedistcheck`

- A boolean value specifying whether to run `make distcheck` after `make`. Defaults to `False`. This setting is equivalent to passing the `--distcheck` option.

`mesonargs`

- A string containing arguments passed to the `meson` invocation of all modules. Can be overridden for particular modules using the `module_mesonargs` dictionary. Defaults to `''`.

`module_autogenargs`

- A dictionary mapping module names to strings specifying the arguments to be passed to `autogen.sh`. The setting in `module_autogenargs` is used instead of the global `autogenargs` setting. If a particular module isn't listed in the dictionary, the global `autogenargs` will be used.

`module_checkout_mode`

- A dictionary specifying which checkout mode to use for modules. This overrides the global `checkout_mode` setting.

`module_cmakeargs`

- A dictionary mapping module names to strings specifying the arguments to be passed to `cmake`. The setting in `module_cmakeargs` is used instead of the global `cmakeargs` setting. If a particular module isn’t listed in the dictionary, the global `cmakeargs` will be used.

`module_makeargs`

- A dictionary mapping module names to strings specifying the arguments to pass to `make`. The setting in `module_makeargs` replaces the value of `makeargs`. If a particular module isn't listed in the dictionary, the global `makeargs` will be used.

`module_makecheck`

- A dictionary mapping module names to boolean values specifying whether to run `make check` after `make`. The setting in `module_makecheck` replaces the value of `makecheck`. If a particular module isn't listed in the dictionary, the global `makecheck` will be used.

`module_mesonargs`

- A dictionary mapping module names to strings specifying the arguments to be passed to `meson`. The setting in `module_mesonargs` is used instead of the global `mesonargs` setting. If a particular module isn’t listed in the dictionary, the global `mesonargs` will be used.

`module_ninjaargs`

- A dictionary mapping module names to strings specifying the arguments to pass to `ninja`. The setting in `module_ninjaargs` replaces the value of `ninjaargs`. If a particular module isn't listed in the dictionary, the global `ninjaargs` will be used.

`module_nopoison`

- A dictionary mapping module names to boolean values. If a module is set to `True`, JHBuild will attempt to build dependent modules even if the specified module failed. The setting in `module_nopoison` replaces the value of `nopoison`. If a particular module isn't listed in the dictionary, the global `nopoison` will be used.

`module_extra_env`

- A dictionary mapping module names to dictionaries with extra environment variables to pass when executing commands for the module.

`module_static_analyzer`

- Dictionary mapping module names to boolean values indicating whether static analysis should be performed while building that module. This allows the global `static_analyzer` configuration option to be overridden.

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

- A string or list of strings specifying the name(s) of the module set(s) to use. This can either be the filename of a moduleset included with JHBuild (excluding the path and extension), or a full HTTP URL to an externally managed moduleset. HTTP URL modulesets are cached locally. If a module with the same name is present in more than one moduleset, the last set listed takes priority. Modulesets provided with JHBuild are updated to match the current GNOME development release.

`modulesets_dir`

- A string specifying the directory containing the modulesets to use. Defaults to the `modulesets/` directory in JHBuild sources.

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

`ninjaargs`

- A string listing additional arguments to be passed to `ninja`. Defaults to `''`.

`nobuild`

- A boolean value, if set to `True` JHBuild will not build modules, but just download and unpack the sources. The default value is `False`.

`nonetwork`

- A boolean value specifying whether to access the network. This affects checking out or updating CVS modules, downloading tarballs and updating module sets. Setting this to `True` is equivalent to passing the `--no-network` option. Defaults to `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`

- A boolean value, if set to `True` JHBuild attempts to build modules even if one or more of the module's dependencies failed to build. This option is equivalent to the `--no-poison` argument. The default value is `False`.

`notrayicon`

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

`noxvfb`

- A boolean value, if set to `True` JHBuild will run any graphical tests on the real X server, rather than using `Xvfb`. This option is equivalent to passing `--no-xvfb`. The default value is `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 `'~/jhbuild/install/'`.

`pretty_print`

- A boolean value specifying whether to pretty format the subprocess output. Only CVS output supports pretty printing. Disable if the pretty printing causes problems. Defaults to `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`

- A boolean value specifying whether to display a progress bar during quiet mode . Defaults to `True`.

`quiet_mode`

- A boolean value, if set to `True` disables the output of running commands. Defaults to `False`.

`repos`

- A dictionary specifying an alternative repository location for a particular repository. This configuration variable is useful to a module developer. By default, JHBuild will check out code from repositories using an anonymous repository location. The dictionary keys are short repository names and the values are the alternative repository location strings. For example:

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

`skip`

- A list of modules to skip. This `--skip` command line option extends the list. This list is empty by default. If the list contains the special value `'*'`, JHBuild will skip all modules not explicitly listed in the `modules` variable. This may be useful if you want to build modules without their implicit dependencies.

`static_analyzer`

- A boolean value: if set to `True`, run a static analysis tool on each module as it’s being built. Defaults to `False`.

`static_analyzer_outputdir`

- Root directory below which static analysis reports will be saved (if `static_analyzer` is `True`). Defaults to `/tmp/jhbuild_static_analyzer`.

`static_analyzer_template`

- Command template for the static analyzer. This has the parameters `outputdir` (the value of the `static_analyzer_outputdir` configuration variable) and `module` (the name of the module currently being built) substituted into it `printf`-style. The resulting command is used as a prefix to `make` when building a module. Defaults to `scan-build`.

`sticky_date`

- A string if set, and if supported by the underlying version control system, JHBuild will update the source tree to the specified date before building. An ISO date format is required, e.g. `'`yyyy`-`mm`-`dd`'`. Defaults to `None`.

`svn_program`

- A string specifying which program to use for subversion support. This can be `svn`, `git-svn` or `bzr`. Defaults to `svn`.

`system_libdirs`

- A list of strings specifying the system library paths. This is used when setting the default values of some environment variables, such as `PKG_CONFIG_PATH`.

`tarballdir`

- A string if set, tarballs will be downloaded to the specified directory instead of `checkoutroot`. This is useful if you have multiple JHBuild environments or regularly clear out `checkoutroot` and want to reduce bandwidth usage. Defaults to `'~/.cache/jhbuild/downloads'`.

`tinderbox_outputdir`

- A string specifying the directory to store `jhbuild tinderbox` output. This string can be overridden by the `--output` option. Defaults to `None`, so either the command line option must be used or this variable must be set in the configuration file.

`trycheckout`

- A boolean value, if set to `True` JHBuild will automatically try to solve failures by 1) running `autogen.sh` again, and 2) checking out a newer version of a module from version control. This setting is equivalent to passing the `--try-checkout` option.

`use_local_modulesets`

- A boolean value that specifies to use modulesets that were checked out along the JHBuild source code; instead of downloading them on-the-fly from GNOME version control system. Defaults to `False`.

`xvfbargs`

- A string listing arguments to pass to `Xvfb` if running graphical tests.

`conditions`

- A set of condition (strings) that can influence the modules that are built and the options that are used for building them. You should use `conditions.add()` and `conditions.discard()` to modify the list if you want to make changes.

  The original set of conditions is determined on a per-OS basis and can be modified using the `--conditions=` commandline argument. The changes made by `--conditions` are visible at the time that jhbuildrc is sourced, so you can set other variables based on the current value of the set, but `--conditions` will be applied again after any changes made by jhbuildrc.

### Weitere Strukturen der Konfigurationsdatei

In addition to the above variables, there are other settings that can be set in the configuration file:

`os.environ`

- A dictionary representing the environment. This environment is passed to processes that JHBuild spawns.

  Some influential environment variables include `CPPFLAGS`, `CFLAGS`, `INSTALL` and `LDFLAGS`. For example:

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

`addpath`(`envvar`, `pathname`)

- This will add a directory to the `PATH` environment variable. `addpath` will correctly handle the case when the environment variable is initially empty (having a stray colon at the beginning or end of an environment variable can have unexpected consequences).

`prependpath`(`envvar`, `pathname`)

- Nach dem Verarbeiten der Konfigurationsdatei ändert JHBuild einige Pfade in Variablen wie `prefix`, zum Beispiel durch Einfügen von `$prefix/bin` am Beginn der Variable `PATH`.

  The `prependpath` function works like `addpath`, except that the environment variable is modified after JHBuild has made its changes to the environment.

## Die Syntax der Modulsatz-Datei

JHBuild uses XML files to describe the dependencies between modules. A RELAX-NG schema and Document Type Definition are included with JHBuild in the `modulesets/` directory. The RELAX-NG schema can be used to edit module set files using `nxml-mode` in Emacs.

The top-level element in a module set file is `moduleset` element. No XML namespace is used. The elements below the top-level come in three types: module sources, include statements and module definitions.

Content in the moduleset file can be conditionally included by use of the <if> tag to surround the conditional content. It is currently only possible to predicate the inclusion on whether a particular condition flag is set or not, using <if condition-set='cond'> or <if condition-unset='cond'>. Conditions are set by default on a per-OS basis but can be influenced by way of the `conditions` variable in jhbuildrc or the `--conditions=` commandline argument.

### Modulquellen

Rather than listing the full location of every module, a number of "module sources" are listed in the module set, and then referenced by name in the module definitions. As well as reducing the amount of redundant information in the module set, it makes it easy for a user to specify an alternative source for those modules (for CVS and Subversion, it is common for developers and users to use different repository access methods).

The `repository` element is used to describe all types of repository. The `branch` element is used inside module definition to specify additional settings.

    <repository name="name"
      type="type"
      [ default="default" ]
      [ password="password" ]
      [ cvsroot="cvsroot" ]
      [ archive="archive" ]
      [ href="href" ]
      [ server="server" ]
      [ database="database" ]
      [ defbranch="defbranch" ]
      [ trunk-template="trunk-template" ]
      [ branches-template="branches-template" ]
      [ tags-template="tags-template" ]
      [ developer-href-example="developer-href-example" ] />

The `name` attribute is a unique identifier for the repository.

The `default` attribute specifies whether this repository is the default source for this module set.

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.

The `developer-href-example` attribute is used to specify the format of the URL for the repository used by developers. This is informational only.

The `branch` element is used inside module definitions.

    <branch
      [ repo="repository" ]
      [ module="module name" ]
      [ checkoutdir="checkoutdir" ]
      [ revision="revision" ]
      [ tag="tag" ]
      [ update-new-dirs="update-new-dirs" ]
      [ override-checkoutdir="override-checkoutdir" ]
      [ subdir="subdir" ]
      [ branch="branch" ]
      [ version="version" ]
      [ size="size" ]
      [ source-subdir="source-subdir" ]
      [ hash="hash" ]/>

All attributes have sensible defaults and depend on the module and repository definitions. Common attributes are described here.

The `repo` attribute is used to specify non-default repository name.

The `module` attribute is used to specify module name to checkout from the repository. Defaults to module id.

The `checkoutdir` attribute is used to specify the checkout directory name. Defaults to module id.

Other attributes are described below

#### 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 substituted in the templates. If either of those are defined `branches-template` is used, otherwise `trunk-template` is used. This way you can override repository to build modules from your personal branch or build many modules from a repository with non-standard layout.

An addition `branch` element accepts `revspec` attribute 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.

For example repository with `template` attributes defined:

    <repository type="bzr" name="launchpad.net"
          href="lp:"
          trunk-template="~bzr-pqm/%(module)s/bzr.dev"
          branches-template="~bzr-pqm/%(module)s/%(branch)s"/>

Example `branch` elements for the above repository:

    <branch repo="launchpad.net"
          module="bzr"
          checkoutdir="bzr-next"/>

    <branch repo="launchpad.net"
          module="bzr"
          branch="2.2"
          checkoutdir="bzr-beta"/>

#### CVS

This repository type is used to define a CVS repository.

The `password` attribute is used to specify the password to the repository.

The `cvsroot` attribute is used to specify the root of the repository.

    <repository type="cvs" name="tango.freedesktop.org"
        cvsroot=":pserver:anoncvs@anoncvs.freedesktop.org:/cvs/tango"
        password=""/>

Additional attributes are: `revision`, `update-new-dirs` and `override-checkoutdir`.

#### Darcs

This repository type is used to define a Darcs repository.

    <repository type="darcs" name="telepathy.freedesktop.org"
          href="http://projects.collabora.co.uk/darcs/telepathy/"/>

#### Git

This repository type is used to define a Git repository.

    <repository type="git" name="git.freedesktop.org"
        href="git://anongit.freedesktop.org/git/"/>

It allows the following attributes on the `branch` element:

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="lokaler-oder-entfernter-Zweig"
            tag="tree-ish"/>

#### Mercurial

This repository type is used to define a Mercurial repository.

    <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

This repository type is used to define a Monotone repository.

The `server` attribute is used to specify the repository server.

The `database` attribute is used to specify the database to use for the repository.

The `defbranch` attribute is used specify the branch of the repository to use.

    <repository type="mtn" name="pidgin.im"
        server="pidgin.im" database="pidgin.im.mtn"
        defbranch="im.pidgin.pidgin"/>

#### Subversion

This repository type is used to define a Subversion repository.

    <repository type="svn" name="svn.gnome.org" default="yes"
        href="http://svn.gnome.org/svn/"/>

It allows a `revision` on the `branch` element. This attribute defines the branch to checkout or, if it is a number, a specific revision to checkout.

    <branch revision="gnome-2-20"/>

It is possible to specify custom `svn` layout using `trunk-template` (defaults to "%(module)s/trunk"), `branches-template` (defaults to "%(module)s/branches/%(branch)s") and `tags-template` (defaults to "%(module)s/tags/%(tag)s")

#### System

This repository type is used to define a fake system repository. A system repository is required to create `systemmodules`.

    <repository type="system" name="system"/>

#### Tarballs

This repository type is used to define a tarball repository.

    <repository type="tarball" name="dbus/dbus-python"
        href="http://dbus.freedesktop.org/releases/dbus-python/"/>

It allows the following attributes on the `branch` element:

The `module` attribute specifies the file to download and compile, the `version` attribute specifies the module version.

The `size` and `hash`, as well as the obsolete `md5sum`, attributes are optional. If these attributes are present, they are used to check that the source package was downloaded correctly.

The `rename-tarball` can be used to rename the tarball file when downloading, in case the original name conflicts with another module.

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.

For module sets shipped with JHBuild, the patch files are looked up in the `jhbuild/patches/` directory; for module sets referred by URI, the patch files are looked for in the same directory as the moduleset file, or in its `patches/` subdirectory. It is also possible for the `file` attribute to specify a URI, in which case it will be downloaded from that location.

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

### Einbinden anderer Modulsätze

JHBuild allows one module set to include the contents of another by reference using the `include` element.

    <include href="uri"/>

The `href` is a URI reference to the module set to be included, relative to the file containing the `include` element.

Only module definitions are imported from the referenced module set - module sources are not. Multiple levels of includes are allowed, but include loops are not (there isn't any code to handle loops at the moment).

### Moduldefinitionen

There are various types of module definitions that can be used in a module set file, and the list can easily be extended. Only the most common ones will be mentioned here.

They are all basically composed of a `branch` element describing how to get the module and `dependencies`, `suggests` and `after` elements to declare the dependencies of the module.

Any modules listed in the `dependencies` element will be added to the module list for `jhbuild build` if it isn't already included, and make sure the dependent modules are built first.

After generating the modules list, the modules listed in the `suggests` element will be used to further sort the modules list (although it will not pull any additional modules). This is intended for cases where a module has an optional dependency on another module.

#### autotools

The `autotools` element is used to define a module which is compiled using the GNU Autotools build system.

    <autotools id="id"
    	      [ autogenargs="autogenargs" ]
    	      [ makeargs="makeargs" ]
    	      [ makeinstallargs="makeinstallargs" ]
    	      [ autogen-sh="autogen-sh" ]
    	      [ makefile="makefile" ]
    	      [ skip-autogen="skip-autogen" ]
    	      [ skip-install="skip-install" ]
    	      [ uninstall-before-install="uninstall-before-install" ]
    	      [ autogen-template="autogen-template" ]
    	      [ check-target="check-target" ]
    	      [ supports-non-srcdir-builds="supports-non-srcdir-builds" ]
    	      [ force-non-srcdir-builds="force-non-srcdir-builds" ]
    	      [ supports-unknown-configure-options="supports-unknown-configure-options" ]
    	      [ supports-static-analyzer="supports-static-analyzer" ]>

      <branch [ ... ] >
        [...]
      </branch>

      <dependencies>
        <dep package="modulename"/>
        ...
      </dependencies>
      <after>
        <dep package="modulename"/>
        ...
      </after>

    </autotools>

The `autogenargs` and `makeargs` and `makeinstallargs` attributes are used to specify additional arguments to pass to `autogen.sh`, `make` and `make install` respectively.

The `autogen-sh` attribute specifies the name of the autogen.sh script to run. The value `autoreconf` can be used if your module has no `autogen.sh` script equivalent. In that case, JHBuild will run `autoreconf -fi`, followed by the proper `configure`. `skip-autogen` chooses whether or not to run autogen.sh, it is a boolean with an extra `never` value to tell JHBuild to never skip running `autogen.sh`. `skip-install` is a boolean attribute specifying whether to skip `make install` command on the module. `makefile` specifies the filename of the makefile to use.

The `uninstall-before-install` specifies any old installed files from the module should before removed before running the install step. This can be used to work around a problem where libtool tries to link one library it is installing against another library it is installing, but because of jhbuild's use of DESTDIR, finds the old installed library instead. The downside of specifying this is that it could cause problems if the user is currently running code that relies on installed files from the module.

The `supports-non-srcdir-builds` attribute is used to mark modules that can't be cleanly built using a separate source directory.

The `force-non-srcdir-builds` attribute is used to mark modules that can't be cleanly built from the source directory, but can be built from outside it.

The `autogen-template` attribute can be used if you need finer control over the autogen command line. It is a python format string, which will be substituted with the following variables: `srcdir`, `autogen-sh`, `prefix`, `libdir`, and `autogenargs`. For example, here is the default autogen-template:

    %(srcdir)s/%(autogen-sh)s --prefix %(prefix)s --libdir %(libdir)s %(autogenargs)s

The `check-target` attribute must be specified (with false as value) for modules that do not have a `make check` target.

The `supports-static-analyzer` attribute must be specified (with false as value) for modules which don’t support being built under a static analysis tool such as `scan-build`.

The `supports-unknown-configure-options` attribute is used to mark modules that will error out if an unknown option is passed to `configure`. Global configure options will not be used for that module.

#### cmake

The `cmake` element is used to define a module which is built using the CMake build system.

      <cmake id="modulename"
                [ cmakeargs="cmakeargs" ]
                [ ninjaargs="ninjaargs" ]
                [ makeargs="makeargs" ]
                [ skip-install="skip-install" ]
                [ cmakedir="cmakedir" ]
                [ use-ninja="use-ninja" ]
                [ force-non-srcdir-builds="force-non-srcdir-builds" ]>
      <branch [ ... ] >
        [...]
      </branch>

      <dependencies>
        <dep package="modulename"/>
        ...
      </dependencies>
      <after>
        <dep package="modulename"/>
        ...
      </after>
    </cmake>

The `cmakeargs` attribute is used to specify additional arguments to pass to `cmake`.

The `ninjaargs` attribute is used to specify additional arguments to pass to `ninja`.

The `makeargs` attribute is used to specify additional arguments to pass to `make`.

The `cmakedir` attribute specifies the subdirectory where cmake will run in relation to srcdir.

The `force-non-srcdir-builds` attribute is used to mark modules that can't be cleanly built from the source directory, but can be built from outside it.

The `use-ninja` attribute is used to mark modules should be built using the Ninja backend for cmake, instead of the Make backend. The default is to use the Ninja backend.

#### Meson

The `meson` element is used to define a module which is configured using the Meson build system and built using the Ninja build tool.

      <meson id="modulename"
                [ mesonargs="mesonargs" ]
                [ ninjaargs="ninjaargs" ]
                [ skip-install="skip-install" ]>
      <branch [ ... ] >
        [...]
      </branch>

      <dependencies>
        <dep package="modulename"/>
        ...
      </dependencies>
      <after>
        <dep package="modulename"/>
        ...
      </after>
    </meson>

The `mesonargs` attribute is used to specify additional arguments to pass to `meson`.

The `ninjaargs` attribute is used to specify additional arguments to pass to `ninja`.

#### distutils

The `distutils` element is used to define a module which is built using python's distutils.

    <distutils id="modulename"
                [ supports-non-srcdir-builds="yes|no" ]>
      <branch [ ... ] >
        [...]
      </branch>

      <dependencies>
        <dep package="modulename"/>
        ...
      </dependencies>
      <after>
        <dep package="modulename"/>
        ...
      </after>
    </distutils>

#### distutils

The `distutils` element is used to define a module which is built using python's distutils

    <distutils id="modulename"
                [ supports-non-srcdir-builds="yes|no" ]>
      <branch [ ... ] >
        [...]
      </branch>

      <dependencies>
        <dep package="modulename"/>
        ...
      </dependencies>
      <after>
        <dep package="modulename"/>
        ...
      </after>
    </distutils>

#### linux

The `linux` element defines a module used to build a linux kernel. In addition, a separate kernel configuration can be chosen using the `kconfig` subelement.

    <linux id="id"
    	  [ makeargs="makeargs" ]>

      <branch [ ... ] >
        [...]
      </branch>

      <dependencies>
        <dep package="modulename"/>
        ...
      </dependencies>
      <after>
        <dep package="modulename"/>
        ...
      </after>

      <kconfig [ repo="repo" ]
    	    version="version"
    	    [ module="module" ]
    	    [ config="config" ] />

    </linux>

#### perl

The `perl` element is used to build perl modules.

The `makeargs` attribute is used to specify additional arguments to pass to `make`.

    <perl id="modulename"
    	 [ makeargs="makeargs" ]>

      <branch [ ... ] >
        [...]
      </branch>

      <dependencies>
        <dep package="modulename"/>
        ...
      </dependencies>
      <after>
        <dep package="modulename"/>
        ...
      </after>

    </perl>

#### systemmodule

The `systemmodule` element is used to specify modules that must be provided by the system. The module should be installed by your distributions package management system.

    <systemmodule id="modulename">
      <pkg-config>pkg-config.pc</pkg-config>

      <branch repo="system" version="version" />
    </systemmodule>

If the system module does not provide a pkg-config file, `systemdependencies` tag can be used to identify the dependencies. Two values are supported by the `type` attribute of the `dep` tag:

1. `path` value. The path is searched for the matching program name.

2. `c_include` value. The C include path is searched for the matching header name. `name` may include a sub-directory. The C include search path can modified by setting `CPPFLAGS` within the configuration variables `cflags` or `module_autogenargs`.

    <systemmodule id="modulename">
      <branch repo="system" version="version" />
      <systemdependencies>
        <dep type="path" name="executable-name" />
      </systemdependencies>
    </systemmodule>

    <systemmodule id="modulename">
      <branch repo="system" version="version" />
      <systemdependencies>
        <dep type="c_include" name="header-name" />
      </systemdependencies>
    </systemmodule>

If the system module may be installed in different locations or installed with different names by different distributions, `altdep` tag can be used as subelements of `dep` tag to specify alternative locations or names. `altdep` tag support the same attributes as `dep` tag does.

    <systemmodule id="modulename">
      <branch repo="system" version="version" />
      <systemdependencies>
        <dep type="path" name="executable-name">
          <altdep type="path" name="alternative-executable-name-1" />
          <altdep type="path" name="alternative-executable-name-2" />
          ...
        <dep>
      </systemdependencies>
    </systemmodule>

    <systemmodule id="modulename">
      <branch repo="system" version="version" />
      <systemdependencies>
        <dep type="c_include" name="header-name">
          <altdep type="c_include" name="alternative-header-name-1" />
          <altdep type="c_include" name="alternative-header-name-2" />
          ...
        <dep>
      </systemdependencies>
    </systemmodule>

#### waf

The `waf` element is used to define a module which is built using the Waf build system.

The `waf-command` attribute is used to specify the waf command script to use; it defaults to `waf`.

The `python-command` attribute is used to specify the Python executable to use; it defaults to `python`. This is useful to build modules against version 3 of Python.

    <waf id="modulename">
    	 [ python-command="python-command" ]
    	 [ waf-command="waf-command" ]>
      <branch [ ... ] >
        [...]
      </branch>

      <dependencies>
        <dep package="modulename"/>
        ...
      </dependencies>
      <after>
        <dep package="modulename"/>
        ...
      </after>
    </waf>

#### testmodule

The `testmodule` element is used to create a module which runs a suite of tests using LDTP or Dogtail.

    <testmodule id="id"
    	       type="type">

      <branch [ ... ] >
        [...]
      </branch>

      <dependencies>
        <dep package="modulename"/>
        ...
      </dependencies>
      <after>
        <dep package="modulename"/>
        ...
      </after>

      <testedmodules>
        <tested package="package" />
      </testedmodules>

    </testmodule>

The `type` attribute gives the type of tests to be run in the module. 'dogtail' uses python to invoke all .py files. 'ldtp' invokes 'ldtprunner run.xml'.

Unless the noxvfb configuration option is set, an Xvfb server is started to run the tests in.

#### metamodule

The `metamodule` element defines a module that doesn't actually do anything. The only purpose of a module of this type is its dependencies.

For example, meta-gnome-desktop depends on all the key components of the GNOME desktop, therefore telling JHBuild to install it actually installs the full desktop.

    <metamodule id="modulename">
      <dependencies>
        <dep package="modulename"/>
        ...
      </dependencies>
      <suggests>
        <dep package="modulename"/>
        ...
      </suggests>
    </metamodule>

The `id` attribute gives the name of the module. The child elements are handled as for `autotools`.

### Veraltete Elemente

#### Modulquellen

##### cvsroot

The `cvsroot` element is now deprecated - the `repository` element should be used instead.

The `cvsroot` element is used to describe a CVS repository.

      <cvsroot name="rootname"
               [ default="yes|no" ]
               root="anon-cvsroot"
               password="anon-password"/>

The `name` attribute should be a unique identifier for the CVS repository.

The `default` attribute says whether this is the default module source for this module set file.

The `root` attribute lists the CVS root used for anonymous access to this repository, and the `password` attribute gives the password used for anonymous access.

##### svnroot

The `svnroot` element is now deprecated - the `repository` element should be used instead.

The `svnroot` element is used to describe a Subversion repository.

      <svnroot name="rootname"
               [ default="yes|no" ]
               href="anon-svnroot"/>

The `name` attribute should be a unique identifier for the Subversion repository.

The `default` attribute says whether this is the default module source for this module set file.

The `href` attribute lists the base URL for the repository. This will probably be either a `http`, `https` or `svn` URL.

#### Veraltete Modultypen

Dieser Abschnitt beschreibt veraltete Elemente, die in vorhandenen Modulsätzen noch verwendet werden können, was allerdings nicht mehr empfohlen wird.

##### tarball

This deprecated element is just a thin wrapper around both `autotools` module type and `tarball` repository type.

The `tarball` element is used to define a module that is to be built from a tarball.

      <tarball id="modulename"
                  [ version="version" ]
                  [ checkoutdir="checkoutdir" ]
                  [ autogenargs="autogenargs" ]
                  [ makeargs="makeargs" ]
                  [ autogen-sh="autogen-sh" ]
                  [ supports-non-srcdir-builds="yes|no" ]>
        <source href="source-url"
                [ size="source-size" ]
                [ hash="source-algo:source-hash" ]
                [ md5sum="source-md5sum" ]/>
        <patches>
          <patch file="filename" strip="level"/>
          ...
        </patches>
        <dependencies>
          <dep package="modulename"/>
          ...
        </dependencies>
        <suggests>
          <dep package="modulename"/>
          ...
        </suggests>
      </tarball>

The `id` and `version` attributes are used to identify the module.

The `source` element specifies the file to download and compile. The `href` attribute is mandatory, while the `size` and `hash`, as well as the obsolete `md5sum`, attributes are optional. If these last two attributes are present, they are used to check that the source package was downloaded correctly.

The `patches` element is used to specify one or more patches to apply 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.

For module sets shipped with JHBuild, the patch files are looked up in the `jhbuild/patches/` directory; for module sets referred by URI, the patch files are looked for in the same directory as the moduleset file, or in its `patches/` subdirectory. It is also possible for the `file` attribute to specify a URI, in which case it will be downloaded from that location.

The other attributes and the `dependencies`, `suggests` and `after` elements are processed as for autotools.