e3_build_tools.definition

Core objects for interacting with e3 environment definition.

Attributes

logger
Specification
Formula

Classes

BuildDefinition	Data structure to store definition of an e3 environment.
SpecificationDefinition	Data structure to make changes to wrappers to create new environments.
Resolver	Class for resolving environment data for build purposes.

Module Contents

e3_build_tools.definition.logger

e3_build_tools.definition.Specification

e3_build_tools.definition.Formula

class e3_build_tools.definition.BuildDefinition(name: str, *, base_ref: str, require_ref: str, modules: Dict[str, e3_build_tools.module.ModuleSource] | None = None)

Data structure to store definition of an e3 environment.

The e3 environment definition includes the list of modules in the e3 environment, and the EPICS base version and require version that the environment will be built for. It provides a set of functions to manage the module list.

name

base_ref

require_ref

modules

property base_version: str

Return e3 base version.

property require_version: str

Return e3 require version.

__str__() → str

Print the list of modules in the environment in YAML format.

__repr__() → str

Return the serialized object.

add_module(module: e3_build_tools.module.ModuleSource) → None

Add a module to the definition.

Raises:

ModuleExistsException: If the module name is already in the existing

modules.

remove_module(module_name: str) → None

Remove a module from the environment.

to_specification(path: pathlib.Path | None = None) → None

Save the current definition to file.

classmethod from_specification(path: pathlib.Path) → BuildDefinition

Construct an EnvironmentDefinition from a specification.

Where a specification is a yaml-file with a specific structure listing the contents of an e3 environment.

Raises:

ModuleExistsException: If the module name is already in the existing

modules.

OSError: If a failure occurs during file opening. TypeError: If input file does not match expected syntax.

class e3_build_tools.definition.SpecificationDefinition(*args, formula, **kwargs)

Bases: BuildDefinition

Data structure to make changes to wrappers to create new environments.

__str__() → str

Print the formula in YAML format.

fetch_starting_reference() → Dict[str, str | Dict[str, str]]

Return the starting of reference for all modules.

update_module_version(module_name: str, version: str) → None

Update the module-level substitution with a new version.

update_global_dependency_from_module(module_name: str) → None

Update the global-level substitution with a new version.

combine_substitutions(name: str) → Dict[str, Dict[str, str]]

Return a deep merge of all substitutions in loaded formula.

submodule_updates(name: str) → Dict[str, str]

Return the submodule updates for a given wrapper.

classmethod from_formula(path: pathlib.Path) → SpecificationDefinition

Construct a SpecificationDefinition from a formula.

Where a formula is a yaml-file with a specific structure listing the contents of an environment definition to make modifications to in order to create a specification.

Raises:

OSError: If a failure occurs during file opening. TypeError: If input file does not match expected syntax. ModuleExistsException: If a module exists more than once in the formula.

class e3_build_tools.definition.Resolver(*, ignore_dependencies: bool = False)

Class for resolving environment data for build purposes.

ignore_dependencies = False

get_sorted_order(environment: BuildDefinition) → List[str]

Return a topological sort of the dependency graph.

The returned list is sorted in an order that ensures all dependencies for a module are built before that module is reached.

The algorithm iterates through the main module list, and then recursively descends through the dependency tree for each module. If a module is already in the sorted list, it is not added again. Modules are added to the sorted list after the recursive call returns so that the module with the dependency is added to the list after the dependency.

Refer to https://en.wikipedia.org/wiki/Topological_sorting#Depth-first_search for more details about the algorithm.