# JHBuild Manual

James
Henstridge
C.J.
Adams-Collier
Frederic
Peters
David
Turner
2004, 2008
James Henstridge
JHBuild Manual v0.5
January 2008
JHBuild Manual v0.1
August 2007

JHBuild is a tool used to build the whole GNOME desktop from the version control system. JHBuild can also be customized to build other projects too.

## Introduction

JHBuild is a tool designed to ease building collections of source packages, called modules. JHBuild uses module set files to describe the modules available to build. The module set files include dependency information that allows JHBuild to discover what modules need to be built and in what order.

JHBuild was originally written for building GNOME, but has since been extended to be usable with other projects. A module set file can be hosted on a web server, allowing for build rules independent of the JHBuild project.

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 is not intended as a replacement for the distribution's package management system. Instead, it makes it easy to build software into a separate install prefix without interfering with the rest of the system.

## Getting Started

JHBuild requires a few set up steps to be run before building software. JHBuild requires some prerequisite software, and it is necessary to install prerequisite tools needed to obtain and build the software modules.

### Installing JHBuild

JHBuild requires a Python runtime. Verify Python >= 3.7 is installed.

The recommended way to download JHBuild is via the version control system, `git`. This can be achieved with the following command. It is recommended to run the command from a new directory where all source code will be installed, for example, `~/jhbuild/checkout`.

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

This will download JHBuild into a new folder named `jhbuild` under the current directory. Now to build and install JHBuild:

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

If the above steps complete successfully, a small shell script will be installed in `~/.local/bin` to start JHBuild. Add `~/.local/bin` to the `PATH`:

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

To permanently add `~/.local/bin` to the `PATH` variable, run the following command:

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

### Configuring JHBuild

JHBuild can be configured via a configuration file. The default location is `~/.config/jhbuildrc`. If a configuration file does not exist, the defaults are used. The configuration file uses Python syntax. An example is provided, see `examples/sample.jhbuildrc`. Copy `examples/sample.jhbuildrc` to `~/.config/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 `~/jhbuild/checkout/` and install all files to subdirectories of `~/jhbuild/install/`. The two directories must be writable.

Configuration variables are documented in . The most commonly used variables are:

`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://username@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 `''`.

### Build Prerequisites

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 can check the tools are installed using the `sanitycheck` command:

    $ jhbuild sanitycheck

If this command displays any messages, please install the required package from your distribution's repository. A list of package names for different distributions is maintained on the GNOME wiki. Run the `sanitycheck` command again after installing the distribution's packages to ensure the required tools are present.

### Using JHBuild

After set up is complete, JHBuild can be used to build software. To build all the modules selected in the `~/.config/jhbuildrc` file, run the following command:

    $ jhbuild build

JHBuild will download, configure, compile and install each of the modules. If an error occurs at any stage, JHBuild will present a menu asking what to do. The choices include dropping to a shell to fix the error, rerunning the build from various stages, giving up on the module, or ignore the error and continue.

Giving up on a module will cause any modules depending on the module to fail.

Below is an example of the menu displayed:

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

It is also possible to build a different set of modules and their dependencies by passing the module names as arguments to the `build` command. For example, to build 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

To get information about a particular module, use the `info` command:

    $ 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

Later, JHBuild can build everything without downloading or updating the sources:

    $ jhbuild build --no-network

To run a particular command with the same environment used by JHBuild, use the `run` command:

    $ jhbuild run program

To start a shell with the same environment used by JHBuild, use the `shell` command:

    $ jhbuild shell

## JHBuild and GNOME

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

### Building GNOME

To build GNOME some development packages are required. This includes:

- DocBook XML DTD and XSLT stylesheets. These need to be registered in the XML catalog (`/etc/xml/catalog`).

- X libraries.

- `libsmbclient` from Samba (used for browsing Windows networks).

- `libbz2` from bzip2.

- `libpng`, `libjpeg` and `libtiff` (used for image loading).

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.

### Running a Single GNOME Application

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 .

Launch a JHBuild shell. The JHBuild shell has all the necessary environment variables set.

    $ jhbuild shell

Verify the correct application will be run. For example:

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

Run the application:

    $ gedit &

Alternatively, run the application using the `run` command:

    $ jhbuild run gedit

### Running the GNOME Desktop Environment

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.

Open a terminal as the user gnomedev. Permanently add `~/.local/bin` to the `PATH` variable, run the following command:

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

Test JHBuild works:

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

#### Setup GNOME to run from the display manager

Build and install 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

Make the file `/usr/bin/gnome-jhbuild-session` executable:

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

