Commands

This page contains documentation for each BuildStream command, along with their possible options and arguments. Each command can be invoked on the command line, where, in most cases, this will be from the project’s main directory.

Top-level commands

bst

Build and manipulate BuildStream projects

Most of the main options override options in the user preferences configuration file.

bst [OPTIONS] COMMAND [ARGS]...

Options

--version
-c, --config <config>

Configuration file to use

-C, --directory <directory>

Project directory (default: current directory)

--on-error <on_error>

What to do when an error is encountered

--fetchers <fetchers>

Maximum simultaneous download tasks

--builders <builders>

Maximum simultaneous build tasks

--pushers <pushers>

Maximum simultaneous upload tasks

--network-retries <network_retries>

Maximum retries for network tasks

--no-interactive

Force non interactive mode, otherwise this is automatically decided

--verbose, --no-verbose

Be extra verbose

--debug, --no-debug

Print debugging output

--error-lines <error_lines>

Maximum number of lines to show from a task log

--message-lines <message_lines>

Maximum number of lines to show in a detailed message

--log-file <log_file>

A file to store the main log (allows storing the main log while in interactive mode)

--colors, --no-colors

Force enable/disable ANSI color codes in output

--strict, --no-strict

Elements must be rebuilt when their dependencies have changed

-o, --option <option>

Specify a project option

--default-mirror <default_mirror>

The mirror to fetch from first, before attempting other mirrors

--pull-buildtrees

Include an element’s build tree when pulling remote element artifacts

--cache-buildtrees <cache_buildtrees>

Cache artifact build tree content on creation

Commands

artifact

Manipulate cached artifacts

build

Build elements in a pipeline

help

Print usage information

init

Initialize a new BuildStream project

shell

Shell into an element’s sandbox environment

show

Show elements in the pipeline

source

Manipulate sources for an element

workspace

Manipulate developer workspaces


bst artifact

Manipulate cached artifacts

bst artifact [OPTIONS] COMMAND [ARGS]...

Commands

checkout

Checkout contents of an artifact

log

Show logs of an artifact

pull

Pull a built artifact

push

Push a built artifact


bst init

Initialize a new BuildStream project

Creates a new BuildStream project.conf in the project directory.

Unless –project-name is specified, this will be an interactive session.

bst init [OPTIONS]

Options

--project-name <project_name>

The project name to use

--format-version <format_version>

The required format version (default: 21)

--element-path <element_path>

The subdirectory to store elements in (default: elements)

-f, --force

Allow overwriting an existing project.conf


bst build

Build elements in a pipeline

Specifying no elements will result in building the default targets of the project. If no default targets are configured, all project elements will be built.

When this command is executed from a workspace directory, the default is to build the workspace element.

bst build [OPTIONS] [ELEMENTS]...

Options

--all

Build elements that would not be needed for the current build plan

--track <track_>

Specify elements to track during the build. Can be used repeatedly to specify multiple elements

--track-all

Track all elements in the pipeline

--track-except <track_except>

Except certain dependencies from tracking

-J, --track-cross-junctions

Allow tracking to cross junction boundaries

--track-save

Deprecated: This is ignored

-r, --remote <remote>

The URL of the remote cache (defaults to the first configured cache)

Arguments

ELEMENTS

Optional argument(s)


bst show

Show elements in the pipeline

Specifying no elements will result in showing the default targets of the project. If no default targets are configured, all project elements will be shown.

When this command is executed from a workspace directory, the default is to show the workspace element.

By default this will show all of the dependencies of the specified target element.

Specify –deps to control which elements to show:

none: No dependencies, just the element itself
plan: Dependencies required for a build plan
run: Runtime dependencies, including the element itself
build: Build time dependencies, excluding the element itself
all: All dependencies
FORMAT
~~~~~~
The –format option controls what should be printed for each element,
the following symbols can be used in the format string:
%{name} The element name
%{key} The abbreviated cache key (if all sources are consistent)
%{full-key} The full cache key (if all sources are consistent)
%{state} cached, buildable, waiting or inconsistent
%{config} The element configuration
%{vars} Variable configuration
%{env} Environment settings
%{public} Public domain data
%{workspaced} If the element is workspaced
%{workspace-dirs} A list of workspace directories
%{deps} A list of all dependencies
%{build-deps} A list of build dependencies
%{runtime-deps} A list of runtime dependencies

