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: 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 DependencyConfiguration(element: Element, path: str, config: MappingNode | None)

Bases: object

An object representing the configuration of a dependency

This is used to provide dependency configurations for elements which implement Element.configure_dependencies()

element: Element

The dependency Element

path: str

The path used to refer to this dependency

config: MappingNode | None

The custom dependency configuration, or None if no custom configuration was provided

class Element

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

project_name

The name of the owning project

Attention

Combining this attribute with Plugin.name does not provide a unique identifier for an element within a project, this is because multiple junction elements can be used specify the same project as a subproject.

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_dependencies(dependencies: Iterable[DependencyConfiguration]) → None

Configure the Element with regards to it’s build dependencies

Elements can use this method to parse custom configuration which define their relationship to their build dependencies.

If this method is implemented, then it will be called with all direct build dependencies specified in their element declaration in a list.

If the dependency was declared with custom configuration, it will be provided along with the dependency element, otherwise None will be passed with dependencies which do not have any additional configuration.

If the user has specified the same build dependency multiple times with differing configurations, then those build dependencies will be provided multiple times in the dependencies list.

Parameters:

dependencies (list) – A list of DependencyConfiguration objects

Raises:

.ElementError – When the element raises an error

The format of the MappingNode provided as DependencyConfiguration.config method should be called by the implementing plugin in order to validate it.

Note

It is unnecessary to implement this method if the plugin does not support any custom dependency configuration.

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.

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(selection: Sequence[Element] = None, *, recurse: bool = True) → Iterator[Element]

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

This generator gives the Element access to all of the dependencies which it is has access to at build time. As explained in the dependency type documentation, this includes the direct build dependencies of the element being built, along with any transient runtime dependencies of those build dependencies.

Subsets of the dependency graph can be selected using the selection argument,, which must consist of dependencies of this element. If the selection argument is specified as None, then the self element on which this is called is used as the selection.

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

Parameters:

  • selection (Sequence[Element]) – A list of dependencies to select, or None

  • recurse (bool) – Whether to recurse

Yields:

The dependencies of the selection, in deterministic staging order

search(name: str) → Element | None

Search for a dependency by name

Parameters:

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: List[str] | None = None, exclude: List[str] | None = 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: str | None = 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, action: str = <buildstream.types.OverlapAction object>, include: ~typing.List[str] | None = None, exclude: ~typing.List[str] | None = None, orphans: bool = True) → 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

  • action (OverlapAction) – The action to take when overlapping with previous invocations

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

Attention

When staging artifacts with their dependencies, use Element.stage_dependency_artifacts() instead.

stage_dependency_artifacts(sandbox: Sandbox, selection: ~typing.Sequence[Element] = None, *, path: str = None, action: str = <buildstream.types.OverlapAction object>, include: ~typing.List[str] | None = None, exclude: ~typing.List[str] | None = 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 staging order and issueing the appropriate warnings.

The selection argument will behave in the same was as specified by Element.dependencies(), If the selection argument is specified as None, then the self element on which this is called is used as the selection.

Parameters:

  • sandbox (Sandbox) – The build sandbox

  • selection (Sequence[Element]) – A list of dependencies to select, or None

  • path (str) – An optional sandbox relative path

  • action (OverlapAction) – The action to take when overlapping with previous invocations

  • include (List[str]) – An optional list of domains to include files from

  • exclude (List[str]) – An optional list of domains to exclude files from

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

:raises (ElementError): 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[Node]

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[Node]) → 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) → str | None

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.

run_cleanup_commands(sandbox: Sandbox) → None

Run commands to cleanup the build directory.

Parameters:

sandbox – The build sandbox

This may be called at the end of a command batch in Element.assemble() to avoid the costs of capturing the build directory after a successful build.

This will have no effect if the build tree is required after the build.