Getting started › Overview

Getting started

arche-lang documentation

  • Concepts — the model before the syntax: definition and instance (component and part), port → message → link, state machines and triggers, requirement → satisfies → verified-by → test plan, system → deployment → generated code. Read it first.
  • Cheat sheet — the core declarations, one line each, the action language and the five commands, on one page.
  • Starting a project — archec new: a project that checks clean from a template (a rover, a CAN sensor node, a drone flight controller), a store package to remix, or a sentence Claude turns into a first model.
  • Tutorial — a water pump, from model to firmware: messages, components, a state machine, a requirement, a test in the simulator, a deployment, the generated Rust, CI and libraries. Start here.
  • The specification — the language itself, like Go's spec: lexical elements, the grammar in EBNF, declarations, types and values, names, packages and paths, structure, behaviour, traces, verification, and its one layout.
  • Effective Arche — how to write a model that reads like every other one; a section per archec vet code (archec explain <code> prints it).
  • Language reference — every declaration: where it goes, its syntax, each property and an example. Generated from the compiler (archec patterns -o docs/patterns.md), so it is what the compiler reads.
  • Commands — every archec command, by what it is for.
  • The browser simulator — see a model work with nothing installed: archec sim, a page that animates it, the Run button of the VS Code diagram, the store's "Try it"; what it simulates and what it does not.
  • Animations — the moving pictures of a story's slides: one of Arche's animation templates, its content written in the model and bound to it; archec animation, a story as one HTML file, the Animations view in VS Code.
  • The product's user interface — ui { } in the component that owns the display: screens, layouts and elements bound to the model, what a press sends, the checks (bindings, dead presses, unreachable screens, safety, fit, contrast, translations), archec ui and the model previews and generators read.
  • Generators of your own — generator rte { templates | script | command }, run as archec gen --target rte: the generator model (JSON, v1), the template language, scripts in a sandbox, commands in any language, libraries and approval.
  • Plugins — generators, importers (archec import x.ccmproject) and exporters (archec export --format) in one folder: the project's plugins/, a Store package of kind plugin, or built into archec (McCOFFEE).
  • Regenerating code — your code between USER CODE markers kept when archec gen writes again, orphans, the @arche tags and the genmap, archec where on a compiler's error, gen --diff, the editor's preview.
  • The quality of the generated code — archec gen --build --lint with each finding at its model element, C unit tests from the test plans and their coverage, defensive code from the model, the traceability matrix.
  • Template documents — your Word or LibreOffice document filled with the model: archec doc --template, its placeholders, loops and diagrams.
  • Fixes and the beginner level — the errors that fix themselves (archec fix, the editor's quick fixes), the plain wording, and level simple.
  • C++ — archec gen --target cpp: C++17 classes, the C's codecs, a std::thread per thread of a deployment, CMake; what it does not do yet.
  • Register maps — archec gen --target regmap: a part's memory blocks as a C header, an AXI4-Lite bank in VHDL and SystemVerilog, IP-XACT, SystemRDL and a document, all from the same blocks; the checks on them.
  • Integration targets — what the tools around the firmware read, generated: CANopen EDS, J1939 parameter groups, MAVLink, SOME/IP, OpenAPI and AsyncAPI; CMake, west, PlatformIO and CI; flash and serial-monitor scripts; the bench's buses and its python-can scripts.
  • Boards — the board store archec ships (ESP32, STM32 Nucleo, Raspberry Pi, nRF52840 DK, Jetson, Kria), your own collections, archec board and the Boards view in VS Code.
  • The Arche Store — sharing architectures, drivers, specifications and boards: archec add, archec store publish, signatures, trust, running a store.
  • How arche-lang works — the toolchain modelled in its own language: the compiler stages and what they pass on, each generator, the editor and its language server, the design decisions, and the test that verifies each promise. Build it and open it in Arche.
  • The project README — what arche-lang is, installing it, five minutes from archec new to generated code.
  • The VS Code extension — highlighting, diagnostics, quick fixes, completion, hover, the diagram and its palette, the simulation debugger, the walkthrough, the side bar, commands and settings.

Topics:

  • How it maps to Arche — what each declaration becomes in the Arche project.
  • Verification — formal checks of state machines and contracts, requirements that cannot hold together, testing with faults, test coverage, runtime verification of the real system's logs.
  • Safety and cybersecurity — error propagation, fault trees, STPA, TARA.
  • Qualifying archec — archec qualify: the tool-qualification kit (ISO 26262-8 §11, DO-330) for the archec features you rely on.
  • Deployment — hardware, threads and buses, archec live, containers.
  • Code generation — every archec gen target.
  • Robots — ROS 2, Gazebo, MuJoCo, plants.
  • Physics — fitting a model to measurements, FMUs in the simulation.
  • Importing — an Arche project, SysML v2, URDF and MJCF, Capella.
  • Handlers in TypeScript or Python — handlers typescript|python|arche, code in .ts and .py files — and the way back from Arche and the simulator.
  • Design notes — one spelling for each thing, pointers, the language's choices, performance.
  • Changes — what each version added.