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.

Element.configure_sandbox()

Configures the Sandbox. This is called before anything else
Element.stage()

Stage dependencies and Sources into the sandbox.
Element.prepare()

Call preparation methods that should only be performed once in the lifetime of a build directory (e.g. autotools’ ./configure).

Optional: If left unimplemented, this step will be skipped.
Element.assemble()

Perform the actual assembly of the element

Miscellaneous¶

Miscellaneous abstract methods also exist:

Element.generate_script()

For the purpose of bst source bundle, an Element may optionally implement this.

Class Reference¶

class Scope¶

Bases: enum.Enum

Types of scope for a given element

ALL = 1¶: All elements which the given element depends on, following all elements required for building. Including the element itself.

BUILD = 2¶: All elements required for building the element, including their respective run dependencies. Not including the given element itself.

RUN = 3¶: All elements required for running the element. Including the element itself.

exception ElementError(message, *, detail=None, reason=None, temporary=False)¶

Bases: buildstream._exceptions.BstError

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

Parameters:	message (str) – The error message to report to the user detail (str) – A possibly multiline, more detailed error message reason (str) – An optional machine readable reason string, used for test cases temporary (bool) – An indicator to whether the error may occur if the operation was run again. (Since: 1.2)

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.

Since: 1.2

BST_FORBID_BDEPENDS = False¶

Whether to raise exceptions if an element has build dependencies.

Since: 1.2

BST_FORBID_SOURCES = False¶

Whether to raise exceptions if an element has sources.

Since: 1.2

normal_name = None¶

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)¶

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(sandbox)¶

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.

prepare(sandbox)¶

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 (`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.

Since: 1.2

assemble(sandbox)¶

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_script()¶

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.

sources()¶

A generator function to enumerate the element sources

Yields:	(`Source`) – 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 (`Scope`) – The scope to iterate in recurse (bool) – Whether to recurse
Yields:	(`Element`) – The dependencies in scope, in deterministic staging order

search(scope, name)¶

Search for a dependency by name

Parameters:	scope (`Scope`) – The scope to search name (str) – The dependency to search for
Returns:	The dependency element, or None if not found.
Return type:	(`Element`)

node_subst_member(node, member_name, default=<object object>)¶

Fetch the value of a string node member, substituting any variables in the loaded value with the element contextual variables.

Parameters:	node (dict) – A dictionary loaded from YAML member_name (str) – The name of the member to fetch default (str) – A value to return when member_name is not specified in node
Returns:	The value of member_name in node, otherwise default
Raises:	`LoadError` – When member_name is not found and no default was provided

This is essentially the same as node_get_member() except that it assumes the expected type is a string and will also perform variable substitutions.

Example:

# Expect a string 'name' in 'node', substituting any
# variables in the returned string
name = self.node_subst_member(node, 'name')

node_subst_list(node, member_name)¶

Fetch a list from a node member, substituting any variables in the list

Parameters:	node (dict) – A dictionary loaded from YAML member_name (str) – The name of the member to fetch (a list)
Returns:	The list in member_name
Raises:	`LoadError`

This is essentially the same as node_get_member() except that it assumes the expected type is a list of strings and will also perform variable substitutions.

node_subst_list_element(node, member_name, indices)¶

Fetch the value of a list element from a node member, substituting any variables in the loaded value with the element contextual variables.

Parameters:	node (dict) – A dictionary loaded from YAML member_name (str) – The name of the member to fetch indices (list of int) – List of indices to search, in case of nested lists
Returns:	The value of the list element in member_name at the specified indices
Raises:	`LoadError`

This is essentially the same as node_get_list_element() except that it assumes the expected type is a string and will also perform variable substitutions.

Example:

# Fetch the list itself
strings = self.node_get_member(node, list, 'strings')

# Iterate over the list indices
for i in range(len(strings)):

    # Fetch the strings in this list, substituting content
    # with our element's variables if needed
    string = self.node_subst_list_element(
        node, 'strings', [ i ])

compute_manifest(*, include=None, exclude=None, orphans=True)¶

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 (list) – An optional list of domains to include files from exclude (list) – An optional list of domains to exclude files from orphans (bool) – Whether to include files not spoken for by split domains
Yields:	(str) – The paths of the files in manifest

stage_artifact(sandbox, *, path=None, include=None, exclude=None, orphans=True, update_mtimes=None)¶

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 (`Sandbox`) – The build sandbox path (str) – An optional sandbox relative path include (list) – An optional list of domains to include files from exclude (list) – An optional list of domains to exclude files from orphans (bool) – Whether to include files not spoken for by split domains update_mtimes (list) – An optional list of files whose mtimes to set to the current time.
Raises:	(`ElementError`) – If the element has not yet produced an artifact.
Returns:	The result describing what happened while staging
Return type:	(`FileListResult`)

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, scope, *, path=None, include=None, exclude=None, orphans=True)¶

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 (`Sandbox`) – The build sandbox scope (`Scope`) – The scope to stage dependencies in path (str) – An optional sandbox relative path include (list) – An optional list of domains to include files from exclude (list) – An optional list of domains to exclude files from orphans (bool) – 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)¶

Integrate currently staged filesystem against this artifact.

Parameters:	sandbox (`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, directory)¶

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

Parameters:	sandbox (`Sandbox`) – The build sandbox directory (str) – An absolute path within the sandbox to stage the sources at

get_public_data(domain)¶

Fetch public data on this element

Parameters:	domain (str) – A public domain name to fetch data for
Returns:	The public data dictionary for the given domain
Return type:	(dict)

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, data)¶

Set public data on this element

Parameters:	domain (str) – A public domain name to fetch data for data (dict) – 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()¶

Fetch the environment suitable for running in the sandbox

Returns:	A dictionary of string key/values suitable for passing to `Sandbox.run()`
Return type:	(dict)

get_variable(varname)¶

Fetch the value of a variable resolved for this element.

Parameters:	varname (str) – The name of the variable to fetch
Returns:	The resolved value for varname, or None if no variable was declared with the given name.
Return type:	(str)