This wiki is no longer updated
The current JHBuild documentation is hosted here: https://gnome.pages.gitlab.gnome.org/jhbuild/
Please contribute any changes upstream: https://gitlab.gnome.org/GNOME/jhbuild/-/tree/master/doc
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:
$ apt-cache search foo $ apt-file search foo.pc
$ 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  Enter shell, run git clean -xfd, then press Ctrl + d (to exit the shell), then finally select  to rebuild.
If your installation was interrupted (due to Ctrl + C or unstable network, say) and choosing  isn't working, it's possible that the installation tree got damaged; choose  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.
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.
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.
So just go to Newcomers/SolveProject and let's start understanding the code.