Installing BuildStream on a Linux distro

BuildStream requires the following base system requirements:

• python3 >= 3.5
• libostree >= v2017.8 with introspection data
• bubblewrap >= 0.1.2
• fuse2
• PyGObject introspection bindings
• psutil python library (so you don’t have to install GCC and python-devel to build it yourself)

BuildStream also depends on the host tools for the Source plugins. Refer to the respective source plugin documentation for host tool requirements of specific plugins.

If you intend to push built artifacts to a remote artifact server, which requires special permissions, you will also need:

• ssh

Installing from source (recommended)

Until BuildStream is available in your distro, you will need to install it yourself from the git repository using python’s pip package manager.

For the purpose of installing BuildStream while there are no distro packages, you will additionally need:

• pip for python3 (only required for setup)
• Python 3 development libraries and headers
• git (to checkout buildstream)

Installing dependencies

Arch Linux

Install the dependencies with:

sudo pacman -S fuse2 ostree bubblewrap git \
               python python-pip python-gobject python-psutil

Debian

Stretch

With stretch, you first need to ensure that you have the backports repository setup as described here

By adding the following line to your sources.list:

deb http://ftp.debian.org/debian stretch-backports main

And then running:

sudo apt-get update

At this point you should be able to get the system requirements with:

sudo apt-get install \
    fuse ostree gir1.2-ostree-1.0 bubblewrap git \
    python3 python3-pip python3-gi python3-psutil
sudo apt-get install -t stretch-backports \
    gir1.2-ostree-1.0 ostree

Buster or Sid

For debian unstable or testing, only the following line should be enough to get the base system requirements installed:

sudo apt-get install \
    fuse ostree gir1.2-ostree-1.0 bubblewrap git \
    python3 python3-pip python3-gi python3-psutil

Fedora

For recent fedora systems, the following line should get you the system requirements you need:

dnf install -y fuse ostree bubblewrap git \
               python3 python3-pip python3-gobject python3-psutil

Installing

Once you have the base system dependencies, you can clone the BuildStream git repository and install it as a regular user:

git clone https://gitlab.com/BuildStream/buildstream.git
cd buildstream
pip3 install --user -e .

This will install buildstream’s pure python dependencies into your user’s homedir in ~/.local and will run BuildStream directly from the git checkout directory.

Keep following the instructions below to ensure that the bst command is in your PATH and to enable bash completions for it.

Note

We recommend the -e option because you can upgrade your installation by simply updating the checked out git repository.

If you want a full installation that is not linked to your git checkout, just omit the -e option from the above commands.

Adjust PATH

Since BuildStream is now installed under your local user’s install directories, you need to ensure that PATH is adjusted.

A regular way to do this is to add the following line to the end of your ~/.bashrc:

export PATH="${PATH}:${HOME}/.local/bin"

Note

You will have to restart your terminal in order for these changes to take effect.

Bash completions

Bash completions are supported by sourcing the buildstream/data/bst script found in the BuildStream repository. On many systems this script can be installed into a completions directory but when installing BuildStream without a package manager this is not an option.

To enable completions for an installation of BuildStream you installed yourself from git, just append the script verbatim to your ~/.bash_completion:

# BuildStream bash completion scriptlet.
#
# On systems which use the bash-completion module for
# completion discovery with bash, this can be installed at:
#
#   pkg-config --variable=completionsdir bash-completion
#
# If BuildStream is not installed system wide, you can
# simply source this script to enable completions or append
# this script to your ~/.bash_completion file.
#
_bst_completion() {
    local IFS=$'
'
    COMPREPLY=( $( env COMP_WORDS="${COMP_WORDS[*]}" \
                   COMP_CWORD=$COMP_CWORD \
                   _BST_COMPLETION=complete $1 ) )
    return 0
}

complete -F _bst_completion -o nospace bst;

Upgrading BuildStream

Assuming you have followed the default instructions above, all you need to do to upgrade BuildStream is to update your local git checkout:

cd /path/to/buildstream
git pull --rebase

If you did not specify the -e option at install time, you will need to cleanly reinstall BuildStream:

pip3 uninstall buildstream
cd /path/to/buildstream
git pull --rebase
pip3 install --user .

Installing from distro packages

Arch Linux

Install buildstream from AUR. Alternatively, use buildstream-git for the lastest version of the development branch.