The shell and the rdc commands
Ce document est disponible en français
rdc.exe, in the RDCore.CLI folder of the platform, is RDCore's command-line program. Started alone, it opens the RD-VBA shell. Given a command, it
runs that command and exits.
| Command line | What it does |
|---|---|
rdc |
Opens the shell on a scratch workspace of its own, deleted when the shell exits. |
rdc --workspace <path> |
Opens the shell on a workspace (see Bringing a VBA project over). |
rdc <command> [<options>] |
Runs a command (below), without the shell. |
rdc --help |
Lists the options rdc itself takes. |
rdc <command> --help |
Lists the options of that command. |
A command rdc does not know is answered with the list of the commands it knows.
The shell
The shell runs what you type. A line with no line number runs right away: Debug.Print 6 * 7. A line that starts with a line number is written into
the current program: 10 Debug.Print "Hello". The current program is the body of an implicit procedure named Main, in an implicit module named
Program. It stays in memory until NEW, LOAD or EXIT.
A numbered line in a block the program has no closer for (an If, a Select Case, a loop, a With) starts block completion. The next line
opens on the number plus 10, selected, and the closers the block needs are shown faint under it, with their numbers: after 120 If x > 0 Then, the
line is 130 and 140 End If is under it. Tab takes the number, and a number you type replaces it. Once the block has a statement, the closer is
offered after the number, and Tab takes it and enters the line. Each line is written into the program as you enter it. Block completion ends at the
last closer, an empty line, a command, or a line with no number. It never renumbers a line: when the program's next line leaves no number for a
closer, the shell says so.
On a workspace (rdc --workspace <path>), the shell runs each line in the workspace's project: Main, Program.Main and the other public procedures
of the project can be called from the prompt. There is no current program. A numbered line, and the commands that work on the program (LIST,
FOLD, NEW, SAVE, LOAD, RUN, ANALYZE, DUCKY, and CONT to a line), answer NO PROGRAM ERROR.
On a workspace, BREAK takes a module and a line of its file: BREAK Other 9, BREAK Other 9 I > 5, BREAK TOGGLE Other 9. BREAK alone lists them
as Other 9, and BREAK CLEAR removes them all. A module the workspace does not have answers UNDEF'D MODULE ERROR, and a line no statement begins on
answers NO STATEMENT AT Other 9.
The shell's language is RDCore BASIC: a variable one line assigns is the one the next line reads, without a Dim, and Print alone is a statement.
| Command | What it does |
|---|---|
HELP |
Lists the shell commands. |
LIST |
Shows the program, formatted, or a range of its lines: LIST 100-200. |
FOLD <line#> |
Folds the block that starts at a line (an If, a Select Case, a loop, a With) in a listing, or unfolds it. |
INLAYS ON, INLAYS OFF |
Shows the language server's hints in a listing (the parameter each argument is given to, the type of a declaration that states none), or hides them. |
NEW |
Clears the program. |
SAVE [<name>], LOAD <name> |
Writes the program to a .rdc text file, or reads it from one. SAVE alone writes to the file the program came from. |
RUN |
Runs the program. |
ANALYZE |
Analyzes the program and reports its diagnostics. |
BREAK <line#> [<condition>] |
Sets or clears a breakpoint at a line; with a condition, it waits on it: BREAK 40 I > 5. BREAK TOGGLE <line#> turns one off or on again, BREAK alone lists them, and BREAK CLEAR removes them all. |
CONT [<line#>] |
Goes on from a stop, or from a line: CONT 200. |
STEP, STEP INTO, STEP OUT |
Runs one statement of the stopped program: over calls, into them, or to the end of the current procedure. |
STACK |
Shows the procedures the stopped program is in, innermost first. |
VARS [<n>], FRAME <n> |
Shows the variables of the stopped program. VARS 1, or FRAME 1 then VARS, is about the procedure that called. |
EDITS |
Shows the edits made at a stop that are not applied to the program, and why (see Edit and Continue). |
DUCKY [<line#>] |
Proposes what can be done about the program, or one of its lines, and does what you choose. |
CONFIG |
Shows your settings and sets them, with completion. Formatting changes apply right away. |
THEME LIST, THEME <name> |
Lists the shell's color themes, or picks one. |
CLEAR |
Clears the console. |
MEMORY, PEEK <address>, POKE <address>, <byte> |
Shows a summary of the session's memory, reads a byte of it, or writes one. |
EXIT |
Ends the session and exits. BYE and QUIT do the same. |
Ctrl+C stops a running program. At a stop (a Stop statement, a failed Debug.Assert, a breakpoint or Ctrl+C) the shell lists the two lines above
the stopped line and the two below it, with the stopped line highlighted, then says BREAK IN and the line number. A run-time error that nothing
handles stops the program at the statement that raised it, as in the VBIDE: the shell lists the lines around that statement the same way, then shows
the error. CONT runs the statement again, and END ends the program as an End statement does: the variables that earlier lines assigned, the
Static locals, the objects and the open files go with it, and no Class_Terminate runs. An error that an On Error statement handles does not stop it. A step lists
nothing: it says only BREAK IN and the line number, or shows the error it stopped at. CONFIG CLI.BreakListingLines
sets how many lines are listed on each side, from the next start of the shell; 0 lists none. At a stop you can type statements as in the VBIDE's
immediate pane, and edit the program before you go on.
A line typed at the prompt runs under the debugger as RUN does: a Stop, a breakpoint or an error in the code it calls stops it there, and STACK
shows the line's own procedure under the one that stopped. A stop in a module of a workspace lists the module's lines around it as LIST lists the
program, then says BREAK IN, the module and its line. A stop at an error in a module of a workspace lists the module's lines the same way, then shows the error with the module and its line.
Note
The shell is a way to try the platform. Its current program is a single procedure: a project with more procedures runs in the shell on a workspace. The shell does not handle BASIC-style line numbers in your own modules.
Commands
Each command takes a workspace as a folder, with or without a .rdproj, or as a single module file. Without one, it works on the current folder.
| Command | Alias | What it does |
|---|---|---|
rdc new <path> |
n |
Makes a workspace of a folder: writes a .rdproj that names each module file the folder holds. --name sets the project's name (the folder's by default), --empty writes a project with no files, and --force replaces an existing .rdproj. |
rdc import <path> |
i |
Makes the .rdproj of a VB6 project, next to its .vbp (see VB6 projects). --force replaces an existing .rdproj. |
rdc run [<options>] [<path>] [<arguments>] |
r |
Runs the workspace's program (below). What follows the path is the program's command line, which Command$ returns. |
rdc build [<path>] |
bd |
Builds the workspace into a program: its executable, and the runtime it runs on (below). |
rdc config |
configure |
Shows the platform's settings and sets them, as the shell's CONFIG does, without starting the platform. |
rdc export-library <library> |
xl |
Describes a type library of this machine (a file such as scrrun.dll, its identifier, or its name) as a file a project can reference by name. --dependencies describes the libraries it depends on too. |
rdc compilation [<path>] |
cc |
Says, for each procedure, whether it runs compiled, what keeps it in the interpreter, and what the interpreter runs for it when it is compiled. |
rdc bench [<path>] |
b |
Times a workspace: its parse, its load, its analysis, then each Public Sub Bench*() of its standard modules, run by the configured execution engine, with what each case allocates. |
rdc describe-ext <extension> |
x |
Writes the manifest of a platform extension. It is for extension authors (see Building on RDCore). |
rdc install |
Installs the platform rdc runs from for your user account, and puts rdc on your PATH (below). It takes no workspace. |
|
rdc splash |
s |
Writes the platform's splash as plain text, whether its output is a console or not. It takes no workspace. |
On a console, a command starts with the platform's splash. Output redirected to a file or a pipe has none, so it holds only what the command writes.
Running a program
rdc run runs the program's entry point:
- the procedure the
.rdprojnames as its entry point in itsbuildsection,Module.ProcedureorProcedure:"build": { "entryPoint": "Module1.Main" }; - otherwise, the
Sub Mainof the one standard module that declares one.
A project with no entry point (RDC30001), or with a Sub Main in more than one standard module (RDC30002), does not run. Neither does a library ("build": { "outputType": "Library" }),
nor a project with a module that does not load. Debug.Print writes to the standard output. A MsgBox or an InputBox is drawn in the console and answered there, as in the shell, on every operating system. The CLI.NativeDialogs setting shows them as Windows dialog boxes instead, on Windows. The setting does not change how a form is shown: it opens a window of its own.
| Option | What it does |
|---|---|
-c, --configuration |
Debug (the default) or Release. |
--unattended |
Nobody answers a dialog: a MsgBox or an InputBox fails the run. The program knows it: the switch is first in Command$ and in the arguments of Main, as it is for a built program, unless the program's command line already has it. |
The options go before the path. Everything after the path is the program's command line, switches included: rdc run --unattended . runs
unattended, and rdc run . --unattended only gives --unattended to the program. A -- right after the path is skipped. With no path, the
current folder runs, and -- comes before the program's command line. Without a path or a --, nothing goes to the program, and an option
rdc does not know is an error.
rdc run . --seed 42
rdc run . -- --seed 42
rdc run -- --seed 42
The exit code says how the run went:
| Exit code | Meaning |
|---|---|
0 |
The program ended: its entry point returned, it ran an End, or it ran a Stop in Release. |
1 |
A run-time error ended it, or a Stop in Debug interrupted it, with no debugger to stop for. The standard error says which, with the error's number and description. |
2 |
It could not start: no entry point, or a module that does not load. |
Building a program
rdc build compiles the workspace into a program that runs without RDCore's parser, and without the workspace's sources: the program runs from its own folder,
wherever it is. It needs the same entry point as rdc run.
| Option | What it does |
|---|---|
-o, --output |
The folder the program is written to; bin/<configuration>/<runtime>/ in the workspace by default. |
-n, --name |
The program's name; the project's by default. |
-c, --configuration |
Debug (the default) or Release. |
-r, --runtime |
The platform the program is built for, such as win-x64 or linux-x64; the one rdc runs on by default. |
The program shows its dialogs as rdc run does, and its exit code says how it ran, as rdc run's does. Run with --unattended among its arguments, it fails at the first MsgBox, InputBox or form it shows. The switch stays in Command$ and in the arguments of Main.
A built program calls the outside world (a Declared procedure, an automation server's object) as rdc run does, through a second process: its own
executable, started again as its external host, which ends with it.
The executable is made of the .NET application host for the program's runtime. rdc comes with the hosts for win-x64, linux-x64, osx-x64 and
osx-arm64, the runtimes the platform is published for, so it builds a program for any of them wherever it runs. For another runtime, it uses the host
in an installed .NET SDK. Where neither has it, the program is built without an executable; run with dotnet <name>.dll, it makes no call to the
outside world.
The executable of a program built for macOS (osx-x64, osx-arm64) is signed ad hoc, as the .NET SDK signs an application's: a Mac with Apple silicon
runs no executable that is not signed. The signature has no certificate: it is not a Developer ID signature.
The program's folder holds, in Symbols, a description of each library its project references, and of each library those depend on. The program
reads them from there, wherever the folder is.
The folder also holds the license terms of what the program runs on:
| File | Terms of |
|---|---|
NOTICE.md, LICENSE-GPLv3.md |
RDCore. |
LICENSE-MIT.md |
RDCore.SDK. |
THIRD-PARTY-NOTICES.txt |
The other packages in the folder, and the program's executable. |
Pass them on with the program. NOTICE.md says what they ask of you, and that your own code stays yours. rdc copies them from the platform it runs
from, and warns when it has none to copy.
Installing the platform
rdc install installs the platform it runs from, such as a release archive you unpacked, for your user account. The IDE add-in installs the
platform in the same place, so each one uses what the other installed.
- It copies the platform into
RDCore/Platform/versions/<version>/in your local application data folder:%LOCALAPPDATA%on Windows,~/.local/shareon Linux,~/Library/Application Supporton macOS. A version that is installed already is not copied again, and no version is removed. - It makes that version the current one, unless the current version is newer.
- It puts the current version's
rdcon your PATH, in place of an earlier version's. On Windows, it adds the version'sRDCore.CLIfolder to your userPath. On Linux and macOS, it links~/.local/bin/rdcto it; when~/.local/binis not on your PATH, it adds a block of lines that puts it there to~/.profile(Linux) or~/.zprofile(macOS). Open a new terminal to use it.
| Option | What it does |
|---|---|
--path-only |
Only puts the current version's rdc on your PATH. |
--no-modify-path |
Installs the platform without changing your PATH or your profile. |
The exit code says how the installation went:
| Exit code | Meaning |
|---|---|
0 |
The platform is installed. |
1 |
It is not: the folder rdc runs from is not a whole platform, no version is installed (--path-only), or ~/.local/bin/rdc is a file of your own. The message says which. |
2 |
The options are not valid. |
ACCUEIL • HOME | ℹ️ BIENVENUE • WELCOME | 🧩 BÂTISSONS • BUILD | RD-VBAL | SDK | 🌐 rubberduckvba.ca