Guides pratiques › Régénérer le code

Guides pratiques

Régénérer le code

archec gen réécrit le code à chaque changement du modèle. Cette page explique ce que devient le code que vous avez écrit autour. Elle montre aussi comment une ligne de code généré renvoie au modèle, et comment voir une régénération avant qu’elle ait lieu.

Une première région#

Une fonction sans corps dans le modèle :

component Brake "Brake" {
  var offset: int32 = 0
  fn calibrate()
}

system Demo {
  part brake: Brake
}
Diagramme : Demo
Ce qu’archec dessine depuis ce code : Demo
Essayer
archec gen main.arche --target c -o generated

Dans generated/c/brake.c, la fonction a une place pour votre code, entre deux marqueurs :

/* @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 */
}

Écrivez votre code à cet endroit, par exemple self->offset = 12; à la place de (void)self;. Modifiez ensuite le modèle : ajoutez var gain: float32 = 1.0 et renommez calibrate en zero. Relancez archec gen :

  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)

Votre ligne est toujours là, dans la fonction renommée.

Votre code : les régions USER CODE#

Une région est un emplacement d’un fichier généré réservé au code que vous écrivez à la main. Le C, le Rust et le Go générés délimitent chaque région par deux commentaires :

/* @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 */
}

En Rust et en Go, les marqueurs sont // USER CODE BEGIN ….

Quand archec réécrit le fichier, il lit d’abord le fichier sur le disque. Puis il remet en place ce qui se trouve entre les marqueurs de chaque identifiant. Les identifiants sont des chemins dans le modèle (Brake.calibrate.body, Brake.init, car.brake_fw.start), pas des numéros de ligne. Le code autour d’une région peut donc se déplacer, s’allonger ou raccourcir : votre code retrouve toujours sa place.

Où se trouvent les régions :

Générateur Régions
c, c/<part>.c <Part>.includes, après les includes. <Part>.init, à la fin de <part>_init. <Part>.<fn>.body, pour une fonction dont le modèle ne donne pas le corps : pas de corps, ou du Python que le langage d’action ne sait pas exprimer. <Part>.<port>.on-receive et <Part>.<port>.on-deadline, de la même façon.
c, c/<part>_ports.c <Part>.ports.includes. <Part>.<port>.send.<MESSAGE>, le corps de chaque fonction d’envoi.
c, c/<binary>/wiring.c <deployment>.<binary>.includes. <deployment>.<binary>.start, dans <binary>_start, après l’initialisation des parts et avant le démarrage des threads.
ros2, ros2_nodes/<binary>/src/<exe>.cpp <deployment>.<binary>.<exe>.includes, après les includes. <part>.node, à la fin du constructeur de chaque nœud. <part>.members, dans sa classe. <deployment>.<binary>.<exe>.start, dans main, après la création des nœuds et avant le démarrage des threads.
ros2, ros2_nodes/<binary>/CMakeLists.txt <deployment>.<binary>.cmake, avant ament_package().
ros2, ros2_nodes/<binary>/c/<part>.c les mêmes que pour la cible c : <Part>.includes, <Part>.init, …
go, parts.go <Part>.init, dans New<Part>. <Part>.<fn>.body, pour une fonction dont le modèle ne donne pas le corps.
embassy, src/app.rs <part path>.<fn>.body, pour une fonction sans corps. Chaque garde à implémenter. Chaque gestionnaire d’entrée (<part path>.on_<port>).

Un corps que donne le modèle est généré : ce n’est pas une région. C’est le cas d’un corps écrit dans le langage d’action, ou en Python que celui-ci sait traduire. Pour le changer, changez le modèle.

Quand une région disparaît#

Imaginons que le modèle n’ait plus une région, parce que sa fonction a été supprimée ou renommée. Le code qu’elle contenait n’est pas perdu. Il est ajouté à <file>.orphans, à côté du fichier, par exemple generated/c/brake.c.orphans. Chaque morceau y est écrit sous l’identifiant de la région, avec la date et la ligne où il se trouvait. Déplacez ce dont vous avez encore besoin dans une région du nouveau code, puis supprimez le fichier. Le fichier .orphans n’est pas compilé.

Une région qui ne contient que ce qu’archec y a mis (son stub) n’est pas orpheline.

Un fichier à vous avec des régions#

Certains fichiers vous appartiennent : archec les écrit une fois, puis plus jamais (keep). C’est le cas de c/<part>_ports.c et de src/app.rs.

Un tel fichier peut avoir des régions. Si rien n’a changé en dehors des régions depuis qu’archec l’a écrit, archec le réécrit autour de vos régions. Un nouveau port ou une nouvelle fonction y arrive ainsi. Dès que vous modifiez le fichier hors des régions, il redevient entièrement à vous et reste tel quel. archec gen le signale ; supprimez le fichier pour en obtenir un neuf. Un fichier plus ancien, sans régions, n’est jamais modifié.

Des régions dans vos propres générateurs#

Vos propres générateurs disposent des mêmes régions. Dans un gabarit :

