L'application Arche sur des sources .arche
L'application Arche est l'éditeur visuel : le canevas, les pages de
spécification, les scénarios, les histoires et la page Code. archec app la sert
sur un projet écrit en arche-lang. Vous modifiez le modèle dans l'application, et
vos changements reviennent dans les fichiers .arche. Dans VS Code, la commande
Arche: Open Arche App fait la même chose depuis l'éditeur.
Premier lancement#
Placez-vous dans un dossier qui contient un main.arche (celui de Comment
arche-lang correspond à Arche convient) :
archec app main.arche
✓ the Arche app on main.arche: http://127.0.0.1:8080/
9 YAML files built from 1 .arche files; saves are written back into the .arche files
Ouvrez l'adresse dans un navigateur. Arrêtez le serveur avec Ctrl+C. Pour choisir le port et autoriser l'application à exécuter le Python du projet :
archec app main.arche --port 9000 --allow-python
Fonctionnement#
Le projet reste dans ses fichiers .arche. Aucun YAML n'est écrit sur le
disque.
Ce que lit l'application#
L'application lit du YAML Arche. archec le construit à partir des sources, comme
le fait archec build : chaque fichier de modèle, de catalogue ou de
spécification que demande l'application est produit par l'émetteur. Il est
reconstruit dès qu'une source change : dans l'éditeur, sur le disque ou après un
git pull.
Ce qu'enregistre l'application#
Un enregistrement est réécrit dans les sources. archec compare ce qu'il a donné à l'application avec ce qu'elle lui renvoie. Chaque différence devient la plus petite modification de la source qui la produit :
| Dans l'application | Dans la source .arche |
|---|---|
| un nom, un texte, un nombre, une position modifiés | le libellé ou la valeur de la propriété remplacés sur place ("Brake" → "Disc brake", at 300, 40 → at 320, 40) |
| une liste de noms modifiée | la propriété réécrite (languages fr, en, de) |
| un composant, un port, un lien, une exigence… ajoutés | sa déclaration, telle que l'écrit archec import, à côté de ses voisines |
| un élément supprimé | sa déclaration effacée |
| un champ pour lequel le langage n'a pas de mot | attr key = value sur la déclaration à laquelle il appartient |
un fichier que le projet n'avait pas (problems.yaml) |
data "problems.yaml" = {…} dans app/problems.arche, inclus depuis le fichier principal |
Chaque enregistrement est vérifié avant toute écriture :
- Les sources modifiées sont construites en mémoire, puis émises de nouveau.
- L'enregistrement n'est accepté que si le fichier ressort exactement tel que l'application l'a envoyé, et si le modèle n'a aucune nouvelle erreur.
- Sinon, l'application reçoit une réponse HTTP 422 avec les différences restantes. Les sources ne sont pas modifiées.
Les panneaux de texte affichent de l'arche-lang#
Certains panneaux de l'application affichaient du YAML : le panneau à côté du
canevas et le mode YAML des pages de spécification (désormais appelé
arche). Ils affichent maintenant la déclaration .arche qui se trouve
derrière ce qui est à l'écran : le composant sélectionné, l'exigence affichée
par le formulaire, ou le fichier à partir duquel un document est écrit (une
liste permet de choisir).
Enregistrer le panneau (Ctrl+S) remplace ce texte dans son fichier. La vérification est la même. Une modification qui laisserait le modèle en erreur est refusée, et les erreurs sont signalées sur leurs lignes.
Dans VS Code#
Arche: Open Arche App démarre le serveur dans l'extension, sur le modèle de
l'espace de travail, puis l'ouvre. arche.app.openIn choisit où : dans votre
navigateur ou dans un onglet VS Code.
- L'application lit le modèle tel que l'éditeur le connaît, texte non enregistré compris.
- Un enregistrement depuis l'application est appliqué comme une seule
modification des fichiers
.arche. Ctrl+Z l'annule. Il est écrit sur le disque si le fichier n'avait pas lui-même de modifications non enregistrées. - Un élément de la barre d'état indique que le serveur tourne. Arche: Stop Arche App l'arrête.
- Le serveur n'écoute que sur 127.0.0.1, avec un jeton dans l'URL qu'il ouvre. Les autres programmes de la machine ne peuvent pas l'utiliser.
| Paramètre | |
|---|---|
arche.app.openIn |
browser (par défaut) ou editor |
arche.app.port |
le port ; 0 (par défaut) en choisit un libre |
arche.app.allowPython |
autorise l'application à exécuter le Python du projet (avec vos droits) |
arche.app.allowBuild |
autorise la page Code à compiler la source et à lancer des serveurs de langage |
Ce qui est servi#
Le serveur est celui de l'application Arche, réécrit en TypeScript dans
src/app/ (l'original est en Go). Il a les mêmes routes, les mêmes formes de
requêtes et de réponses, les mêmes codes de statut et les mêmes messages :
l'application fonctionne donc sans modification.
| Routes | Module | Remarques |
|---|---|---|
modèles, fichiers, catalogues (/api/models, /api/files, /api/layout, /api/types, …), versions |
server.ts, project.ts, writeback.ts |
YAML construit à partir des sources et réécrit dans celles-ci ; les versions If-Match/ETag fonctionnent comme avant |
/api/arche/source, /api/arche/language |
source.ts |
nouveau : le texte .arche derrière ce qu'affiche l'application |
| fiches techniques, images, organigramme, modèles pptx, présentations | stores.ts |
de vrais fichiers, dans le dossier du projet (ou dans le dossier que copie une entrée assets) |
/api/source/* |
sources.ts, sourceindex.ts, sourcedeps.ts, sourcewrite.ts |
le code sous le source-root du projet |
/api/git/* |
git.ts |
la commande git |
/api/python/*, /api/code/* |
python.ts, codetools.ts |
seulement avec --allow-python, --allow-build |
| présence, utilisateur et configuration Arche | server.ts |
~/.arche/config (thème, lecture seule) et .arche/config.yaml (droits git) restent en YAML : ce sont des réglages, pas le projet |
Le mode lecture seule (readOnly: true dans ~/.arche/config) refuse toute
écriture, comme le faisait le serveur Go.
archec app --source-index affiche l'index du code du projet en JSON, puis
s'arrête. Il affiche ce qu'affichait l'option --source-index du serveur Go.
Utilisez-le pour les vérifications modèle/code d'une tâche de CI. Il faut un
source-root dans le bloc project (source-root "code/firmware").
Options#
| Option | |
|---|---|
--port 8080, --host 127.0.0.1 |
où il écoute |
--static <dir> |
l'application construite (par défaut : à côté d'archec, ou ../arche/frontend/dist) |
--allow-python [--python python3] |
l'environnement d'exécution Python |
--allow-build |
compilations et serveurs de langage |
--token <t> |
ne répondre qu'aux requêtes qui le portent (?token= une fois, puis un cookie) |
--source-index |
afficher l'index du code et s'arrêter |
Limites#
- Le terminal SSH (
/api/terminal/ssh) n'est pas servi. Utilisez un terminal de votre éditeur. --source-indexs'arrête sur une erreur si le blocprojectn'a pas desource-root.