Building on a Flatpak SDK

Here we demonstrate how to build and run software using a Flatpak SDK for the base runtime.


This example is distributed with BuildStream in the doc/examples/flatpak-autotools subdirectory.

Project structure

The following is a simple project definition:


name: flatpak-autotools


element-path: elements

    type: arch
    description: The machine architecture
    - x86-64
    - x86-32

Here we use an arch option to allow conditional statements in this project to be made depending on machine architecture. For this example we only support the i386 and x86_64 architectures.

Note that we’ve added a source alias for the repository to download the SDK from.


kind: import
description: Import the base freedesktop SDK
- kind: ostree
  url: gnomesdk:repo/
  gpg-key: keys/gnome-sdk.gpg
  - arch == "x86-64":
      track: runtime/org.freedesktop.BaseSdk/x86_64/1.4
      ref: 0d9d255d56b08aeaaffb1c820eef85266eb730cb5667e50681185ccf5cd7c882
  - arch == "x86-32":
      track: runtime/org.freedesktop.BaseSdk/i386/1.4
      ref: 16036b747c1ec8e7fe291f5b1f667cb942f0267d08fcad962e9b7627d6cf1981
  source: files
  target: usr

This is the import element used to import the actual Flatpak SDK, it uses an ostree source to download the Flatpak since these are hosted in OSTree repositories.

While declaring the ostree source, we specify a GPG public key to verify the OSTree download. This configuration is optional but recommended for OSTree repositories. The key is stored in the project directory at keys/gnome-sdk.gpg, and can be downloaded from

We also use conditional statements to decide which branch to download.

For the config section of this import element, it’s important to note two things:

  • source: We only want to extract the files/ directory from the SDK,

    This is becase Flatpak runtimes dont start at the root of the OSTree checkout, instead the actual files start in the files/ subdirectory

  • target: The content we’ve extracted should be staged at /usr

    This is because Flatpak runtimes only contain the data starting at /usr, and they expect to be staged at /usr at runtime, in an environment with the appropriate symlinks setup from /.


kind: import
description: Base usr merge symlinks

# Depend on the base-sdk.bst such that the
# symlinks get added after staging the SDK
- base/sdk.bst

- kind: local
  path: files/links

This is another import element, and it uses the local source type so that we can stage files literally stored in the same repository as the project.

The purpose of this element is simply to add the symlinks for /lib -> /usr/lib, /bin -> /usr/bin and /etc -> /usr/etc, we have it depend on the base/sdk.bst element only to ensure that it is staged after, i.e. the symlinks are created after the SDK is staged.

As suggested by the .bst file, the symlinks themselves are a part of the project and they are stored in the files/links directory.


kind: stack
description: Base stack

- base/sdk.bst
- base/usrmerge.bst

This is just a stack element for convenience sake.

Often times you will have a more complex base to build things on, and it is convenient to just use a stack element for your elements to depend on without needing to know about the inner workings of the base system build.


kind: autotools
description: Autotools project

- base.bst

- kind: local
  path: files/src

Finally, we show an example of an autotools element to build our sample “Hello World” program.

We use another local source to obtain the sample autotools project, but normally you would probably use a git or other source to obtain source code from another repository.

Using the project

Now that we’ve explained the basic layout of the project, here are just a few things you can try to do with the project.


The following examples assume that you have first changed your working directory to the project root.

Build the hello.bst element

To build the project, run bst build in the following way:

user@host:~/flatpak-autotools$ bst build hello.bst

[--:--:--][        ][    main:core activity                 ] START   Build
[--:--:--][        ][    main:core activity                 ] START   Loading elements
[00:00:00][        ][    main:core activity                 ] SUCCESS Loading elements
[--:--:--][        ][    main:core activity                 ] START   Resolving elements
[00:00:00][        ][    main:core activity                 ] SUCCESS Resolving elements
[--:--:--][        ][    main:core activity                 ] START   Resolving cached state
[00:00:00][        ][    main:core activity                 ] SUCCESS Resolving cached state
[--:--:--][        ][    main:core activity                 ] START   Checking sources
[00:00:00][        ][    main:core activity                 ] SUCCESS Checking sources

BuildStream Version 1.3.0+2025.g5a9b3f64.dirty
  Session Start: Tuesday, 09-04-2019 at 13:48:55
  Project:       flatpak-autotools (/home/user/flatpak-autotools)
  Targets:       hello.bst
  Cache Usage:   12K / None (0%)

User Configuration
  Configuration File:      /home/user/.config/buildstream.conf
  Cache Directory:         /home/user/.cache/buildstream
  Log Files:               /home/user/.cache/buildstream/logs
  Source Mirrors:          /home/user/.cache/buildstream/sources
  Build Area:              /home/user/.cache/buildstream/build
  Strict Build Plan:       Yes
  Maximum Fetch Tasks:     10
  Maximum Build Tasks:     4
  Maximum Push Tasks:      4
  Maximum Network Retries: 2

