lumen.toml reference¶

lumen.toml sits at the app root, beside the src/ directory holding the app's code, and declares everything static about the app: its entry file, window, skin, locale, script engine, runtime modules, build hooks, and subsystem settings. The file is optional; every key has a default.

Unknown top-level sections and unknown keys inside a section are rejected with a parse error naming the offending key. A parse error aborts the command.

Command line flags override the matching config key.

[app]
entry = "main.lmn"
locale = "de-DE"

[window]
title = "My App"
size = [1280, 720]

[skin]
name = "auto"

[script]
engine = "candela"

[app]¶

Auto-detection for kind looks for a Cargo.toml depending on lumen (rust), a CMakeLists.txt (cpp), or a .py file importing lumen (python), and falls back to markup.

[window]¶

[pages]¶

Multi-page navigation. See Pages.

Without include, every .lmn file in src/ is a page except layout.lmn, which contributes its <template> declarations to every page instead of becoming one. Discovery does not descend into subdirectories, so a page kept in one needs an include entry naming it, plus enabled = true when src/ itself holds fewer than two .lmn files. A page's key is its filename stem either way: pages/settings.lmn is settings.

An include entry naming a file that is not there yet is skipped: lumenc prints a warning naming the path, the page is not navigable, and it does not count toward the multi-page default. So the block can list the pages an app will have before they are written. When every entry is missing there is no page set left to run, and the app fails to load naming the file the list asked for.

The entry key resolves in this order: [pages] entry when it names an existing page, then index, then the [app] entry stem, then main, then the first page alphabetically. A skipped entry is not an existing page, so an entry naming one falls through to the next candidate.

[skin]¶

With no skin named, no platform skin applies. A small user-agent stylesheet setting per-tag sizing floors applies to every app either way.

[script]¶

With the key absent, each script file picks its host from its own extension: a .cdl file runs under candela, a .lua file under Lua, a .rhai file under Rhai. An app holding more than one language runs one host per language. An inline <script> block has no extension to read; it joins the app's one external language when there is exactly one, and candela otherwise. Set engine when that is not the host you want, most often for an inline script written in something other than candela.

[mcp]¶

The introspection and automation server. See Testing and Tooling.

The server runs by default for a windowed run. A headless run turns it off unless simulate = true or [runtime] mcp = true.

With simulate on, the server snapshots every tick instead of once a second, so an automation driver sees each frame.

The introspection port has no authentication, so issues defaults to off: turning it on lets any caller that can reach 127.0.0.1:<port> trigger a git/gh subprocess. With it off, lumen_framework_status reports that the lookup is disabled instead of running either command.

[profile]¶

chrome writes lumen-trace.json in the current directory, tracy connects to a running tracy-profiler, and stderr prints per-system spans live. All three need a lumenc built with the profiling cargo feature; tracy also needs profiling-tracy.

[asset_roots]¶

[perf]¶

Per-cache memory budgets.

[runtime]¶

Forces a subsystem on or off at startup instead of letting the runtime decide. Every key is optional; leaving one out keeps the automatic behaviour.

These gate startup, not linkage: the code is still in the binary. To leave a subsystem out of a build, use [capabilities].

[capabilities]¶

Which optional subsystems a build of this app carries, one key per capability name. Two builds read it: lumenc package --static, which links the app from a prebuilt kit and takes only the capabilities the app needs, and lumenc bundle --static, which compiles a runtime from source. The shared runtime and lumenc run always carry everything, and ignore this section.

An entry settles its capability outright. A capability the section leaves out follows its own rule: most are carried when the app's sources (markup, scripts, styles, this file) mention the builtins they answer, and the development ones only when asked for here. A key naming a capability the kit does not carry stops the package and lists what it does.

bundle --static maps the names it knows (http-fetch, async, mcp) to the features it compiles with and ignores the rest.

The script host is selected by [script] engine or inferred from the app's script files, not here.

[web]¶

What lumenc web needs that only a site has. The rest of the file still describes the app: [window] title is the documents' title, [app] gives the entry file and the locale, [pages] the page set, [asset_roots] where an asset comes from, and [script] engine which engine runs the app's code.

