Utilities

helix.utils.source(package, resource)

Fetch the content of a specific file in this package.

Parameters

  • package (str) – The package path relative to which the resource exists. In most cases you probably want to supply __name__ to search relative to the current code.

  • resource (str) – The resource filename to load.

Returns

The content of the package resource as a string.

helix.utils.substitute(template, safe=True, **kwargs)

Substitute parameters in a template string.

Template substitution makes use of Python string templates (described in PEP 292).

Parameters

  • template (str) – The template string.

  • safe (bool) – If True, missing parameters will be ignored and some template parameters may remain in the return value.

  • **kwargs – Template parameters.

Returns

The substituted template string.

helix.utils.find(name, environment=None, guess=None)

Finds a particular binary on this system.

Attempts to find the binary given by name, first checking the value of the environment variable named environment (if provided), then by checking the system path, then finally checking hardcoded paths in guess (if provided). This function is cross-platform compatible - it works on Windows, Linux, and Mac. If there are spaces in the path found, this function will wrap its return value in double quotes.

Parameters

  • name (str) – Binary name.

  • environment (str) – An optional environment variable to check.

  • guess (iterable) – An optional list of hardcoded paths to check.

Returns

A string with the absolute path to the binary if found, otherwise None.

helix.utils.run(cmd, cwd=None, exception=None, propagate=False, stdout=None, stderr=None)

Run the given command as a subprocess.

This function caputres stdout and stderr by default and returns them, and raises the given exception if the process fails.

Parameters

  • cmd (str) – The command to run.

  • cwd (str) – The working directory in which to run the command.

  • exception – An exception to raise if the command fails.

  • propagate (bool) – If True, command output will be written to stdout and stderr of the current process, otherwise command output is captured and returned (and written to stdout and stderr if provided). Default: False.

  • stdout (file) – An open file-like object or fileno where stdout should be written or None.

  • stderr (file) – An open file-like object or fileno where stderr should be written or None.

Returns

Output to stdout and stderr as binary strings.

Note

Without adding sufficient complexity (additional threads) output cannot be both captured and printed stdout/stderr of the current process in real time. If this is called with propagate=True, then no output will be returned or written to the provided stdout/stderr arguments.

helix.build.build(configuration, output, options=None)

Build a given configuration.

Builds the given configuration dictionary using output as a working directory.

Parameters

  • configuration – A dictionary describing blueprint, components, and transforms to use for this build.

  • output (str) – The path to the output directory.

  • options (dict) – An optional dictionary of additional options to be passed to the build command.

Returns

A list of build artifact paths.

Example

Example configuration dictionary:

{
    "name": "test",
    "blueprint": {"name": "cmake-cpp"},
    "components": [
        {"name": "minimal-example"},
        {
            "name": "configuration-example",
            "configuration": { "second_word": "world" }
        }
        {"class": components.MinimalExampleComponent}
    ],
    "transforms": [
        ...
    ]
}

Configuration parameters are passed via the configuration key. Note that Blueprints, Components and Transforms may be specified by either name or directly by class.