Project Options
  arch: x86-64

   buildable 7eb6e2158599b3d8272db936253cac6c670a6a26a14e4683d9222560812c7f50 base/sdk.bst 
     waiting 6ab7422f7a587b2173f818beb22ab61ffadd8c32e68adbce39b5118b08e2f4fc base/usrmerge.bst 
     waiting fcf89ac9656b81cece176a4ab99b38359e7f9c7c4c1f411a79f64cca278689bb base.bst 
     waiting ee6b6f779f6fb0227e4858e9e120f36898ade69db866fc47f74532114f7f85ea hello.bst 
[--:--:--][7eb6e215][   fetch:base/sdk.bst                  ] START   flatpak-autotools/base-sdk/7eb6e215-fetch.921.log
[--:--:--][7eb6e215][   fetch:base/sdk.bst                  ] START   Staging ref: 0d9d255d56b08aeaaffb1c820eef85266eb730cb5667e50681185ccf5cd7c882 from origin:
[--:--:--][6ab7422f][   fetch:base/usrmerge.bst             ] START   flatpak-autotools/base-usrmerge/6ab7422f-fetch.923.log
[--:--:--][ee6b6f77][   fetch:hello.bst                     ] START   flatpak-autotools/hello/ee6b6f77-fetch.924.log
[--:--:--][6ab7422f][   fetch:base/usrmerge.bst             ] START   Staging local files at files/links
[00:00:00][6ab7422f][   fetch:base/usrmerge.bst             ] SUCCESS Staging local files at files/links
[--:--:--][        ][   fetch:hello.bst-0                   ] START   Staging local files at files/src
[00:00:00][6ab7422f][   fetch:base/usrmerge.bst             ] SUCCESS flatpak-autotools/base-usrmerge/6ab7422f-fetch.923.log
[00:00:00][        ][   fetch:hello.bst-0                   ] SUCCESS Staging local files at files/src
[00:00:00][ee6b6f77][   fetch:hello.bst                     ] SUCCESS flatpak-autotools/hello/ee6b6f77-fetch.924.log
[00:00:18][7eb6e215][   fetch:base/sdk.bst                  ] SUCCESS Staging ref: 0d9d255d56b08aeaaffb1c820eef85266eb730cb5667e50681185ccf5cd7c882 from origin:
[00:00:59][7eb6e215][   fetch:base/sdk.bst                  ] SUCCESS flatpak-autotools/base-sdk/7eb6e215-fetch.921.log
[--:--:--][7eb6e215][   build:base/sdk.bst                  ] START   flatpak-autotools/base-sdk/7eb6e215-build.927.log
[--:--:--][7eb6e215][   build:base/sdk.bst                  ] START   Staging sources
[00:00:00][7eb6e215][   build:base/sdk.bst                  ] SUCCESS Staging sources
[--:--:--][7eb6e215][   build:base/sdk.bst                  ] START   Caching artifact
[00:00:01][7eb6e215][   build:base/sdk.bst                  ] SUCCESS Caching artifact
[00:00:03][7eb6e215][   build:base/sdk.bst                  ] SUCCESS flatpak-autotools/base-sdk/7eb6e215-build.927.log
[--:--:--][6ab7422f][   build:base/usrmerge.bst             ] START   flatpak-autotools/base-usrmerge/6ab7422f-build.932.log
[--:--:--][6ab7422f][   build:base/usrmerge.bst             ] START   Staging sources
[00:00:00][6ab7422f][   build:base/usrmerge.bst             ] SUCCESS Staging sources
[--:--:--][6ab7422f][   build:base/usrmerge.bst             ] START   Caching artifact
[00:00:00][6ab7422f][   build:base/usrmerge.bst             ] SUCCESS Caching artifact
[00:00:00][6ab7422f][   build:base/usrmerge.bst             ] SUCCESS flatpak-autotools/base-usrmerge/6ab7422f-build.932.log
[--:--:--][fcf89ac9][   build:base.bst                      ] START   flatpak-autotools/base/fcf89ac9-build.937.log
[--:--:--][fcf89ac9][   build:base.bst                      ] START   Caching artifact
[00:00:00][fcf89ac9][   build:base.bst                      ] SUCCESS Caching artifact
[00:00:00][fcf89ac9][   build:base.bst                      ] SUCCESS flatpak-autotools/base/fcf89ac9-build.937.log
[--:--:--][ee6b6f77][   build:hello.bst                     ] START   flatpak-autotools/hello/ee6b6f77-build.942.log
[--:--:--][ee6b6f77][   build:hello.bst                     ] START   Staging dependencies
[00:00:04][ee6b6f77][   build:hello.bst                     ] SUCCESS Staging dependencies
[--:--:--][ee6b6f77][   build:hello.bst                     ] START   Integrating sandbox
[00:00:00][ee6b6f77][   build:hello.bst                     ] SUCCESS Integrating sandbox
[--:--:--][ee6b6f77][   build:hello.bst                     ] START   Staging sources
[00:00:00][ee6b6f77][   build:hello.bst                     ] SUCCESS Staging sources
[--:--:--][ee6b6f77][   build:hello.bst                     ] START   Running configure-commands
[--:--:--][ee6b6f77][   build:hello.bst                     ] STATUS  Running command

    export NOCONFIGURE=1;
    if [ -x ./configure ]; then true;
    elif [ -x ./autogen ]; then ./autogen;
    elif [ -x ./ ]; then ./;
    elif [ -x ./bootstrap ]; then ./bootstrap;
    elif [ -x ./ ]; then ./;
    else autoreconf -ivf .;

