Référence › Référence du langage › Project & files

Référence › Référence du langage

Cette page n’est pas encore traduite : voici la version anglaise.

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, inside component
  • 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, inside importer, inside exporter
  • 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_" }