Invoking BuildStream

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

Show the version and exit.

-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

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

--track-save

Write out the tracked references to their element files

Arguments

ELEMENTS

Optional argument(s)

checkout

Checkout a built artifact to the specified directory

bst checkout [OPTIONS] ELEMENT DIRECTORY

Options

-f, --force

Overwrite files existing in checkout directory

--integrate, --no-integrate

Whether to run integration commands

Checkout hardlinks instead of copies (handle with care)

Arguments

ELEMENT

Required argument

DIRECTORY

Required argument

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)

--track

Track new source references before fetching

Arguments

ELEMENTS

Optional argument(s)

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)

-r, --remote <remote>

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

Arguments

ELEMENTS

Optional argument(s)

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)

-r, --remote <remote>

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

Arguments

ELEMENTS

Optional argument(s)

shell

Run a command in the target element’s sandbox environment

This will first 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 with sh -i.

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

Options

-b, --build

Create a build sandbox

-s, --sysroot <sysroot>

An existing sysroot

Arguments

ELEMENT

Required argument

COMMAND

Optional argument(s)

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)

--order <order>

Staging or alphabetic ordering of dependencies

-f, --format <format>

Format string for each element

--downloadable

Refresh downloadable state

Arguments

ELEMENTS

Optional argument(s)

source-bundle

Produce a source bundle to be manually executed

bst source-bundle [OPTIONS] TARGET

Options

--except <except_>

Elements to except from the tarball

--compression <compression>

Compress the tar file using the given algorithm.

--track

Track new source references before building

-f, --force

Overwrite files existing in checkout directory

--directory <directory>

The directory to write the tarball to

Arguments

TARGET

Required argument

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 element itself all: All dependencies
bst track [OPTIONS] [ELEMENTS]...

Options

--except <except_>

Except certain dependencies from tracking

-d, --deps <deps>

The dependencies to track (default: none)

Arguments

ELEMENTS

Optional argument(s)

workspace

Manipulate developer workspaces

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

close

Close a workspace

bst workspace close [OPTIONS] ELEMENT

Options

-s, --source <source>

The source of the workspace to remove. Projects with one source may omit this

--remove-dir

Remove the path that contains the closed workspace

Arguments

ELEMENT

Required argument

list

List open workspaces

bst workspace list [OPTIONS]

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

-s, --source <source>

The source to create a workspace for. Projects with one source may omit this

--track

Track and fetch new source references before checking out the workspace

Arguments

ELEMENT

Required argument

DIRECTORY

Required argument

reset

Reset a workspace to its original state

bst workspace reset [OPTIONS] ELEMENT

Options

-s, --source <source>

The source of the workspace to reset. Projects with one source may omit this

--track

Track and fetch the latest source before resetting

--no-checkout

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

Arguments

ELEMENT

Required argument