Le shell et les commandes rdc

This document is available in English

rdc.exe, dans le dossier RDCore.CLI de la plateforme, est le programme en ligne de commande de RDCore. Lancé seul, il ouvre le shell RD-VBA. Avec une commande, il exécute cette commande et se termine.

Ligne de commande Ce qu'elle fait
rdc Ouvre le shell sur un espace de travail temporaire qui lui est propre, supprimé à la sortie du shell.
rdc --workspace <chemin> Ouvre le shell sur un espace de travail (voir Apporter un projet VBA).
rdc <commande> [<options>] Exécute une commande (ci-dessous), sans le shell.
rdc --help Liste les options que prend rdc lui-même.
rdc <commande> --help Liste les options de cette commande.

À une commande qu'il ne connaît pas, rdc répond par la liste des commandes qu'il connaît.


Le shell

Le shell exécute ce que vous tapez. Une ligne sans numéro de ligne s'exécute sur-le-champ : Debug.Print 6 * 7. Une ligne qui commence par un numéro de ligne est écrite dans le programme courant : 10 Debug.Print "Bonjour". Le programme courant est le corps d'une procédure implicite nommée Main, dans un module implicite nommé Program. Il reste en mémoire jusqu'à NEW, LOAD ou EXIT.

Une ligne numérotée dans un bloc qui n'a pas de fermeture dans le programme (un If, un Select Case, une boucle, un With) lance la complétion de bloc. La ligne suivante s'ouvre sur le numéro plus 10, sélectionné, et les fermetures dont le bloc a besoin s'affichent en grisé sous elle, avec leurs numéros : après 120 If x > 0 Then, la ligne est 130 et 140 End If est en dessous. Tab prend le numéro, et un numéro que vous tapez le remplace. Une fois que le bloc a une instruction, la fermeture est proposée après le numéro, et Tab la prend et valide la ligne. Chaque ligne est écrite dans le programme dès que vous la validez. La complétion de bloc se termine à la dernière fermeture, à une ligne vide, à une commande ou à une ligne sans numéro. Elle ne renumérote jamais une ligne : quand la ligne suivante du programme ne laisse aucun numéro pour une fermeture, le shell le dit.

Sur un espace de travail (rdc --workspace <chemin>), le shell exécute chaque ligne dans le projet de l'espace de travail : Main, Program.Main et les autres procédures publiques du projet peuvent être appelées depuis l'invite. Il n'y a pas de programme courant. Une ligne numérotée, et les commandes qui se servent du programme (LIST, FOLD, NEW, SAVE, LOAD, RUN, ANALYZE, DUCKY, et CONT vers une ligne), répondent ERREUR : AUCUN PROGRAMME.

Sur un espace de travail, BREAK prend un module et une ligne de son fichier : BREAK Other 9, BREAK Other 9 I > 5, BREAK TOGGLE Other 9. BREAK seul les liste sous la forme Other 9, et BREAK CLEAR les retire tous. Un module que l'espace de travail n'a pas répond ERREUR : MODULE NON DÉFINI, et une ligne où ne commence aucune instruction répond AUCUNE INSTRUCTION À Other 9.

La langue du shell est le BASIC de RDCore : la variable qu'une ligne assigne est celle que lit la ligne suivante, sans Dim, et Print seul est une instruction.

