ScriptElement - Abstract class for scripting elements

The ScriptElement class is a convenience class one can derive for implementing elements that stage elements and run command-lines on them.

Any derived classes must write their own configure() implementation, using the public APIs exposed in this class.

Derived classes must also chain up to the parent method in their preflight() implementations.

class ScriptElement(context, project, artifacts, meta, plugin_conf)

Bases: buildstream.element.Element

BST_STRICT_REBUILD = True
BST_FORBID_RDEPENDS = True
BST_FORBID_SOURCES = True
set_work_dir(work_dir=None)

Sets the working dir

The working dir (a.k.a. cwd) is the directory which commands will be called from.

Parameters:
  • work_dir (str) – The working directory. If called without this argument
  • it'll default to the value of the variable cwd. (set,) –
set_install_root(install_root=None)

Sets the install root

The install root is the directory which output will be collected from once the commands have been run.

Parameters:
  • install_root (str) – The install root. If called without this argument
  • it'll default to the value of the variable install-root. (set,) –
set_root_read_only(root_read_only)

Sets root read-only

When commands are run, if root_read_only is true, then the root of the filesystem will be protected. This is strongly recommended whenever possible.

If this variable is not set, the default permission is read-write.

Parameters:
  • root_read_only (bool) – Whether to mark the root filesystem as
  • read-only. –
layout_add(element, destination)

Adds an element-destination pair to the layout.

Layout is a way of defining how dependencies should be added to the staging area for running commands.

Parameters:
  • element (str) – The name of the element to stage, or None. This may be any element found in the dependencies, whether it is a direct or indirect dependency.
  • destination (str) – The path inside the staging area for where to stage this element. If it is not “/”, then integration commands will not be run.

If this function is never called, then the default behavior is to just stage the Scope.BUILD dependencies of the element in question at the sandbox root. Otherwise, the Scope.RUN dependencies of each specified element will be staged in their specified destination directories.

Note

The order of directories in the layout is significant as they will be mounted into the sandbox. It is an error to specify a parent directory which will shadow a directory already present in the layout.

Note

In the case that no element is specified, a read-write directory will be made available at the specified location.

add_commands(group_name, command_list)

Adds a list of commands under the group-name.

Note

Command groups will be run in the order they were added.

Note

This does not perform substitutions automatically. They must be performed beforehand (see node_subst_list())

Parameters:
  • group_name (str) – The name of the group of commands.
  • command_list (list) – The list of commands to be run.
preflight()

Preflight Check

Raises:

This method is run after Plugin.configure() and after the pipeline is fully constructed.

Implementors should simply raise SourceError or ElementError 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 returned Consistency.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 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.

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.

setup()