Building system components

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.

It is strongly recommended to use either Fedora 27 or Ubuntu 17.10. You will run into build errors using older distributions, like Ubuntu 16.04 or Debian stable. We do have unsupported instructions for other distributions.

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.

Unlike Flatpak, JHBuild does not allow you to build and run the result in a separate container. Additionally, there are limits as to what JHBuild allows you to build, especially when it comes to integration with base OS services.

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.

If you are using Ubuntu 17.10:

$ 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 27:

$ sudo dnf install @c-development @development-tools redhat-rpm-config gnome-common pygobject2 dbus-python perl-Text-CSV perl-XML-Parser gettext-devel gtk-doc ninja-build perl-JSON-PP perl-File-Copy-Recursive

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://git.gnome.org/browse/jhbuild

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. To make sure you can run it directly from the command line, you probably only need to restart your terminal. In some distributions, it might be necessary to add the executable to your PATH environment variable:

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

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

{i} In case you are trying to develop GNOME Shell, it is kind of special, and it needs an argument to replace you current running instance:

$ jhbuild run gnome-shell --replace

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+

{i} 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

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

{i} 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.

{i} The '-a' option means, 're-run autogen.sh'

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

{i} 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+
$ jhbuild run gtk4-demo

{i} 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, 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, 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.

Newcomers/BuildSystemComponent (last edited 2017-11-21 15:42:08 by MichaelCatanzaro)