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, meta, plugin_conf)
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.
Since: 1.2
- BST_FORBID_SOURCES = True
Whether to raise exceptions if an element has sources.
Since: 1.2
- 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
set –
cwd. (it'll default to the value of the variable) –
- 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
set –
install-root. (it'll default to the value of the variable) –
- 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. –
- set_create_dev_shm(create_dev_shm=False)
Sets whether to use shared memory device in the sandbox
- Parameters:
work_dir (bool) – Whether to enable creation of the shared memory device
- 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
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.
- setup()