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:

Class Reference

class Scope(value)

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

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)