To add a new session entry in the display manager, create `/usr/share/xsessions/gnome-jhbuild.desktop` and enter:

    [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

Restart `gdm`.

#### Running GNOME from the display manager

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

### Static Analysis

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.

## Command Reference

JHBuild uses a command line syntax similar to tools like CVS:

    jhbuild
          global-options
          command
          command-arguments

The global JHBuild options are:

`-f`, `--file` config

  Use an alternative configuration file instead of the default `~/.config/jhbuildrc`.

`-m`, `--moduleset` moduleset

  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.

Command specific options are listed below.

### autobuild

The `autobuild` command automatically builds the modules as specified in the configuration file, and then upload the results to 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=reporturl`, `-r reporturl`

  This option specifies the JhAutobuild URL to report to.

`--verbose`, `-v`

  If specified, JHBuild's output will be more verbose.

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

See the `build` command documentation for available options.

### build

The `build` command builds one or more packages, including their dependencies.

    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

If no module names are provided on the command line, the modules list from the configuration file will be used.

`-a`, `--autogen`

  Always run `autogen.sh` before building modules.

`-c`, `--clean`

  Run `make clean` before building modules.

`--check`

  Run `make check` after building modules.

`-d`, `--dist`

  Run `make dist` after building modules.

`--distcheck`

  Run `make distcheck` after building modules.

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

  Do not build soft dependencies.

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

  Do not access the network when building modules. This will skip download or update stages in a build. If a module can't be built without network access, the module build will fail.

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

  Do not build the listed modules. Used to skip the building of specified dependencies.

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

  Start at the named module rather than at the beginning of the list. This option is useful if the build was interrupted.

`-D` date

  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`

  Run graphical tests on the actual X server rather than in a simulated Xvfb.

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

  If one or more of a module's dependencies failed, this option forces JHBuild to try to build the module anyway.

`-f`, `--force`

  Build the modules even if policy states it is not required.

`--build-optional-modules`

  Modules listed as optional dependencies, may not be required to build the module. This option forces JHBuild to build optional dependencies.

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

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

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

### buildone

The `buildone` command is similar to `build`, but it does not build the dependent modules. It is useful for rebuilding one or more modules.

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

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

At least one module must be listed on the command line.

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

  The branch to check.

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

### clean

The `clean` command cleans the build directories of one or more modules.

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

If no module names are provided on the command line, the modules list from the configuration file will be used.

See the `build` command documentation for a description of available options.

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

If no module names are provided on the command line, the modules list from the configuration file will be used.

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

The output of the dot command can be piped to the dot utility to generate a PostScript file:

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

Or a PNG image:

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

#### Sample JHBuild dot output

### gui

The `gui` command starts a graphical interface to JHBuild which can be used to select modules to build and change some options.

    jhbuild gui

The graphical interface is rendered using GTK, so extra support libraries are required.

### info

The `info` command displays information about one or more modules.

    jhbuild info
              --installed
              module

The command displays the module name, type, dependencies, dependent packages, the source directory, and the time it was last installed with JHBuild. If available, information specific to the module type such as the CVS repository or download URL will also be displayed.

If there is no module specified the command will display information about all the modules defined in the module set.

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
            module

If no module names are provided on the command line, the modules list from the configuration file will be used.

The `--skip`, `--start-at`, `--tags`, and `--ignore-suggests` options are processed as per the `build` command.

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

  This option forces JHBuild to list optional dependencies.

### rdepends

The `rdepends` command displays the reverse dependencies of a module.

    jhbuild rdepends
            module

`--dependencies`

  Show dependency path next to modules.

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

If using JHBuild to build GNOME, this command can be useful in X startup scripts.

`--in-builddir`=module

  Run the command in the build directory of the specified module.

`--in-checkoutdir`=module

  Run the command in the source directory of the specified module.

### sanitycheck

The `sanitycheck` command performs a number of checks to verify the build environment is okay.

    jhbuild sanitycheck

Some of the checks include:

- The checkout and install prefixes are writable.

- The required build tools are installed.

- Some commonly used macros are available in the search paths of the `aclocal` commands associated with the various versions of `automake`.

- The XML catalog contains the DocBook DTD and stylesheets.

### shell

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

    jhbuild shell

This command is equivalent to the following:

    $ 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

The `sysdeps` command displays:

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=directory
            --skip=module
            --start-at=module
            -D date
            -C
            -N
            -f
            --nodeps
            module

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

`-o`, `--output`=directory

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

### uninstall

The `uninstall` command uninstalls one or more modules.

    jhbuild uninstall
            module

### update

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

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

The `--skip`, `--start-at`, `--tags`, `--ignore-suggests` and `-D` options are processed as per the `build` command.

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

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

At least one module must be listed on the command line.

## Configuration File Reference

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/'

### Configuration Variables

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

  The definition of branches depends on the module VCS:

  - CVS: revision. E.g. `'BRANCH-PROJECT-0_8'`

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

    #### Simple example

        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/'

`shallow_clone`

  A boolean value specifying if JHBuild should prefer smaller version control downloads. Equivalent to `git clone --depth 1` or `bzr co --light`. Defaults to `False`.

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

### Other Configuration File Structures

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

  After processing the configuration file, JHBuild will alter some paths based on variables such as `prefix` (e.g. adding `$prefix/bin` to the start of `PATH`).

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

## Module Set File Syntax

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.

### Module Sources

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="local-or-remote-branch"
            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.

### Including Other Module Sets

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

### Module Definitions

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>

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

### Deprecated Elements

#### Module Sources

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

#### Deprecated Module Types

This section describes deprecated elements, they may still be used in existing module sets but it is advised not to use them anymore.

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