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: Context, project: Project, load_element: LoadElement, plugin_conf: str | None, *, artifact_key: str | None = None)

Bases: Element

BST_STRICT_REBUILD = True

Whether to rebuild this element in non strict mode if any of the dependencies have changed.

BST_FORBID_RDEPENDS = True

Whether to raise exceptions if an element has runtime dependencies.

BST_FORBID_SOURCES = True

Whether to raise exceptions if an element has sources.

set_work_dir(work_dir: str | None = None) → None

Sets the working dir

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

Parameters:

work_dir – The working directory. If called without this argument set, it’ll default to the value of the variable cwd.

set_install_root(install_root: str | None = None) → 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 – The install root. If called without this argument set, it’ll default to the value of the variable install-root.

set_root_read_only(root_read_only: bool) → None

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 – Whether to mark the root filesystem as read-only.

layout_add(element: Element, dependency_path: str, location: str) → None

Adds an element to the layout.

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

Parameters:

  • element (Element) – The element to stage.

  • dependency_path (str) – The element relative path to the dependency, usually obtained via the dependency configuration

  • location (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 build dependencies of the element in question at the sandbox root. Otherwise, the specified elements including their runtime dependencies will be staged in their respective locations.

Note

The order of directories in the layout is not significant.

The paths in the layout will be sorted so that elements are staged in parent directories before subdirectories.

The elements for each respective staging directory in the layout will be staged in the predetermined deterministic staging order.

add_commands(group_name: str, command_list: List[str]) → None

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:

  • .SourceError – If it’s a Source implementation

  • .ElementError – If it’s an Element implementation

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 affect the output and return a dictionary of these settings.

For Sources, this is guaranteed to only be called if Source.is_resolved() has returned True which is to say that the Source is expected to have an exact source ref indicating exactly what source is going to be staged.

Note

If your plugin is concerned with API stability, then future extensions of your plugin YAML configuration which affect the unique key returned here should be added to this key with care.

A good rule of thumb is to only compute the new value in the returned key if the value of the newly added YAML key is not equal to it’s default value.

configure_sandbox(sandbox)

Configures the the sandbox for execution

Parameters:

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 – 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 – The build sandbox

Returns:

An absolute path within the sandbox to collect the artifact from

:raises (ElementError): When the element raises an error

Elements must implement this method to create an output artifact from its sources and dependencies.

setup()