The BuildElement class is a convenience element one can derive from for implementing the most common case of element.

Description of assemble activities

This element will perform the following steps to assemble an element:

Stage dependencies

The dependencies in the Scope.BUILD scope will be staged at the root of the sandbox

Integrate dependencies

The integration commands taken from the bst public domain of each dependency will be run in the sandbox to create and update caches. Typically ldconfig among other things is run in this step.

Stage sources

Sources are now staged according to their configuration into the %{build-root} directory (normally /buildstream/build) inside the sandbox.

Run commands

Commands are now run in the sandbox.

Commands are taken from the element configuration specified by the given BuildElement subclass, which can in turn be overridden by the user in element declarations (.bst files).

Commands are run in the following order:

  • configure-commands: Commands to configure how the element will build
  • build-commands: Commands to build the element
  • install-commands: Commands to install the results into %{install-root}
  • strip-commands: Commands to strip debugging symbols installed binaries

Sometimes it is interesting to append or prepend commands to an existing command list without replacing it entirely, for this; array composition prepend and append directives can be used.


    - echo "Do something before default configure-commands"

Working Directory

Note that by default the working directory is where the sources are staged in %{build-root}, but this can be overridden to build inside of a subdirectory of the build directory using the command-subdir variable in an element declaration. e.g.:

  command-subdir: src

The above fragment will cause all commands to be run in the src/ subdirectory of the staged sources.

Result collection

Finally, the resulting build artifact is collected from the the %{install-root} directory (which is normally configured as /buildstream/install) inside the sandbox.

All build elements must install into the %{install-root} using whatever semantic the given build system provides to do this. E.g. for standard autotools packages we simply do make DESTDIR=%{install-root} install.

class BuildElement(context, project, artifacts, meta, plugin_conf)

Bases: buildstream.element.Element


Configure the Plugin from loaded configuration data


node (dict) – The loaded configuration dictionary


Plugin implementors should implement this method to read configuration data and store it. Use of the node_get_member() convenience method will ensure that a nice LoadError is triggered whenever the YAML input configuration is faulty.

Implementations may raise SourceError or ElementError for other errors.


During configure, logging is suppressed unless buildstream is run with debugging output enabled.


Preflight Check


This method is run after configure() and after the pipeline is fully constructed. Element plugins are free to use the dependencies() method and inspect public data at this time.

Implementors should simply raise SourceError or ElementError with an informative message in the case that the host environment is unsuitable for operation.

Plugins which require host tools (only sources usually) should obtain them with utils.get_host_tool() which will raise ProgramNotFoundError automatically.


Return something which uniquely identifies the plugin input

Returns:A string, list or dictionary which uniquely identifies the sources to use

This is used to construct unique cache keys for elements and sources, sources should return something which uniquely identifies the payload, such as an sha256 sum of a tarball content. Elements should implement this by collecting any configurations which could possibly effect the output and return a dictionary of these settings.


Configures the the sandbox for execution

Parameters:sandbox (Sandbox) – The build sandbox
Raises:(ElementError) – When the element raises an error

Elements must implement this method to configure the sandbox object for execution.


Stage inputs into the sandbox directories

Parameters:sandbox (Sandbox) – The build sandbox
Raises:(ElementError) – When the element raises an error

Elements must implement this method to populate the sandbox directory with data. This is done either by staging Source objects, by staging the artifacts of the elements this element depends on, or both.


Assemble the output artifact

Parameters:sandbox (Sandbox) – The build sandbox
Returns:An absolute path within the sandbox to collect the artifact from
Return type:(str)
Raises:(ElementError) – When the element raises an error

Elements must implement this method to create an output artifact from its sources and dependencies.


Generate a build (sh) script to build this element

Returns:A string containing the shell commands required to build the element
Return type:(str)

BuildStream guarantees the following environment when the generated script is run:

  • All element variables have been exported.
  • The cwd is self.get_variable(‘build_root’)/self.normal_name.
  • $PREFIX is set to self.get_variable(‘install_root’).
  • The directory indicated by $PREFIX is an empty directory.

Files are expected to be installed to $PREFIX.

If the script fails, it is expected to return with an exit code != 0.