Bâtir sur RDCore
This document is available in English
Cette page s'adresse aux contributeurs, et à quiconque crée une extension ou un client sur la plateforme. Pour utiliser RDCore, voyez Démarrage.
Contribuer
- Lisez et acceptez d'abord l'accord de licence contributeur (CLA) qui convient à votre situation. Ça facilitera la suite.
- Parcourez la feuille de route du projet et choisissez un ticket du jalon en cours.
- Faites un fork du référentiel RDCore dans votre compte GitHub.
- Faites un clone du référentiel sur un poste libre de droits (donc pas sur un poste fourni par votre employeur).
- Ouvrez
RDCore.slnxdans Microsoft Visual Studio Community Edition 2026 (gratuit pour les contributions open source).- Vous pouvez aussi compiler la solution avec
dotnet build.
- Vous pouvez aussi compiler la solution avec
- Démarrez une nouvelle branche à partir de main, nommée d'après le ticket.
- Effectuez et testez votre contribution dans votre branche locale.
- Lorsqu'elle fonctionne et est prête pour revue, ouvrez une pull request qui fait référence au ticket.
- Écrivez
Closes #suivi du numéro du ticket dans le corps de la pull request. - La même mention dans un commit de votre branche paraît dans l'historique du ticket dès que vous poussez le commit dans votre fork. Les autres contributeurs voient ainsi que le ticket est en cours.
- Écrivez
- Signez la CLA : copiez le texte de signature qu'elle donne dans un commentaire sur votre pull request.
- Vous ne le faites qu'une seule fois.
- Une fois votre pull request fusionnée, supprimez votre branche et resynchronisez main avant de commencer un autre ticket.
- Une pull request est fusionnée en un seul commit (squash), sans les commits de votre branche. D'autres commits sur une branche déjà fusionnée se fusionnent mal. Pour soumettre un correctif, démarrez une nouvelle branche à partir de main, une fois que main a le commit fusionné.
Compiler la plateforme à partir des sources
Pour assembler l'arborescence de la plateforme que livre une préversion, exécutez PlatformPublish.ps1 à partir d'un clone. Il requiert git dans le PATH, pour consigner le commit qu'il compile. Il s'exécute avec PowerShell 7 (pwsh) sous Windows, Linux et macOS, et avec Windows PowerShell 5.1 sous Windows.
- Sans arguments, il demande une confirmation, puis publie un build Debug dans
artifacts/rdcore-dev. -Configuration Release -RuntimeIdentifier win-x64correspond à la préversion pour Windows;linux-x64,osx-x64etosx-arm64, à celles pour Linux et macOS.-VersionSuffix <suffixe>ajoute un suffixe de préversion, par exemplerc.1.-PlatformRoot <chemin>choisit le dossier de sortie, relatif à la racine du référentiel.-Silentomet la confirmation.
Le workflow de publication y ajoute ensuite THIRD-PARTY-NOTICES.txt, SOURCE.md et release.json. Les mainteneurs trouveront la procédure complète dans RELEASING.md (en anglais).
Créer une extension RDCore
Il suffit de quelques lignes dans votre point d'entrée pour que votre application RDCore soit prise en charge :
public class Program
{
public static async Task<int> Main(string[] args)
{
using var host = new RDCoreConsoleClientHost();
return await host.RunAsync(args);
}
}
Hôte
Avant de pouvoir écrire ces lignes, il faudra définir votre hôte en héritant de RDCoreLanguageClientHost si vous construisez un 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>();
}
}
...ou alors en héritant de RDCorePlatformServerHost si vous construisez plutôt un serveur :
internal class CoreDiagnosticsAppHost() : RDCorePlatformServerHost<CoreDiagnosticsApp>()
{
protected override void ConfigureAdditionalExternalServices(IServiceCollection services, IConfiguration configuration)
{
}
}
Application
Dans les deux cas, l'hôte ajoute des services au IServiceCollection, et l'application est créée avec ces services injectés.
Ensuite, pour un client, héritez de 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) { }
}
...et pour un serveur, héritez plutôt de RDCoreServerApp :
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) { }
}
Dans les deux cas, l'application configure ses capacités LSP, et les handlers qui prennent en charge les requêtes et notifications LSP.
Client ou Serveur?
- Une application client est généralement une application de type IDE.
- Une application serveur peut être un serveur de langage satellite ou une extension (plug-in) de la plateforme.
- LSP 3.17 Specifications
Important
Les extensions de la plateforme RDCore requièrent un manifest (extension.manifest.json, schéma ExtensionInfo) pour que le serveur de langage puisse les découvrir et les démarrer lors de l'assemblage de la plateforme. Le manifest est généré par la CLI en mode commande :
rdc.exe describe-ext RDCore.Diagnostics.exe --description "…" --unsafe-dev-mode
describe-ext reflète les capacités déclarées par l'exécutable d'extension (ses déclarations [assembly: ProvidesCorePlatformClientCapability<T>]) dans le manifest. PlatformPublish.ps1 l'exécute une fois par extension lors de l'assemblage de la plateforme.
Important
Les bibliothèques référencées (Excel, Word, Access, ADODB, Scripting, …) sont connues d'un projet par leur nom, comme si la bibliothèque était du code VBA, et ce que chacune déclare est livré avec la plateforme sous forme de description de bibliothèque dans Symbols/<Nom>.json (format : LibraryDescription). Un projet est vérifié contre la description : il peut donc être analysé sur une machine qui n'a pas la bibliothèque. Une bibliothèque dont la plateforme n'a pas de description est une référence qui ne peut pas être résolue, et les types qui la nomment sont des erreurs de compilation. Les bibliothèques qui dépendent les unes des autres sont rejetées, non résolues.
Une description indique la bibliothèque de types dont elle est tirée, par son identifiant et sa version, et chaque bibliothèque dont elle dépend (dependsOn) par son nom et l'identifiant et la version de la bibliothèque de types contre laquelle elle a été construite. Une référence qui donne un identifiant et une version désigne la description tirée de cette bibliothèque de types : Symbols/<Nom>.<qualificatif>.json décrit une autre bibliothèque de types du même nom, comme DAO.dao2535.json à côté de DAO.json (RD-VBAL §2.3.1.2 The library a reference is).
Une description est générée, jamais écrite à la main, sur une machine Windows qui a la bibliothèque, par la CLI en mode commande :
rdc.exe export-library Excel --dependencies --output Symbols
export-library accepte un fichier (scrrun.dll), l'identifiant que la machine a donné à la bibliothèque, ou son nom; quand plusieurs versions d'une bibliothèque sont enregistrées, la plus récente est décrite. Un fichier qui contient plus d'une bibliothèque se donne avec le numéro de la ressource de la bibliothèque, comme un .vbp la référence : MSVBVM60.DLL\3 est VBRUN, alors que MSVBVM60.DLL seul est sa première bibliothèque, VBA. --dependencies décrit aussi les bibliothèques dont elle dépend, qu'un projet doit avoir pour la référencer : chacune est la bibliothèque de types à laquelle la bibliothèque est liée, et celle dont le dossier de sortie a déjà le nom pour une autre bibliothèque de types est écrite sous <Nom>.<racine du fichier>.json. Un membre dont le type est déclaré par une bibliothèque que la machine n'a pas n'est pas décrit, et l'exportation dit lequel.
La description est ce contre quoi un projet est vérifié; ce contre quoi il s'exécute, ce sont les objets de la bibliothèque sur la machine qui l'exécute. New Scripting.Dictionary est un vrai dictionnaire, et New Excel.Application démarre un vrai Excel, piloté de l'extérieur par son modèle objet. Ce sont les serveurs d'automation de Windows. Sur un autre système, un programme qui crée un de ces objets apprend que la plateforme n'en a pas (erreur 429), mais le même programme peut être analysé n'importe où. Chacun de ces appels passe par la même chaîne d'interception que tout appel à l'extérieur de l'espace de travail, et un administrateur peut tous les refuser avec "AllowAutomation": false dans appsettings.json (erreur 70, Permission denied). Le réglage ne refuse pas ce que la plateforme implémente elle-même : la bibliothèque standard, et LoadPicture, SavePicture et StdPicture de stdole.
Capacités
Le serveur de langage démarre chaque extension qui a un manifest valide, et entame avec elle un LSP handshake. Les paramètres d'initialisation de l'extension doivent déclarer chaque capacité qu'elle a : celles que définit le protocole (LSP), et celles que définit l'hôte de l'environnement. Une extension déclare une capacité de plateforme telle que CliCommand au moyen d'un attribut d'assembly :
[assembly: ProvidesCorePlatformClientCapability<CliCommand>]
La section RD-VBAL §2.0.2 décrit les capacités de la plateforme.
Note
Les extensions tant de première que de tierces parties distribuées à travers l'infranuagique RDCore PEUVENT utiliser un capability provider qui PEUT valider la disponibilité de certaines capacités avancées en requérant une authentification 2FA, la validation d'une inscription active (gratuite ou payante), et la validation d'un build signé avec le build officiel du canal de distribution certifié.
Extension de la plateforme (SDK et coeur de langage)
Le coeur de langage est conçu pour être étendu à travers des extensions de la plateforme de type serveur, moyennant un échange de capacités donnant accès à des points d'extensions.
Voir RD-VBAL § 1.1 pour les détails et la philosophie d'extension de la plateforme à ce niveau.
ACCUEIL • HOME | ℹ️ BIENVENUE • WELCOME | 🧩 BÂTISSONS • BUILD | RD-VBAL | SDK | 🌐 rubberduckvba.ca