Jhbuild

JHBuild is the recommended way to build and run GNOME development code. It will download the code, configure and build it for you, in a way that does not interfere with or modify your existing system. JHBuild will also figure out which dependencies are required from your distribution, and it will build any development software that is needed.

This guide contains for an recommended JHBuild setup, which is different from the one recommended in the JHBuild documentation. When setting up JHBuild you should not mix different guides - they may not be compatible. However, the official JHBuild manual might be useful for learning command line and configuration file options.

Introduction

A general knowledge of basic UNIX commands is assumed. Specifically, you should understand that ~/x means "a file or directory named 'x' inside of your home directory". You should also be comfortable with commands like cd, mkdir, rm, etc. You should also know how to edit text files in specific locations.

This document uses the convention that when a directory name is written it will always be suffixed with a trailing slash (like ~/jhbuild/). When the name of a regular file is written, there will be no slash (like ~/.config/jhbuildrc). This convention is followed in texts forming explanations but may not be followed in commands (in grey boxes) for reasons of correct command or file syntax.

This document also uses the convention that commands that you are supposed to type at the shell prompt are in a grey box and have a dollar sign and space ('$ ') preceeding them. You should type (or copy/paste) the command without the leading $ (but be sure to include any other $ characters not at the start). Other text may appear in a grey box as well, without a leading $. The meaning of this text will be clear from context.

Remove existing jhbuild install

It's possible that you're visiting this page after having used jhbuild before (or getting half-way through trying to use it). You should make sure that any files you created before are removed so that we can start fresh.

Specifically, ensure that none of these exist:

• ~/bin/jhbuild

• ~/.local/bin/jhbuild

• ~/.local/share/jhbuild/

• ~/.cache/jhbuild/

• ~/.config/jhbuildrc

• ~/.jhbuildrc

• ~/jhbuild/

Be extremely careful when copying the following command. A very small mistake (such as a misplaced space) could result in deleting large numbers of your personal files.

 $ rm -rf ~/bin/jhbuild ~/.local/bin/jhbuild ~/.local/share/jhbuild ~/.cache/jhbuild ~/.config/jhbuildrc ~/.jhbuildrc ~/jhbuild

You may also have a ~/checkout/ directory that was created by jhbuild. It is safe to erase this directory as long as you have not placed files in it by yourself. Depending on how far you got with a previous jhbuild setup, you may also have an /opt/gnome/ directory that can be deleted.

Some jhbuild setup instructions also advise you to modify your ~/.bashrc by adding a PATH= line. This will cause some very serious problems, so you should ensure that you have not done this. Check your .bashrc file to ensure that there are no lines at the very bottom saying something about 'export PATH=(big list of directories)'. If you find that line, erase it.

Finally, remove any distribution package for jhbuild you may have installed (apt-get remove jhbuild, yum remove jhbuild). These packages are almost always out of date and it's best to avoid them.

Understanding the directory layout

The jhbuild setup described on this page will result in the following directories and files existing.

We group these sets of files into two categories:

• the files that comprise jhbuild itself
• files created by jhbuilding (downloading, compiling and installing GNOME programs)

Almost all files that we create will be installed in the newly-created ~/jhbuild/ directory.

Files that comprise jhbuild itself

• we will download jhbuild in ~/jhbuild/jhbuild/

• jhbuild will install itself into two locations:

  • ~/.local/share/jhbuild/ - the bulk of files will be installed to this directory

  • ~/.local/bin/jhbuild - the main executable will be installed as this file

• ~/bin/jhbuild - we will create this symbolic link so that jhbuild is in the PATH

Files created by jhbuilding

• ~/.cache/jhbuild/downloads/ - jhbuild will download .tar.gz files to here

• ~/jhbuild/checkout/ - jhbuild will unpack and compile software in this directory

• ~/jhbuild/install - jhbuild will install software into this directory

Download and install jhbuild

First, create the ~/jhbuild/ directory mentioned above.

 $ mkdir ~/jhbuild

If you get an error saying that the directory already exists then you should probably delete it and create it again freshly. Old files hanging around in this directory can cause problems later on.

Change into that directory and use git to download jhbuild from gitlab.gnome.org:

 $ cd ~/jhbuild
 $ git clone --depth=1 https://gitlab.gnome.org/GNOME/jhbuild.git

You should see something along these lines:

Cloning into 'jhbuild'...
remote: Counting objects: 32729, done.
remote: Compressing objects: 100% (10433/10433), done.
remote: Total 32729 (delta 25359), reused 28610 (delta 22178)
Receiving objects: 100% (32729/32729), 6.40 MiB | 701 KiB/s, done.
Resolving deltas: 100% (25359/25359), done.