Commande Ce qu'elle fait
HELP Liste les commandes du shell.
LIST Affiche le programme, mis en forme, ou une plage de ses lignes : LIST 100-200.
FOLD <ligne#> Réduit dans un listage le bloc qui commence à une ligne (un If, un Select Case, une boucle, un With), ou le développe.
INLAYS ON, INLAYS OFF Affiche dans un listage les indices du serveur de langage (le paramètre auquel chaque argument est donné, le type d'une déclaration qui n'en indique pas), ou les masque.
NEW Efface le programme.
SAVE [<nom>], LOAD <nom> Écrit le programme dans un fichier texte .rdc, ou l'en lit. SAVE seul écrit dans le fichier d'où vient le programme.
RUN Exécute le programme.
ANALYZE Analyse le programme et rapporte ses diagnostics.
BREAK <ligne#> [<condition>] Place ou retire un point d'arrêt à une ligne; avec une condition, il attend celle-ci : BREAK 40 I > 5. BREAK TOGGLE <ligne#> le désactive ou le réactive, BREAK seul les liste, et BREAK CLEAR les retire tous.
CONT [<ligne#>] Reprend après un arrêt, ou à partir d'une ligne : CONT 200.
STEP, STEP INTO, STEP OUT Exécute une instruction du programme interrompu : sans entrer dans les appels, en y entrant, ou jusqu'à la fin de la procédure courante.
STACK Affiche les procédures où se trouve le programme interrompu, de la plus interne à la plus externe.
VARS [<n>], FRAME <n> Affiche les variables du programme interrompu. VARS 1, ou FRAME 1 puis VARS, porte sur la procédure appelante.
EDITS Affiche les modifications faites lors d'un arrêt qui ne sont pas appliquées au programme, et pourquoi (voir Modifier et continuer).
DUCKY [<ligne#>] Propose ce qui peut être fait du programme, ou d'une de ses lignes, et fait ce que vous choisissez.
CONFIG Affiche vos paramètres et les modifie, avec complétion. Les changements de mise en forme s'appliquent aussitôt.
THEME LIST, THEME <nom> Liste les thèmes de couleurs du shell, ou en choisit un.
CLEAR Efface la console.
MEMORY, PEEK <adresse>, POKE <adresse>, <octet> Affiche un sommaire de la mémoire de la session, en lit un octet, ou en écrit un.
EXIT Termine la session et quitte. BYE et QUIT font de même.

Ctrl+C arrête un programme en cours d'exécution. Lors d'un arrêt (une instruction Stop, un Debug.Assert qui échoue, un point d'arrêt ou Ctrl+C), le shell liste les deux lignes au-dessus de la ligne de l'arrêt et les deux au-dessous, la ligne de l'arrêt étant mise en évidence, puis affiche INTERRUPTION À LA LIGNE et le numéro de ligne. Une erreur d'exécution que rien ne gère arrête le programme à l'instruction qui l'a déclenchée, comme dans le VBIDE : le shell liste de la même façon les lignes autour de cette instruction, puis affiche l'erreur. CONT exécute de nouveau l'instruction, et END termine le programme comme une instruction End : les variables que les lignes précédentes ont affectées, les variables locales Static, les objets et les fichiers ouverts disparaissent avec lui, et aucun Class_Terminate ne s'exécute. Une erreur qu'une instruction On Error gère ne l'arrête pas. Un pas ne liste rien : il affiche seulement INTERRUPTION À LA LIGNE et le numéro de ligne, ou l'erreur à laquelle il s'est arrêté. CONFIG CLI.BreakListingLines fixe combien de lignes sont listées de chaque côté, à partir du prochain démarrage du shell; 0 n'en liste aucune. Lors d'un arrêt, vous pouvez taper des instructions comme dans le volet exécution du VBIDE, et modifier le programme avant de reprendre.

Une ligne tapée à l'invite s'exécute sous le débogueur comme avec RUN : un Stop, un point d'arrêt ou une erreur dans le code qu'elle appelle l'arrête là, et STACK montre la procédure propre à la ligne sous celle qui s'est arrêtée. Un arrêt dans un module d'un espace de travail liste les lignes du module autour de cet arrêt comme LIST liste le programme, puis affiche INTERRUPTION DANS, le module et sa ligne. Un arrêt à une erreur dans un module d'un espace de travail liste de la même façon les lignes du module, puis affiche l'erreur avec le module et sa ligne.

Note

Le shell est une façon d'essayer la plateforme. Son programme courant est une seule procédure : un projet qui en a plus s'exécute dans le shell sur un espace de travail. Le shell ne prend pas en charge les numéros de ligne à la BASIC dans vos propres modules.


Les commandes

Chaque commande prend un espace de travail, soit un dossier, avec ou sans .rdproj, soit un seul fichier de module. Sans espace de travail, elle travaille sur le dossier courant.

Commande Alias Ce qu'elle fait
rdc new <chemin> n Fait d'un dossier un espace de travail : écrit un .rdproj qui nomme chaque fichier de module du dossier. --name fixe le nom du projet (celui du dossier par défaut), --empty écrit un projet sans fichiers, et --force remplace un .rdproj existant.
rdc import <chemin> i Crée le .rdproj d'un projet VB6, à côté de son .vbp (voir Projets VB6). --force remplace un .rdproj existant.
rdc run [<options>] [<chemin>] [<arguments>] r Exécute le programme de l'espace de travail (ci-dessous). Ce qui suit le chemin est la ligne de commande du programme, que retourne Command$.
rdc build [<chemin>] bd Construit un programme à partir de l'espace de travail : son exécutable et le runtime sur lequel il s'exécute (ci-dessous).
rdc config configure Affiche les paramètres de la plateforme et les modifie, comme le CONFIG du shell, sans démarrer la plateforme.
rdc export-library <bibliothèque> xl Décrit une bibliothèque de types de cette machine (un fichier comme scrrun.dll, son identifiant ou son nom) dans un fichier qu'un projet peut référencer par son nom. --dependencies décrit aussi les bibliothèques dont elle dépend.
rdc compilation [<chemin>] cc Indique, pour chaque procédure, si elle s'exécute compilée, ce qui la garde dans l'interpréteur, et ce que l'interpréteur exécute pour elle lorsqu'elle est compilée.
rdc bench [<chemin>] b Chronomètre un espace de travail : son analyse syntaxique, son chargement, son analyse, puis l'exécution de chaque Public Sub Bench*() de ses modules standard par le moteur d'exécution configuré, avec ce que chaque cas alloue.
rdc describe-ext <extension> x Écrit le manifeste d'une extension de la plateforme. Elle s'adresse aux auteurs d'extensions (voir Bâtir sur RDCore).
rdc install Installe pour votre compte d'utilisateur la plateforme d'où rdc est lancé, et met rdc dans votre PATH (ci-dessous). Elle ne prend pas d'espace de travail.
rdc splash s Écrit l'écran d'accueil de la plateforme en texte brut, que sa sortie soit une console ou non. Elle ne prend pas d'espace de travail.

Dans une console, une commande commence par l'écran d'accueil de la plateforme. Une sortie redirigée vers un fichier ou un tube n'en a pas : elle ne contient que ce que la commande écrit.

Exécuter un programme

rdc run exécute le point d'entrée du programme :

  • la procédure que le .rdproj nomme comme point d'entrée dans sa section build, Module.Procedure ou Procedure : "build": { "entryPoint": "Module1.Main" };
  • sinon, le Sub Main du seul module standard qui en déclare un.

Un projet sans point d'entrée (RDC30001), ou avec un Sub Main dans plus d'un module standard (RDC30002), ne s'exécute pas. Une bibliothèque ("build": { "outputType": "Library" }) ne s'exécute pas non plus, pas plus qu'un projet dont un module ne se charge pas. Debug.Print écrit sur la sortie standard. Un MsgBox ou un InputBox s'affiche dans la console et on y répond, comme dans le shell, sous tous les systèmes d'exploitation. Le paramètre CLI.NativeDialogs les affiche plutôt comme des boîtes de dialogue Windows, sous Windows. Le paramètre ne change pas la façon dont un formulaire s'affiche : il ouvre sa propre fenêtre.

Option Ce qu'elle fait
-c, --configuration Debug (par défaut) ou Release.
--unattended Personne ne répond aux boîtes de dialogue : un MsgBox ou un InputBox fait échouer l'exécution. Le programme le sait : l'option vient en premier dans Command$ et dans les arguments de Main, comme pour un programme construit, sauf si la ligne de commande du programme l'a déjà.

Les options viennent avant le chemin. Tout ce qui suit le chemin est la ligne de commande du programme, options comprises : rdc run --unattended . s'exécute sans surveillance, et rdc run . --unattended ne fait que donner --unattended au programme. Un -- juste après le chemin est ignoré. Sans chemin, c'est le dossier courant qui s'exécute, et -- précède la ligne de commande du programme. Sans chemin ni --, rien ne va au programme, et une option que rdc ne connaît pas est une erreur.

rdc run . --seed 42
rdc run . -- --seed 42
rdc run -- --seed 42

Le code de sortie indique comment s'est passée l'exécution :

Code de sortie Signification
0 Le programme s'est terminé : son point d'entrée est revenu, il a exécuté un End, ou il a exécuté un Stop en Release.
1 Une erreur d'exécution l'a terminé, ou un Stop en Debug l'a interrompu, sans débogueur où s'arrêter. La sortie d'erreur indique lequel, avec le numéro et la description de l'erreur.
2 Il n'a pas pu démarrer : aucun point d'entrée, ou un module qui ne se charge pas.

Construire un programme

rdc build compile l'espace de travail en un programme qui s'exécute sans l'analyseur syntaxique de RDCore, et sans les sources de l'espace de travail : le programme s'exécute à partir de son propre dossier, où qu'il soit. Il lui faut le même point d'entrée qu'à rdc run.

Option Ce qu'elle fait
-o, --output Le dossier où le programme est écrit; bin/<configuration>/<runtime>/ dans l'espace de travail par défaut.
-n, --name Le nom du programme; celui du projet par défaut.
-c, --configuration Debug (par défaut) ou Release.
-r, --runtime La plateforme pour laquelle le programme est construit, comme win-x64 ou linux-x64; celle où s'exécute rdc par défaut.

Le programme affiche ses boîtes de dialogue comme rdc run, et son code de sortie indique comment s'est passée son exécution, comme celui de rdc run. Exécuté avec --unattended parmi ses arguments, il échoue au premier MsgBox, InputBox ou formulaire qu'il affiche. L'option reste dans Command$ et dans les arguments de Main.

Un programme construit appelle le monde extérieur (une procédure déclarée par Declare, un objet d'un serveur d'automation) comme rdc run, par un second processus : son propre exécutable, relancé comme son hôte externe, qui se termine avec lui.

L'exécutable est fait de l'hôte d'application .NET du runtime du programme. rdc est livré avec les hôtes de win-x64, linux-x64, osx-x64 et osx-arm64, les runtimes pour lesquels la plateforme est publiée : il construit donc un programme pour chacun d'eux, où qu'il s'exécute. Pour un autre runtime, il prend l'hôte d'un SDK .NET installé. Là où ni l'un ni l'autre ne l'a, le programme est construit sans exécutable; exécuté avec dotnet <nom>.dll, il n'appelle pas le monde extérieur.

L'exécutable d'un programme construit pour macOS (osx-x64, osx-arm64) est signé ad hoc, comme le SDK .NET signe celui d'une application : un Mac doté d'une puce Apple n'exécute aucun exécutable qui n'est pas signé. La signature n'a pas de certificat : ce n'est pas une signature Developer ID.

Le dossier du programme contient, dans Symbols, une description de chaque bibliothèque que son projet référence, et de chaque bibliothèque dont elles dépendent. Le programme les lit à partir de là, où que soit le dossier.

Le dossier contient aussi les conditions de licence de ce sur quoi le programme s'exécute :

Fichier Conditions de
NOTICE.md, LICENSE-GPLv3.md RDCore.
LICENSE-MIT.md RDCore.SDK.
THIRD-PARTY-NOTICES.txt Les autres paquets du dossier, et l'exécutable du programme.

Transmettez-les avec le programme. NOTICE.md dit ce qu'elles vous demandent, et que votre propre code reste le vôtre. rdc les copie depuis la plateforme d'où il s'exécute, et avertit quand il n'en a aucune à copier.

Installer la plateforme

rdc install installe la plateforme d'où il est lancé, comme une archive de version que vous avez décompressée, pour votre compte d'utilisateur. Le complément de l'IDE installe la plateforme au même endroit : chacun utilise ce que l'autre a installé.

  • Il copie la plateforme dans RDCore/Platform/versions/<version>/ de votre dossier de données d'application locales : %LOCALAPPDATA% sous Windows, ~/.local/share sous Linux, ~/Library/Application Support sous macOS. Une version déjà installée n'est pas copiée de nouveau, et aucune version n'est supprimée.
  • Il fait de cette version la version courante, à moins que la version courante soit plus récente.
  • Il met le rdc de la version courante dans votre PATH, à la place de celui d'une version antérieure. Sous Windows, il ajoute le dossier RDCore.CLI de la version à votre Path d'utilisateur. Sous Linux et macOS, il crée le lien ~/.local/bin/rdc vers celui-ci; quand ~/.local/bin n'est pas dans votre PATH, il ajoute à ~/.profile (Linux) ou à ~/.zprofile (macOS) un bloc de lignes qui l'y met. Ouvrez un nouveau terminal pour l'utiliser.
Option Ce qu'elle fait
--path-only Met seulement le rdc de la version courante dans votre PATH.
--no-modify-path Installe la plateforme sans modifier votre PATH ni votre profil.

Le code de sortie indique comment s'est passée l'installation :

Code de sortie Signification
0 La plateforme est installée.
1 Elle ne l'est pas : le dossier d'où rdc est lancé n'est pas une plateforme complète, aucune version n'est installée (--path-only), ou ~/.local/bin/rdc est un de vos propres fichiers. Le message indique lequel.
2 Les options ne sont pas valides.

ACCUEIL • HOME | ℹ️ BIENVENUE • WELCOME | 🧩 BÂTISSONS • BUILD | RD-VBAL | SDK | 🌐 rubberduckvba.ca