BuildStream, the software integration tool

BuildStream, the software integration tool

Install

Release Snapshot

This page is a "quick start" guide for installing BuildStream, with links to detailed instructions found in the reference documentation.

BuildStream is currently only supported natively on Linux. Users of Unix-like systems where OCI technology is available can still use BuildStream by following the Container Images guide.

Do you need BuildStream 2 or BuildStream 1?

There are two major versions of BuildStream currently supported.

Apache BuildStream 2 is the latest version, stable since 2022 and recommended for all new projects.

BuildStream 1 is the "classic taste" version, stable and supported since 2018. No new feature development is planned for BuildStream 1.

If you want to build a specific project, check its project.conf file for the min-version setting. If the setting is 2.0 or above you need BuildStream 2, if the setting is not present then you need BuildStream 1.

If you want BuildStream 1 and 2 on the same host, you'll need to use a venv as they cannot share a single Python environment. See the "Installing in virtual environments" guide for instructions.

Installing BuildStream 2

If your distribution has an up-to-date buildstream package >= 2.0, use that. Repology has a useful table of package versions.

Otherwise, try installing from PyPI into your home directory:

pip3 install --user 'BuildStream == 2.*'

Note that:

  • Some host packages are required which Pip cannot provide, see the list in the reference manual's "Installing Dependencies" section.

  • BuildStream 2 and its dependency grpc contain binary modules. The pip install command will work differently depending on whether prebuilt 'wheel' packages are available for your platform, and may fail if it can't build from source -- if this happens, follow the full build + install procedure linked below.

The full build + install procedure for BuildStream 2 is documented in the reference manual's "Installing" section.

Installing BuildStream 1

If your distribution has an up-to-date buildstream package < 2.0, use that. Repology has a useful table of package versions.

Otherwise, install from PyPI into your home directory:

pip3 install --user 'BuildStream == 1.*'

Some host packages are required beyond what Pip provides, see the list in the reference manual's "Installing dependencies" section

The full build + install procedure for BuildStream 1 is documented in the reference manual's "Installing from source" section.

Container Images

BuildStream can run inside container tools such as Docker, Podman, and Toolbx.

Prebuilt images containing bst are available at docker.io/buildstream/buildstream via the buildstream-docker-images project. Please read that project's USING.md file for usage instructions.

Note that the Docker --privileged flag is usually needed, as BuildStream runs element build commands in a nested container.

BuildStream Plugins

BuildStream is extensible via plugins written in Python. Projects should provide their own setup instructions they require specific plugins from the host.

Here are some common plugin sets:

Plugins for BuildStream 2:

Plugins for BuildStream 1: