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.

In order to avoid damaging the OS installation you're using, GNOME uses BuildStream. BuildStream builds GNOME components and their dependencies, and safely installs them in a separate environment, without interfering with your OS installation.

Getting Started


In order to build GNOME using BuildStream, you will need at least a recent stable Linux based system, or you can use Docker in some cases as described in the docker installation instructions.

Depending on what you want to build (building all of the release modules will obviously take more space than only building one application that you care about), you will want to have a lot of free disk space. The base runtime providing the system dependencies and toolchain alone will cost a couple of GB. For a full build of GNOME from scratch, we recommend having at least 20GB of free space at your disposal.

Install BuildStream

See the instructions here to install BuildStream. You also need to install bst-external for some extra plugins.

Note that you don't need to have any C compiler or anything beyond the requirements of BuildStream itself, as host tooling will never be used.

Configuring BuildStream

We recommend the following user configuration for building GNOME modules using BuildStream.

Simply create a file at ~/.config/buildstream.conf with the following content:

# This configuration reduces the amount of necessary rebuilds
    strict: False

# This configuration lets you control the number of allowed parallel builds
  builders: 2

For more in depth technical documentation on the user configuration options, see the manual here.

Building GNOME

BuildStream 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.

Download the GNOME project

Download the GNOME Build Metadata repository using git:

$ git clone

This repository is a BuildStream project describing everything about how to build GNOME modules and how they depend on eachother. Choose a directory that you will remember to store this repository because you will need to use is often in order to build GNOME and update the repository with the latest changes.

Your first build

To build a given module (we will be using GTK+ in our examples), run the following command:

$ cd /path/to/gnome-build-meta
$ bst build --track-all sdk/gtk+-3.bst

Your first build will be very slow because a huge amount of dependencies will be built. Expect this to take a few hours to run. Future builds will be much faster.

Running software built with BuildStream

To run an application that you have built, use the shell command.

$ cd /path/to/gnome-build-meta
$ bst shell sdk/gtk+-3.bst

[ ... BuildStream now prepares a sandbox and launches a shell ... ]

$ gtk3-demo

{i} In case you are trying to develop integrated components such as GNOME Shell, GDM, gnome-session or gnome-keyring, these are more difficult and not yet supported. In the future BuildStream will generate a system image for you to test in a VM.


So far we have showed only how to build and run GNOME modules where the source code is opaque and controlled entirely by BuildStream.

However of course you will want to develop your own software within GNOME and test changes you make to any GNOME module, for this we use the workspaces feature.

For example, to open a workspace for GTK+ in your home directory, simply run:

$ cd /path/to/gnome-build-meta
$ bst workspace open sdk/gtk+-3.bst ~/gtk

This will clone the GTK+ repository from the local cache with a checkout at the exact commit which would be used in the present project state, you are now free to pull new changes from the upstream repository at will, switch branches and modify source code directly, the next build will use the content of the workspace directly.

By default, the workspace will use the public upstream git URI, if you have GNOME commit access you may want to change the origin URL in your workspace like so:

$ cd ~/gtk
$ git remote set-url origin ssh://

To speed up development, you might wish to manually build your project rather than relying on bst build to do it for you. You may enter a build shell inside the build directory:

$ cd /path/to/gnome-build-meta
$ bst shell --build sdk/gtk+-3.bst

Updating a single module

It is possible to upgrade only a single dependency at a time and then test that your application works when running against an updated module, without rebuilding everything in between.

For example, to test gedit against a refreshed GTK+, you can run the following commands:

$ cd /path/to/gnome-build-meta
$ bst track sdk/gtk+-3.bst

[ BuildStream fetches the latest GTK+ ]

$ bst build core/gedit.bst

[ This only needs to rebuild GTK+ ]

$ bst shell core/gedit.bst

[ Now you get a shell with your prebuilt gedit, running against an updated GTK+ library ]

Fetching the latest build metadata

You should periodically pull the latest changes from the GNOME Build Metadata repository in order to maximize your chances of a successful build. For example, this is necessary when a module adds a new dependency that is not present in your old checkout of gnome-build-meta.

$ cd /path/to/gnome-build-meta
$ git pull --rebase

When things go wrong

Sometimes things will not build the first time around especially when building the current development branches of everything. When a build fails BuildStream will offer you an interactive prompt with some options to view the log file, or get an interactive shell to debug what was wrong with the build.

Barring any bug which might occur with the tooling, the only causes of failures can be:

  • Network connectivity issues, failing to download some sources
  • A legitimate bug in the modules we build

If a legitimate bug occurs in the build, the only recourses are to:

  • find a previous version of the said module which does not cause the build to break
  • fix the bug yourself

In any case, the first thing to do might be to file a bug against the offending module, whether it is the fault of that module or one of its dependencies will be sorted out by the maintainers.

If you want to fix the bug yourself:

  • Follow the instructions mentioned above to open a workspace on the offending module
    • modify the source code in the workspace
    • try your build again
    • repeat until this works
  • Create a patch, using git format-patch in the regular way, and submit that for review in the appropriate bug tracking

  • When the upstream maintainers of the given module have accepted your patch:
    • close your local workspace using bst workspace close

    • try to build with the new version of the offending module to verify that the fix was successful upstream

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 2018-12-12 09:37:00 by AbderrahimKitouni)