Uniquely identifies a task within the build engine.

It is opaque because that is good module design, and also because there are sibling tasks created by the build engine that parallel the user-defined tasks (which come from create_key).

create_key_for_asset ~module_id ~module_semver ~asset_path () creates a key for the asset at path assetpath within the bundle with module id module_id and version module_semver.

load_state ~config ~initiator ~traces loads the state from the previous builds and from the thunk files of the include directories in config.

The return value is (state, tasks, keys). The keys keys must be fetched and BuildTaskFactory.add_values_tasks_gracefully must be called on them before any user tasks are run.

show_key key returns a human-readable representation of key.

cloak key makes the explicit key key an opaque key.

uncloak key makes the opaque key key an explicit key.

cloak_state state makes the explicit state state an opaque state.

uncloak_state state makes the opaque state state an explicit state.

run_single ~config ~observer_module key executes the given target key with the specified options and returns the up-to-date value for the target.

The return value is the up-to-date state.

Include Directories

includedirs is the list of include directories. The reference implementation does not have any predetermined include directories, so at least one include directory must be specified to be useful. All "values.json", "values.jsonc", "*.values.json", and "*.values.jsonc" files in the include directories are scanned before the targets are built. "*.thunk.json", and "*.thunk.jsonc" files are also scanned but are deprecated.

If an include directory does not exist it is skipped.

If a ".values.json" file can't be read, a warning is issued, but the build process continues.

If there is a duplicate key, an error is issued, and the build process stops.

Time

The build system considers the "current" instant of time to be timestamp. The format of timestamp is (year, month, day, hour, minute) where year is 1970 to 9999, month is 1 to 12, day is 1 to 31, hour is 0 to 23, minute is 0 to 59, and the timezone is UTC.

Errors

observer_module is the module that will receive errors during the build process. It must implement the MlFront_Thunk.ThunkParsers.Results.OBSERVER_RESULT signature.

Throws EngineShutdown if there is a fatal error.

make_tasks_from_values_files ?explain ?parsetrace ?verbose ~threaddir ~includedirs ~timestamp ~inferred_package_id_or_reason_whynone observer_module values_files makes and runs a series of tasks in two phases.

The first BuildCore.Alacarte_3_2_apparatus.O.item.IncludeFile phase parses the ASTs in parallel from the values files values_files while adding tasks for distributions, forms, bundles and assets contained in those ASTs.

The second BuildCore.Alacarte_3_2_apparatus.O.item.Distribution phases runs each distribution task once in parallel. This is to make sure that distribution values can be lazy-loaded so that forms, bundles and assets can depend on the distribution values.

Syntax and semantic errors are reported to observer_module, but errors are skipped.

The return value has the up-to-date state.

Confer run_single.

remove_invalid_values ~config state removes entries from the value store and the trace store that are no longer valid according to the integrity check specified in config.

This is useful to call after loading the state with load_state_and_tasks because the value store may contain entries that are no longer valid due to changes outside of the build system.