Project & files
How a project is set up, split over files, and given its libraries and generators.
On this page: project · library · translations · include · package · raw · file · generator · importer · exporter · option
Splitting a specification over files, project metadata, the versioned libraries a project uses, and code generators of your own.
project#
Project metadata: name, version, authors. One per project.
- Keywords:
project - Set: the model
- Where: top level
- Syntax:
project "Name" { version "1.0" … }
| Property | Value | Meaning |
|---|---|---|
description |
text | Prose description. $…$ and $$…$$ are LaTeX math; a ```latex block is kept as LaTeX. |
version |
string | Specification version. |
edition |
string | The language edition it is written in, as go.mod names a Go version: edition "0.12" — the old keyword spellings are errors from 0.12 on (archec fmt --edition 0.12 writes the standard ones and sets it). Without one, the project is read as it always was. |
author |
string | Author(s). |
layout |
refs | Left pane modules for layout.yaml. |
libraries |
text | Folders shared between projects, where include also looks (after the including file's own folder): libraries "../shared", "/opt/arche-libs". include "std/…" is the standard library that ships with archec. |
trust |
verified | reviewed | community | sigstore |
Which Arche Store libraries the project accepts: trust verified (only verified publishers, such as board vendors), trust reviewed (also libraries a store reviewer read), trust community (any, the default). Add sigstore to take only packages whose Sigstore bundle cosign verified when they were added: trust reviewed, sigstore. Your own libraries, not from the store, are always accepted. |
level |
simple | full |
How much of the language the editor offers: level simple is the 1.0 core (docs/core.md) — completion offers its declarations and properties, and a declaration beyond it says how to use it; level full is everything (the default). |
pointer-size |
number | Bytes in an address: the size of every *T pointer (default 4). |
uses |
any | A library the project depends on, and the versions it accepts: uses kria-parts "^1.4" (1.4 or newer, before 2.0), "~1.4" (1.4.x), "1.4.2", ">=1.2 <2". It is looked for in the libraries folders, as <name>/ or <name>@<version>/ with a library.arche; the newest version in the range is used, or the one arche.lock names (archec lib lock). include "kria-parts/kria.arche" is then a file of that version. |
assets |
text | Files and folders copied into the generated project as they are (images, sources, templates): assets "visuals", "code". Paths are relative to this file. |
languages |
refs | Languages of the content, the source one first (layout.yaml languages); translations are written "Texte" en "Text", or with en "Text" on the next line, indented under the text. |
logo |
string | The logo shown in the app (layout.yaml). |
source-root |
string | The folder of the implementation sources (layout.yaml sourceRoot). |
pptx-template |
any | The PowerPoint template slides are exported with, and how much of it they take (full): layout.yaml pptxTemplate. |
pip |
text | The Python packages its Python bodies import, as pip takes them (repeatable, or a list): pip "numpy>=1.26", "sympy". archec sim checks them in the Python it runs and prints the pip command for what is missing; it installs nothing. |
infer-links |
bool | infer-links false: a link gets a type and carried messages only when they are written on it (not from its ports). |
auto-catalogs |
bool | auto-catalogs false: kinds, layers, tags, port types and colors that are used but not declared are not added to their catalogs. |
derived-from |
string | The store package the project was started from, as archec new --from (or --template) records it: derived-from "arche/rover-esp32@0.1.0". The project is a copy, free to change; when it is published, its library carries this line on, so the store draws the family tree. |
omit |
text | Files the generated project does not have, though archec would write them: omit "layers.yaml". |
code |
text | TypeScript or Python files shared by the whole model: their functions can be named from any component (on-enter log_on). |
ai |
offline | local-ai | online |
The most AI the project accepts: ai offline (none: every check stays local and deterministic), ai local-ai (a model on this machine, such as Ollama or llama.cpp), ai online (Claude too). It only restricts: what is used is what you set with archec config ai … or --ai, capped by this. docs/ai-engineering.md. |
allow |
any | A service the project may reach, with the only URL it may reach it at: allow store "https://store.acme.corp". It only restricts (a cloned project never turns egress on): a service listed with a URL is refused at any other one. Services: claude, local-ai, store, polarion, parts, issues, libraries, sigstore, github. |
deny |
any | A service the project never reaches, whatever your config allows: deny claude, deny all, or one URL: deny store "https://store.arche-lang.xyz". |
private |
text | Files never sent out, whatever is allowed (globs from this folder; a glob without / matches a name in any folder): private "secret/**", "*.key". A call that would carry one is refused. |
handlers |
typescript | python | arche |
The language the behaviour is written in: typescript (what archec new writes), python, or arche (the action language, translated to TypeScript for Arche and to C, Rust or Go for firmware). A block says its own (ts, python, ```arche). Without it, a project with Python code is python, any other typescript. docs/handlers.md. |
project "Autonomous car" {
version "0.3"
author "Systems team"
}
library#
A library: a folder of .arche files shared between projects, named and versioned in its library.arche. The folder is <name>/ or <name>@<version>/ in a project's libraries folder, so versions sit side by side; a project says which it accepts with uses <name> "<range>". archec lib lists what a project uses and archec lib lock records it in arche.lock.
- Keywords:
library - Set: project tooling
- Where: top level
- Syntax:
library kria-parts { version "1.4.0" }
| Property | Value | Meaning |
|---|---|---|
description |
text | Prose description. $…$ and $$…$$ are LaTeX math; a ```latex block is kept as LaTeX. |
version |
string | Its version, as major.minor.patch: a new major version for a change that breaks the projects using it, a new minor one for an addition. |
archec |
string | The archec versions it works with, as a range: archec ">=0.10". |
uses |
any | A library it uses in turn, with the versions it accepts. |
author |
string | Author(s). |
owner |
ident | Who publishes it in the Arche Store: owner acme makes it acme/kria-parts there. A project still uses kria-parts. |
kind |
architecture | driver | spec | board | template | ui-kit | library | generator | plugin |
What it holds, which the Arche Store shows differently: an architecture (a system to reuse or extend), a driver (a component and its code), a spec (requirements, interfaces, ICDs), a board, a template (a project to start from: archec new --template owner/name copies it), a ui-kit (a theme for a ui: theme "owner/name"), a generator (generators for the projects that use and include it, docs/generators.md), a plugin (generators, importers and exporters in its plugin.arche, brought by uses alone, docs/plugins.md), or a library of parts and types (the default). |
shelf |
refs | The store shelves its pieces go on: types, units, boards, drivers, sensors (and actuators), algorithms. archec shelf and the store's Shelves page show each piece with the same seven lines (docs/shelves.md). |
license |
string | Its license, as an SPDX expression: license "Apache-2.0". archec store publish refuses a library without one. |
keywords |
refs | Words the Arche Store search finds it by. |
derived-from |
string | The store package it was made from, written as archec add takes it: derived-from "st/stm32g4-base@^1.0". The store draws the family tree. |
export-control |
any | Its export classification, which the publisher declares: none, ear99, or a control number such as "5D002". archec store publish refuses a library without it, and holds one that reads like defence technology for review. It is the publisher's statement, not legal advice. |
edition |
string | The language edition its files are written in (as a project's edition). |
url |
string | Its home page or repository. |
renamed |
any | Declarations it renamed, old name to new, and the edition the rename is made for: renamed "1.0", { Led: GpioLed, Button: GpioButton }. A model that writes an old name builds as if it wrote the new one, with a warning (renamed) up to that edition and an error from the next; archec fix and the quick fix write the new name (docs/editions.md). |
pip |
text | The Python packages its Python bodies import, as pip takes them (repeatable, or a list): pip "numpy>=1.26", "sympy". archec sim checks them in the Python it runs and prints the pip command for what is missing; it installs nothing. |
library kria-parts "KR260 parts" {
version "1.4.0"
archec ">=0.10"
}
translations#
The texts of the model in another language, apart: each line is an element (its id, or its path) and its name in that language, or one of its text properties (REQ-1.description), or — for a text no path names, a sequence step or a branch — the text itself ("initialisation" "start-up"), translated wherever it is written. The model's own files then read in one language; it is the same as writing en "…" after each text. archec refactor translations main.arche --extract en moves the inline ones into a file of their own. An entry that names nothing, or repeats a translation written inline, is pointed out.
- Keywords:
translations - Set: project tooling
- Where: top level
- Syntax:
translations en { REQ-1 "Start"; REQ-1.text "The pump shall start."; Station.ctrl "Controller"; "démarrage" "start-up" }
translations en {
REQ-START "Start on command"
REQ-START.text "The pump shall start within 100 ms of a START command."
}
include#
Include another .arche file (relative path). Each file is included once; cycles are reported. Inside a system or component body, the file holds part of that body (its parts, links, functions…), read as if written where the include is — a large system split into one file per subsystem. requires "../../interfaces/spi" at the top of a file is an include that says what the file depends on: a component kept in a components/<name>/ folder (a component library) may use only what its folder declares, the standard library, and what it requires — so the folder can be copied into another project (component-not-self-contained). include "std/units", "std/buses", "std/interfaces", "std/parts" are the standard library shipped with archec; a path not found beside the file is looked for in the project's libraries.
- Keywords:
include·requires(old spelling:import) - Set: the model
- Where: top level, inside
system, insidecomponent - Syntax:
include "path/to/file.arche"
include "common/messages.arche"
package#
package chassis on its own line, first in a file, puts the whole file in the package, as in Go; package chassis { … } groups part of one. A group of declarations — components, messages, types, requirements — under one name, so a large model reads by part. Inside, names are written as usual; from anywhere, chassis.BrakeEcu names one explicitly (a bare BrakeEcu works too). Arche ids are global, so a name is still declared once in the whole project: a package groups and qualifies, it does not let two things share an id. include inside a package puts that file's declarations in it.
- Keywords:
package(old spelling:namespace) - Set: the model
- Where: top level
- Syntax:
package name (the rest of the file is in it, as in Go) | package name { declarations… }
| Property | Value | Meaning |
|---|---|---|
description |
text | Prose description. $…$ and $$…$$ are LaTeX math; a ```latex block is kept as LaTeX. |
package chassis {
message BRAKE_CMD { force: float32 }
component BrakeEcu { in can: can receives BRAKE_CMD }
}
system Car { part brakes: chassis.BrakeEcu }
raw#
A file of the project that Arche does not define: data "file.yaml" = { … } writes the value as YAML (a record, a list), checked as any value is; `raw "file.yaml" ```yaml … ```` writes the text verbatim — the escape hatch for anything the language does not model yet.
- Keywords:
raw·data - Set: project tooling
- Where: top level
- Syntax: `data "file.yaml" = { key: value, … } | raw "file.yaml" ```yaml … ````
raw "plots.yaml" ```yaml
version: 1
plots: []
```
file#
Fields of a generated file itself (its top level), with attr: file "requirements.yaml" { attr version = nil }.
- Keywords:
file - Set: project tooling
- Where: top level
- Syntax:
file "name.yaml" { version 1; attr key = value }
| Property | Value | Meaning |
|---|---|---|
version |
any | The file's version field; version nil when it has none. |
file "deliverables.yaml" { attr version = 1 }
generator#
A code generator of your own, run as archec gen --target <id> beside the built-in targets. It reads the generator model — the project as JSON, every name resolved, each message's layout on the wire, each element's file and line (schemas/generator-model.v1.json) — and returns files. Three kinds: templates "folder" (text files with {{ }} placeholders), script "gen.js" (module.exports = function generate(model, ctx) { … }, run in a sandbox) or command "python3 gen.py" (any language: the model as JSON on stdin, the files as JSON on stdout). from <generator> is another one with other options: how a project sets those of a generator a library ships. Its files go to <output>/<id>/, never over one marked keep that exists.
- Keywords:
generator - Set: project tooling
- Where: top level
- Syntax:
generator id "Label" [from base] { templates "dir" | script "gen.js" | command "…"; option k "…" { type string; default v }; options { k v }; builtins c; after c; needs deployment; output "dir"; api 1 }
| Property | Value | Meaning |
|---|---|---|
description |
text | Prose description. $…$ and $$…$$ are LaTeX math; a ```latex block is kept as LaTeX. |
templates |
string | A folder of templates (relative to this file): every file in it is one, {{ }} filled from the model; a file named _x is a partial ({{> x}}). See docs/generators.md. |
script |
string | A JavaScript file, or TypeScript (gen.ts: its types stripped; archec generator types writes the model's declarations), relative to this file, whose export is function generate(model, ctx), returning { files: { "path": "text" } }. It runs in a sandbox: no require, no file system but its own folder (ctx.readFile), no network. |
command |
string | A command run in this file's folder: the model as JSON on its stdin, { "files": [{ "path", "text", "keep" }], "notes", "errors" } on its stdout. |
options |
any | Its options, as a record — what the model's options holds; archec gen --option k=v changes one for a run. |
needs |
deployment |
needs deployment: it reads a deployment, and says so when there is none. |
output |
string | The folder its files go to, under the output (its id by default; "." for the output itself). |
api |
number | The version of the generator model it reads (1). |
builtins |
any | Built-in targets whose files it reads: the model's builtins holds them, { c: [{ path, text }] }, for a template or a command (a script may also call ctx.builtin("c")). |
after |
any | A hook: it changes the files of these targets, and archec gen --target c runs it after the target (--no-hooks does not) — a license header on every file, a file more. A script or a command; it gets the files (ctx.files, the model's after) and returns only what it changes, null to take a file away. |
generator rte "RTE glue" {
templates "generators/rte"
options { prefix "kc_" }
needs deployment
}
importer#
An importer of your own: a file of another tool read into arche-lang, run as archec import <file> when its extensions match one no built-in importer reads (or --importer <id>). A script "import.ts" (export default function importFile(input, ctx), sandboxed: ctx.readFile reads the imported file's folder and the plugin's own, nothing else) or a command "python3 x.py" (the input as JSON on stdin) returns .arche files with notes and errors; archec writes them and checks them. Usually in a plugin (docs/plugins.md).
- Keywords:
importer - Set: project tooling
- Where: top level
- Syntax:
importer id "Label" [from base] { script "import.ts" | command "…"; extensions ".x", ".y"; option k "…" { type string; default v }; options { k v } }
| Property | Value | Meaning |
|---|---|---|
description |
text | Prose description. $…$ and $$…$$ are LaTeX math; a ```latex block is kept as LaTeX. |
script |
string | A JavaScript or TypeScript file, relative to this file, whose export is function importFile(input, ctx): input holds the file's name, path and text and the options; it returns { files: { "main.arche": "…" }, notes, errors }. Sandboxed: no require, no network; ctx.readFile(rel) reads beside the imported file, ctx.readOwn(rel) the plugin's folder. |
command |
string | A command run in this file's folder: the input as JSON on its stdin (file, name, text, options), { "files": [{ "path", "text" }], "notes", "errors" } on its stdout. |
extensions |
any | The file endings it reads (.kv): archec import picks it for those, unless a built-in importer reads them. |
reads |
any | Folders around the imported file, relative to its folder, that its script may read too (ctx.readFile) — where the format's files name others; archec import --allow-read <dir> adds one for a run. |
options |
any | Its options, as a record — what the input's options holds; --option k=v changes one for a run. |
api |
number | The version of the importer input it reads (1). |
importer kv "Key-value files" {
script "import.ts"
extensions ".kv"
}
exporter#
An exporter of your own: the model written as a file of another tool, run as archec export <main.arche> --format <id> -o out.x (or picked by -o's ending). It reads the generator model (the same JSON, version 1) and returns files, as a generator does: templates, a script or a command. Usually in a plugin (docs/plugins.md).
- Keywords:
exporter - Set: project tooling
- Where: top level
- Syntax:
exporter id "Label" [from base] { templates "dir" | script "export.ts" | command "…"; extension ".x"; option k "…" { type string; default v }; options { k v }; needs deployment }
| Property | Value | Meaning |
|---|---|---|
description |
text | Prose description. $…$ and $$…$$ are LaTeX math; a ```latex block is kept as LaTeX. |
templates |
string | A folder of templates, as a generator's (docs/generators.md). |
script |
string | A JavaScript or TypeScript file whose export is function generate(model, ctx), returning { files: { "path": "text" } }, sandboxed as a generator's. |
command |
string | A command run in this file's folder: the generator model as JSON on its stdin, { "files": [{ "path", "text" }] } on its stdout. |
extension |
string | The ending of the file it writes (.kv): archec export -o out.kv picks it by that ending. |
options |
any | Its options, as a record — the model's options; --option k=v changes one for a run. |
needs |
deployment |
needs deployment: it reads a deployment, and says so when there is none. |
api |
number | The version of the generator model it reads (1). |
exporter kv "Key-value files" {
script "export.ts"
extension ".kv"
}
option#
An option of a generator, declared: its type, its default, the values it may take, what it is for. archec check holds what a generator started from it (or --option) sets to it — an option it does not declare, a value of the wrong type or not among its values; its default goes into the model's options when nothing sets it; the editor completes and explains it in options { }; archec gen --list lists it.
- Keywords:
option - Set: project tooling
- Where: inside
generator, insideimporter, insideexporter - Syntax:
option name "What it is for" { type string|int|float|bool|list; default v; values a, b }
| Property | Value | Meaning |
|---|---|---|
description |
text | Prose description. $…$ and $$…$$ are LaTeX math; a ```latex block is kept as LaTeX. |
type |
string | int | float | bool | list |
What it holds: string, int, float, bool or list (any, when not said). |
default |
any | Its value when nothing sets it. |
values |
any | The values it may take, and no other. |
option prefix "The prefix of the C names" { type string; default "kc_" }