Element - Base element class

Abstract Methods

For loading and configuration purposes, Elements must implement the Plugin base class abstract methods.

Build Phase

The following methods are the foundation of the element’s build phase, they must be implemented by all Element classes, unless explicitly stated otherwise.

Miscellaneous

Miscellaneous abstract methods also exist:

  • Element.generate_script()

    For the purpose of bst source checkout --include-build-scripts, an Element may optionally implement this.

Class Reference

exception ElementError(message: str, *, detail: str = None, reason: str = None, collect: str = None, temporary: bool = False)

Bases: buildstream._exceptions.BstError

This exception should be raised by Element implementations to report errors to the user.

Parameters

  • message – The error message to report to the user

  • detail – A possibly multiline, more detailed error message

  • reason – An optional machine readable reason string, used for test cases

  • collect – An optional directory containing partial install contents

  • temporary – An indicator to whether the error may occur if the operation was run again.

class Element

Bases: buildstream.plugin.Plugin

Base Element class.

All elements derive from this class, this interface defines how the core will be interacting with Elements.

BST_ARTIFACT_VERSION = 0

The element plugin’s artifact version

Elements must first set this to 1 if they change their unique key structure in a way that would produce a different key for the same input, or introduce a change in the build output for the same unique key. Further changes of this nature require bumping the artifact version.

BST_STRICT_REBUILD = False

Whether to rebuild this element in non strict mode if any of the dependencies have changed.

BST_FORBID_RDEPENDS = False

Whether to raise exceptions if an element has runtime dependencies.

BST_FORBID_BDEPENDS = False

Whether to raise exceptions if an element has build dependencies.

BST_FORBID_SOURCES = False

Whether to raise exceptions if an element has sources.

BST_RUN_COMMANDS = True

Whether the element may run commands using Sandbox.run.

BST_ELEMENT_HAS_ARTIFACT = True

Whether the element produces an artifact when built.

normal_name

A normalized element name

This is the original element without path separators or the extension, it’s used mainly for composing log file names and creating directory names and such.

configure_sandbox(sandbox: Sandbox) → None

Configures the the sandbox for execution

Parameters

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(sandbox: Sandbox) → None

Stage inputs into the sandbox directories

Parameters

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.

prepare(sandbox: Sandbox) → None

Run one-off preparation commands.

This is run before assemble(), but is guaranteed to run only the first time if we build incrementally - this makes it possible to run configure-like commands without causing the entire element to rebuild.

Parameters

sandbox – The build sandbox

:raises (ElementError): When the element raises an error

By default, this method does nothing, but may be overriden to allow configure-like commands.

assemble(sandbox: Sandbox) → str

Assemble the output artifact

Parameters

sandbox – The build sandbox

Returns

An absolute path within the sandbox to collect the artifact from

:raises (ElementError): When the element raises an error

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

generate_script() → str

Generate a build (sh) script to build this element

Returns

A string containing the shell commands required to build the element

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.

sources() → Iterator[Source]

A generator function to enumerate the element sources

Yields

The sources of this element

dependencies(scope, *, recurse=True)

A generator function which yields the dependencies of the given element.

If recurse is specified (the default), the full dependencies will be listed in deterministic staging order, starting with the basemost elements in the given scope. Otherwise, if recurse is not specified then only the direct dependencies in the given scope will be traversed, and the element itself will be omitted.

Parameters

  • scope – The scope to iterate in

  • recurse – Whether to recurse

Yields

The dependencies in scope, in deterministic staging order

search(scope: buildstream.types.Scope, name: str) → Optional[buildstream.element.Element]

Search for a dependency by name

Parameters

  • scope – The scope to search

  • name – The dependency to search for

Returns

The dependency element, or None if not found.

node_subst_vars(node: ScalarNode) → str

Replace any variables in the string contained in the node and returns it.

Warning: The method is deprecated and will get removed in the next version

Parameters

node – A ScalarNode loaded from YAML

Returns

The value with all variables replaced

Raises

LoadError – When the node doesn’t contain a string or a variable was not found.

Example:

# Expect a string 'name' in 'node', substituting any
# variables in the returned string
name = self.node_subst_vars(node.get_scalar('name'))
node_subst_sequence_vars(node: SequenceNode[ScalarNode]) → List[str]

Substitute any variables in the given sequence

Warning: The method is deprecated and will get removed in the next version

Parameters

node – A SequenceNode loaded from YAML

Returns

The list with every variable replaced

Raises

LoadError –

compute_manifest(*, include: Optional[List[str]] = None, exclude: Optional[List[str]] = None, orphans: bool = True) → str

