GNOME.org

JHBuild Manual

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

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

2.1. Installing 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, ~/jhbuild/checkout.

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

2.2. 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 Section 6 ― Configuration File 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 ~/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.

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

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

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

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

3. JHBuild and GNOME

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

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

3.2. 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 Section 3.3 ― Running the GNOME Desktop Environment.

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

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

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

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

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

4.1. 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 ~/.config/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.

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

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

Command specific options are listed below.

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

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

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

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

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

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

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

5.8. 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
Figure 1 Sample JHBuild dot output

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

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

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

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

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

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

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

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

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

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

5.18. uninstall

The uninstall command uninstalls one or more modules.

jhbuild uninstall module...

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

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

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

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

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

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

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 '~/jhbuild/install/'.

pretty_print

A boolean value specifying whether to pretty format the subprocess output. Only CVS output supports pretty printing. Disable if the pretty printing causes problems. Defaults to True.

print_command_pattern

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

progress_bar

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

quiet_mode

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

repos

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

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

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

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.

Defaults to '~/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_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.

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.

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

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

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

7.1.1. 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"/>

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

7.1.3. 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/"/>

7.1.4. 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"/>

7.1.5. 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"/>

7.1.6. 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"/>

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

7.1.8. 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"/>

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

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

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

7.3.1. 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" ]
	      [ 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 -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 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.

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

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

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

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

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

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

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

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

7.4. Deprecated Elements

7.4.1. Module Sources

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

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

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

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

  • JHBuild Manual