The value of the %{symbol} without the leading ‘%’ character is understood as a pythonic formatting string, so python formatting features apply, examle:

bst show target.bst –format
‘Name: %{name: ^20} Key: %{key: ^8} State: %{state}’

If you want to use a newline in a format string in bash, use the ‘$’ modifier:

bst show target.bst –format
$’———- %{name} ———-n%{vars}’
bst show [OPTIONS] [ELEMENTS]...

Options

--except <except_>

Except certain dependencies

-d, --deps <deps>

The dependencies to show (default: all)

--order <order>

Staging or alphabetic ordering of dependencies

-f, --format <format_>

Format string for each element

Arguments

ELEMENTS

Optional argument(s)


bst shell

Run a command in the target element’s sandbox environment

When this command is executed from a workspace directory, the default is to shell into the workspace element.

This will stage a temporary sysroot for running the target element, assuming it has already been built and all required artifacts are in the local cache.

Use ‘–’ to separate a command from the options to bst, otherwise bst may respond to them instead. e.g.

bst shell example.bst – df -h

Use the –build option to create a temporary sysroot for building the element instead.

Use the –sysroot option with an existing failed build directory or with a checkout of the given target, in order to use a specific sysroot.

If no COMMAND is specified, the default is to attempt to run an interactive shell.

bst shell [OPTIONS] [ELEMENT] [COMMAND]...

Options

-b, --build

Stage dependencies and sources to build

-s, --sysroot <sysroot>

An existing sysroot

--mount <mount>

Mount a file or directory into the sandbox

--isolate

Create an isolated build sandbox

-t, --use-buildtree <cli_buildtree>

Defaults to ask but if set to always the function will fail if a build tree is not available

Arguments

ELEMENT

Optional argument

COMMAND

Optional argument(s)


bst source

Manipulate sources for an element

bst source [OPTIONS] COMMAND [ARGS]...

Commands

checkout

Checkout sources for an element

fetch

Fetch sources in a pipeline

track

Track new source references


bst workspace

Manipulate developer workspaces

bst workspace [OPTIONS] COMMAND [ARGS]...

Commands

close

Close workspaces

list

List open workspaces

open

Open a new workspace

reset

Reset a workspace to its original state

Artifact subcommands

bst artifact checkout

Checkout contents of an artifact

When this command is executed from a workspace directory, the default is to checkout the artifact of the workspace element.

bst artifact checkout [OPTIONS] [ELEMENT]

Options

-f, --force

Allow files to be overwritten

-d, --deps <deps>

The dependencies to checkout (default: run)

--integrate, --no-integrate

Whether to run integration commands

Checkout hardlinks instead of copying if possible

--tar <tar>

Create a tarball from the artifact contents instead of a file tree. If LOCATION is ‘-‘, the tarball will be dumped to the standard output.

--directory <directory>

The directory to checkout the artifact to

Arguments

ELEMENT

Optional argument


bst artifact log

Show logs of all artifacts

bst artifact log [OPTIONS] [ARTIFACTS]...

Arguments

ARTIFACTS

Optional argument(s)


bst artifact pull

Pull a built artifact from the configured remote artifact cache.

Specifying no elements will result in pulling the default targets of the project. If no default targets are configured, all project elements will be pulled.

When this command is executed from a workspace directory, the default is to pull the workspace element.

By default the artifact will be pulled one of the configured caches if possible, following the usual priority order. If the –remote flag is given, only the specified cache will be queried.

Specify –deps to control which artifacts to pull:

none: No dependencies, just the element itself
all: All dependencies
bst artifact pull [OPTIONS] [ELEMENTS]...

Options

-d, --deps <deps>

The dependency artifacts to pull (default: none)

-r, --remote <remote>

The URL of the remote cache (defaults to the first configured cache)

Arguments

ELEMENTS

Optional argument(s)


bst artifact push

Push a built artifact to a remote artifact cache.

