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, ~/checkout/gnome2.

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

Alternatively, if autotools or gnome-doc-utils is not installed, install JHBuild as follows:

$ cd jhbuild
$ make -f Makefile.plain
...
$ make -f Makefile.plain install
...
$

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.

2.2. Configuring JHBuild

The ~/.jhbuildrc file uses Python syntax to set configuration variables for JHBuild. An example is provided within the jhbuild directory, see sample.jhbuildrc. Copy sample.jhbuildrc to ~/.jhbuildrc and customize as required.

The sample configuration will make JHBuild build the meta-gnome-desktop module and its dependencies from the gnome-2.30 module set. JHBuild will unpack source trees to ~/checkout/gnome2 and install all files to subdirectories of /opt/gnome2. 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 ~/checkout/gnome2.

prefix

A string specifying the prefix to install modules to. This directory must be writable. Defaults to '/opt/gnome2'.

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

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

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

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