BuildElement - Abstract class for build elements
The BuildElement class is a convenience element one can derive from for implementing the most common case of element.
Abstract method implementations
Element.configure_sandbox()
In Element.configure_sandbox()
,
the BuildElement will ensure that the sandbox locations described by the %{build-root}
and %{install-root}
variables are marked and will be mounted read-write for the
assemble phase
.
The working directory for the sandbox will be configured to be the %{build-root}
,
unless the %{command-subdir}
variable is specified for the element in question,
in which case the working directory will be configured as %{build-root}/%{command-subdir}
.
Element.stage()
In Element.stage()
, the BuildElement
will do the following operations:
Stage all the dependencies in the
Scope.BUILD
scope into the sandbox root.Run the integration commands for all staged dependencies using
Element.integrate()
Stage any Source on the given element to the
%{build-root}
location inside the sandbox, usingElement.stage_sources()
Element.prepare()
In Element.prepare()
,
the BuildElement will run configure-commands
, which are used to
run one-off preparations that should not be repeated for a single
build directory.
Element.assemble()
In Element.assemble()
, the
BuildElement will proceed to run sandboxed commands which are expected to be
found in the element configuration.
Commands are run in the following order:
configure-commands
: Commands to configure the element before buildingbuild-commands
: Commands to build the elementinstall-commands
: Commands to install the results into%{install-root}
strip-commands
: Commands to strip debugging symbols installed binaries
The result of the build is expected to end up in %{install-root}
, and
as such; Element.assemble() method will return the %{install-root}
for
artifact collection purposes.
In addition to the command lists specified above, build elements support
specifying the create-dev-shm
boolean parameter. If configured, this
parameter causes the sandbox to mount a tmpfs filesystem at /dev/shm
.
Example of create-dev-shm:
kind: manual
config:
# Enable /dev/shm
create-dev-shm: true
- class BuildElement(context, project, meta, plugin_conf)
Bases:
Element
- configure(node)
Configure the Plugin from loaded configuration data
- Parameters:
node (dict) – The loaded configuration dictionary
- Raises:
Plugin implementors should implement this method to read configuration data and store it.
Plugins should use the
Plugin.node_get_member()
andPlugin.node_get_list_element()
methods to fetch values from the passed node. This will ensure that a nice human readable error message will be raised if the expected configuration is not found, indicating the filename, line and column numbers.Further the
Plugin.node_validate()
method should be used to ensure that the user has not specified keys in node which are unsupported by the plugin.Note
For Elements, when variable substitution is desirable, the
Element.node_subst_member()
andElement.node_subst_list_element()
methods can be used.
- preflight()
Preflight Check
- Raises:
This method is run after
Plugin.configure()
and after the pipeline is fully constructed.Implementors should simply raise
SourceError
orElementError
with an informative message in the case that the host environment is unsuitable for operation.Plugins which require host tools (only sources usually) should obtain them with
utils.get_host_tool()
which will raise an error automatically informing the user that a host tool is needed.
- get_unique_key()
Return something which uniquely identifies the plugin input
- Returns:
A string, list or dictionary which uniquely identifies the input
This is used to construct unique cache keys for elements and sources, sources should return something which uniquely identifies the payload, such as an sha256 sum of a tarball content.
Elements and Sources should implement this by collecting any configurations which could possibly effect the output and return a dictionary of these settings.
For Sources, this is guaranteed to only be called if
Source.get_consistency()
has not returnedConsistency.INCONSISTENT
which is to say that the Source is expected to have an exact ref indicating exactly what source is going to be staged.
- configure_sandbox(sandbox)
Configures the the sandbox for execution
- Parameters:
sandbox (
Sandbox
) – The build sandbox
:raises (
ElementError
): When the element raises an errorElements 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 errorElements 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)
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 errorElements must implement this method to create an output artifact from its sources and dependencies.
- 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 errorBy default, this method does nothing, but may be overriden to allow configure-like commands.
Since: 1.2
- 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.