Specifying no elements will result in pushing the default targets of the project. If no default targets are configured, all project elements will be pushed.

When this command is executed from a workspace directory, the default is to push the workspace element.

The default destination is the highest priority configured cache. You can override this by passing a different cache URL with the –remote flag.

If bst has been configured to include build trees on artifact pulls, an attempt will be made to pull any required build trees to avoid the skipping of partial artifacts being pushed.

Specify –deps to control which artifacts to push:

none: No dependencies, just the element itself
all: All dependencies
bst artifact push [OPTIONS] [ELEMENTS]...

Options

-d, --deps <deps>

The dependencies to push (default: none)

-r, --remote <remote>

The URL of the remote cache (defaults to the first configured cache)

Arguments

ELEMENTS

Optional argument(s)

Source subcommands

bst source fetch

Fetch sources required to build the pipeline

Specifying no elements will result in fetching the default targets of the project. If no default targets are configured, all project elements will be fetched.

When this command is executed from a workspace directory, the default is to fetch the workspace element.

By default this will only try to fetch sources which are required for the build plan of the specified target element, omitting sources for any elements which are already built and available in the artifact cache.

Specify –deps to control which sources to fetch:

none: No dependencies, just the element itself
plan: Only dependencies required for the build plan
all: All dependencies
bst source fetch [OPTIONS] [ELEMENTS]...

Options

--except <except_>

Except certain dependencies from fetching

-d, --deps <deps>

The dependencies to fetch (default: plan)

--track

Track new source references before fetching

-J, --track-cross-junctions

Allow tracking to cross junction boundaries

Arguments

ELEMENTS

Optional argument(s)


bst source track

Consults the specified tracking branches for new versions available to build and updates the project with any newly available references.

Specifying no elements will result in tracking the default targets of the project. If no default targets are configured, all project elements will be tracked.

When this command is executed from a workspace directory, the default is to track the workspace element.

If no default is declared, all elements in the project will be tracked

By default this will track just the specified element, but you can also update a whole tree of dependencies in one go.

Specify –deps to control which sources to track:

none: No dependencies, just the specified elements
all: All dependencies of all specified elements
bst source track [OPTIONS] [ELEMENTS]...

Options

--except <except_>

Except certain dependencies from tracking

-d, --deps <deps>

The dependencies to track (default: none)

-J, --cross-junctions

Allow crossing junction boundaries

Arguments

ELEMENTS

Optional argument(s)


bst source checkout

Checkout sources of an element to the specified location

When this command is executed from a workspace directory, the default is to checkout the sources of the workspace element.

bst source checkout [OPTIONS] [ELEMENT] [LOCATION]

Options

-f, --force

Allow files to be overwritten

--except <except_>

Except certain dependencies

-d, --deps <deps>

The dependencies whose sources to checkout (default: none)

--fetch

Fetch elements if they are not fetched

--tar

Create a tarball from the element’s sources instead of a file tree.

--include-build-scripts

Arguments

ELEMENT

Optional argument

LOCATION

Optional argument

Workspace subcommands

bst workspace open

Open a workspace for manual source modification

bst workspace open [OPTIONS] ELEMENTS...

Options

--no-checkout

Do not checkout the source, only link to the given directory

-f, --force

The workspace will be created even if the directory in which it will be created is not empty or if a workspace for that element already exists

--track

Track and fetch new source references before checking out the workspace

--directory <directory>

Only for use when a single Element is given: Set the directory to use to create the workspace

Arguments

ELEMENTS

Required argument(s)


bst workspace close

Close a workspace

bst workspace close [OPTIONS] [ELEMENTS]...

Options

--remove-dir

Remove the path that contains the closed workspace

-a, --all

Close all open workspaces

Arguments

ELEMENTS

Optional argument(s)


bst workspace reset

Reset a workspace to its original state

bst workspace reset [OPTIONS] [ELEMENTS]...

Options

--soft

Reset workspace state without affecting its contents

--track

Track and fetch the latest source before resetting

-a, --all

Reset all open workspaces

Arguments

ELEMENTS

Optional argument(s)


bst workspace list

List open workspaces

bst workspace list [OPTIONS]