Reference › Commands › Generate

Reference › Commands

Generate

The commands that write code, and files for other tools, from the model.

Commands: archec gen · archec generator · archec plugin · archec fmi · archec kicad · archec sysml · archec export · archec api · archec capella

On this page: More on these commands

Command What it does
archec gen <main.arche> --target <t> [-o generated] [--deployment D] [--check] [--trace] [--monitors] Source code from the model. embassy: a Rust crate per binary (channels, CAN codec, state machines, tasks; your app.rs kept). sbom: a CycloneDX 1.5 bill of materials (sbom/bom.cdx.json) — the hardware with its vendor and part number, the libraries at the version arche.lock names, a firmware per binary on its processor. proto, ros2, dds: the messages, structs, enums and unions (and an interface's operations as a service) for protobuf (proto3), ROS 2 (.msg, .srv, as the ament package <project>_msgs) and DDS (OMG IDL 4); ros2 with a deployment that says packaging ros2 (the one --deployment names, else the first) also writes ros2_nodes/: an ament_cmake package per binary on a Linux processor — an rclcpp executable per process, a node per part around its C module (publishers, subscriptions, services, a timer per periodic thread, parameters from its props, QoS from the links) — and <deployment>_bringup with its launch file; colcon build in the output folder builds them. gazebo: the plant of that deployment in Gazebo (gz sim Harmonic), as the package gazebo/ — an SDF world with a link per sensor, actuator or part with a mass (gpu_lidar, camera, imu, navsat sensors where the part is one), the ros_gz_bridge config, sim_adapter.py (Gazebo's standard messages into the model's, the nodes' commands into gz topics) and a launch file that starts it all with the nodes on simulated time; the world and the adapter are yours once written. mujoco: the plant in MuJoCo (mujoco/<system>.xml, MJCF) — a body per part with a mass or a shape, nested as the parts are and placed by their joint … at, its geom from its shape with its mass, its hinge, slide, ball or free joint, a sensor per kind sensor part (jointpos, jointvel, accelerometer, gyro, force, torque, touch, rangefinder, framepos, framequat, from its name or the unit of what it sends), an actuator per kind actuator part on the joint of the body it is in (motor, position or velocity from the unit of the field that commands it; on a free body, a thruster on a site), the timestep from the solver step, a keyframe from the joints' = value — and mujoco/plant_bridge.py, the commands into data.ctrl and data.sensordata into the sensors' messages at their period: --stdio for archec sim --plant, --csv out.csv [--control seq.csv] for a fixed control sequence, --viewer, --ros2 a ROS 2 node on the topics of gen --target ros2 (see MuJoCo). tests: a test case per transition a message triggers (the shortest way to its source, then its trigger and the state after) and per received message at its limits; the cases with a TODO are listed in tests/generated.allow for archec test --allow. ears-tests: a test case per EARS requirement (the trigger sent by the part wired to send it, the response expected in time). go: a Go program per binary that says language go, on a Linux board of the hardware store: the board's adaptor and a driver per device linked to it (bus and address, or pins, from the links), the parts it runs (variables, arche bodies translated, state machines, messages on channels), a goroutine per thread, a link to a part another go binary runs as JSON over HTTP (`net.go`, each binary on its port from 9001, `ARCHE_LISTEN`/`ARCHE_PEER_<BINARY>` to move them; tested in `net_test.go`), `user.go` yours; the store's Go code it uses is copied in, so it builds with nothing outside Go. On a host (a processor with `compute { os linux }` and no board), the same without the hardware. The parts' HTTP handlers (`handler GET "/items/{id}" -> item`) become a server (`http.go`: the routes `--target openapi` describes, each call run on its part's thread, on `ADDR` or the port of the part's `attr url`, else :8080) and `http_test.go`, a test of each route for `go test`. `ui-web`: the product's screens (each `ui`) as a web app that runs on its own — `ui-web/index.html`, `ui.js`, `ui.css`, `ui.json`: by default the model simulated in the page (a press sends its message into the run), with `?ws=ws://host:port` the values from a WebSocket instead (see [ui](../ui.md#the-web-target-gen---target-ui-web)). `c`: C99 — the types and their codecs (the same bytes as the DBC and the Rust), a module per component (its variables and state, its functions with arche bodies translated, goto, fire for its transitions, its after timers, deadlines and watchdogs, in the order the specification gives), the send functions yours to wire, and with a deployment a FreeRTOS task per thread. --monitors: the requirements as run-time monitors in each binary (EARS responses within their deadline, formal invariants, eventually … within and … leads to … within, one flag and one deadline each), the checks archec replay makes on a log; a violation calls arche_monitor_violation, yours in monitor_hook.c; no heap. With --trace, each verdict is also a trace line, `arche-trace monitor <1 fail
archec gen <main.arche> --target c|embassy --build [--lint] [--sarif f] Builds what was just written (codegen quality): c with each binary's Makefile (or each module on its own without a deployment) and -std=c99 -Wall -Wextra -Werror -pedantic, embassy with cargo build. --lint adds cppcheck's MISRA C:2012 addon and clang-tidy for C, cargo clippy for Rust — each only when installed, a missing one said. Each finding is printed at the model element its generated line comes from (main.arche:57 error [cc-unused-variable] … — c/controller_ports.c:6 in controller_send_cmd (port cmd of Controller)); --sarif writes them as SARIF 2.1.0 at those elements. Exit 1 when the build fails.
archec gen <main.arche> --target c-tests [-o generated] [--run] [--coverage] The model's test plans as C unit tests of the generated C (codegen quality): under c-tests/, the component modules, arche_tests.c (difftest's harness — the parts on a virtual clock, the links' latency — and a function per case) and a Makefile (make test, make coverage). A case's send(...), a part's variable set, part.state == "S", sent("MSG") and expressions are translated; a case with anything else is a SKIP that says why. --run builds and runs them (PASS/FAIL/SKIP per case, exit 1 when one fails) and writes c-tests/results.json as archec test writes its results; --coverage with gcov reads the lines that ran back as the states, transitions and functions covered, reported as archec test --coverage does.
archec gen <main.arche> --target c --defensive [-o generated] Defensive C from the model (codegen quality): each message's ranges as <msg>_in_range(), and with a deployment each input of a binary checked as it is dispatched — a value out of its range rejected (not clamped), an input quiet for longer than its port's stale-after (else its message's period × 1.5) flagged stale (<binary>_input_stale()), a wire format's wrong checksum and its counter repeated (rejected) or jumping (lost messages, counted), as AUTOSAR E2E does; each counted in arche_errors and logged once until the input is good again. Opt-in: it changes what the parts see.
archec gen <main.arche> --target trace-matrix [-o generated] [--results r.json]… The traceability matrix (codegen quality), trace-matrix/matrix.md and matrix.csv: each requirement, the model elements that satisfy it, the C generated for each (file, line, function), the cases that verify it and their last result — from --results files, else arche-out/.archec/test-results.json (Arche's simulator) and <out>/c-tests/results.json (the C) — then the gaps (no element, no code, no case, a failing or unrun case).
archec gen <main.arche> --target modelica [-o generated] The systems whose parts have equations or physical ports as a Modelica package (modelica/<project>.mo) and an OpenModelica script per system (simulate_<System>.mos, results as CSV): a std/physics part as the Modelica Standard Library 4.0 component it is (Resistor → Modelica.Electrical.Analog.Basic.Resistor, HeatCapacitor → Modelica.Thermal.HeatTransfer.Components.HeatCapacitor…), the other components models with their equations, physical ports as MSL connectors, signals as RealInput/RealOutput, links as connects, a fn main that waits and sets as when clauses, an experiment per system from its test plans and its solver step. The table, and what is left out, in physics.
archec gen <main.arche> --target ui-lvgl|ui-slint [-o generated] [--deployment D] Each ui { } as code for a device (ui). ui-lvgl: ui-lvgl/ui_<id>.c/.h for LVGL 9 — its screens, widgets, theme, the bindings read from the part's struct of --target c (each message it reads kept by the part, the parts beside it copied by the wiring), the events calling the part's send functions — and ui_<id>_task.c (written once: lv_init, your display, the loop); a binary built with -DARCHE_UI starts it. ui-slint: a crate per ui under ui-slint/<id>/ — the .slint file, the Rust glue (Received, Sent, the events) and a std host main.rs (written once). An element a target makes only in part is a note; none is dropped.
archec gen <main.arche> --list The targets: the built-in ones, and the project's own generators (generator … { templates | script | command }) with their kind and where they are written.
archec gen <main.arche> --target <generator> [-o generated] [--deployment D] [--option k=v]… [--check] Runs a generator of your own (generators): the generator model in, its files into <out>/<output>/ (its id by default), never outside, never over a file it marks keep that exists. --option sets one of its options for the run (JSON when it reads as JSON). Its problems are printed at the elements' lines; exit 1 on an error.
archec generator new <id> --templates|--script|--command [--label "…"] [--into main.arche] A generator that works, to start from: its files in generators/<id>/, its declaration added to the file.
archec gen <main.arche> --target canopen|j1939|mavlink|someip|openapi|asyncapi [-o generated] [--deployment D] Protocol descriptions (integration targets). canopen: a CiA 306 EDS per binary on a CAN bus, a transmit PDO per frame it sends and a receive PDO per frame it takes (the route's id the COB-ID, the period the event timer), the messages as objects from 0x2000 mapped at their bits; node id and identity from attr canopen_node_id, vendor_id, product_code. j1939: per bus with 29-bit routes, the parameter groups — PGN, priority, PDU format, destination or group extension, source address read from the id — with an SPN per signal at its J1939 position, length, resolution and offset (attr spn on the field gives its number). mavlink: the catalog as a MAVLink 2 dialect for mavgen — a message per message, a field per signal (arrays of scalars as arrays, enums with their entries, units MAVLink knows), ids from attr mavlink_id, else numbered from 65536 and listed. someip: the SOME/IP services as JSON — an interface a port provides (its operations methods, the messages its provider sends events), an Ethernet port that publishes, each instance with its binary and its consumers, the data types; ids from attr someip_service_id, someip_method_id, someip_event_id, else numbered and listed. openapi: an OpenAPI 3.1 document per component with HTTP handlers — an operation per handler, path, query and body parameters from its function, the return type the answer. asyncapi: an AsyncAPI 3.0 document per system — a channel per sending port at its topic, send and receive operations, a server per bus. What the model does not say is in the notes.
archec gen <main.arche> --target cmake|west|platformio|ci [-o generated] [--deployment D] Build systems around the C of --target c, written into the same folder (integration targets). cmake: a project per C binary (its model a library, its runtime POSIX on a host, FreeRTOS cross-compiled), a toolchain file from each microcontroller's core, port.cmake yours for the kernel, startup and linker script, and cmake/CMakeLists.txt that builds every C binary on the host. west: a Zephyr application per binary on a Zephyr board — its CMake, prj.conf, the devicetree overlay and a west.yml pinning Zephyr and the board's HAL. platformio: platformio.ini per binary on a board PlatformIO knows, its platform, board and framework, the C as its sources. ci: a GitHub Actions workflow and a GitLab pipeline — archec check and archec ci, archec gen --check per target the deployment uses, the C built with CMake and run, each Rust binary built with cargo.
archec gen <main.arche> --target flash [-o generated] [--deployment D] Per binary on a microcontroller (the lab): flash/<binary>/flash.sh [image], which flashes it with the first of its chip's tools installed (STM32: probe-rs, OpenOCD; nRF52: probe-rs, nrfjprog, OpenOCD; RP2040: picotool, probe-rs, OpenOCD; ESP32: espflash, esptool; TOOL= chooses), the image from cargo's target folder or build-<binary>/; and flash/<binary>/monitor.sh, which reads its --trace output for ARCHE_DURATION seconds — a C binary's from the board's UART at the link's bitrate, a Rust one's defmt over RTT with probe-rs — then runs archec timing and archec live --replay on it.
archec gen <main.arche> --target bench [-o generated] [--deployment D] The hardware test rack of a deployment (the bench): bench/<deployment>.yaml — each bus with its type, bitrate, the rack's interface, the nodes on it and the frames it carries; the devices under test with their board, chip, flash and monitor scripts; the power supplies and what they feed; the IO links — and per CAN bus setup_<bus>.sh (SocketCAN at its bitrate, CAN FD, or a vcan) and bench_<bus>.py (python-can: the frames named after the model and checked against their periods, --as <binary> to stand in for a missing node, --interface virtual without hardware).
archec gen <main.arche> --target regmap [-o generated] The register map of each part with addressed memory blocks, in regmap/<part>/: a C header (offsets, field masks and shifts, access macros on a base, static asserts on the layout), an AXI4-Lite register bank in VHDL and in SystemVerilog (rw/w registers out, r values in, a write strobe per element, large blocks as RAM ports, reset values, SLVERR elsewhere), IP-XACT (IEEE 1685-2014), SystemRDL 2.0 and a Markdown memory map (register maps).
archec gen <main.arche> --target vhdl [-o generated] [--deployment D] The FPGA components of the model (FPGA components) as VHDL-2008, in vhdl/: a package of the model's data, an entity per component with a clock (its signals and messages as ports, one clocked process, the state machine as a case, the action-language bodies translated with their widths), the AXI4-Lite bank of a component with addressed memory blocks, the system's top, a GHDL testbench per test case, and sources.txt. USER CODE regions are kept. Extension: fpga.
archec gen <main.arche> --target cpp [-o generated] [--deployment D] C++17 in cpp/: constants as inline constexpr, enums as enum class, unions as std::variant, optional fields as std::optional, messages as structs with encode/decode on the C's wire layout (the same bytes); a class per component — its variables, its functions (```arche bodies and the Python the action language can say translated), its state machine as an enum class State and a switch (go_to, fire, on-exit and on-enter, after timers, watchdogs, deadlines), what it sends as std::function members; with a deployment, a main.cpp per binary that says language cpp (each binary when none does) with a std::thread per thread of the model, the links inside the binary wired and the others through hooks.cpp (yours); a CMakeLists.txt (C++).
archec gen <main.arche> --list The targets: the built-in ones, and the project's own generators (generator … { templates | script | command }) with their kind, the targets they run after or read (builtins), where they are written, and their declared options (type, default, values, what each is for, the value set when it is not the default).
archec gen <main.arche> --target <t> [--no-hooks] A target's files go through the project's hooks on it — the generators that say after <t> (a built-in target or one of the project's), in the order they are written — before they are written or --checked: each gets the files and returns what it changes (generators). --no-hooks: the target's files as they are.
archec gen <main.arche> --target <generator> [-o generated] [--deployment D] [--option k=v]… [--check] Runs a generator of your own (generators): the generator model in, its files into <out>/<output>/ (its id by default), never outside, never over a file it marks keep that exists. --option sets one of its options for the run (JSON when it reads as JSON; as the option's type when it declares one, and held to it). Its problems are printed at the elements' lines; exit 1 on an error.
archec generator new <id> --templates|--script [--ts]|--command [--label "…"] [--into main.arche] A generator that works, to start from: its files in generators/<id>/, its declaration added to the file. --ts: the script in TypeScript (generate.ts), typed by generator-model.v1.d.ts written beside it.
archec generator types [-o generator-model.v1.d.ts] The generator model and a script's ctx as TypeScript declarations (schemas/generator-model.v1.d.ts), for a script "gen.ts".
archec gen <main.arche> --target <t> [--move <old>=<new>]… [--orphans ok] Your code in a region the new code no longer has stops the write: nothing is written, exit 1, each stranded region shown with the new regions it may belong to. --move puts a region's code into another; --orphans ok lets it go to <file>.orphans. A rename made with the editor's Rename or archec refactor rename carries the code by itself (arche.renames.json), and a clear rename by hand is recognised (regeneration).
archec refactor rename <main.arche> <element> <new-name> [--dry-run] The element renamed everywhere (its declaration, every reference, its uses in its component's code), as the editor's Rename does, and recorded in arche.renames.json so archec gen carries your code to the new name.
archec gen <main.arche> --target <t> --diff What a write would change, as a unified diff (your USER CODE regions carried, as a write carries them); nothing written, exit 1 when something would change. --check lists the files instead. Generated C, Rust and Go keep the code between USER CODE BEGIN <id> / END <id> markers each time they are written again; a region the model no longer gives goes to <file>.orphans (regeneration).
archec generator model <main.arche> [--deployment D] [-o model.json] The generator model, version 1 — what a generator reads (schemas/generator-model.v1.json).
archec generator test <main.arche> <id> [--update] [--expected dir] The generator's output against the files you approved (expected/<id>/ beside its declaration): each file missing, changed (at its first different line) or new; exit 1 on a difference. --update approves the output as it is.
archec plugin list [main.arche] [--json] The plugins found — the project's plugins/<name>/plugin.arche, the libraries of kind plugin it uses (the Store's among them), ARCHE_PLUGINS, the ones built into archec (lib/plugins) — each with where it comes from and the generators, importers and exporters it brings, their options, and what needs approval; the errors in a plugin's own declarations (exit 1). Without a project: the built-in plugins and ./plugins (plugins).
archec plugin approve <main.arche> <plugin> [--revoke] Every script and command a library's plugin brings, listed with its code, then each recorded in arche.lock at the library's fingerprint (acme/importer:kv, acme/exporter:x, acme/gen); a change to the library asks again.
archec fmi <main.arche> <System|Def> [-o dir] [--build] An FMI 2.0 co-simulation FMU of the equations (sources; --build compiles and zips it). A physical network goes in sorted and solved, a nonlinear loop by Newton's method in C; its states, the parts' variables and out signals are outputs, an in signal linked to nothing an input.
archec kicad <main.arche> [System] [-o file.net] A system's wiring as a KiCad netlist (.net, the s-expression format pcbnew reads): each part with signals a symbol with no footprint (a board A1, the others U1), its pins those of its ports (uart2.TX/PA2, a port type's wires, CAN_H/CAN_L, SDA/SCL, V+/GND); a net per signal — TX to RX crossed, the same signal otherwise, everything on a kind bus by signal (chassis_can_CAN_H), every GND one net. The system is the one named, else the deployment's platform. See boards.
archec sysml <main.arche> [-o model.sysml] The architecture in SysML v2 textual notation.
archec export <main.arche> [--json] [-o model.json] [--compact] The resolved model as one JSON document, for scripts: every declaration an element with its id (its path, Vehicle.ctrl; a requirement its own id; one with no name its parent's id and kind, Vehicle/link1), kind, file and line, parent and children, type, definition, direction, unit and properties — a quantity as {"value": 10, "unit": "ms"}, a name as {"ref": "REQ-1", "id": "REQ-1"} with what it resolves to; each link's and transition's ends resolved; the traces once each, from whatever wrote them (satisfies, verifies, derives, a trace, a requirement inside a component, and the old satisfied-by); and the diagnostics. Written even with errors (exit 1). The Python package lib/python/archelang reads it: archelang.load("main.arche").requirements.untraced() (Python).
archec export <main.arche> --format <exporter> [-o out.x] [--option k=v]… [--deployment D] The model as a file of another tool, by a plugin's exporter (the generator model in, its files out): one file to -o (or stdout), several into -o as a folder. Without --format, -o's ending picks the exporter whose extension it is; -o model.json stays the JSON. Its problems are printed at the elements' lines; a library's script runs once approved (plugins).
archec api serve <main.arche> [--port 9000] [--host 127.0.0.1] The model over the OMG Systems Modeling API (SysML v2 REST/HTTP), read-only, for a SysML v2 tool or a script: /projects, its branch, /commits (git's history of the project's folder, newest first, and the files as they are when they differ; a model outside git is one commit), /tags (each baseline, at the commit that added it), /commits/{c}/elements[/{e}], /roots, /elements/{e}/relationships?direction=in|out|both, and POST /query-results with a Query (PrimitiveConstraint: property, operator = < <= > >= instanceOf, value, inverse; CompositeConstraint and/or; select, scope). Lists are paged by page[size], page[after], page[before], with a Link header. An element's @id is the same in every commit; elements are typed as archec sysml writes them (a definition a PartDefinition, a part a PartUsage, a port a PortUsage, a link a ConnectionUsage, a requirement a RequirementUsage, a trace a Dependency), with what archec knows of each under arche (its id, kind, file, line, properties); ?kind= and ?type= filter /elements (archec's own). The memberships between elements are not elements: owner and ownedElement say the ownership directly.
archec capella <main.arche> [-o dir|project.zip] A Capella 6.1 project (one Arcadia level per layer), checked against Capella's metamodel; what Capella cannot hold is listed.
archec capella <model.capella|folder|project.zip> [-o dir] [--prefix p] [--layers oa,sa,la,pa,epbs] [--no-diagrams] [--project dir] A Capella model in arche-lang, through the Arche project the app's Capella import makes.

More on these commands#

Python#

lib/python/archelang reads a model in a script or a notebook, through archec export --json (standard library only; pandas for the tables, when installed):

import archelang                                   # pip install -e lib/python, or PYTHONPATH=lib/python
m = archelang.load("examples/autonomous-car/main.arche")
m.requirements.unverified()                        # [<requirement REQ-SAF-001 …>, …]
m["REQ-BRK-001"].satisfied_by                      # [<component Adcu …>]
m["Car.brakes"].ports                              # a part's ports, its definition's
m.find(kind="port", direction="in")
m["REACTION_TIME"].value                           # Quantity(value=150, unit='ms')
m.requirements.to_dataframe()                      # with pandas
m["REQ-BRK-001"].set("priority", "high")           # archec edit: written only if it adds no error

Each element has its id, kind, label, file and line, parent and children, properties (el.period, el.prop("stale-after")), and its traces (satisfies, verified_by, derives…). Links and transitions have their source, target, and the parts they are on. archelang finds archec on the PATH, or ARCHEC names it. examples/brake-by-wire/model.ipynb is a short notebook.

SysML v2 API#

archec api serve main.arche serves the model over the OMG Systems Modeling API (the SysML v2 REST API), read-only: the project, its commits — git's history of the model's folder, and the files as they are — its baselines as tags, the elements at each commit, their relationships, and queries.

archec api serve examples/autonomous-car/main.arche --port 9000
curl -s localhost:9000/projects
curl -s -X POST localhost:9000/projects/<id>/query-results \
  -d '{"@type":"Query","where":{"@type":"PrimitiveConstraint","property":"@type","operator":"=","value":"RequirementUsage"}}'