JHBuild Manual

Before downloading JHBuild, you should make sure you have a copy of Python >= 2.0 installed on your system. It is also essential that the Expat XML parser extension is installed. This will be the case if you are using Python >= 2.3, or had expat installed when building Python. You can check whether this is the case by running the following simple command from the Python interpreter:

>>> import xml.parsers.expat
>>>

If this completes without an exception, then it is installed correctly.

At the moment, the only way to download JHBuild is via CVS. This can be achieved with the following commands. They should be run in the directory where jhbuild will be installed (for example, ~/cvs/gnome2).

$ cvs -d :pserver:anonymous@anoncvs.gnome.org:/cvs/gnome login
Logging in to :pserver:anonymous@anoncvs.gnome.org:2401/cvs/gnome
CVS password: press enter
$ cvs -d :pserver:anonymous@anoncvs.gnome.org:/cvs/gnome checkout jhbuild
$

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

$ cd jhbuild
$ make
...
$ make install
...
$

If these steps complete successfully, a small shell script should be installed in ~/bin to start JHBuild. If this directory is not in the PATH, it will need to be added (possibly by editing ~/.profile or ~/.bashrc).

Before JHBuild can be run, it will be necessary to set up a ~/.jhbuildrc file that configures how JHBuild will behave.

The ~/.jhbuildrc file uses Python syntax to set a number of configuration variables for JHBuild. A minimal configuration file might look something like this:

moduleset = 'gnome-2.10'
modules = [ 'meta-gnome-desktop' ]
checkoutroot = os.path.join(os.environ['HOME'], 'cvs', 'gnome2')
prefix = os.path.join(os.environ['HOME'], 'prefix')
os.environ['INSTALL'] = os.path.join(os.environ['HOME'],
                                     'bin', 'install-check')

This will get JHBuild to build the meta-gnome-desktop module (and its dependencies) from the gnome-2.10 module set. It will unpack source trees to ~/cvs/gnome2 and install modules to ~/prefix. It also sets the INSTALL environment variable to a program that handles installation of headers specially in order to decrease the work during a rebuild.

Some of configuration variables available include:

Before any modules can be built, it is necessary to have certain build tools installed. These include the GNU auto tools (autoconf, automake, libtool and gettext), pkg-config nad Python.

JHBuild can check if your distro has installed these tools using the sanitycheck command:

$ jhbuild sanitycheck

If this command prints any messages, these can be fixed in one of two ways:

The bootstrap command can be invoked like so:

$ jhbuild bootstrap

This will download and install all the build prerequisites. Once it is finished, the sanitycheck command should be rerun to verify that everything is in place.

Now that everything is set up, JHBuild can be used to build some software. To build all the modules selected in the ~/.jhbuildrc file, run the following command:

$ jhbuild build

This will download, configure, compile and install each of the modules. If an error occurs at any stage, JHBuild will present a menu asking the user what to do. These choices include dropping to a shell to fix the error, rerunning the build stage, giving up on the module (which will also cause any modules depending on it to fail), or ignore the error and continue.

It is also possible to build a different set of modules (and their dependencies) by passing their names as arguments to the build command:

$ jhbuild build gtk+

If you exit JHBuild part way through a build for some reason, it is possible to pick up a build at a particular package using the --start-at option:

$ jhbuild build --start-at=pango

To build one or more modules, without their dependencies, the buildone command can be used:

$ jhbuild buildone gtk+

To get a list of the modules jhbuild will build, and the order they will be built in, use the list command:

$ jhbuild list

To get information about a particular module, the info command can be used:

$ jhbuild info gtk+

If your internet bandwidth varies, you can get JHBuild to download or update all the software it will build in one go without actually building it:

$ jhbuild update

Later on, you can tell JHBuild to build everything without downloading or updating:

$ jhbuild build --no-network

If you want to run a particular command with the same environment variables set that JHBuild uses, use the run command:

$ jhbuild run program

To start a shell with that environment, use the shell command:

$ jhbuild shell

The bootstrap command is used to install a set of build utilities required to build most modules (eg. autoconf, automake, etc).

Internally bootstrap is implemented using the same code as build, using the bootstrap.modules moduleset.

The build command is used to build one or more packages, including their dependencies.

If no module names are given on the command line, then the module list found in the configuration file will be used.

The buildone command is similar to build, but it does not use dependency information to expand the module list. It is useful for quickly rebuilding one or more modules.

The --autogen, --clean, --no-network and -D options are processed the same as for build.

Unlike build, at least one module must be listed on the command line.

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

If no module names are given on the command line, then the module list found in the configuration file will be used.

The output of this command can easily be piped to the dot utility to generate a postscript file:

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

The info command is used to display information about one or more modules.

The command prints the module name, type, dependencies, dependent packages, and the time it was last installed with JHBuild. It may also print some information specific to the module type, such as the CVS repository or download URL.

The list command is used to show the expanded list of modules the build command would build.

If no module names are given on the command line, then the module list found in the configuration file will be used.

The run command is used to run an arbitrary command using the same environment as JHBuild uses when building modules.

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

The sanitycheck command performs a number of checks to see whether the build environment is okay.

Some of the checks include:

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

This command is roughly equivalent to the following:

$ jhbuild run $SHELL

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.

The --autogen, --clean, --no-network, --skip, --start-at and -D options are processed the same as for build.

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

The --skip, --start-at and -D options are processed the same as for build.

The updateone command is similar to update, but it does not use dependency information to expand the module list. It is useful for quickly updating one or more modules.

The -D option is processed the same as for update.

Unlike update, at least one module must be listed on the command line.

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

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

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

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

<arch-archive name="archivename"
              [ default="yes|no" ]
              href="mirror-url"/>

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

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.

<cvsmodule module="modulename"
           [ revision="branch-or-tag" ]
           [ checkoutdir="directory" ]
           [ root="rootname" ]
           [ autogenargs="autogenargs" ]
           [ makeargs="makeargs" ]
           [ supports-non-srcdir-builds="yes|no" ]>
  <dependencies>
    <dep package="modulename"/>
    ...
  </dependencies>
  <suggests>
    <dep package="modulename"/>
    ...
  </suggests>
</cvsmodule>

<svnmodule module="modulename"
           [ checkoutdir="directory" ]
           [ root="rootname" ]
           [ autogenargs="autogenargs" ]
           [ makeargs="makeargs" ]
           [ supports-non-srcdir-builds="yes|no" ]>
  <dependencies>
    <dep package="modulename"/>
    ...
  </dependencies>
  <suggests>
    <dep package="modulename"/>
    ...
  </suggests>
</svnmodule>

<archmodule version="modulename"
            [ checkoutdir="directory" ]
            [ root="rootname" ]
            [ autogenargs="autogenargs" ]
            [ makeargs="makeargs" ]
            [ supports-non-srcdir-builds="yes|no" ]>
  <dependencies>
    <dep package="modulename"/>
    ...
  </dependencies>
  <suggests>
    <dep package="modulename"/>
    ...
  </suggests>
</archmodule>

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

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