Table of Contents

2.2.3 ProjectFile

Note

This specification may be incomplete at this time.

RD-VBA discovers a file system folder as a workspace folder when the folder contains a text file named .rdproj that can be successfully deserialized into a ProjectFile. That folder is then the root of that workspace folder.

A folder that contains no .rdproj is the project it holds: RD-VBA synthesizes one in memory (IProjectFileLoader.LoadOrSynthesizeAsync), and opening the folder writes nothing into it.

  • Every source file of the workspace's language (RD-VBAL §2.0.2.1.1) under the folder, at any depth, is a module. A folder whose name starts with a dot (.git, .vscode) is not searched, nor a link to another folder.
  • Each folder that holds a module, at any depth, is a folder of the project.
  • Paths are relative to the root, separated by /, in ordinal order. Of two files that declare the same VB_Name, the first in that order is the module (RD-VBAL §2.2.3.3).
  • The project is named after the folder when the folder's name is a valid identifier name other than VBA, and VBAProject otherwise, as the VBE names a new project.

The synthesized project is written to .rdproj on its first change, a file the client created, renamed or deleted (see RD-VBAL §2.0.2), and is a project file like any other from then on. The language server is the only writer of a .rdproj.

{
  "Version": "",
  "Configuration": [],
  "ProjectInfo": RDCoreProject
}
Member Type Description
Version string The RD-VBA language core version the project file was serialized with.
Configuration array of string The locations (relative paths) of any configuration files to bind at run-time.
ProjectInfo RDCoreProject An object that describes the content of an RD-VBA project.
Tip

This model is intended to natively support VB6 project files (.vbp).

2.2.3.1 RDCoreProject

RDCoreProject is a serializable model representing an RD-VBA project.

{
  "Name": "",
  "References": [RDCoreReference],
  "Modules": [RDCoreModule],
  "OtherFiles": [RDCoreFile],
  "Folders": []
}
Member Type Description
Name string The name the project file was serialized with.
References array of RDCoreReference The project references.
Modules array of RDCoreModule The project source files.
OtherFiles array of RDCoreFile Any non-source files included in the project.
Folders array of string The names of all the folders in the project, whether they contain source code files or not.
Important

The Name of a project must be a valid identifier name. It should not be VBA, or any other reserved identifier name.

The rule is worded "should not" because whether a source project can reference a different project that has the same name is explicitly specified as host-dependent behavior. An RD-VBA host environment should explicitly deny the addition of any such ambiguous project reference.

The standard library symbols are present in a project whether or not its .rdproj mentions the library at all (see RD-VBAL §6.0 Standard Library).

2.2.3.2 RDCoreReference

RDCoreReference describes a reference within a project.

{
  "Name": "",
  "Guid": "",
  "AbsolutePath": "",
  "Major": 0,
  "Minor": 0,
  "IsUnremovable": false
}
Member Type (default) Description
Name string The identifier name (token) used in workspace source code to reference this library.
Guid string A Globally Unique Identifier optionally identifying the referenced library in a host-defined application registry.
AbsolutePath string The full path to the physical location of the referenced library, if it exists.
Major number (0) The major version number of the referenced library, if available.
Minor number (0) The minor version number of the referenced library, if available.
IsUnremovable boolean (false) A soft indicator marking the reference as unremovable from an LSP client.
Note

🧩 A supplied Guid necessarily refers to a COM registered library. Resolving such a library implies platform-specific Windows Registry lookups. The environment host may use implementation-dependent alternative means to provide symbols and semantics for such references.

👉 An RDCoreReference for a reference to a VBHostProjectType project must have the "unremovable" flag (IsUnremovable) set (see RD-VBAL §2.4.2 Non-intrinsic Types).

The order in which project references appear in the .rdproj file of a workspace folder determines the reference priority (see RD-VBAL §2.3.1.3 Name Resolution).

IRuntimeSession.References is the runtime-facing view of the .rdproj RDCoreReference list (see RD-VBAL §2.3.1.2 Session Services).

2.2.3.3 RDCoreModule

RDCoreModule describes the modules (source files) of a workspace folder.

{
  "Name": "",
  "Super": null
}
Member Description
Name The identifier name (token) used in workspace source code to reference this module.
DocClassType A string value that can be parsed as a member of the DocClassType enumeration.
Important

The value of the Name property of an RDCoreModule must be unique across the entire workspace.

The Name of an RDCoreModule is always supplied by a VB_Name attribute (see RD-VBAL §3.1.1 Attributes). In case of a mismatch between Name and the value of the VB_Name attribute, the attribute value always takes precedence.

2.2.3.3.1 DocClassType Enum

Note

🧩 This enum type is an extension point: it is intended to be extended as additional document modules are explicitly supported.

The DocClassType enumeration defines constants that internally map extensible (document) modules to certain specific class types:

Name Value
Unknown 0
ExcelWorkbook 1
ExcelWorksheet 2
AccessForm 3
AccessReport 4

