The VS Code extension
The extension makes VS Code an editor for arche-lang models. It checks the model
as you type, completes and explains names, draws the system beside the text, and
steps through a simulated test. This page lists what it does once installed.
The README says how to install it.
A first look#
Install the extension from the arche-lang folder:
npm install
npm run package # → arche-lang.vsix
code --install-extension arche-lang.vsix
For CAD (CAD as code), install the build for your machine instead. It carries the CAD engine and works with no network:
node tools/cad/package.mjs darwin-arm64 # → arche-lang-darwin-arm64.vsix (about 270 MB)
code --install-extension arche-lang-darwin-arm64.vsix
The targets are darwin-arm64, darwin-x64, linux-x64, linux-arm64 and
win32-x64. The script fetches a portable Python and the engine's wheels,
each checked against a pinned hash; neither is kept in git.
Then open a folder with a main.arche in it, for example this model with a typo
in its last line:
message GO: bool
component Lamp "Lamp" {
in cmd: can receives GO
}
component Button "Button" {
out click: can sends GO
}
system Room "Room" {
part lamp: Lamp
part button: Button
button.click -> lamp.cdm
}
lamp.cdm is underlined in red, with the message that archec check prints:
Cannot find 'lamp.cdm' in Room. Did you mean 'lamp'? [unresolved]
The light bulb on it (Ctrl+. or Cmd+.) offers Change to 'cmd'. Press ⌘K V to see the diagram: two blocks and the link between them.
Reading and writing#
Highlighting:
- keywords, declarations and units (
50ms,2Mbps); - LaTeX inside
$…$, Python inside```pythonblocks, YAML inside```yaml; ```archeblocks in Markdown too.
A
```archebody is coloured as the action language:var,if/while/for,send port MSG { field: … },goto State, the builtins, calls and operators. It is also coloured by meaning: the component's variables, its functions and ports, a message and its fields, a parameter, a local. The settingarche.bodies.highlightputs a faint background behind each body.- keywords, declarations and units (
Live diagnostics: syntax errors and the full set of lint checks, across
includes. A file is checked in the context of the file that includes it.Quick fixes for every "did you mean …?". Fixes lists them.
A name from a file you did not include:
part h: Heater, withHeaterdeclared inlib.arche, says so:'Heater' is declared in lib.arche, which this model doesn't include.The preferred quick fix is Include "lib.arche". It adds the line after the file's other includes. A name the store has, such asPidorBme280, gets Use Pid from arche-algorithms: it adds theusesand theinclude. The project is the main file's folder and its subfolders, withoutnode_modules,.arche,out,build,arche-out,distand hidden folders.archec checksays the same, andarchec fixadds the include when only one file has the name.What proves each requirement: a line above each
requirementsays what proves it today, asarchec statusdoes:proved by 3 tests · timing on board nucleo-f446re ✓ · 2 h ago,out of date: Thermostat.update changed, ornothing proves it. It reads the evidence thatarchec test,verify,timingandreplayrecord, and follows the model as you type. A click shows that requirement's full status in the Arche Status output; Show Requirement Status shows them all (status).Completion of what fits where you are:
- the keywords and properties of the block you are in;
- members after
.:adcu.gives its ports, functions and children, including those of its definition; - messages after
sends [, port types afterport x:, types aftervar x:, states in transitions, and include paths; - after
part x:, the boards of the store and of your collections, with vendor and part number. Choosing a board the model does not include yet also adds itsincludeand the project'suses; - after
part x:, a type or a port type, also the names of the project's files that the model does not include yet, and the store's algorithms. Each says where it comes from (lib.arche — adds include,store: arche-algorithms — adds uses + include). They come after the model's own, only those that start as you typed, a few at most. Choosing one adds the include, and theusesfor the store; - in
pins { … }, the roles, then the board's pins and what each is wired to; - in a part of a board, its connectors with their pins.
Hover on a name shows its declaration, its documentation, and its ports, functions or fields. On a keyword or a property, it shows the documentation and an example.
- On a board, or a part of one: vendor, part number, URL, its processors (core, clock, memory), its connectors and the pins they are wired to.
- On a pin in
pins { … }: the chip it is on, and what the board wires to it. A pin name that the board's chip does not have is a warning (board-pin), with the nearest name as a quick fix.
Signature help in bodies:
- while you build a message, its fields with their types, units and ranges.
The field you are writing is highlighted. This works for
BRAKE_CMD { force: … }in an ```arche body andBRAKE_CMD(force=…)in Python; - on
send port MESSAGE(orsend(port, message)): first the ports that send, then the messages the port carries.
- while you build a message, its fields with their types, units and ranges.
The field you are writing is highlighted. This works for
Navigation: go to definition, find references, rename across files, outline, workspace symbols (⌘T), format document. A
.archefile is formatted when you save it (it only re-indents and trims trailing spaces; turn it off with"[arche]": { "editor.formatOnSave": false }in your settings).These work in a
```archebody too, by what each name is. Ctrl+click ongotgoes to the component'svar got; onbump(), to itsfn bump; onsend o TRACK { id: … }, to the port, the message and its field. A parameter goes to the function's signature, and a local to itsvar.Renaming a message's field also renames it in the records of the bodies. It leaves a parameter of the same name alone. Renaming a parameter or a local stays inside its body.
Move Definition to a File…: right-click a top-level definition (a component, a message, a struct, a requirement, a system…) or a use of it (
part a: Pump), or a block of the diagram; also under Refactor…. Pick New file… or a file of the project: the declaration moves there with its///lines, the file is included when it is not yet, and nothing is done unless the project stays the same. One undo takes it back. The command line has it asarchec refactor move-definition(commands/refactor.md).Models in JavaScript and TypeScript: a test can hold a model as
archeSrc`…`(fromtest/helpers.js, with its fences written\`\`\`). The extension colours it as arche, and Ctrl+click and hover work on its names. Each string is compiled as a model of its own. The settingarche.embedded.problemsshows its errors in the Problems view. It is off by default, because a test's model may be wrong on purpose.Inlay hints: what archec computed, shown at the end of the line that gives it. For example:
2 * TICK + 500us= 2.5ms,2.5kHz= 400us period,period TICK= 1ms;component LidarFront extends Lidarinherits ports cloud, power;budget power 10W= 8.5W of 10W: the checker's roll-up, with⚠when over;- a deployment thread
R=200us/D=1ms: the timing analysis; part s: Sensor[N]= 4 parts.
A plain quantity gets no hint. The setting
arche.inlayHints.enabledturns them off.Shelf hints: a quiet hint (a faint underline, no warning) where the model writes by hand what a shelf of the store already has: a function that looks like a PID, a debounce or a CRC, a message whose fields are a
Vec3or aGeoPoint, a component named as a store device. The hint says what it looks like and why. Its quick fix adds theusesand theinclude; for a message or a struct whose fields have the very same names and types, it also replaces it (message ACCEL: Vec3). A function written by hand is never replaced: the hint says which part to add and what to call. The hints are on at the beginner level (the settingarche.level, or a project'slevel simple) and off otherwise;arche.suggestions(auto,on,off) decides.archec suggestlists the same in a terminal.Semantic highlighting: each name is coloured by what it resolves to. That is a definition, part, port, message or type, requirement, state, function, variable or constant, deployment, or thread. A quantity's unit is coloured apart from its number. The grammar still colours the rest.
arche-lang shown as text is coloured too: the
```archeblocks of a Markdown preview (an explanation, the patterns, a README), a shelf card's code and a board's page, the UI preview's inspector and the spec's code (archec doc --html), in the editor theme's light or dark colours. The words are the grammar's, as on the website.
Code files: Arche's names in Python and TypeScript#
A model's code files (code "ctrl.py", code "sensor.ts") use names that
Arche gives them: its helpers (wait, send, goto…) and the model's
messages, components and constants. Pylance and VS Code's TypeScript need to be
told these names. The extension tells them, and writes nothing beside your
code: no arche.py, no arche.d.ts, no tsconfig.json.
The names are kept in one place per project, .arche/typings in the folder of
the main file:
| File | What it holds |
|---|---|
.arche/typings/arche/__init__.pyi |
Arche's helpers, typed. The same text for every model. |
.arche/typings/arche/_model.pyi |
This model's messages and constants. |
.arche/typings/arche.d.ts |
The same for TypeScript: the API, a type per message and per component. |
.arche/typings/project.json |
The main file and the code files the model names. |
.arche/typings/.gitignore |
Makes git ignore the folder. No .gitignore of yours is changed. |
The Python files are there when the model has .py files, arche.d.ts when it
has .ts files. A file is written again only when its text changes.
The place depends only on the main file's name. For main.arche it is
.arche/typings. For any other main file it is .arche/typings/<name>:
bench.arche has .arche/typings/bench/arche/… and
.arche/typings/bench/arche.d.ts. So two main files in one folder never write
over each other.
Python. The extension sets a default for Pylance (and basedpyright):
python.analysis.extraPathsis[".arche/typings/_workspace", ".arche/typings"]. You write no setting.from arche import *resolves, and names are completed and checked with their types.A Python language server reads one
archepackage per workspace folder. When the workspace folder is the folder of onemain.arche, that is the project's own package. In any other case, the extension also writes.arche/typings/_workspace/arche/at the root of the workspace folder. These cases are a project in a sub-folder, several projects, or a main file with another name. That package holds the names of every model in the workspace folder. When two models declare the same name, the first model's declaration is used (the models are sorted by path). If you need each project to see only its own names, open each project as its own workspace folder, or usearche.editorStubs: beside.The default does not apply when you set
python.analysis.extraPathsyourself, or when the folder has apyrightconfig.jsonor a[tool.pyright]table. Then add.arche/typingsto your ownextraPaths.TypeScript. The extension brings a TypeScript server plugin. For a file of an Arche project, the plugin adds the model's
arche.d.tsto the TypeScript project and resolves"arche"(and"./arche") to it. A file reads thearche.d.tsof the model that names it inproject.json. A file that no model names yet reads the nearest one above it. Go to Definition onsendopens the file in.arche/typings. Without atsconfig.jsonof yours, the files are not checked in strict mode, as before. With one, your options are kept. A workspace's own TypeScript version loads the plugin too.Stubs from earlier versions. Earlier versions of the extension wrote
arche.py,arche.d.tsand atsconfig.jsonbeside the code. Once per workspace, it removes them and says how many. It removes anarche.pyorarche.d.tsonly when the file starts with archec's "Generated by archec" line, and atsconfig.jsononly when it is exactly the one archec wrote. It only looks in folders that hold a.archefile, and in the folders under them. A file you wrote or edited is never removed.The setting
arche.editorStubs:projectis the default, described above;besidewritesarche.py,arche.d.tsandtsconfig.jsonbeside the code, as before, and removes.arche/typings;offwrites and removes nothing.
On the command line,
archec stubs main.archewrites the same files in the same place. See python.md for pyright and mypy.
The diagram#
Diagram to the side (⌘K V, or the diagram button in the editor title). It is drawn in the Arche canvas theme, light or dark, following VS Code. The setting
arche.diagram.themeforces one. It shows:- the system's blocks, with their ports as coloured dots;
- the links, with pill labels;
- every state machine and every scenario.
It uses your positions when every part has one: the
canvaslines, oraton a part. Otherwise it lays the blocks out itself; Layout switches between the two. It updates as you type and follows the cursor.Arche actions on the drawing, as on the Arche canvas. Each one edits your
.archesource, as one step you can undo.- Click a block, port, link or state. It is selected, what is not connected to it fades, and the source is revealed. The properties panel shows its identity: Rename… (everywhere, through the language server), name, description, kind, layer, colour, tags. For a port: its direction, type, sends and receives. For a link: its name, its messages, and Flip.
- Drag a block to move it. This writes its line in the system's
canvasblock when there is one, and otherwiseat x, yon the part. On an automatic layout, the first move keeps every block where it is. - Drag from a port to a port to link them. In a state machine, drag from a state to another to add a transition.
- Double-click a block to go inside it, or a link to name it. Del deletes the selection. + adds a part, or a state.
Steps drawn from the code:
app -> core : init expanddraws, after the step, the call tree ofinit.expand 2goes two calls down.A function with a
```archebody draws what its body does:- each of its own functions that it calls;
- each
port.op(…), as a step to the part across the link, with its dashed reply. There is no reply for aonewayoperation or one that gives nothing; - each
send, as a message; - an
ifas analt, or anoptwhen it has noelse; awhileor aforas aloop. Each is labelled with its own text; - what calls nothing is left out.
A click on such a step opens the line of the body it comes from.
For a Python or TypeScript body, and for a child's function (which a body cannot call), the diagram draws the
callsof each function. A function markedparalleldraws its calls as apar.Two checks go with it. A
calls gthat the```archebody never makes is a hint (calls-not-in-body). A step from a component to one inside it that none of its functionscallsis a warning (seqstep-not-called).Long scenarios, a page at a time: a scenario of several sequences shows them all, or one alone. The sequence picker shows one, with only the lifelines it reaches.
- A
ref otherstep is a box over the lifelines its sequence covers. A click opens that sequence alone; ◂ Back returns. - A click on a composite's band folds its children into one lifeline.
fold Sys.compon a sequence, or on the scenario, folds it from the start. - A click on a fragment's tab (
▾ alt) folds it into one row:▸ alt — 5 steps, folded.foldedin the fragment starts it shut. - Hover a constant that lists what each row needs (
SERVICES, or[SERVICES]in a text) to see its matrix: a row per entry, a column per thing it may need.
- A
The palette, left of the diagram (‹ hides it). It holds:
- the core elements: component, part, in and out port, function, link, state;
- the boards of the board store and of your collections;
- the packages of the configured Arche Store (
arche.store); - a search box (
esp32 can).
Drag an item onto the canvas, or click it to add it in the middle:
- a component or a part goes where it falls;
- a port or a function goes on the block under the pointer;
- a board is added as
archec board addwrites it: its part, itsinclude, and theusesof its collection. When the diagram shows no hardware system, it goes in a new one; - a store package is added once you said yes to the code it brings. It is
installed into
.arche/store; then come itsuses, itsinclude, and a part of its main component.
The User interface section holds a Screen, a Dialog, an Overlay, the layouts and the elements of a
ui { }. Dropped on a block, they go into its definition's ui.Each drop is one edit you can undo. Each item's tooltip says what it is and how it is written. You can also drag boards and packages from the Store Shelves and Store views.
Property forms, under the properties panel. A selected part, component or port has a field for each property its declaration takes. The fields come from the language's description (
src/spec.ts). They are grouped as the language groups them: compute, timing, delivery, physical, product, integrity, traceability. A field is:- a dropdown for a choice (
os,pattern), or for the names in scope (satisfiesrequirements,variants); - a checkbox for yes or no;
- a number and a unit for a quantity (
power 15W,latency 2ms).
Each field has the property's documentation as its help. A value is checked before it is written: a number, a unit of that quantity, a declared name. The error shows under the field.
- a dropdown for a choice (
The simulation debugger#
Start it with Run › Start Debugging, or with Debug Test on a case in the Testing view. A test case runs in simulation with arche-cli, and you step through its run event by event.
- The call stack is the event, at the line it is about:
- a message, at the function it ran, the transition it fires, or the case line that sent it;
- a state change, at the state;
- an expectation, at its
expectline.
- Variables has the time, the event (message, from, to, function), every
component's state, the expectations checked so far, and the count of each
message sent. Hover or watch
time,adcu.stateorsent("BRAKE_CMD"). - Breakpoints go on
.archelines. A failed expectation stops the run (Failed expectations and errors). - Stepping: step over goes to the next event, and step out to the next instant. Step back and reverse continue work too, since the run is recorded.
A launch.json entry looks like this:
{ "type": "arche", "request": "launch", "program": "${workspaceFolder}/main.arche", "case": "TP-AEB/TC-AEB-01" }
Without case, you pick one. With "trace", the debugger replays a trace
exported from the Arche app in the same way.
A recent arche-cli keeps the trace records with --trace
(PLAN__CASE.trace.json, variable writes included). So a run also has a
Variables scope: each component's variables as they stand at the event.
Why? and Why not?#
Stopped at an event, press Why? (the question mark in the debug toolbar, or the call stack's menu). The event's causes open as a list, back to where they started: the transition and its guard's values, the message and where in the model it is sent, the thread that sent it. Each line has its time, and picking one opens its line in the model (why.md).
Outside the debugger, two commands ask for a run first: a test case, run on
archec's simulator, or a trace file of the board (archec gen --trace).
- Arche: Why Did This Happen? then lists the run's timeline to pick an event from.
- Arche: Why Did This Not Happen? (also in the editor's context menu) takes the transition under the cursor, or one you pick. It says whether its state was never active, its trigger never came, or its guard was never true, and how close the values came.
The same answers go to the Arche output.
Getting started#
- Get started with arche-lang (Help › Welcome › Walkthroughs, or Arche: Get Started with arche-lang). Its steps: understand the concepts, create a project, add a component, add a board from the palette, wire a sensor, run the simulation, generate C. Each step ticks itself when the model (or the workspace) shows it done. The first step ticks once the cheat sheet is open. arche-lang: Show Cheat Sheet opens the cheat sheet at any time.
- Convert to arche body: a
```pythonbody that says only what the action language says gets a hint. This quick fix writes it as a```archebody (fixes).
The side bar and the commands#
Arche side bar: click the Arche icon in the activity bar. You browse the model as in the Arche app:
- Model: systems → components → ports, functions, variables, memory, state machine, requirements. Then definitions, messages, data types, constants, requirements, actors, missions, scenarios, test plans, traces, catalogs.
- Files: the include tree.
- Store Shelves (it was Boards): the store's six shelves — types, units,
boards, peripheral drivers, sensors and actuators, algorithms. A piece
shows its one-line summary; a click opens its card (the seven lines, what
it writes, an algorithm's response chart) with Add to This Project, as
archec shelf adddoes. A board or a device asks where it goes, as Add Board to Model… and Add Device to Model… do. Filter Shelves… narrows every shelf by a word (shelves, boards). - Store: the packages of the Arche Store (store).
A click jumps to the source. The inline buttons open the diagram and add a part. Right-click for Add part / port / function / state, Rename…, Set name…, Set kind… and Delete. The tree follows the model of the file you edit; Select the model to browse pins one.
Commands (⇧⌘P → "Arche"):
- Build Project, also the ▶ button in the editor title;
- Export LaTeX Specification…;
- Open in Arche: runs
arche --project …and opens the browser; - Validate Project Folder…;
- Show Pattern Reference;
- Show Requirement Status: what proves each requirement, in the Arche Status output (status).
- Run Test Ladder…:
archec test --ladder, one line per rung in the Arche Status output; the board only when you choose it. A rung whose tool is not installed (Renode, probe-rs) is skipped. - Run FPGA Tests in GHDL:
archec test --target vhdl, the test cases on the VHDL of the model's FPGA components (FPGA components), with the GHDL the extension's platform build carries. - Synthesise FPGA Design:
archec synth, the FPGA components synthesised, placed and routed for the model's device: its cells and the fmax of each clock, in the Arche Status output. The tools are not in the extension:archec synth --install-toolssays where to get them. - Prove a Fix Against a Git Ref…:
archec test --against <ref>: a case that fails on the older build and passes here proves the fix. - Check Board's Build from Trace…:
archec status --build <trace>: is the firmware that wrote the trace this model's build.
Settings#
| Setting | What it does |
|---|---|
arche.outputDirectory |
Where Build Project writes the Arche project. Default arche-out. In a workspace with several projects, each one builds into its own sub-folder, arche-out/<project folder>. |
arche.entry |
The main .arche file of the workspace. Empty: the file you edit, or the file that includes it. |
arche.paths.app |
The Arche app, which Open in Arche starts. Point it at arche/dist/arche-darwin-arm64. Empty: arche on the PATH. |
arche.port |
The port that Open in Arche serves on. |
arche.buildOnSave |
Build the Arche project again each time a .arche file is saved. |
arche.lint.minimumSeverity |
The lowest severity shown in the Problems view. |
arche.format.indent |
Spaces per indentation level. |
arche.diagram.theme |
The diagram's colours: auto, light or dark. |
arche.suggestions |
The shelf hints: auto (on at the beginner level, the default), on or off. |
arche.editorStubs |
Where Arche's names for Python and TypeScript tooling are written: project (in .arche/typings, the default), beside (beside the code, as earlier versions did) or off. |
Limits#
- A debugger run is at most 50 000 records.
- With an older arche-cli, the debugger keeps only the sequence view. There are
no variable values, a state change is timed at the event before it, a run is
at most 2000 events, and only the run of a failing case is kept. The
debugger builds its own copy of the project and adds one last step that
fails on purpose (
expect False). That step is not shown, and a case that passes is reported as passing. - VS Code wants Shift held to drop a board or a package from the Store Shelves and Store views into the diagram.
- The errors of a model held in a JavaScript or TypeScript test are not shown
unless
arche.embedded.problemsis on.