Configuration System

TEMU has a YAML-based configuration system with multiple configuration sources.

The project-file layer, list-valued configuration entries, temu_configGetStringList(), and the path-list configuration entries described on this page are new in TEMU 5.0.

The system is used for:

  • user-scoped preferences

  • project-scoped runtime setup

  • command-line overrides

  • internal API-provided configuration values

Configuration values are exposed through the public temu_configGet*() API and through a small set of CLI inspection commands.

Configuration File Location

By default, TEMU reads user configuration from:

~/.config/temu/config.yaml

The ~/.config/temu/ directory is created automatically during startup if it does not already exist.

The configuration file can be overridden on the command line:

temu --config-file /path/to/config.yaml

Project-scoped configuration can be loaded separately with:

temu --project /path/to/temu-project.yaml
--project is new in TEMU 5.0.

See Project Files for the project-file format.

Configuration Sources

The currently active configuration layers are:

  • built-in defaults

  • user configuration file

  • project file

  • environment overrides for selected settings

  • command-line overrides

  • runtime/API overrides

Higher-priority sources override lower-priority sources.

In general:

  • project values override the user configuration file

  • command-line options override project and user configuration

  • runtime/API changes override all startup configuration

YAML Format

Configuration values are looked up by slash-separated paths such as logging/stderr. Each path component maps to one YAML level.

For example, the following YAML sets three TEMU configuration values:

logging:
  stderr: true

license:
  checkout-script: /home/user/.config/temu/license-checkout.temu

python:
  lib3_13: /opt/python3.13/lib/libpython3.13.so

Scalars and Lists

The configuration system supports both scalar values and string/path lists.

List-valued configuration entries are new in TEMU 5.0.

Scalar values include:

  • bool

  • string

  • signed integers

  • unsigned integers

  • floating-point values

List values are used for search paths such as plugin, script, Python, executable, and OS-awareness configuration paths.

List-valued entries may be written either as a plain sequence or as an operation mapping:

paths:
  executables:
    prepend:
      - build/images
    append:
      - deploy/images

The supported list operations are:

  • replace

  • prepend

  • append

  • remove

Access Patterns

The configuration API provides these lookup functions:

  • temu_configGetBool()

  • temu_configGetString()

  • temu_configGetSigned()

  • temu_configGetUnsigned()

  • temu_configGetDouble()

  • temu_configGetStringList()

temu_configGetStringList() is new in TEMU 5.0.

The TEMU command line also exposes helper commands for inspecting values:

  • config-bool <path>

  • config-str <path>

  • config-int <path>

  • config-uint <path>

  • config-float <path>

  • config-strlist <path>

  • config-pathlist <path>

Queried Configuration Variables

The following table lists the most visible built-in configuration variables and their typical effect.

Table 1. Selected Built-In Configuration Variables
Path Type Default Description Related override

gdb/log-commands

bool

false

Enables extra logging of GDB remote protocol commands in the built-in GDB server.

TEMU_GDB_SERVER_LOG_COMMANDS

license/checkout-script

string

not set

If set, TEMU executes the referenced command file with immediately after successful license initialization.

none

logging/stderr

bool

false

Selects stderr instead of stdout for the standard text logging backend.

TEMU_LOG_STDERR, --log-stderr

logging/with-cycles

bool

false

Uses cycle counts instead of wall-clock timestamps in text logging.

--log-with-cycles

logging/file/mode

string

disabled

Controls file logging. Supported values are disabled, explicit, and auto.

none

logging/file/path

string

not set

Explicit path for file logging when logging/file/mode is explicit.

none

logging/file/timestamp-format

string

%Y-%m-%dT%H-%M-%S

Format string used when auto-generating log filenames.

none

models/mec/debug

bool

false

Enables extra debug behavior for the MEC model and emits an informational message when the device is created.

TEMU_DEBUG_MEC

plugins/loader/debug

bool

false

Enables debug tracing in the plugin loader, for example when searching plugin paths and resolving library names.

TEMU_DEBUG_PLUGIN_LOADER

python/lib3_13

string

not set

Overrides the shared-library path used when TEMU loads Python 3.13 support with dlopen(). If unset, TEMU tries a built-in list of candidate paths.

none

python/paths

path list

empty

Additional Python module search paths.

--python-path

plugins/paths

path list

. plus installation defaults

Additional plugin search paths.

--lib-path, plugin-append-path, plugin-prepend-path, plugin-remove-path

scripts/paths

path list

. plus installation defaults

Script search paths used for exec and other script resolution.

--script-path

paths/executables

path list

.

Search paths for resolving relative executable and image file names.

none

paths/os-awareness-configs

path list

.

Search paths for resolving relative OS-awareness YAML files.

none

runtime/root

path

not set

Base directory for generated runtime state.

none

runtime/logs

path

not set

Base directory for generated log files.

none

runtime/snapshots

path

not set

Base directory for snapshot files.

none

snapshots/json/debug

bool

false

Enables debug logging while deserializing JSON snapshots, including object creation and property restore progress.

TEMU_DEBUG_SNAPSHOTS

Defaults and Fallbacks

Each built-in configuration variable may have a registered default value.

If no active configuration source provides a value, the registered default is used.

The fallback parameter passed to temu_configGet*() is only used if:

  • the key has no active configured value, and

  • the key has no registered default

Related Documentation