Guides pratiques › Utiliser l’application Arche

Guides pratiques

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 :

  1. Les sources modifiées sont construites en mémoire, puis émises de nouveau.
  2. 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.
  3. 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-index s'arrête sur une erreur si le bloc project n'a pas de source-root.