JHBuild takes a bit of work to set up on a system. As well as installing JHBuild's prerequisites, it is necessary to install the prerequisite tools needed to obtain and build the software sources.
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 Subversion. This can be achieved with the following commands. They should be run in the directory where JHBuild will be installed (for example, ~/checkout/gnome2).
$ svn co http://svn.gnome.org/svn/jhbuild/trunk jhbuild ... $
This will download JHBuild into a new folder named jhbuild under the current directory. Now to build and install it:
$ cd jhbuild $ ./autogen.sh ... $ make ... $ make install ... $
Alternatively, if your work environment doesn't have autotools or gnome-doc-utils installed you can also build and install JHBuild that way:
$ cd jhbuild $ make -f Makefile.plain ... $ make -f Makefile.plain 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. This can be done with the command:
$ PATH=$PATH:~/bin $
This command will need to be run every time you login and want to use JHBuild. In order to permanently add ~/bin to your PATH variable, run the following command:
$ echo PATH=$PATH:~/bin >> ~/.bashrc $
Before JHBuild can be run, it is necessary to set up a configuration file, located at ~/.jhbuildrc. This file specifies 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.22'
modules = [ 'meta-gnome-desktop' ]
checkoutroot = os.path.join(os.environ['HOME'], 'checkout', 'gnome2')
prefix = os.path.join(os.environ['HOME'], 'prefix')
os.environ['INSTALL'] = os.path.join(os.environ['HOME'],
'bin', 'install-check')
This will make JHBuild build the meta-gnome-desktop module and its dependencies from the gnome-2.22 module set. It will unpack source trees to ~/checkout/gnome2 and install all files to subdirectories of ~/prefix. It also sets the INSTALL environment variable, so modules use a different install program which handles installation of headers differently, in order to reduce the time taken for rebuilds.
Some of configuration variables available include:
A string or list of strings specifying the name(s) of the module set(s) to use. If a module set name is a fully qualified URL, then the module set will be cached locally and regularly updated. If a module with the same name is present in more than one module set, the last set listed takes priority.
A list of strings giving the modules you want to build. The list of modules actually built will be recursively expanded to include all the dependencies unless the buildone is used.
The base directory where all source modules are unpacked or checked out of revision control.
The directory prefix to install modules to. You must have write permissions to this directory, or JHBuild will be unable to install files.
A dictionary representing the environment. This can be used to set or get environment variable values as shown in the example configuration above.
A list of module names that to not include when deciding what to build. One use of this variable is to use the version of a package included with the distribution instead of building it.
A string listing additional arguments to pass to the autogen.sh or configure scripts for modules.
A string listing arguments to be pass to the make command.
By default, JHBuild will check out code from repositories using an anonymous repository location. This dictionary is used to tell JHBuild to use an alternative repository location for a particular repository (a developer would probably want to do this). This variable is a dictionary where the keys are short repository names (for example, svn.gnome.org is used for the GNOME SVN repository), and the values are the alternative repository location strings.
Before any modules can be built, it is necessary to have certain build tools installed. These can 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 if your system has these tools installed using the sanitycheck command:
$ jhbuild sanitycheck
If this command prints any messages, these can be fixed in one of two ways:
Install the required package from your distribution's repository. A list of package names for different distributions is maintained on the GNOME wiki. The sanitycheck command should be run again afterwards to make sure required tools are present.
Run the bootstrap command to install the build prerequsites.
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.
The bootstrap command does not build all the packages required by these tools. If your distribution does not provide those packages, then they will need to be built separately.
Some packages to check for include m4, perl and a C compiler (For example, gcc).
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 what to do. These choices include dropping to a shell to fix the error, rerunning the build from various stages, 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, for example, to build gtk+:
$ 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 module using the --start-at option:
$ jhbuild build --start-at=pango
To build one or more modules, ignoring their dependencies, the buildone command can be used. This command should only be used if you have manually installed all dependencies, else the build will fail.
$ jhbuild buildone gtk+
To get a list of the modules and dependencies jhbuild will build, and the order in which they will be built, 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, or you wish to modify the sources before building them, you can download or update all the software sources without actually building them:
$ jhbuild update
Later on, you can tell JHBuild to build everything without downloading or updating the sources:
$ 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 the environment used by JHBuild, use the shell command:
$ jhbuild shell