Compute and return this element’s selective manifest

The manifest consists on the list of file paths in the artifact. The files in the manifest are selected according to include, exclude and orphans parameters. If include is not specified then all files spoken for by any domain are included unless explicitly excluded with an exclude domain.

Parameters

  • include – An optional list of domains to include files from

  • exclude – An optional list of domains to exclude files from

  • orphans – Whether to include files not spoken for by split domains

Yields

The paths of the files in manifest

get_artifact_name(key: Optional[str] = None) → str

Compute and return this element’s full artifact name

Generate a full name for an artifact, including the project namespace, element name and cache key.

This can also be used as a relative path safely, and will normalize parts of the element name such that only digits, letters and some select characters are allowed.

Parameters

key – The element’s cache key. Defaults to None

Returns

The relative path for the artifact

stage_artifact(sandbox: Sandbox, *, path: str = None, include: Optional[List[str]] = None, exclude: Optional[List[str]] = None, orphans: bool = True) → buildstream.utils.FileListResult

Stage this element’s output artifact in the sandbox

This will stage the files from the artifact to the sandbox at specified location. The files are selected for staging according to the include, exclude and orphans parameters; if include is not specified then all files spoken for by any domain are included unless explicitly excluded with an exclude domain.

Parameters

  • sandbox – The build sandbox

  • path – An optional sandbox relative path

  • include – An optional list of domains to include files from

  • exclude – An optional list of domains to exclude files from

  • orphans – Whether to include files not spoken for by split domains

:raises (ElementError): If the element has not yet produced an artifact.

Returns

The result describing what happened while staging

Note

Directories in dest are replaced with files from src, unless the existing directory in dest is not empty in which case the path will be reported in the return value.

Example:

# Stage the dependencies for a build of 'self'
for dep in self.dependencies(Scope.BUILD):
    dep.stage_artifact(sandbox)
stage_dependency_artifacts(sandbox: Sandbox, scope: buildstream.types.Scope, *, path: str = None, include: Optional[List[str]] = None, exclude: Optional[List[str]] = None, orphans: bool = True) → None

Stage element dependencies in scope

This is primarily a convenience wrapper around Element.stage_artifact() which takes care of staging all the dependencies in scope and issueing the appropriate warnings.

Parameters

  • sandbox – The build sandbox

  • scope – The scope to stage dependencies in

  • An optional sandbox relative path (path) –

  • include – An optional list of domains to include files from

  • exclude – An optional list of domains to exclude files from

  • orphans – Whether to include files not spoken for by split domains

:raises (ElementError): If any of the dependencies in scope have not yet produced artifacts, or if forbidden overlaps occur.

integrate(sandbox: Sandbox) → None

Integrate currently staged filesystem against this artifact.

Parameters

sandbox – The build sandbox

This modifies the sysroot staged inside the sandbox so that the sysroot is integrated. Only an integrated sandbox may be trusted for running the software therein, as the integration commands will create and update important system cache files required for running the installed software (such as the ld.so.cache).

stage_sources(sandbox: Sandbox, directory: str) → None

Stage this element’s sources to a directory in the sandbox

Parameters

  • sandbox – The build sandbox

  • directory – An absolute path within the sandbox to stage the sources at

get_public_data(domain: str) → MappingNode[Any, Any]

Fetch public data on this element

Parameters

domain – A public domain name to fetch data for

Returns:

Note

This can only be called the abstract methods which are called as a part of the build phase and never before.

set_public_data(domain: str, data: MappingNode[Any, Any]) → None

Set public data on this element

Parameters

  • domain – A public domain name to fetch data for

  • data – The public data dictionary for the given domain

This allows an element to dynamically mutate public data of elements or add new domains as the result of success completion of the Element.assemble() method.

get_environment() → Dict[str, str]

Fetch the environment suitable for running in the sandbox

Returns

A dictionary of string key/values suitable for passing to Sandbox.run()

get_variable(varname: str) → Optional[str]

Fetch the value of a variable resolved for this element.

Parameters

varname – The name of the variable to fetch

Returns

The resolved value for varname, or None if no variable was declared with the given name.

batch_prepare_assemble(flags: int, *, collect: Optional[str] = None) → None

Configure command batching across prepare() and assemble()

Parameters

  • flags – The sandbox flags for the command batch

  • collect – An optional directory containing partial install contents on command failure.

This may be called in Element.configure_sandbox() to enable batching of all sandbox commands issued in prepare() and assemble().

get_logs() → List[str]

Obtain a list of log file paths

Returns

A list of log file paths