[capabilities] does not apply. A site loads one prebuilt runtime that ships with the toolchain, so there is nothing per-app to compile or trim.

[web]
out_dir   = "dist/web"
base_path = "/"
url  = "https://example.com"
host = "netlify"
locales = ["en-US", "de-DE"]

[web.seed]
count = 3
greeting = "Hello"

[[web.seed.todos]]
id    = "1"
title = "write it down"

[web.pages.settings]
title = "Settings"
description = "Everything you can change"
index = false

[web.seed] gives the signals the pages are rendered with, and the same values are handed to the runtime so it starts where the page left off. A value is a string, a number or a boolean. A name written as [[web.seed.<name>]] instead is an array signal: each entry is one row, its keys are the fields a <for> row template reads, and the values are strings. A <for each="<name>"> is emitted with those rows in it, and an element bound to a seeded signal with bind-text, bind-checked, bind-value or bind-disabled is emitted showing that value. A seeded signal beats the default the markup beside the binding would have set, and a script that publishes the signal itself beats both. [web.pages.<key>] sets one page's title and description, which fall back to the site's, and index, which defaults to true. A page with index = false carries <meta name="robots" content="noindex"> and is left out of the sitemap; it keeps its canonical, Open Graph and hreflang metadata.

See the web guide.

[dependencies]¶

The runtime capabilities the app declares, brought in at startup. A name is answered by a module the binary was built with, or by a library beside the app; one table covers both runtime kinds, and the kind is detected at load from the symbols the file exports, never declared:

• A runtime module: an engine-locked Rust dylib with full ECS reach. Its entries carry the name the table key gives it, so a module found under another name is not loaded.
• A portable plugin (lumen_plugin_v1): a C-ABI library offering script functions, language preludes, and events.
• A candela script library: .cdl sources the app's own scripts import. It is not a library the engine opens; it compiles into the app.

One table entry per library; the key is its name.

[dependencies]
lumen-archive = { bundled = true }
lumen-audio = { bundled = true }
lumen-canvas = { bundled = true, tags = ["canvas"] }
lumen-fs = { bundled = true }
markdown-widgets = "1.2"
shape-tools = { path = "modules/shape-tools", config = { units = "mm" } }

The first-party modules ship with the toolchain, so bundled = true is all they need; see runtime modules for getting them onto a machine:

A build that compiles a declared module in answers the name from that copy and opens nothing. A name it neither compiles in nor can open beside a shared engine is skipped with a notice.

Each entry declares exactly one source:

A module that brings a markup element declares it too:

A compile loads nothing, so lumenc build, lumenc check, and lumenc package know an element exists only because the app said so. A run also learns it from the module itself, which registers its tags as it installs - so an app missing the key runs and fails to build. Declare it either way and both paths agree.

The table is unordered, so entries load in sorted-name order; where an entry sits in the file carries no meaning.

Each kind carries its own handshake, verified at load. A runtime module read off disk is version-locked to the exact engine build it was compiled against and opens only on Linux and macOS, into a dynamically linked engine; a module compiled into the executable has nothing to verify and answers on every platform. Windows only has the second shape, which is what lumenc package --static produces, so a Windows package of an app declaring this table is that one. A portable plugin is checked against the plugin ABI version and the script wire version, and loads on every desktop platform, static builds included. Any failure - a missing file, a failed handshake, a library exporting neither entry symbol (the banner names both; a compiler plugin is pointed at [[plugins]]) - is an unmissable stderr banner naming the entry and the reason, and the app starts without it. One case is quieter: a runtime module a statically linked build neither compiled in nor can open is skipped with a single stderr line rather than the banner, because that is a property of how the binary was put together; the line points at lumenc package --static, which compiles the declared modules in. The modules Lumen ships are not in that case: lumenc run carries them, so an app declaring one runs with it during development on every platform. lumenc bundle --static says the same thing at build time, naming the declared modules. lumenc web refuses an app that declares a native library here, because a browser cannot load one; a candela package is script source, so it travels to the web like the app's own scripts.

