Project Files

TEMU project files provide a way to apply project-scoped configuration, search paths, runtime settings, and startup scripts with a single file.

Project-file support described on this page is new in TEMU 5.0.

Project files can be loaded:

from the command line with temu --project <file>
with target selection from the command line using temu --project <file> --target <name>
from the C API with temu_loadProject(path, target)

Project files are intended for settings that belong to a runnable project rather than to one user account.

Command Line Usage

To load a project file on startup:

temu --project ./temu-project.yaml

To load a specific target within the project:

temu --project ./temu-project.yaml --target bare-metal

When --project is given by itself, TEMU loads the project file, runs the configured startup scripts, and then enters interactive mode.

When --project is combined with other --run-* options or positional scripts, TEMU respects the command-line order. For example:

temu ./tests/paths.temu --project ./temu-project.yaml

runs ./tests/paths.temu before the project is loaded, while:

temu --project ./temu-project.yaml ./post-startup.temu

loads the project first and runs ./post-startup.temu afterwards.

C API Usage

The support library exposes the following function:

int temu_loadProject(const char *path, const char *target);

temu_loadProject() is new in TEMU 5.0.

The function:

loads the project file
applies its configuration values with project priority
resolves project-relative paths
runs configured startup scripts
runs target-specific startup scripts when target is set

It returns 0 on success and non-zero on failure.

File Format

A project file is a YAML mapping.

The currently supported top-level keys are:

project: Project metadata such as project name, vendor, copyright, and license.
paths: Common project search paths mapped onto the normal configuration system.
runtime: Runtime output locations such as the runtime root, log directory, and snapshot directory.
config: Additional project-scoped configuration values.
startup: Startup scripts to run after the project configuration has been applied.
targets: Optional named target entries that can add target-specific configuration and startup scripts.

Example

version: 1

project:
  name: foo
  vendor: Vendor Name
  copyright: Acme Inc
  license: Commercial

paths:
  plugins:
    prepend:
      - build/plugins
  temu_scripts:
    prepend:
      - scripts/temu
  python:
    prepend:
      - scripts/python
  components:
    prepend:
      - components
  target:
    prepend:
      - target

runtime:
  root: .temu
  logs: logs
  snapshots: snapshots

config:
  logging:
    file:
      mode: auto

startup:
  temu-scripts:
    - scripts/temu/imports.temu
    - scripts/temu/startup.temu

targets:
  bare-metal:
    startup:
      temu-scripts:
        - scripts/temu/run-bare-metal.temu

Project Metadata

The project section describes the project itself.

The currently used keys are:

project/name
project/vendor
project/copyright
project/license

These values are exposed through the configuration system when the project is loaded. The scaffolded plugin template uses this metadata for generated plugin metadata fields.

Path Mappings

The paths section is a convenience layer over the normal configuration system.

The currently supported mappings are:

paths.plugins → plugins/paths
paths.temu_scripts → scripts/paths
paths.python → python/paths
paths.components → components/paths
paths.target → target/paths
paths.sources → sources/paths

Each entry accepts either a plain list or explicit list operations:

replace
prepend
append
remove

Example:

paths:
  plugins:
    prepend:
      - build/plugins
  components:
    append:
      - third-party/components

Configuration Values

The config section maps directly to normal TEMU configuration keys. Nested YAML keys are flattened using /.

For example:

config:
  logging:
    stderr: true

sets the configuration key logging/stderr.

This section is intended for configuration values that do not have a dedicated top-level project-file section.

Examples include:

logging/stderr
logging/file/mode
logging/file/path
logging/with-cycles

Scalars

Scalar values in the project file replace lower-priority values from the user configuration file.

Lists

List-valued configuration entries may be written either as plain sequences or using list operations.

A plain sequence means replace:

config:
  plugins:
    paths:
      - build/plugins
      - deploy/plugins

The explicit list operations are:

replace
prepend
append
remove

Runtime Paths

The runtime section configures where generated runtime state is written.

The main keys are:

runtime/root
runtime/logs
runtime/snapshots

Path resolution intentionally differs slightly between these keys:

runtime/root is resolved relative to the project file directory
runtime/logs and runtime/snapshots are interpreted relative to runtime/root unless set to absolute paths

So with:

runtime:
  root: .temu
  logs: logs
  snapshots: snapshots

the effective runtime directories are:

<project>/.temu/logs
<project>/.temu/snapshots

Similarly, logging/file/path is interpreted relative to runtime/logs when file logging mode is explicit.

Path Resolution

Relative paths in project files are generally resolved relative to the project file directory for project-owned path values.

This includes, for example:

paths.plugins
paths.temu_scripts
paths.python
paths.components
paths.target
project startup script paths
runtime/root

This makes project files relocatable as long as their referenced files remain in the same relative layout.

Startup Scripts

The startup section can contain:

temu-scripts: TEMU command scripts (.temu, .ts, or similar).
python-scripts: Python startup scripts.

The aliases temu and python are also accepted as list keys.

Relative startup script paths are resolved relative to the project file directory.

The startup scripts run after the project configuration has been applied. This means they can rely on:

project-defined plugin paths
component search paths
script search paths
runtime output directories

Targets

Projects may define an optional targets mapping for target-specific startup and configuration.

Each entry under targets.<name> may contain the same sections as the main project file, except that it is applied after the project-wide configuration. This allows a single project to share:

component setup
common imports
common paths
runtime settings

while selecting different payload or scenario scripts with:

temu --project ./temu-project.yaml --target bare-metal

Target startup scripts are appended after the project-wide startup scripts.

Relationship to User Configuration

User configuration and project files are separate layers.

user configuration is intended for user-scoped preferences
project files are intended for project-scoped runtime setup

Project values override the normal user configuration file, but command-line options still take precedence over project values.