Generators of your own
A generator turns the model into files: code, configuration or documents.
archec has about twenty-five built-in targets, such as C, Rust, Go, DBC, ARXML
and ROS 2 (archec gen --list). Your company may need others: its own
runtime glue, a test bench's configuration, a document in its own layout. A
generator declaration adds one, and you run it like a built-in target.
A first generator#
A model with two messages, and a generator made of one template:
message BRAKE_CMD "Brake command" {
field force: float32 [N]
field urgent: bool
}
message SPEED "Speed" {
field kmh: float32
}
system Car {
}
generator msgs "Message structs" {
templates "generators/msgs"
}
The folder generators/msgs/ holds one file, messages.h. What is between
{{ and }} is filled from the model:
/* {{ project.name }}: its messages. */
{{#each messages}}
typedef struct {
{{#each fields}}
{{ type | ctype }} {{ id | snake }};
{{/each}}
} {{ id | snake }}_t;
{{/each}}
Run it:
archec gen main.arche --target msgs -o generated
generated/msgs/messages.h
generated/msgs/messages.h holds:
/* car: its messages. */
typedef struct {
float force;
bool urgent;
} brake_cmd_t;
typedef struct {
float kmh;
} speed_t;
Here the project is in a folder named car: the project's name is its
folder's name.
To start faster, archec generator new writes a generator that already works:
archec generator new rte --templates # or --script, or --command
✓ generator rte (templates) → main.arche, generators/rte/messages.md, generators/rte/parts.txt
archec gen main.arche --target rte · archec generator model main.arche · docs/generators.md
How a generator works#
A generator reads the generator model and returns files. The generator
model is the project as plain JSON. archec generator model main.arche prints
it.
A generator comes in one of three kinds:
- templates: a folder of text files with
{{ }}placeholders; - a script: a JavaScript or TypeScript function;
- a command: a program in any language, which reads the model as JSON.
All three kinds read the same model.
A generator has two siblings:
- an
importerreads a file of another tool into arche-lang; - an
exporterwrites the model as a file of another tool.
All three can come together in a plugin: a folder that the project, a Store package or archec itself ships (plugins).
Generators declare their options, can start from another generator
(from), and can run after a built-in target to change its files (hooks).
The sections below show each one.
The generator model#
The generator model is the project as plain JSON, version 1. Its schema is
schemas/generator-model.v1.json. Every name is resolved and every value is
worked out. What a generator would otherwise have to compute is already
computed:
| Key | What it holds |
|---|---|
project |
name, version, root |
options |
the generator's options, as the project sets them |
messages |
id, label, fields (type, unit, range), layout: bytes and the signals on the wire — scalar, offset, unit, label, and for a message with a wire format its bits, order, scale, offset, checksum |
types |
kind (type, enum, struct, union), literals with their values, fields, underlying; exception: true for an exception; native for a type … native: its name in c, cpp, rust, go, with the include or import that declares it |
exceptions |
the ids of the exception types |
interfaces |
operations (params with their direction when out or inout, result, oneway, raises), attributes (type, readonly), extends, messages |
constants, parameters |
values worked out (value), and as written (source) |
components |
the definitions: ports (direction, type, sends, receives, the onReceive and onDeadline bodies, the interfaces it provides and requires, its pattern, topic and topicParts, service, dataflow, the handlers that run what it receives: { message, function }), functions (a body in the action language with its Python, C, C++, Rust and Go; params with their direction), variables, machine (states, transitions with trigger, guard, action), lifecycle (the init, start, stop and release bodies), parts, props, requirements traced to it |
systems, parts |
the systems — each link with its pattern and what its two ends and itself say of it (topic, service, dataflow, timeout, async, deferred) — and every part by its path (Car.brakes.mcu) with its definition, the params it is made with, its variables' initial values and the ones it overrides |
requirements |
id, label, text and every property |
deployment |
the active one (or --deployment): binaries with their processor (path, label, board, os) and threads (period, priority, the parts and functions they run, the step each period calls: part.fn), buses with the CAN frames each carries (id, message, from, to, fd, periodNs from the message's period), containers |
deployment (execution and memory) |
each thread's process, queue, affinity and the ports it runs; each binary's options (the running generator's: the project's, then the binary's options <generator> { … }), its processor's memories and its processes with their own options; allocators (kind, blockBytes, blocks, alignment, memory, parent, the binary or process they are in); placements: each part that runs, its execution (active, passive, protected), thread, process, memory per use (hrt, lrt, saved, tmp, comm) and its ports (the thread that runs one, its memory, its buffering). See Deployment |
components[].algorithm |
a kind algorithm: its stereotypes, parameters (instantiation, configuration, internal), workingMemory, the cycle functions it has, the metrics it publishes and reads; a composite's composite (L1, LN), roles (definition, stereotypes, after, arguments, configuration), delegations and connections. A port's buffering |
metrics |
the messages of kind metric: their package, fields, and the topic each part publishes them on |
Each element has at: the file and line where it is written. When a
generator finds something wrong, it reports it on the element. archec prints
the problem at that line, and VS Code shows it in Problems.
- An element in a package has
package. - An element with
attr key = valuelines has them inattrs. Anattrholds what the language has no word for, such as another tool's id or name. An exporter writes them back, and may keep anattrid as the element's own id. - Parts, threads, binaries, processes, allocators, memories and placements
have
attrstoo.
The model only grows within version 1: adding a field keeps it version 1. A
generator says which version it reads with api 1.
Bodies in C, Rust and Go#
A body is the code of a function, of a state's onEnter and onExit, of a
port's onReceive and onDeadline, or of a component's lifecycle. In the
model, each body has:
source, as written;python;c,cpp,rustandgo, from the same translators the built-in targets use.cppis written as--target cppwrites it (this->n).
A body written in Python is translated too when the action language can say
the same thing, as the C and Go targets do. Otherwise c, rust and go are
absent.
The translation cannot know your runtime. So what the body does to the outside is written as the built-in targets write it, and your generator provides those names:
| The body says | c |
rust |
go |
|---|---|---|---|
a variable n |
self->n |
self.n |
self.n |
send tx GO { … } |
pump_send_tx(self, &(go_t){ … }); (pump_send_tx_go when the port sends several messages) |
_out.send_tx(Go { … }).await; |
self.Send("tx", GO{…}) |
goto Running |
pump_goto(self, PUMP_RUNNING); |
self.sm.goto_name("Running"); |
self.Goto(Pump_Running) |
state == Running |
pump_in(self, PUMP_RUNNING) |
self.sm.state.is_in("Running") |
self.In(Pump_Running) |
a call of the part's f() |
pump_f(self) |
self.f(_out).await |
self.F() |
a call through a port, brake.apply(2.5) |
as the C target writes it | _out.call_brake_apply(2.5).await |
as the Go target writes it |
wait 10ms, now() |
arche_wait_ns(…), arche_now_ns() |
embassy_time::Timer::after(…), Instant::now() |
archeWait(…), archeNow() |
log a, b |
arche_log("%g %ld", …) |
a comment | archeLog(a, b) |
Types are named as the targets name them: go_t in C, Go in Rust, GO
in Go. Durations are in nanoseconds (uint64_t, u64, int64). In a part
without a state machine, a goto is written as a comment.
The model is enough. examples/generators/dbc.js reads nothing but the
model, and writes the same DBC files as --target dbc, byte for byte. The
tests check it.
Templates#
A templates generator is a folder of text files. Each file is a template:
what is between {{ and }} is filled from the model. The file written has
the template's name, without a .tpl suffix if it has one.
/* {{ project.name }}: its messages. */
{{#each messages where layout.bytes}}
typedef struct {
{{#each fields}}
{{ type | ctype @root.options.prefix }} {{ id | snake }};{{#if unit}} /* {{ unit }} */{{/if}}
{{/each}}
} {{ @root.options.prefix }}{{ id | snake }}_t;
{{/each}}
| Written | What it does |
|---|---|
{{ name }}, {{ a.b }} |
a value: the current element's; else the one of the loop around it, and so on out to the model |
{{ .name }}, {{ ../name }}, {{ @root.name }} |
the current element's only; the one of the loop around; the model's |
{{ x | snake | default "none" }} |
filters, one after the other |
{{#each list where field=a,b and other}} … {{else}} … {{/each}} |
once per element (@index, @number, @first, @last); {{else}} when there is none |
{{#if cond}} … {{else}} … {{/if}}, {{#unless cond}} |
field, field=a,b, field!=a, field~text, field>3, joined by and |
{{#with element}} … {{/with}} |
inside one element |
{{#file "src/{{ id | snake }}.c"}} … {{/file}} |
a file of its own — inside an #each, one per element |
{{> name}} |
another template of the folder, one whose name starts with _ (a partial, not a file) |
{{ keep }} |
the file is yours once written: archec does not write over it again |
{{#region "{{ id }}.init"}} … {{/region}} |
a USER CODE region. What is inside is the default. The developer's code there is kept each time the file is written again (regeneration). The comment style follows the file's name, or "c", "line" or "hash" after the id. "user-code" writes // -- start of user code: name markers (regeneration). |
{{! … }}, {{!-- … --}} |
a comment; the second may hold {{ }} |
A line that holds only a block tag ({{#each …}}, {{/if}}, {{else}}…)
leaves nothing behind, not even its line break. So a template of code reads
like the code it makes.
Filters change a value. They are:
- names:
snake,camel,pascal,kebab,constant(BRAKE_CMD),upper,lower; - types:
ctype,rusttype,pytypegive a type of the model in that language, through its aliases.ctype "acme_"writes a declared type asacme_name_t; - values:
hex(hex 4→0x00FF),json,quote,default "x"; - lists:
join ", ",map "id",sort "id",length,first,last; - text:
indent 4,replace "a" "b",trim,pad 12.
A filter's argument written without quotes is a name read from the model
(ctype @root.options.prefix).
A script#
generator can-db "CAN databases" { script "dbc.js"; needs deployment }
module.exports = function generate(model, ctx) {
const files = {};
for (const m of model.messages) {
if (m.layout.problem) { ctx.warn(m, `${m.id} has no fixed layout`); continue; }
files[`${ctx.filters.snake(m.id)}.txt`] = m.layout.signals.map((s) => s.name).join('\n');
}
return { files }; // { "path": "text" }, or { "path": { text, keep: true } }
};
export default function generate… works too. The script returns its files;
it does not write them. ctx gives:
options;readFile(rel): a file of the script's own folder;render(template, data): the template language;region(id, default, style): a USER CODE region around the default code, kept when the file is written again (regeneration).styleis"c","line","hash"or a file name."user-code"writes the// -- start of user code: <name>markers; the file name is then the fifth argument;filters;note(msg);warn(where, msg)anderror(where, msg).whereis an element of the model, a path or id, or{ file, line };builtin(target, { deployment, trace, monitors }): a built-in target's files as{ "path": "text" }(see below);- as a hook (
after c):target,files({ "path": "text" }) andkept(the paths markedkeep).
In TypeScript#
script "gen.ts" (or .mts, .cts) is TypeScript. archec strips the types
and runs what is left like any script.
- Node 22.13 and 23.2 and later strip the types themselves. The lines stay
where they were, so an error's line is the line in the
.tsfile. Anenumor anamespaceis written out, and its lines may move. - On an older node, esbuild or typescript strip them, when the project or archec has one of them installed. Otherwise the error says so.
The file generator-model.v1.d.ts gives the types of the model and of ctx.
archec generator types writes it. archec generator new rte --script --ts
writes a script and this file side by side:
import type { GeneratorContext, GeneratorModel, GeneratorResult } from './generator-model.v1';
export default function generate(model: GeneratorModel, ctx: GeneratorContext): GeneratorResult {
const files: Record<string, string> = {};
for (const m of model.messages) files[`${m.id}.txt`] = m.fields.map((f) => f.id).join('\n');
return { files };
}
export function generate works too. archec only strips the types; it never
checks them. Run tsc --noEmit in your editor or CI to check them.
The sandbox#
The script runs in a sandbox: plain JavaScript, with nothing of node or npm.
It has no process, no file system beyond its own folder, and no network. A
script that loops forever is stopped after 30 s.
A script may be several files. import { view } from './core/view' (or
require('./core/view')) loads a module of its own, .ts or .js, with
export as usual. A module comes from the script's folder; in a plugin or a
library, it may come from anywhere in it. A module outside, or a module of
node or npm (import fs from 'fs'), is an error.
A command, in any language#
generator icd-md "ICD" { command "python3 icd.py"; output "docs" }
The command runs in the folder of the file where the generator is declared. It reads the model as JSON on its stdin. It writes this JSON on its stdout:
{ "files": [{ "path": "icd.md", "text": "…", "keep": false }],
"notes": ["9 messages"],
"errors": [{ "where": "BRAKE_CMD", "message": "…", "severity": "warning" }] }
What it writes on stderr is shown as notes. It is an error when the command exits with an error, or writes something other than that JSON.
Options, and one generator from another#
options { … } is a record, and the model's options holds it.
--option prefix=acme_ changes one option for a run. For other values every
time, write another generator from the first:
generator rte-bench "RTE for the bench" from rte { options { prefix "bench_" } }
An option the first generator does not have is a warning
(generator-option).
Options declared, with their types#
A generator can declare its options. This matters most for one that a library ships:
generator rte "Our RTE glue" {
templates "generators/rte"
option prefix "The prefix of the C names" { type string; default "acme_" }
option os "The RTOS it runs on" { type string; values posix, freertos; default posix }
option depth "Queue depth" { type int; default 8 }
}
typeisstring,int,float,boolorlist. Withouttype, any value is taken.valuesare the only values the option takes.defaultis the value when nothing sets it. The model'soptionsholds it.
archec check then checks what a generator from it sets (generator-option):
- an option it does not declare is a warning;
- a value of another type, or not among its
values, is an error at the value.
--option is read as the option's type and checked the same way.
--option prefix=12 is the string "12"; --option list=a,b is a list.
archec gen --list lists each generator's options. In VS Code, options { }
completes their names and then their values, and hovering over one says what
it is.
A built-in target's files#
A generator often wants what a built-in target writes, plus a little. For
example, the C of --target c with a file of glue, or the DBC in another
layout. The generator reads the target's files instead of writing them again.
A script calls ctx.builtin:
module.exports = function generate(model, ctx) {
const c = ctx.builtin('c'); // { "c/arche_types.h": "…", … }
const files = {};
for (const [p, text] of Object.entries(c)) files[p] = `#pragma once_ours\n${text}`;
files['c/glue.c'] = ctx.render('…', model);
return { files };
};
A template or a command names the targets it reads with builtins. The
model's builtins then holds their files, as
{ "c": [{ "path", "text", "keep" }] }:
generator listing "What C writes" { templates "listing"; builtins c, dbc }
{{#each builtins.c}}{{ path }}: {{ text | length }} characters
{{/each}}
The files are the ones the target writes before any hook, for the deployment
of the run (--deployment). freertos, zephyr, posix and components
are not available, because Arche writes them.
Hooks: after a target#
A hook is a generator that runs after a target and changes its files.
For example, a company puts its license header on every file it ships. It
does not need a whole generator for that, or an edit by hand after each run.
It writes a hook:
generator license "Our license header" { script "license.js"; after c, go }
module.exports = function (model, ctx) {
const files = {};
for (const [p, text] of Object.entries(ctx.files))
if (/\.[ch]$/.test(p)) files[p] = `/* (c) ACME. All rights reserved. */\n${text}`;
files['LICENSE'] = ctx.readFile('LICENSE');
return { files };
};
archec gen --target c then writes the target's files through the hook. A
hook returns only what it changes:
- a path with its text replaces that file, or adds it;
- a path with
nulltakes the file away; - a file it does not name stays as it was.
A command hook reads the same in the model's after:
{ "target": "c", "files": [{ "path", "text", "keep" }] }. To take a file
away, it writes { "files": [{ "path": "c/x.h", "text": null }] }.
- Order: the hooks on a target run in the order they are written. A hook
in an included file counts where the file is included. Each hook works on
the files the previous one left.
archec gen --listshows the hooks (after c). - Paths are as written under
-o(c/arche_types.h), not under a folder of the hook's own. - keep: a file marked
keepis yours once written. When the target marks a filekeep, it stays marked when a hook changes it. What the hook does to it counts only when the file is first written.ctx.keptlists these files. - A hook is a script or a command, not templates.
- A hook runs only through its target.
archec gen --target licensesays so. The target can be any built-in target or one of the project's own generators.--no-hooksleaves the hooks out. - A library's hook runs only once approved, like its other scripts.
Where the files go#
The files go into <-o>/<output>/:
- by default,
<output>is the generator's id; output "dir"picks another folder;output "."writes into the-ofolder itself.
A path that would leave that folder is refused. A file marked keep is
written once and never again. --check says what would change and writes
nothing.
Testing a generator#
First approve the output as it is:
archec generator test main.arche rte --update
✓ 2 file(s) approved → expected/rte
Later, compare the output with the approved files:
archec generator test main.arche rte
✓ rte: 2 file(s) as approved
When they differ, it lists the files missing, changed (at the first line that differs) and new.
The approved files are kept in expected/<id>/ beside the declaration.
Commit them. A change to the model or to the generator then shows as a
difference in CI.
From a library, from the Store#
A library can ship generators. Their paths are relative to the library's own
files. A Store package can be of kind generator. uses acme-gen "^1.0" and
include "acme-gen/generators.arche" make its generators targets of the
project. A package of kind plugin needs no include: uses is enough, and
it may bring importers and exporters too (plugins).
A library's templates run as they are, because they run no code. A library's script or command runs on the machine of whoever builds the project. So it runs only after the project approves it:
archec generator approve main.arche rte # lists the code it runs, then records it
The approval goes into arche.lock, with the library's fingerprint as it is
now. arche.lock is committed and reviewed with the rest. If the library
changes, the generator is refused until it is approved again.
--revokewithdraws an approval.archec auditlists a generator's JavaScript, with the rest of the code the project brings in.
The sandbox is not a security boundary: node's vm is not one. That is why
the approval is what decides.
What is checked#
| Code | |
|---|---|
generator |
more than one kind or none; a folder or file that does not exist; from a generator that does not exist, or a chain that goes round; an api this archec does not give; builtins or after naming something that is not a target; a hook of templates |
generator-option |
an option it, or the generator it starts from, does not declare (a warning); a value of another type, not among the option's values, or a default that does not fit its type (errors) |
In VS Code#
- Running: a ▶ Generate lens sits above each generator. Generate code… lists the project's generators after the built-in targets. What a generator reports appears in Problems, at the element's line. A hook's lens (▶ Generate c) runs its target, and Generate code… runs a target through its hooks.
- Writing: after
from, completion offers the project's generators. Inoptions { }, it offers the declared options, then their values; hovering says what each is for. In a file of atemplatesfolder:{{offers the model's names;{{#offers the blocks;|offers the filters;- hovering over any of them says what it is.
Limits#
- A hook is a script or a command. A hook made of templates is reported (
generator). - A hook declared by a built-in plugin does not run.
builtinscannot readfreertos,zephyr,posixorcomponents: Arche writes them, not archec.- The sandbox is not a security boundary. A library's script or command runs only once approved, and the approval is what protects you.
- archec strips a TypeScript script's types but never checks them.
- The C, Rust and Go of a body name your runtime's functions as the built-in
targets do; your generator provides them. A Python body the action language
cannot say has no
c,rustorgo.