A declared library is native code loaded into the app's process, the same trust model as [[hooks]]. A permissions key is reserved and rejected; capability declarations are not supported yet. git, rev, and registry sources are reserved and rejected the same way.

Registry packages¶

A version source in [dependencies] or [[plugins]] names a package published to the registry at reg.lumenfx.dev. lpm is the client that resolves those requirements and downloads what they resolve to; every compile path runs it before it compiles, so nothing has to be fetched by hand. See the CLI reference for add, remove, fetch, and update.

A package declares the platform it is for, and the table that named it says what the app wants it for:

A package for any other platform is an error naming both the package and the platform.

Windows is the one gap: an engine-locked runtime module from the registry does not load there, because there is no shared engine for one to load into. Portable plugins, compiler plugins, and candela packages work everywhere.

lumen.lock¶

lpm writes lumen.lock beside lumen.toml, recording the exact version every requirement resolved to. It is format version 2, and lumenc never reads or writes it: the file belongs to lpm.

Commit it. A build from a fresh clone then resolves to the versions the lock names rather than to whatever is newest, which is what makes two machines build the same app. lumenc update is how a pin moves; editing the lock by hand is not.

[[hooks]]¶

Build and setup commands the app declares for itself. Each [[hooks]] entry is one command.

[[hooks]]
when    = "prebuild"
os      = "linux"
run     = "mkdir -p lib && cc -shared -fPIC -O2 -o lib/libmd.so md.c"
inputs  = ["md.c"]
outputs = ["lib/libmd.so"]

The output lands in lib/, the directory a script's dylib import loads shared libraries from (see the project layout).

prebuild hooks fire for lumenc run, build, and bundle. prerun hooks fire for lumenc run only, after every prebuild hook. lumenc check never runs hooks.

Matching hooks run in declaration order with the app directory as the working directory, through sh -c on Linux and macOS and cmd /C on Windows. A hook that exits non-zero aborts the command; later hooks do not run.

A hook is skipped when both inputs and outputs are non-empty, every listed file exists, and every output is at least as new as the newest input. A hook missing either list, or one whose listed files are not all on disk, always runs.

Hooks run shell commands read from a file in the app directory, the same trust model as a Cargo build script. lumenc run --no-hooks skips them.

An unknown when or os value, or an empty run, is a parse error naming the offending value.

[[plugins]]¶

Compiler plugins the app declares. Each entry is one plugin; entries run in declaration order on every compile path (run, build, check, package, web). See authoring compiler plugins for what a plugin can do.

[[plugins]]
name    = "markdown"
version = "1.2"
config  = { flavor = "gfm" }

[[plugins]]
name = "local-dev"
path = "plugins/local-dev"

Declare exactly one source per entry. git, rev, and registry sources are not supported yet and error saying so, and a permissions key is rejected the same way: a plugin is native code running in the compiler's process, the same trust model as a build script.

A version source resolves to a prebuilt, per-platform cdylib the registry publishes, downloaded before the compile that needs it and pinned in lumen.lock. lumenc add markdown --plugin writes the entry and resolves it in one step.

Unlike [[hooks]], plugins also run under lumenc check, so the tree being validated is the tree a build produces; emit outputs are discarded there, though a version source may still write lumen.lock. A plugin is native code loaded into the compiler's process, the same trust model as a Cargo build script.

[signals]¶

An optional typed schema for the app's signals, read by lumenc lint --signals. Nothing else consumes it, and a missing entry is not an error; it downgrades the lint severity.

Each key maps a signal name to a type: i64 (also int, integer), f64 (also float, number), bool (also boolean), string (also str, text), color, vec2, array, or object (also map). An unknown type is a parse error.

A value can also be a table. An inline table with no type key is an object whose entries are its field types. An explicit type = "array" or type = "object" with a fields table types the record at the leaf.

There is no signal_set_string; signal_set is already the typed write for a string-declared signal, so the lint's untyped-write finding does not fire on it.

[signals]
count = "i64"
theme = "string"
user = { name = "string", email = "string" }

[signals.users]
type = "array"
fields = { id = "i64", name = "string", email = "string" }