Building on RDCore
Ce document est disponible en français
This page is for contributors, and for anyone building an extension or a client on the platform. To use RDCore, see Getting started.
Contributing
- First read and accept the Contributor Licence Agreement (CLA) that fits your situation. It makes the next steps smoother.
- Browse the project roadmap and pick a ticket under the current milestone.
- Fork the RDCore repository to your GitHub account.
- Clone the repository on a workstation that is free of rights (that is, NOT your employer's computer).
- Open
RDCore.slnxin Microsoft Visual Studio Community Edition 2026 (free for open-source contributions).- You can also build the solution with
dotnet build.
- You can also build the solution with
- Start a new branch from main, named after the ticket.
- Implement and test your contribution in your local branch.
- When it works and is ready for review, open a pull request that refers to the ticket.
- Write
Closes #and the ticket number in the body of the pull request. - The same mention in a commit of your branch shows in the ticket's history as soon as you push the commit to your fork. Other contributors see that the ticket is being worked on.
- Write
- Sign the CLA: copy the signature text it gives into a comment on your pull request.
- You only do this once.
- Once your pull request is merged, delete your branch and resynchronize main before you start on another ticket.
- A pull request is merged as one squash commit, without the commits of your branch. More commits on a branch that was already merged are hard to merge again. To submit a fix, start a new branch from main, once main has the merged commit.
Building the platform from source
To assemble the platform tree that a preview build ships, run PlatformPublish.ps1 from a clone. It needs git on the PATH, to record the commit it builds. It runs under PowerShell 7 (pwsh) on Windows, Linux and macOS, and under Windows PowerShell 5.1 on Windows.
- With no arguments, it asks for confirmation, then publishes a Debug tree to
artifacts/rdcore-dev. -Configuration Release -RuntimeIdentifier win-x64matches the Windows preview build;linux-x64,osx-x64andosx-arm64match the Linux and macOS ones.-VersionSuffix <suffix>adds a prerelease suffix, such asrc.1.-PlatformRoot <path>picks the output folder, relative to the repository root.-Silentskips the confirmation.
The release workflow then adds THIRD-PARTY-NOTICES.txt, SOURCE.md and release.json. Maintainers will find the whole procedure in RELEASING.md.
Building an RDCore extension
It only takes a few lines in your entry point to make your application an RDCore app:
public class Program
{
public static async Task<int> Main(string[] args)
{
using var host = new RDCoreConsoleClientHost();
return await host.RunAsync(args);
}
}
Host
Before you can write these lines, you must define a host by inheriting RDCoreLanguageClientHost if you're writing a client :
internal class RDCoreConsoleClientHost() : RDCoreLanguageClientHost<RDCoreConsoleClientApp>()
{
protected override void ConfigureAdditionalExternalServices(IServiceCollection services, IConfiguration configuration)
{
services
.AddSingleton<IAppThemeService, AppThemeService>()
.AddSingleton<IAppThemeLoaderService, AppThemeLoaderService>()
.AddSingleton<IConsoleMessageWriter, DefaultConsoleMessageWriter>()
.AddSingleton<ILoggerProvider, RDCoreConsoleLoggerProvider>()
.AddSingleton<ShowSplashCommand>();
}
}
...or by inheriting RDCorePlatformServerHost if you're building a server app instead:
internal class CoreDiagnosticsAppHost() : RDCorePlatformServerHost<CoreDiagnosticsApp>()
{
protected override void ConfigureAdditionalExternalServices(IServiceCollection services, IConfiguration configuration)
{
}
}
Application
In both cases, the host adds services to the IServiceCollection, and the application is created with those services injected.
Then, for a client, inherit RDCoreClientApp:
internal class RDCoreConsoleClientApp(
IOptions<SdkAppOptions> options,
IChildConnectionFactory connectionFactory,
ILogger<RDCoreConsoleClientApp> logger)
: RDCoreClientApp(options, connectionFactory, logger)
{
public override CoreServerComponent PlatformComponent => CoreServerComponent.ClientApp;
protected override void ConfigureServices(IServiceCollection services)
{
}
protected override ClientCapabilities ConfigureClientCapabilities(ClientCapabilities capabilities)
{
return capabilities;
}
protected override void ConfigureHandlers(IRDCoreLSPHandlerConfigurationBuilder builder)
{
}
protected override void Dispose(bool disposing) { }
}
...and for a server, inherit RDCoreServerApp instead:
internal class CoreDiagnosticsApp(
IOptions<SdkAppOptions> options,
IServerStateProvider serverStateProvider,
IHealthCheckService<CoreDiagnosticsApp> healthCheckService,
ILanguageServerProtocolTransportLayer transportLayer,
ILogger<CoreDiagnosticsApp> logger)
: RDCoreServerApp(options, serverStateProvider, healthCheckService, transportLayer, logger)
{
public override CoreServerComponent PlatformComponent => CoreServerComponent.Extension;
protected override void ConfigureHandlers(IRDCoreLSPHandlerConfigurationBuilder builder)
{
}
protected override void RegisterServerCapabilities(ILanguageServer server, ClientCapabilities clientCapabilities)
{
}
protected override void Dispose(bool disposing) { }
}
Either way, the application configures its LSP capabilities, and the handlers that handle the LSP requests and notifications.
Client or Server?
- A client application is typically an IDE application.
- A server application could be a satellite language server, or a platform extension (plug-in).
- LSP 3.17 Specifications
Important
RDCore Platform Extensions need a manifest (extension.manifest.json, schema ExtensionInfo) for the language server to discover and bring them up during platform assembly. The manifest is generated by the CLI in command mode:
rdc.exe describe-ext RDCore.Diagnostics.exe --description "…" --unsafe-dev-mode
describe-ext reflects the extension executable's advertised capabilities (its [assembly: ProvidesCorePlatformClientCapability<T>] declarations) into the manifest. PlatformPublish.ps1 runs it once per extension while assembling the platform.
Important
Referenced libraries (Excel, Word, Access, ADODB, Scripting, …) are known to a project by their name, as if the library were VBA code, and what each declares ships with the platform as a library description in Symbols/<Name>.json (format: LibraryDescription). A project is checked against the description, so it can be analyzed on a machine that does not have the library. A library that the platform has no description of is a reference that cannot be resolved, and the types that name it are compile errors. Libraries that depend on one another are rejected, not resolved.
A description states the type library it was made from, by its identifier and version, and each library it depends on (dependsOn) by its name and the identifier and version of the type library it was built against. A reference that gives an identifier and a version is to the description made from that type library: Symbols/<Name>.<qualifier>.json describes another type library of the same name, such as DAO.dao2535.json beside DAO.json (RD-VBAL §2.3.1.2 The library a reference is).
A description is generated, never written by hand, on a Windows machine that has the library, by the CLI in command mode:
rdc.exe export-library Excel --dependencies --output Symbols
export-library takes a file (scrrun.dll), the identifier the machine gave the library, or its name; when several versions of a library are registered, the latest is described. A file that holds more than one library is given with the number of the library's resource, as a .vbp references it: MSVBVM60.DLL\3 is VBRUN, where MSVBVM60.DLL alone is its first library, VBA. --dependencies describes the libraries it depends on too, which a project needs in order to reference it: each is the type library the library is linked with, and one whose name the output folder already has for another type library is written as <Name>.<file stem>.json. A member whose type is declared by a library the machine does not have is not described, and the export says which.
The description is what a project is checked against; what it runs against are the objects of the library on the machine that runs it. New Scripting.Dictionary is a real dictionary, and New Excel.Application starts a real Excel, driven from the sidelines through its object model. These are the automation servers of Windows. On another system, a program that creates one of these objects is told that the platform has none (error 429), but the same program can be analyzed anywhere. Every such call passes through the same interception chain as any call outside the workspace, and an administrator can refuse them all with "AllowAutomation": false in appsettings.json (error 70, Permission denied). The setting does not refuse what the platform implements itself: the standard library, and stdole's LoadPicture, SavePicture and StdPicture.
Capabilities
The language server brings up each extension that has a valid manifest, and starts an LSP handshake with it. The extension's initialization parameters must state every capability it has: those the protocol (LSP) defines, and those the environment host defines. An extension advertises a platform capability such as CliCommand with an assembly attribute:
[assembly: ProvidesCorePlatformClientCapability<CliCommand>]
RD-VBAL §2.0.2 describes the platform capabilities.
Note
First and third party extensions distributed through the RDCore Platform Cloud Infrastructure MAY use a capability provider that MAY validate the availability of certain advanced capabilities by requiring 2FA authentication, the validation of an active subscription (free or paid), and the validation of the signed build against the certified distribution channel build.
Platform-level extensions (SDK and language core)
The language core is engineered to be extended through server type extensions, via an exchange of capabilities giving access to extension points.
Please see RD-VBAL § 1.1 for more details and the platform's extension philosophy at that level.
ACCUEIL • HOME | ℹ️ BIENVENUE • WELCOME | 🧩 BÂTISSONS • BUILD | RD-VBAL | SDK | 🌐 rubberduckvba.ca