After that is done, enter the ~/jhbuild/jhbuild directory.

 $ cd ~/jhbuild/jhbuild

The easiest and fastest way to make and install jhbuild is using the 'simple install' option:

 $ ./autogen.sh --simple-install
 $ make
 $ make install

jhbuild should now be installed.

Ensure ~/.local/bin or ~/bin/ exists and is in your PATH

PATH is an environment variable that gives a list of directories to search for commands. If you type "foo" at the shell prompt then the shell looks for a file named "foo" in each of the directories listed in PATH, in order.

You can view the current value of your PATH by typing:

 $ echo $PATH

It should contain various directories with names like /usr/bin/. There are usually between about 5 and 10 of them depending on how your distribution sets things up.

Most distributions (Fedora, Debian, Ubuntu, etc.) will automatically add ~/bin/ or ~/.local/bin to your path if it exists on login. If ~/.local/bin is in your PATH, skip to the next step. If not, create the ~/bin folder if it don't exist.

 $ mkdir ~/bin

Log out of your desktop and log back in again to ensure that the directory is added to your PATH. Use the echo command above to check.

Later on, we will put a link to the jhbuild executable into the ~/bin/ directory. Because it is in your PATH, you will be able to just type "jhbuild" at the command prompt without having to give the full location every time.

Now we have to set up the link in ~/bin/ so that jhbuild is in our PATH:

 $ ln -sf ~/.local/bin/jhbuild ~/bin/jhbuild

Again, if you get an error that the file already exists, you should delete ~/bin/jhbuild and try to create it fresh, using the above command.

~/.config/jhbuildrc

The JHBuild configuration file allows you to specify a range of options, including which modules and versions should be built, if any modules which should be skipped, and modifications to build options. As of some recent changes to jhbuild, there is no longer a need to use a config file. The default values should be fine.

However, if you want to make some tweaks, you can create the file at ~/.config/jhbuildrc and add configuration modifications to the file. Details on how to use the configuration file can be found in the JHBuild manual. An empty file is the same as having no file at all, so if you want to make changes, you can just create a file with a single line that has your change and grow from there. There is no need to copy a 'sample file' to start with.

At this point your jhbuild should be ready to go.

System dependencies

jhbuild has an integrated "sysdeps" feature to let you know if you have the required packages installed on your system for building a particular GNOME component. You can check with the following command (for example, if you want to build gedit):

$ jhbuild sysdeps gedit

If you are on an rpm-based Linux distribution (Fedora, etc.) then you can also use jhbuild to install sysdeps:

$ jhbuild sysdeps --install gedit

If you are on a dpkg-based Linux distribution (Debian, Ubuntu, etc.) then it is possible to use jhbuild to install sysdeps, but it is slow, and requires that you first install an additional package called apt-file and update its cache from time to time:

$ sudo apt-get install apt-file
$ sudo apt-file update
$ jhbuild sysdeps --install gedit

jhbuild sysdeps doesn't know about a few basic dependencies that you should make sure you have installed. Here is a non-exaustive list:

• git
• gcc
• g++ (gcc-c++)
• docbook-xsl
• python-libxml2

On dpkg-based systems, this might help:

$ sudo apt-get install docbook-xsl build-essential git-core python-libxml2

On rpm-based systems, try this:

$ sudo yum groupinstall "Development Tools"
$ sudo yum install docbook-style-xsl libxml2-python

Using jhbuild

You should now be able to build GNOME programs using jhbuild. Try building something simple:

 $ jhbuild build glib

This will download the code for glib, configure, build and install it for you. It will also install any dependencies that are required. To see a list of other GNOME modules that you can try, see gitlab.gnome.org.

If you want to run programs that you have compiled with jhbuild, you must do so using:

 $ jhbuild run commandname

Running a command explicitly with jhbuild is required so that jhbuild doesn't replace the system-installed version of the command (the one that gets run when you just type commandname) with a possibly-broken new version.

Updating a build

To update a module to use the latest code, simply re-run the original build command (such as jhbuild build glib in the example above). This will update any modules that have changed since the command was last run.

To test local changes that have been made to a module, run:

 $ jhbuild buildone -n modulename

'buildone' only builds the specified module, ignoring any dependencies that may have been updated. The -n option means that the code will not be updated from its online repository. Local changes will be preserved.

If things go wrong

Here are a list of some common issues you may hit:

-bash: jhbuild: Command not found

This means that one way or another, jhbuild is not in your PATH. You should check three things:

First, Ensure that ~/bin/ is in your PATH:

 $ echo $PATH

The path name will be expanded and look like /home/you/bin (where "you" is your username). If it is not there, you probably need to logout of your desktop and log back in again after having created the ~/bin/ directory. It is also possible that your distribution does not automatically add this directory to your PATH: consider filing a bug, or use their support resources to determine how to do this for yourself.