Document modules can only be added to a VBA project via the host application that defines them. Exporting a document module from an MS-VBA project via the VBIDE Extensibility API produces a .cls file, which would then re-import as a class module.

Rubberduck (the VBE add-in) exported document modules with a .doccls extension, to distinguish the two class types. Document modules are distinguished from class modules because a document module's base class metadata is externally defined.

RD-VBA can load the necessary symbols for document module interfaces, but their implementation belongs to their respective host application.

Note

RD-VBA cannot create a Workbook host document, nor a Worksheet module in its Sheets collection, because that is the responsibility of Microsoft Excel.

Instead, RD-VBA identifies the interfaces a document module requires using the DocClassType enum. This allows static semantics to correctly identify all the members and available events of a document module.

Workspace source code that is directly dependent on a host document necessarily requires an appropriate host to evaluate correctly. In such cases, the RD-VBA runtime implementation may start an automation host process as needed, if such a host exists in the runtime environment.

🎯 A more portable approach is to refactor MS-VBA legacy code so that any host-dependent calls are decoupled from the logic. RDCore semantic analysis capabilities should support all the diagnostics and refactoring tools needed to do this.

2.2.3.4 RDCoreFile

RDCoreFile describes additional (non-source) files contained in a workspace folder, but not necessarily given to a language server for processing.

Tip

For example, an RDCoreProject could include README.md, CONTRIBUTING.md, and LICENCE.md text/markdown files as RDCoreFile entries. These files would always be bundled with the project, but ignored by the RD-VBA language core.

{
  "Name": ""
}
Member Description
Name The identifier name (token) used in workspace source code to reference this module.

2.2.3.5 Importing a VB6 Project

A VB6 project (.vbp) is imported as the RDCoreProject of its folder (VbpProjectImporter): the .rdproj is written next to the .vbp, which is read and left as it is. A .vbp is read in the ANSI code page of the environment, as VB6 writes it, unless it starts with a byte-order mark (a copy re-encoded in UTF-8); its keys are read up to its first [section], the settings of add-ins.

.vbp key Becomes
Name The project's Name.
Module, Class A module: the file after the ;.
Form A module.
UserControl, PropertyPage, UserDocument, Designer A file of the project (OtherFiles), which is not compiled; the import says so.
RelatedDoc, ResFile32 A file of the project.
Reference (*\G{GUID}#version#lcid#path#description) A reference to the library the platform ships with that GUID, at the version (written in hexadecimal: 2.a is 2.10). The reference to VBA is implicit, and skipped.
CondComp The project's PrecompilerConstants ("DEBUG = 1 : TRACE = 0"): name = n arguments separated by colons, spaces optional, each a name and a whole number from -32768 to 32767 with an optional sign. As vb6.exe does, a line with any other argument - a string, &H10, True, 1.5, a name without a value, a colon at the end - is refused whole, and the import says so.

A path is resolved against the .vbp's folder first: ..\MyProj\Util.bas, from MyProj\MyProj.vbp, is the project's own Util.bas, and Sub\..\Util.bas is too. The project's folders are those of the files it lists. What cannot be carried over is skipped, and the import says what and why, in the language of the user interface:

Skipped Why
A reference to a library the platform has no description of It cannot be resolved.
A reference to another project (*\A) A project cannot reference another one yet.
A control (Object) The platform hosts no ActiveX controls.
A file outside the project's folder (..\Shared\Utils.bas) It belongs to another project: its folder is a workspace folder of its own, as a shared library loaded from a sibling folder is. The platform never takes in a folder outside the workspace folders it is given, and a project cannot reference another one yet.
A file at an absolute path A project lists the files of its own folder.
The startup object (Startup) A project file does not say it yet.
Conditional compilation arguments VB6 refuses VB6 refuses the whole line.

A folder that has a .rdproj already keeps what the .vbp does not describe (VbpImport.Into). The .vbp describes the project's name, references, modules and other files, their folders, and its conditional compilation arguments, which replace what the .rdproj says of them: a file the .vbp no longer lists is no longer the project's. The project file's settings files (Configuration), the document class of a module (Super, by its path), and the type library information of a reference (TypeLibInfoPath, by its name) are kept, so a client that keeps a .vbp and a .rdproj in step can import the .vbp again after each change. A .rdproj that cannot be read is replaced whole.

rdcore.importProject imports a VB6 project in a client of the platform (RD-VBAL §2.0.2). rdc import <path> does in command mode, without starting the platform: <path> is the .vbp, or a folder with one. It writes what was skipped as warnings. A folder that has a .rdproj already keeps it, unless --force is given. It exits with 1 when <path> is not found, or is a folder with no .vbp or several.

Note

Not implemented. A VB6 project group (.vbg) is to be imported as a workspace file (RD-VBAL §2.2.2).

⏮️ RD-VBAL §2.2.2 WorkspaceFile | ⏭️ RD-VBAL §2.3 Application Host

Edit this page