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

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

Note that you dont 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 --track-save core-deps/gtk+-3.bst

Fetching the latest build metadata

In order to build the latest of GNOME, you will need to get the latest changes from the GNOME Build Metadata repository.

Since BuildStream itself will also make changes to the repository, this is a little bit tricky, use the following commands to always get the latest:

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

Note that BuildStream developers are working on a simplification of this workflow, in the future we will have the option to store the references in a separate file, making this step much more transparent and easy.

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 core-deps/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 core-deps/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://

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 core-deps/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 ]

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-01-29 11:06:59 by TristanVanBerkom)