Secondly, ensure that the symbolic link ~/bin/jhbuild exists and points to ~/.local/bin/jhbuild:

 $ ls -l ~/bin/jhbuild

should show something along these lines:

lrwxrwxrwx 1 you you 30 Jun 21 13:55 /home/you/bin/jhbuild -> /home/you/.local/bin/jhbuild

If it does not, you need to create the symbolic link properly. Follow the instructions above.

Finally, ensure that the destination of the symbolic link exists and is executable:

 $ ls -l ~/.local/bin/jhbuild

should show something like:

-rwxr-xr-x 1 you you 775 Jun 21 13:53 /home/you/.local/bin/jhbuild

If not, then jhbuild was not properly installed. Make sure you followed the above instructions properly and that there were no failures at that point.

I am getting errors about /opt/gnome

Old versions of jhbuild tried to install files to /opt/gnome. Make sure you're using the new version of jhbuild, and not from a distro package. You can test if you're using a distro-installed version of jhbuild like so:

$ which jhbuild
/usr/bin/jhbuild

If the file is /usr/bin/jhbuild, then it's a distro-installed version of jhbuild. Uninstall this, and follow the instructions above to set up a more recent, local version from git.

Errors about missing dependencies

You may see errors like:

Required packages:
  System installed packages which are too old:
    (none)
  No matching system package installed:
    python-devel (python3.pc, required=3.2)
    libffi (libffi.pc, required=3.0.0)
    python2-devel (python.pc, required=2.5)
    zlib (zlib.pc, required=1.0)
    flex (required=2.0)
    bison (required=2.0)
    cairo (cairo.pc, required=1.10.2)
jhbuild build: Required system dependencies not installed. Install using the command 'jhbuild sysdeps --install' or to ignore system dependencies use command-line option --nodeps

or

configure: error: libnl development header are required

or

configure: error: Package requirements (udisks2 >= 1.99.0) were not met:

No package 'udisks2' found

These are by far the most common type of error you will see when building software with jhbuild.

This means that you need to install some additional supporting packages from your distribution. On Debian (or Ubuntu) systems these packages usually have names like lib_____-dev where the blank is filled in by the name of the package that is being complained about (for example libudisks2-dev and libnl-dev for the above errors). On RPM-based systems (Fedora, SuSE, etc). the packages usually have names ending with '-devel' rather than '-dev' and may or may not start with lib.

In all cases, these are just conventions, and packages could be named anything at all. Search in your package manager. If that doesn't work, try asking on IRC (#newcomers on irc.gnome.org).

In some cases, 'jhbuild sysdeps --install' (as mentioned above) may help. This is not always reliable, however (but we are trying to improve it).

I am having another problem building a particular module

jhbuild operates by building the bleeding edge development version of GNOME. There are often problems. Check JhbuildIssues to see if your problem is mentioned. Otherwise, try asking for help on the mailing list or IRC channel of the project that fails to build. Often many other people are experiencing the same problems as you are and they may have figured out how to fix them.

Sometimes bugs are related to existing installed or checked out versions of files causing issues with the build of the new version. In this case, option 6, Go to phase "wipe directory and start over", can be very helpful, but it might mean that you need to download the module again.

An even bigger hammer is to quit jhbuild and completely erase your ~/jhbuild/checkout and ~/jhbuild/install directories. You will be left in a clean state but you will have to redownload and recompile everything.

Tips

Here we collect some useful tips for using with JHBuild.

Enable GDB helper script for more descriptive stacktraces

How to enable the GLib GDB helper script under JHBuild so your GDB stacktraces show GLib signal emissions like this instead of this (and some other features provided by the helper script):

• Tested on FEDORA:

  • Install Glib normally from JHBuild ($ jhbuild build glib)

  • Link the directory where Python looks for scripts under JHBuild to the system one:

    $ ln -s /usr/share/gdb/python ~/jhbuild/install/share/gdb/python

    • so now it should look like this:

      $ ls -l ~/jhbuild/install/share/gdb/

      python -> /usr/share/gdb/python

  • Edit your ~/.config/jhbuildrc to add the following so that the directory where the gobject_gdb.py and glib_gdb.py scripts are located can be picked up by Python under JHBuild:

    prependpath('PYTHONPATH', '/home/YOUR_USER/jhbuild/install/share/glib-2.0/gdb')

  • Now configure GDB to use our custom data directory, eg:

    $ echo "set data-directory /home/YOUR_USER/jhbuild/install/share/gdb" >> ~/.config/gdb/gdbinit

  • Now we are done, we can run GDB under JHBuild to show better stacktraces, like this:

    $ jhbuild run gdb --args evince (using evince binary here as an example)