Element

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, *, reason=None)

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
  • reason (str) – An optional machine readable reason string, used for test cases
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.

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.

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=None)

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)

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
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.
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 in the build phase of an element and never before. This may be called in Element.configure_sandbox(), Element.stage() and in Element.assemble()

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

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.

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.