# Handbok för JHBuild

## Introduktion

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

## Komma igång

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.

### Installera JHBuild

JHBuild requires a Python runtime. Verify Python >= 2.3 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, `~/checkout/gnome`.

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

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
    $

Before running JHBuild, it is necessary to set up a configuration file located at `~/.jhbuildrc`.

### Konfigurera JHBuild

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

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

Configuration variables are documented in config-reference. 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. Unless `buildroot` is set, builds will occur in this directory too. Defaults to `~/checkout/gnome`.

`prefix`

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

`autogenargs`

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

`makeargs`

- A string listing additional arguments to be passed to `make`. 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, the errors can be fixed in one of two ways:

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

2. Run the `bootstrap` command to download, build and install the build prerequisites:

       $ jhbuild bootstrap

   When complete, run the `sanitycheck` command to verify the required tools are present.

   The `bootstrap` command does not build all the package dependencies required by the build tools. If your distribution does not provide the required packages, they will need to be built outside of the JHBuild environment.

   The build tools dependencies include m4, perl and a C compiler (for example, gcc).

### Using JHBuild

After set up is complete, JHBuild can be used to build software. To build all the modules selected in the `~/.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

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:

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

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
    /opt/gnome/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 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 `~/.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 ``/opt/gnome`/share/dbus-1/services/`. Replace `/opt/gnome` with GNOME install `prefix` in the command below:

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

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

    #!/bin/sh

    GNOME=/opt/gnome

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

    jhbuild run gnome-session

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 within the `~gnomedev/.xsession-errors` file.

## Buildbot Integration

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.

### Configuring a Buildbot Slave

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 commands are options to the `bot` command. To download and install the extra required software, run the following command:

    $ jhbuild bot --setup

Once this step has completed successfully, three new configuration variables are required in `~/.jhbuildrc`.

It is not possible to use an alternate configuration file, the `--file` will not get desired effects.

    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.

The administrators of build.gnome.org can be reached on the Build Brigade mailing list.

## Kommandoreferens

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

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 required to build most modules (e.g. autoconf, automake, etc).

    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
            --ignore-suggests
            --no-network
            --skip=module
            --start-at=module
            --tags=tags
            -D date
            --no-xvfb
            --try-checkout
            --no-poison
            --force
            --build-optional-modules
            --min-age=time
            module

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

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

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

### 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
            --clean
            --check
            --distcheck
            --no-network
            -D date
            --no-xvfb
            --force
            --min-age=time
            module

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

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

### 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 a list of dependency modules that are provided by installed system packages. JHBuild will not build the modules from source if the configuration variable `partial_build` is `True`.

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

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

    jhbuild sysdeps
            --install

`--install`

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

#### `sysdeps` example

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

### tinderbox

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
            --clean
            --no-network
            --output=directory
            --skip=module
            --start-at=module
            -D date
            -C
            -N
            -f
            module

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

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

- The directory to write the HTML files.

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

`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 `None`, which 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 an unversioned copy of the sources) and `copy` (checkout in a directory different from the one it will build).

`copy_dir`

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

`cvs_program`

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

`dvcs_mirror_dir`

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

`installprog`

- A string specifying a program to use as replacement for `/usr/bin/install`. If available, defaults to the `install-check` wrapper provided by JHBuild. The `install-check` wrapper optimizes header installation to reduce the time taken for rebuilds.

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

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

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

`nobuild`

- A boolean value, if set to `True` JHBuild will not build modules, but just download and unpack the sources. The default vale 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`, notifications are emitted. 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 `'/opt/gnome'`.

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

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

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

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

- A boolean value that specifies whether to install libraries to `lib64` directories. If set, `--libdir=\${exec_prefix}/lib64` will be passed to configure. Defaults to `True` if running on `x86_64`, `ppc64` or `s390x` Linux, and `False` on other systems.

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

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

  `addpath` has special handling for the `ACLOCAL_FLAGS` environment variable, which expects paths to be listed in the form `-I `pathname``.

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

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

An addition `branch` element accepts `revspec` attibute to anchor on a particular revision. Any valid `bzr revspec` is accepted, for example `date:yesterday, -5, tag:0.1` to get first revision since yesterday, 5 commits behind the tip or tag "0.1". See `bzr help revisionspec` for all possible values.

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

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

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" ]
    	      [ autogen-template="autogen-template" ]
    	      [ check-target="check-target" ]
    	      [ supports-non-srcdir-builds="supports-non-srcdir-builds" ]>

      <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 -i`, 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`. `makefile` specifies the filename of the makefile to use.

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

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.

#### cmake

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

    <cmake id="modulename">
      <branch [ ... ] >
        [...]
      </branch>

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

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

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

    <waf id="modulename">
    	 [ 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.

If `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" ]
                  [ checkourdir="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.