JHBuild Introduction

If you want to contribute to GNOME applications, please visit the Newcomers page, and follow the instructions you find there.

While GNOME applications can be easily built through Flatpak, system components require deeper integration with your environment. This means that you need to have an updated version of the operating system as a requirement.

In order to avoid damaging the OS installation you're using, GNOME has developed a tool called JHBuild. JHBuild builds GNOME components and their dependencies, and safely installs them in a separate prefix, without interfering with your OS installation.

NOTE: The GNOME release team does not maintain the JHBuild modulesets that define the dependencies of each module; these modulesets are maintained by developers in the community, so they may not reflect latest changes in the modules they reference. Every time you encounter a build issue, make sure to file a bug.

Setting up JHBuild

JHBuild allows you to build and run GNOME platform components and their required modules in a separate environment, isolating the installation from your operating system; this allows you to develop, test, and modify GNOME components without compromising the ability to use your computer.

To download and compile JHBuild you will need to first install some dependencies. Some of the packages listed below are not strictly needed to build JHBuild itself, but we strongly recommend to install them so to avoid common build errors that may happen across GNOME modules.

If you are using Ubuntu 19.04:

$ sudo apt install apt-file docbook docbook-xsl build-essential git-core gettext libtext-csv-perl autotools-dev autoconf gettext pkgconf autopoint yelp-tools libjson-pp-perl libfile-copy-recursive-perl
$ sudo apt-file update

If you are using Fedora:

$ sudo dnf install @c-development @development-tools redhat-rpm-config gnome-common python3-devel python3-gobject python3-gobject-base python3-gobject-base-noarch python3-dbus perl-Text-CSV perl-XML-Parser gettext-devel gtk-doc ninja-build perl-JSON-PP perl-File-Copy-Recursive docbook-style-xsl docbook5-style-xsl docbook-utils unicode-ucd autoconf-archive appstream-devel libappstream-glib-devel sassc vala cmake meson

If you are using openSUSE Tumbleweed:

$ sudo zypper install jhbuild-recommended-deps

Then, create a folder structure for the code. Given that JHBuild will use ~/jhbuild/checkout (the tilde ~ means your home directory) for the code of all GNOME stack, we will use that folder for the code of JHBuild as well:

$ mkdir -p ~/jhbuild/checkout

Then download the code with git in that folder:

$ cd ~/jhbuild/checkout
$ git clone https://gitlab.gnome.org/GNOME/jhbuild.git

Now compile and install the code. We can use the standard way to compile and install JHBuild. It will be installed in ~/.local/bin:

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

Now JHBuild should be installed. In some distributions, it might be necessary to add the executable to your PATH environment variable:

$ echo 'PATH=~/.local/bin:$PATH' >> ~/.bashrc; . ~/.bashrc

and restart your terminal.

Your first build

First we need to install some system dependencies and check that JHBuild has been installed properly:

$ jhbuild sysdeps --install
$ jhbuild sanitycheck

There should be no missing "required dependencies" after running jhbuild sysdeps --install (it is OK to be missing "optional dependencies"), and nothing should happen when you run jhbuild sanitycheck. If something is wrong, stop and ask for help.

Next, build a few useful packages that are always good to have. You only need to do this your first time using JHBuild:

$ jhbuild build adwaita-icon-theme dconf glib-networking gvfs libcanberra

Finally, you can build the project you're interested in. For example, if you want to build the current tip of the GTK+ development branch:

$ jhbuild build gtk+

JHBuild will go through the module and its dependencies one at a time, downloading the development code, configuring, compiling and installing it for you.

It will create ~/jhbuild/checkout/ and ~/jhbuild/install directories in your home directory; it will also create a temporary ~/.cache/jhbuild directory that will be used to store the intermediate build files.

This will take a little long time, so it's time for a coffee break.

If something goes wrong, see the next chapter at when things go wrong.

When it's done, you will be able to modify or see the source code of the applications. The code will be in ~/jhbuild/checkout, where you can search for the project name.

If you want to stop building and continue later where you were, just kill the process pushing <ctrl> + <c> twice to stop it, and take note in which module you stopped it. To start where you were, just do:

$ jhbuild build gtk+ --start-at=moduleWhereYouStopped

Running software installed through JHBuild

To run a module that you have installed through JHBuild, you just use the run command.

$ jhbuild run gtk4-demo

Updating a module

You can update the module installed through JHBuild to include any changes to the development code since it was last built. It's not usually necessary to rebuild all of the module's dependencies. JHBuild has the buildone command for this.

$ jhbuild buildone gtk+

Be careful, this switches to master branch and can conflict with your local changes. If you want to build your changes, see section Building a module that you have modified

Never run jhbuild buildone gtk+ unless you have first run jhbuild build gtk+ to build its dependencies.

In the future, if you have problems rebuilding your module with just the buildone command, try running jhbuild build gtk+ again to update its dependencies. The module might require newer versions of its dependencies.

$ jhbuild build -afc gtk+
$ jhbuild run gtk4-demo

And it will update the module and all dependencies to the latest code.

The '-a' option means, 're-run the configuration step'

The '-f' option means, 'build modules even if they haven't changed'

The '-c' option means, 'run make clean before building'

Building a module that you have modified

Once you've built a module, if you modify the source code for that module, you can build and test your changes executing:

$ jhbuild buildone -n gtk+

Or, from within the module's source directory:

$ cd ~/jhbuild/checkout/gtk+
$ jhbuild make

Then, you can run:

$ jhbuild run gtk4-demo

The -n option prevents downloading updates - this will avoid conflicts with local changes you have made.

When things go wrong

Sometimes things will not build the first time you're using JHBuild. Don't worry, though, this is normal and usually is fairly easy to fix. When JHBuild hits a problem it gives you a set of options that you can use which will let you try the build again.

• If there's a problem configuring because of a missing dependency, something like "Config error: No package 'foo-2.0' found", or jhbuild install sysdeps cannot find some dependency, search for which package provides the required library. Usually it means you are missing the devel package. Search for them with:

• Debian/Ubuntu

   $ apt-cache search foo
   $ apt-file search foo.pc

• Fedora

   $ dnf search foo
   $ dnf provides 'pkgconfig(foo)'
   $ dnf provides '*foo.pc'
   -- or, install directly with --
   $ sudo dnf install 'pkgconfig(foo)'

And install the devel version which is usually suffixed with -dev or -devel, i.e. foo-devel.

• If there is an error in Make or Ninja, choose [4] Enter shell, run git clean -xfd, then press Ctrl + d (to exit the shell), then finally select [1] to rebuild.

• If your installation was interrupted (due to Ctrl + C or unstable network, say) and choosing [1] isn't working, it's possible that the installation tree got damaged; choose [6] Go to phase "wipe directory and start over".

• Are you working behind a proxy? If git:// and ftp:// protocols are not allowed, you can follow this guide.

• If you are working behind a proxy on Ubuntu or any other Debian-based systems, please ensure that proxy is set in /etc/apt/apt.conf. You can follow the steps given here.

• If your package manager shows that the required package is already up-to-date (and it's not) or if it's unable to locate the package, then there is a bug. Ask for help.

• Otherwise, ask for help. Here you have a few ways for it.

Further information

If you want further customization, you can create a configuration file named jhbuildrc in ~/.config. See the config reference for details.

For more information about JHBuild commands, see the command reference.

Next steps

Now that you know how to make changes and test it in the desired module you want, the next step is to learn how to approach solving bugs in GNOME.