How-to guides › Regenerate code

How-to guides

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
}
Diagram: Demo
What archec draws from this code: Demo
Try it
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, binary or part.

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's src/arche.rs and the Go main.go have 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 commit arche.lock.
    • The next archec gen applies 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.
  • 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 gen says 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. --check and --diff stop 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 ok lets it go to <file>.orphans, as before.
    • In VS Code, Preview Generated Changes asks the same question for each stranded region.
    • archec check warns about this earlier (gen-stranded), while you edit the model. It reads generated/ beside the model.