How-to guides › Use VS Code

How-to guides

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 ```python blocks, YAML inside ```yaml;
    • ```arche blocks in Markdown too.

    A ```arche body 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 setting arche.bodies.highlight puts a faint background behind each body.

  • 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, with Heater declared in lib.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 as Pid or Bme280, gets Use Pid from arche-algorithms: it adds the uses and the include. The project is the main file's folder and its subfolders, without node_modules, .arche, out, build, arche-out, dist and hidden folders. archec check says the same, and archec fix adds the include when only one file has the name.

  • What proves each requirement: a line above each requirement says what proves it today, as archec status does: proved by 3 tests · timing on board nucleo-f446re ✓ · 2 h ago, out of date: Thermostat.update changed, or nothing proves it. It reads the evidence that archec test, verify, timing and replay record, 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 after port x:, types after var 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 its include and the project's uses;
    • 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 the uses for 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 and BRAKE_CMD(force=…) in Python;
    • on send port MESSAGE (or send(port, message)): first the ports that send, then the messages the port carries.
  • Navigation: go to definition, find references, rename across files, outline, workspace symbols (⌘T), format document. A .arche file 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 ```arche body too, by what each name is. Ctrl+click on got goes to the component's var got; on bump(), to its fn bump; on send o TRACK { id: … }, to the port, the message and its field. A parameter goes to the function's signature, and a local to its var.

    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 as archec refactor move-definition (commands/refactor.md).

  • Models in JavaScript and TypeScript: a test can hold a model as archeSrc`…` (from test/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 setting arche.embedded.problems shows 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 Lidar inherits 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.enabled turns 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 Vec3 or a GeoPoint, a component named as a store device. The hint says what it looks like and why. Its quick fix adds the uses and the include; 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 setting arche.level, or a project's level simple) and off otherwise; arche.suggestions (auto, on, off) decides. archec suggest lists 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 ```arche blocks 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.extraPaths is [".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 arche package per workspace folder. When the workspace folder is the folder of one main.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 use arche.editorStubs: beside.

    The default does not apply when you set python.analysis.extraPaths yourself, or when the folder has a pyrightconfig.json or a [tool.pyright] table. Then add .arche/typings to your own extraPaths.

  • TypeScript. The extension brings a TypeScript server plugin. For a file of an Arche project, the plugin adds the model's arche.d.ts to the TypeScript project and resolves "arche" (and "./arche") to it. A file reads the arche.d.ts of the model that names it in project.json. A file that no model names yet reads the nearest one above it. Go to Definition on send opens the file in .arche/typings. Without a tsconfig.json of 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.ts and a tsconfig.json beside the code. Once per workspace, it removes them and says how many. It removes an arche.py or arche.d.ts only when the file starts with archec's "Generated by archec" line, and a tsconfig.json only when it is exactly the one archec wrote. It only looks in folders that hold a .arche file, and in the folders under them. A file you wrote or edited is never removed.

  • The setting arche.editorStubs:

    • project is the default, described above;
    • beside writes arche.py, arche.d.ts and tsconfig.json beside the code, as before, and removes .arche/typings;
    • off writes and removes nothing.
  • On the command line, archec stubs main.arche writes 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.theme forces 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 canvas lines, or at on 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 .arche source, 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 canvas block when there is one, and otherwise at x, y on 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 expand draws, after the step, the call tree of init. expand 2 goes two calls down.

    A function with a ```arche body 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 a oneway operation or one that gives nothing;
    • each send, as a message;
    • an if as an alt, or an opt when it has no else; a while or a for as a loop. 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 calls of each function. A function marked parallel draws its calls as a par.

    Two checks go with it. A calls g that the ```arche body never makes is a hint (calls-not-in-body). A step from a component to one inside it that none of its functions calls is 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 other step 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.comp on 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. folded in 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.
  • 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 add writes it: its part, its include, and the uses of 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 its uses, its include, 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 (satisfies requirements, 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.

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 expect line.
  • 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.state or sent("BRAKE_CMD").
  • Breakpoints go on .arche lines. 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 ```python body that says only what the action language says gets a hint. This quick fix writes it as a ```arche body (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 add does. 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-tools says 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.problems is on.