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
- 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
-
--pull-buildtrees¶ Include an element’s build tree when pulling remote element artifacts
-
--cache-buildtrees<cache_buildtrees>¶ Cache artifact build tree content on creation
- Options
always|auto|never
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
Some subcommands take artifact references as arguments. Artifacts can be specified in two ways:
When elements are given, the artifact corresponding to the element is used.
The commands also support shell-style wildcard expansion: ? matches a single character, and * matches zero or more. The patterns are matched against artifact refs by default. If the pattern ends with .bst then it matches element paths instead. Some example arguments are:
bst artifact [OPTIONS] COMMAND [ARGS]...
Commands
-
checkout Checkout contents of an artifact
-
delete Remove artifacts from the local cache
-
list-contents List the contents of an artifact
-
log Show logs of artifacts
-
pull Pull a built artifact
-
push Push a built artifact
-
show Show the cached state of artifacts
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] [TARGET_DIRECTORY]
Options
-
--project-name<project_name>¶ The project name to use
-
--min-version<min_version>¶ The required format version
- Default
2.0
-
--element-path<element_path>¶ The subdirectory to store elements in
- Default
elements
-
-f,--force¶ Allow overwriting an existing project.conf
Arguments
-
TARGET_DIRECTORY¶ Optional argument
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.
Specify –deps to control which dependencies to build:
bst build [OPTIONS] [ELEMENTS]...
Options
-
-d,--deps<deps>¶ The dependencies to build
- Options
build|plan|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
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:
FORMAT
The --format option controls what should be printed for each element,
the following symbols can be used in the format string:
The value of the %{symbol} without the leading ‘%’ character is understood as a pythonic formatting string, so python formatting features apply, example:
If you want to use a newline in a format string in bash, use the ‘$’ modifier:
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
- Default
stage
- 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
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.
Use the –build option to create a temporary sysroot for building the element instead.
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
-
--mount<HOSTPATH PATH>¶ Mount a file or directory into the sandbox
-
--isolate¶ Create an isolated build sandbox
-
-t,--use-buildtree<cli_buildtree>¶ Stage a buildtree. If always is set, will always fail to build if a buildtree is not available. –pull and pull-buildtrees configuration is needed if trying to query for remotely cached buildtrees.
- Default
ask
- Options
ask|try|always|never
-
--pull¶ Attempt to pull missing or incomplete artifacts
Arguments
-
ELEMENT¶ Optional argument
-
COMMAND¶ Optional argument(s)
bst source¶
Manipulate sources for an element
bst source [OPTIONS] COMMAND [ARGS]...
Commands
-
checkout Checkout sources of an element
-
fetch Fetch sources in a pipeline
-
push Push 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] [TARGET]
Options
-
-f,--force¶ Allow files to be overwritten
-
-d,--deps<deps>¶ The dependencies to checkout
- Default
run
- Options
run|build|none|all
-
--integrate,--no-integrate¶ Whether to run integration commands
-
--hardlinks¶ Checkout hardlinks instead of copying if possible
-
--tar<LOCATION>¶ Create a tarball from the artifact contents instead of a file tree. If LOCATION is ‘-‘, the tarball will be dumped to the standard output.
-
--compression<compression>¶ The compression option of the tarball created.
- Options
gz|xz|bz2
-
--pull¶ Pull the artifact if it’s missing or incomplete.
-
--directory<directory>¶ The directory to checkout the artifact to
Arguments
-
TARGET¶ Optional argument
bst artifact log¶
Show build logs of artifacts
bst artifact log [OPTIONS] [ARTIFACTS]...
Options
-
--out<out>¶ Output logs to individual files in the specified path. If absent, logs are written to stdout.
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:
bst artifact pull [OPTIONS] [ARTIFACTS]...
Options
-
-d,--deps<deps>¶ The dependency artifacts to pull
- Default
none
- Options
build|none|run|all
-
-r,--remote<remote>¶ The URL of the remote cache (defaults to the first configured cache)
Arguments
-
ARTIFACTS¶ 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:
bst artifact push [OPTIONS] [ARTIFACTS]...
Options
-
-d,--deps<deps>¶ The dependencies to push
- Default
none
- Options
build|none|run|all
-
-r,--remote<remote>¶ The URL of the remote cache (defaults to the first configured cache)
Arguments
-
ARTIFACTS¶ Optional argument(s)
bst artifact delete¶
Remove artifacts from the local cache
bst artifact delete [OPTIONS] [ARTIFACTS]...
Options
-
-d,--deps<deps>¶ The dependencies to delete
- Default
none
- Options
none|run|build|all
Arguments
-
ARTIFACTS¶ Optional argument(s)
bst artifact show¶
show the cached state of artifacts
bst artifact show [OPTIONS] [ARTIFACTS]...
Options
-
-d,--deps<deps>¶ The dependencies we also want to show
- Default
none
- Options
build|run|all|none
Arguments
-
ARTIFACTS¶ Optional argument(s)
bst artifact list-contents¶
List the contents of an artifact.
Note that ‘artifacts’ can be element names, which must end in ‘.bst’, or artifact references, which must be in the format <project_name>/<element>/<key>.
bst artifact list-contents [OPTIONS] [ARTIFACTS]...
Options
-
-l,--long¶ Provide more information about the contents of the artifact.
Arguments
-
ARTIFACTS¶ 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:
bst source fetch [OPTIONS] [ELEMENTS]...
Options
-
--except<except_>¶ Except certain dependencies from fetching
-
-d,--deps<deps>¶ The dependencies to fetch
- Default
plan
- Options
plan|none|build|run|all
-
-r,--remote<remote>¶ The URL of the remote source cache (defaults to the first configured cache)
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:
bst source track [OPTIONS] [ELEMENTS]...
Options
-
--except<except_>¶ Except certain dependencies from tracking
-
-d,--deps<deps>¶ The dependencies to track
- Default
none
- Options
build|run|all|none
-
-J,--cross-junctions¶ Allow crossing junction boundaries
Arguments
-
ELEMENTS¶ Optional argument(s)
bst source push¶
Push sources required to build the pipeline
Specifying no elements will result in pushing the sources of the default targets of the project. If no default targets are configured, sources of all project elements will be pushed.
When this command is executed from a workspace directory, the default is to push the sources of the workspace element.
Specify –deps to control which sources to fetch:
bst source push [OPTIONS] [ELEMENTS]...
Options
-
-d,--deps<deps>¶ The dependencies to push
- Default
none
- Options
none|plan|build|run|all
-
-r,--remote<remote>¶ The URL of the remote source cache (defaults to the first configured cache)
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]
Options
-
-f,--force¶ Allow files to be overwritten
-
--except<except_>¶ Except certain dependencies
-
-d,--deps<deps>¶ The dependencies whose sources to checkout
- Default
none
- Options
build|none|run|all
-
--tar<LOCATION>¶ Create a tarball containing the sources instead of a file tree.
-
--compression<compression>¶ The compression option of the tarball created.
- Options
gz|xz|bz2
-
--include-build-scripts¶
-
--directory<directory>¶ The directory to checkout the sources to
Arguments
-
ELEMENT¶ 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
-
--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¶ Mark workspace to re-execute configuration steps (if any) on next build. Does not alter workspace contents.
-
-a,--all¶ Reset all open workspaces
Arguments
-
ELEMENTS¶ Optional argument(s)