2. Getting Started
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 build the software in CVS (or where ever else it is stored).
2.1. Installing JHBuild
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.
2.2. Configuring JHBuild
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:
- moduleset
A string giving the name of the module set to build. If it is a fully qualified URL, then the module set will be cached locally and regularly updated.
- modules
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.
- checkoutroot
The base directory where all source modules should be unpacked.
- prefix
The directory prefix to install modules to.
- os.environ
A dictionary representing the environment. This can be used to set or get environment variable values as seen in the example above.
- skip
A list of module names that should not be included 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
- autogenargs
A string listing arguments that should be passed to the autogen.sh or configure scripts for modules.
- makeargs
A string listing arguments that should be passed to make.
- cvsroots
By default, JHBuild will check out code from CVS using an anonymous CVS root. This dictionary is used to tell JHBuild to use an alternative CVS root 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, gnome.org is used for the Gnome CVS repository), and the values are the alternative CVS root strings.
- svnroots
Similar to cvsroots but for Subversion repositories.
2.3. Build Prerequisites
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:
Install the required package from the distribution. The sanitycheck command should be run again afterwards to make sure everything is okay.
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 the OS 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. |
2.4. Using JHBuild
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