{{#region "{{ id }}.glue"}}
    todo!()
{{/region}}

Cela écrit les marqueurs autour du code par défaut. Le style de commentaire dépend du nom du fichier : /* */, // pour .rs et .go, # pour les scripts et les Makefiles. Un second argument peut imposer le style : "c", "line" ou "hash".

Un script appelle ctx.region(id, defaultCode, style, indent).

Des régions avec les marqueurs d’un autre générateur#

Un autre générateur de code a peut-être déjà écrit des fichiers avec ses propres marqueurs. Le style "user-code" écrit ces marqueurs-là : le code de ces fichiers est ainsi reporté dans les nouveaux.

// -- start of user code: additional members
int m_count = 0;
// -- end of user code

Le marqueur dépend du nom du fichier. C’est # -- dans un fichier .txt ou CMake, et <!-- start of user code: name--> en XML. Les styles "user-code-hash" et "user-code-xml" choisissent l’un d’eux.

Le nom de la région peut contenir des espaces, et le marqueur de fin ne nomme rien. À la régénération, archec lit ces marqueurs comme les siens, par leur nom. Reprenez le nom que l’autre générateur a donné à la région :

  • dans un gabarit : {{#region "additional members" "user-code"}} ;
  • dans un script : ctx.region("additional members", "", "user-code", "", "Core.h").

Le code du fichier sur le disque revient alors à cet endroit.

Du code au modèle#

Chaque fonction ou type généré à partir d’un élément du modèle porte une étiquette :

/* @arche Brake.calibrate main.arche:42 fn */

Une étiquette donne :

  • le chemin de l’élément ;
  • son fichier (relatif au projet) et sa ligne ;
  • sa nature : component, fn, init, machine, on-receive, send, thread, binary ou part.

À partir des étiquettes, archec gen écrit generated/.archec/genmap.json. Pour chaque fichier, il contient les plages de lignes de chaque élément, de son étiquette jusqu’à la fermeture de ses accolades. Il contient aussi de quoi reporter les régions : un hash des stubs, et un hash du fichier hors de ses régions.

archec where lit cette table pour ramener l’erreur d’un compilateur au modèle :

$ 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

Il lit les formats d’erreur de :

  • gcc, clang et Go : file:line:col: ;
  • rustc : --> file:line:col ;
  • MSVC : file(line).

Un chemin est d’abord résolu depuis l’endroit où le compilateur a tourné : --from, ou à défaut le dossier courant. Il est ensuite comparé, par sa fin, à la table de generated/ ou de --gen <dir>.

Dans VS Code :

  • un fichier généré avec des étiquettes affiche une lentille Go to model element au-dessus de chaque fonction étiquetée. Une commande du même nom utilise la position du curseur ;
  • sur un élément d’un fichier .arche, Show generated code ouvre le code généré à partir de lui.

Avant d’écrire : --diff et l’aperçu#

archec gen main.arche --target c --diff

Cette commande affiche un diff unifié de ce qu’une écriture changerait. Vos régions sont reportées exactement comme l’écriture les reporterait. Rien n’est écrit. Dans le premier exemple, l’ajout de var gain affiche :

--- 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;

et la même chose pour brake.c. Le code de sortie vaut 1 quand quelque chose changerait, 0 sinon.

--check fait la même chose, mais liste les fichiers au lieu du diff. Les deux conviennent à la CI. Une région qui deviendrait orpheline est signalée aussi.

Dans VS Code, Arche: Preview Generated Changes… ouvre l’éditeur de diff de VS Code pour chaque fichier qui changerait. Il demande ensuite s’il faut les écrire.

Limites#

  • Une étiquette porte la ligne de l’élément. Une modification du modèle au-dessus de l’élément change donc le fichier généré (ses étiquettes), même quand le code reste le même.
  • Les plages de la table suivent les accolades. Un élément écrit sans accolades (une déclaration) se termine à son ;. Une accolade dans une chaîne qui contient un guillemet échappé peut fausser le décompte.
  • Le src/arche.rs d’embassy et le main.go du Go n’ont pas de régions : ils n’appartiennent qu’au générateur.
  • Les fichiers écrits une seule fois et antérieurs aux régions (main.c, drivers.c, user.go) restent à vous et ne sont jamais réécrits.

Renommer un élément#

Une région porte le nom de son élément : renommer l’élément change donc le nom de la région. Par exemple, BrakeEcu.on_cmd.body devient BrakeEcu.on_command.body. Votre code suit quand même l’élément, de l’une de trois façons.

  • Avec les outils de renommage, le code est reporté exactement. Ces outils sont le Renommer de l’éditeur (F2) et archec refactor rename main.arche BrakeEcu.on_cmd on_command.
    • Ils enregistrent le renommage dans arche.renames.json, à côté du modèle. Committez ce fichier, comme vous committez arche.lock.
    • Le archec gen suivant applique chaque entrée une fois par dossier de sortie. Le genmap retient la dernière entrée appliquée.
    • Un composant renommé écrit un autre fichier (brake.c → brake_unit.c), et le code l’y suit. L’ancien fichier est signalé comme n’étant plus généré : supprimez-le.
  • À la main, un renommage est reconnu quand il est sans ambiguïté. C’est le cas quand exactement une région contenant du code a disparu, et qu’exactement une nouvelle région prend sa place. La nouvelle région doit porter le même nom à un segment près, et avoir le même stub côté générateur. archec gen le signale : Brake.hold.body → Brake.clamp.body (your code carried: looked like a rename).
  • Dans tous les autres cas, archec gen s’arrête. Cela couvre deux fonctions de même signature renommées en même temps, et un élément supprimé.
    • Rien n’est écrit, et le code de sortie vaut 1. --check et --diff s’arrêtent de la même façon : la CI le voit.
    • La sortie nomme chaque région laissée en plan, et les nouvelles régions auxquelles elle pourrait correspondre. Ensuite, au choix :
      • --move Brake.apply.body=Brake.press.body (répétable) place le code là où il doit aller ;
      • --orphans ok le laisse partir dans <file>.orphans, comme avant.
    • Dans VS Code, Preview Generated Changes pose la même question pour chaque région laissée en plan.
    • archec check prévient plus tôt (gen-stranded), pendant que vous modifiez le modèle. Il lit le dossier generated/ à côté du modèle.