Regenerating code
archec gen writes the code again each time the model changes. This page says
what happens to the code you wrote around it. It also shows how a line of
generated code leads back to the model, and how to see a regeneration before it
happens.
A first region#
A function with no body in the model:
component Brake "Brake" {
var offset: int32 = 0
fn calibrate()
}
system Demo {
part brake: Brake
}archec gen main.arche --target c -o generated
In generated/c/brake.c, the function has a place for your code, between two
markers:
/* @arche Brake.calibrate main.arche:3 fn */
void brake_calibrate(brake_t *self)
{
/* USER CODE BEGIN Brake.calibrate.body */
(void)self;
/* USER CODE END Brake.calibrate.body */
}
Write your code there, for example self->offset = 12; in place of
(void)self;. Then change the model: add var gain: float32 = 1.0, and rename
calibrate to zero. Run archec gen again:
generated/c/brake.c: Brake.calibrate.body → Brake.zero.body (your code carried: looked like a rename)
…
your code kept in 1 region(s) of 1 file(s)
Your line is still there, in the renamed function.
Your code: USER CODE regions#
A region is a place in a generated file for code you write by hand. Generated C, Rust and Go mark each region with two comments:
/* @arche Brake.calibrate main.arche:42 fn */
void brake_calibrate(brake_t *self)
{
/* USER CODE BEGIN Brake.calibrate.body */
self->offset = adc_read(3);
/* USER CODE END Brake.calibrate.body */
}
In Rust and Go the markers are // USER CODE BEGIN ….
When archec writes the file again, it first reads the file on disk. Then it
puts back what is between the markers of each id. The ids are model paths
(Brake.calibrate.body, Brake.init, car.brake_fw.start), not line numbers.
So the code around a region can move, grow or shrink, and your code still lands
in its place.
Where the regions are:
| Generator | Regions |
|---|---|
c, c/<part>.c |
<Part>.includes, after the includes. <Part>.init, at the end of <part>_init. <Part>.<fn>.body, for a function whose body the model does not give: no body, or Python the action language cannot say. <Part>.<port>.on-receive and <Part>.<port>.on-deadline, in the same way. |
c, c/<part>_ports.c |
<Part>.ports.includes. <Part>.<port>.send.<MESSAGE>, the body of each send function. |
c, c/<binary>/wiring.c |
<deployment>.<binary>.includes. <deployment>.<binary>.start, in <binary>_start, after the parts are initialised and before the threads start. |
ros2, ros2_nodes/<binary>/src/<exe>.cpp |
<deployment>.<binary>.<exe>.includes, after the includes. <part>.node, at the end of each node's constructor. <part>.members, in its class. <deployment>.<binary>.<exe>.start, in main, after the nodes are made and before the threads start. |
ros2, ros2_nodes/<binary>/CMakeLists.txt |
<deployment>.<binary>.cmake, before ament_package(). |
ros2, ros2_nodes/<binary>/c/<part>.c |
the same as the c target: <Part>.includes, <Part>.init, … |
go, parts.go |
<Part>.init, in New<Part>. <Part>.<fn>.body, for a function the model gives no body. |
embassy, src/app.rs |
<part path>.<fn>.body, for a function with no body. Each guard to implement. Each input handler (<part path>.on_<port>). |
A body the model gives is generated, not a region. That is a body in the action language, or Python it can translate. To change it, change the model.
When a region disappears#
Say the model no longer has a region, because its function was removed or
renamed. The code that was in it is not dropped. It is added to
<file>.orphans beside the file, for example generated/c/brake.c.orphans.
Each piece is written under the region's id, with the date and the line it was
at. Move what you still need into a region of the new code, then delete the
file. The .orphans file is not compiled.
A region that still holds only what archec put there (its stub) is not an orphan.
A file of yours with regions#
Some files are yours: archec writes them once and never again (keep).
Examples are c/<part>_ports.c and src/app.rs.
Such a file may have regions. If nothing outside the regions changed since
archec wrote it, archec writes it again around your regions. That way a new
port or a new function reaches it. As soon as you edit outside the regions, the
file is yours as before, and it is left as it is. archec gen says so; delete
the file to get a fresh one. An older file with no regions is never touched.
Regions in your own generators#
Your own generators get the same regions. In a template:
{{#region "{{ id }}.glue"}}
todo!()
{{/region}}
This writes the markers around the default code. The comment style follows the
file's name: /* */, // for .rs and .go, # for scripts and Makefiles. A
second argument can name the style instead: "c", "line" or "hash".
A script calls ctx.region(id, defaultCode, style, indent).
Regions in another generator's markers#
Another code generator may already have written files with its own markers.
The style "user-code" writes those markers, so the code in such files is
carried into the new ones:
// -- start of user code: additional members
int m_count = 0;
// -- end of user code
The marker depends on the file's name. It is # -- in a .txt or CMake file,
and <!-- start of user code: name--> in XML. The styles "user-code-hash"
and "user-code-xml" choose one of these.
The region's name may hold spaces, and the end marker names nothing. archec reads these markers on regeneration like its own, by name. Use the name the other generator gave the region:
- in a template:
{{#region "additional members" "user-code"}}; - in a script:
ctx.region("additional members", "", "user-code", "", "Core.h").
The code in the file on disk then comes back there.
From the code to the model#
Each generated function or type that comes from a model element has a tag:
/* @arche Brake.calibrate main.arche:42 fn */
A tag gives:
- the element's path;
- its file (relative to the project) and line;
- its kind:
component,fn,init,machine,on-receive,send,thread,binaryorpart.
From the tags, archec gen writes generated/.archec/genmap.json. For each
file, it holds the line ranges of each element, from its tag to where its
braces close. It also holds what is needed to carry the regions: a hash of the
stubs, and a hash of the file outside its regions.
archec where reads this map to point a compiler's error back at the model:
$ make -C generated/c/brake_fw 2>&1 | archec where main.arche --from generated/c/brake_fw -
../brake.c:17:5: error: use of undeclared identifier 'adc_read'
↳ main.arche:42: Brake.calibrate (fn), in your USER CODE region Brake.calibrate.body
$ archec where main.arche "generated/c/brake.c:17:5: error: …"
main.arche:42 Brake.calibrate (fn) ← generated/c/brake.c:17, in your USER CODE region Brake.calibrate.body
It reads the error formats of:
- gcc, clang and Go:
file:line:col:; - rustc:
--> file:line:col; - MSVC:
file(line).
A path is first resolved from where the compiler ran: --from, else the
current folder. Then it is matched by its end against the map in generated/,
or in --gen <dir>.
In VS Code:
- a generated file with tags has a Go to model element lens above each tagged function. A command of that name uses the cursor;
- on an element of a .arche file, Show generated code opens the code generated from it.
Before writing: --diff and the preview#
archec gen main.arche --target c --diff
This prints a unified diff of what a write would change. Your regions are
carried, exactly as the write would carry them. Nothing is written. In the
first example, adding var gain prints:
--- a/generated/c/brake.h
+++ b/generated/c/brake.h
@@ -7,6 +7,7 @@
/* @arche Brake main.arche:1 component */
typedef struct {
int32_t offset;
+ float gain;
} brake_t;
and the same for brake.c. The exit code is 1 when something would change, 0
when nothing would.
--check does the same, but lists the files instead of the diff. Both fit CI.
A region that would become an orphan is said too.
In VS Code, Arche: Preview Generated Changes… opens VS Code's diff editor for each file that would change. Then it asks whether to write them.
Limits#
- A tag carries the element's line. So a model edit above the element changes the generated file (its tags), even when the code is the same.
- The ranges in the map follow braces. An element written without braces (a
declaration) ends at its
;. A brace inside a string with an escaped quote can throw the count off. embassy'ssrc/arche.rsand the Gomain.gohave no regions: they are the generator's alone.- Files written once that are older than regions (
main.c,drivers.c,user.go) stay yours and are never rewritten.
Renaming an element#
A region is named after its element, so a rename changes the region's name.
For example, BrakeEcu.on_cmd.body becomes BrakeEcu.on_command.body. Your
code still follows the element, in one of three ways.
- With the rename tools, the code is carried exactly. These tools are the
editor's Rename (F2) and
archec refactor rename main.arche BrakeEcu.on_cmd on_command.- They record the rename in
arche.renames.json, beside the model. Commit it, as you commitarche.lock. - The next
archec genapplies each entry once per output folder. The genmap remembers the last one it applied. - A renamed component writes another file (
brake.c→brake_unit.c), and the code follows it there. The old file is said to be no longer generated: delete it.
- They record the rename in
- By hand, a rename is recognised when it is clear. It is clear when
exactly one region with code is gone, and exactly one new region takes its
place. The new region must have the same name but for one part, and the same
stub from the generator.
archec gensays so:Brake.hold.body → Brake.clamp.body (your code carried: looked like a rename). - Anything else stops
archec gen. That covers two functions of the same signature renamed at once, and an element removed.- Nothing is written, and the exit code is 1.
--checkand--diffstop in the same way, so CI sees it. - The output names each stranded region, and the new regions it may belong
to. Then either:
--move Brake.apply.body=Brake.press.body(repeatable) puts the code where it belongs;--orphans oklets it go to<file>.orphans, as before.
- In VS Code, Preview Generated Changes asks the same question for each stranded region.
archec checkwarns about this earlier (gen-stranded), while you edit the model. It readsgenerated/beside the model.
- Nothing is written, and the exit code is 1.