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.

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

Options:: continue | quit | terminate

--fetchers <fetchers>: Maximum simultaneous download tasks

--builders <builders>: Maximum simultaneous build tasks

--pushers <pushers>: Maximum simultaneous upload tasks

--max-jobs <max_jobs>: Number of parallel jobs allowed for a given build task

--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 VALUE>: Specify a project option

--default-mirror <default_mirror>: The mirror to fetch from first, before attempting other mirrors

Commands

build: Build elements in a pipeline

checkout: Checkout a built artifact

fetch: Fetch sources in a pipeline

help: Print usage information

init: Initialize a new BuildStream project

pull: Pull a built artifact

push: Push a built artifact

shell: Shell into an element’s sandbox environment

show: Show elements in the pipeline

source-bundle: Produce a build bundle to be manually executed

track: Track new source references

workspace: Manipulate developer workspaces

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: 18)

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

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

Arguments

ELEMENTS: Optional argument(s)

bst fetch

Fetch sources required to build the pipeline

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 fetch [OPTIONS] [ELEMENTS]...

Options

--except <except_>: Except certain dependencies from fetching

-d, --deps <deps>

The dependencies to fetch (default: plan)

Options:: none | plan | all

--track: Track new source references before fetching

-J, --track-cross-junctions: Allow tracking to cross junction boundaries

Arguments

ELEMENTS: Optional argument(s)

bst track

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

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 track [OPTIONS] [ELEMENTS]...

Options

--except <except_>: Except certain dependencies from tracking

-d, --deps <deps>

The dependencies to track (default: none)

Options:: none | all

-J, --cross-junctions: Allow crossing junction boundaries

Arguments

ELEMENTS: Optional argument(s)

bst pull

Pull a built artifact from the configured remote artifact cache.

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 pull [OPTIONS] [ELEMENTS]...

Options

-d, --deps <deps>

The dependency artifacts to pull (default: none)

Options:: none | all

-r, --remote <remote>: The URL of the remote cache (defaults to the first configured cache)

Arguments

ELEMENTS: Optional argument(s)

bst push

Push a built artifact to a remote artifact cache.

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

Specify –deps to control which artifacts to push:

none: No dependencies, just the element itself

all: All dependencies

bst push [OPTIONS] [ELEMENTS]...

Options

-d, --deps <deps>

The dependencies to push (default: none)

Options:: none | all

-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

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

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)

Options:: none | plan | run | build | all

--order <order>

Staging or alphabetic ordering of dependencies

Options:: stage | alpha

-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

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 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 <HOSTPATH PATH>: Mount a file or directory into the sandbox

--isolate: Create an isolated build sandbox

Arguments

ELEMENT: Required argument

COMMAND: Optional argument(s)

bst checkout

Checkout a built artifact to the specified location

bst checkout [OPTIONS] ELEMENT LOCATION

Options

-f, --force: Allow files to be overwritten

-d, --deps <deps>

The dependencies to checkout (default: run)

Options:: run | none

--integrate, --no-integrate: Whether to run integration commands

--hardlinks: Checkout hardlinks instead of copies (handle with care)

--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.

Arguments

ELEMENT: Required argument

LOCATION: Required argument

bst source bundle

Produce a source bundle to be manually executed

bst source bundle [OPTIONS] ELEMENT

Options

--except <except_>: Elements to except from the tarball

--compression <compression>

Compress the tar file using the given algorithm.

Options:: none | gz | bz2 | xz

--track: Track new source references before bundling

-f, --force: Overwrite an existing tarball

--directory <directory>: The directory to write the tarball to

Arguments

ELEMENT: Required argument

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

bst workspace open

Open a workspace for manual source modification

bst workspace open [OPTIONS] ELEMENT DIRECTORY

Options

--no-checkout: Do not checkout the source, only link to the given directory

-f, --force: Overwrite files existing in checkout directory

--track: Track and fetch new source references before checking out the workspace

Arguments

ELEMENT: Required argument

DIRECTORY: Required argument

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]