[--:--:--][ee6b6f77][   build:hello.bst                     ] STATUS  Running command

    ./configure --prefix=/usr \
    --exec-prefix=/usr \
    --bindir=/usr/bin \
    --sbindir=/usr/sbin \
    --sysconfdir=/etc \
    --datadir=/usr/share \
    --includedir=/usr/include \
    --libdir=/usr/lib \
    --libexecdir=/usr/libexec \
    --localstatedir=/var \
    --sharedstatedir=/usr/com \
    --mandir=/usr/share/man \

[00:00:05][ee6b6f77][   build:hello.bst                     ] SUCCESS Running configure-commands
[--:--:--][ee6b6f77][   build:hello.bst                     ] START   Running build-commands
[--:--:--][ee6b6f77][   build:hello.bst                     ] STATUS  Running command


[00:00:00][ee6b6f77][   build:hello.bst                     ] SUCCESS Running build-commands
[--:--:--][ee6b6f77][   build:hello.bst                     ] START   Running install-commands
[--:--:--][ee6b6f77][   build:hello.bst                     ] STATUS  Running command

    make -j1 DESTDIR="/buildstream-install" install

[--:--:--][ee6b6f77][   build:hello.bst                     ] STATUS  Running command

    if false || false; then
      find "/buildstream-install" -name "*.la" -print0 | while read -d '' -r file; do
        if grep '^shouldnotlink=yes$' "${file}" &>/dev/null; then
          if false; then
            echo "Removing ${file}."
            rm "${file}"
            echo "Not removing ${file}."
          if false; then
            echo "Removing ${file}."
            rm "${file}"
            echo "Not removing ${file}."

[00:00:00][ee6b6f77][   build:hello.bst                     ] SUCCESS Running install-commands
[--:--:--][ee6b6f77][   build:hello.bst                     ] START   Running strip-commands
[00:00:00][ee6b6f77][   build:hello.bst                     ] SUCCESS Running strip-commands
[--:--:--][ee6b6f77][   build:hello.bst                     ] START   Caching artifact
[00:00:00][ee6b6f77][   build:hello.bst                     ] SUCCESS Caching artifact
[00:00:12][ee6b6f77][   build:hello.bst                     ] SUCCESS flatpak-autotools/hello/ee6b6f77-build.942.log
[00:01:17][        ][    main:core activity                 ] SUCCESS Build

Pipeline Summary
  Total:       4
  Session:     4
  Fetch Queue: processed 3, skipped 1, failed 0 
  Build Queue: processed 4, skipped 0, failed 0

Run the hello world program

The hello world program has been built into the standard /usr prefix, and will automatically be in the default PATH for running things in a bst shell.

To just run the program, run bst shell in the following way:

user@host:~/flatpak-autotools$ bst shell hello.bst -- hello

[--:--:--][        ][    main:core activity                 ] START   Loading elements
[00:00:00][        ][    main:core activity                 ] SUCCESS Loading elements
[--:--:--][        ][    main:core activity                 ] START   Resolving elements
[00:00:00][        ][    main:core activity                 ] SUCCESS Resolving elements
[--:--:--][        ][    main:core activity                 ] START   Resolving cached state
[00:00:02][        ][    main:core activity                 ] SUCCESS Resolving cached state
[--:--:--][ee6b6f77][    main:hello.bst                     ] START   Staging dependencies
[00:00:04][ee6b6f77][    main:hello.bst                     ] SUCCESS Staging dependencies
[--:--:--][ee6b6f77][    main:hello.bst                     ] START   Integrating sandbox
[00:00:00][ee6b6f77][    main:hello.bst                     ] SUCCESS Integrating sandbox
[--:--:--][ee6b6f77][    main:hello.bst                     ] STATUS  Running command


Hello World!
This is amhello 1.0.