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, .github) 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 interactive shell, given no workspace, runs in a scratch one of its own: a project named VBAProject whose one module is Program. MS-VBA refuses a module named as its project ("Name conflicts with existing module, project, or object library"), so the two names differ. VBAProject is the name that a project-qualified reference to the program's members uses (VBAProject.Program.Main), and the name that Err.Source and the dialogs' title give.

A project's name is the language core's default until a client gives it another: a client may rename its project, Untitled1 say, as an IDE names a new project on startup. The name the platform reports follows the project file. When the .rdproj names the project anew, the workspace is reloaded and the environment host composes its session again, so that Err.Source, a dialog's default title, the session's status and a project-qualified reference all give the new name. A host whose program is running keeps its session, and the name it had, until it composes the session again.

Note

Not implemented. No request of the platform renames a project. The language server is the only writer of a .rdproj, so a client renames its project only by changing the file outside the editor, which the platform reads as any other change to its project file (RD-VBAL §2.0.2).

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": "1.1",
  "Configuration": [],
  "ProjectInfo": RDCoreProject
}
Member Type Description
Version string The version of the .rdproj format the file is written in, as major.minor (§2.2.3.0). It is not the version of RDCore. A file written by hand may leave it out or leave it empty.
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.0 The format's version

A .rdproj says which version of its own format it is written in, and that version changes only when the format does. The format is at version 1.1, which adds the project's build section (§2.2.3.1) to the format 1.0. A change that an older RDCore can still read, such as a new member, raises the second number: 1.2. A change it cannot read raises the first: 2.0. So a project written by a later RDCore opens in an earlier one, unless the format changed in a way the earlier one cannot read.

RDCore opens a project file whatever version it says:

  • The same format, or an older one. The project opens. An older file is written in the current format the next time RDCore saves it.
  • A newer second number (1.2 when RDCore writes 1.1). The project opens, and RDCore notes it in its log. The members it does not know are kept as they are, and written back when it saves the file, along with the file's version: the RDCore that wrote them still finds them there.
  • A newer first number, or a version that is not one (2.0, or v1). RDCore notes it in its log and reads the file as best it can. If it can read it, the project opens. When it saves the file, it keeps the file's version and the members it does not know, but it writes the members it knows the way its own format has them. If the newer format changed what one of those means, saving in the older RDCore loses that change.

Only the first two numbers count: 1.0.0 is the format 1.0. Before the format had a version of its own, RDCore stamped a project file with its own version, 1.0.0 or a 0.1.x version: those files are in the format 1.0, and open. RDCore reads a build section in a file of the format 1.0 as the format 1.1 has it.

A project file that cannot be read at all, because it is not JSON or a member is not what the format says it is, does not open. Instead, RDCore offers to regenerate it from the source files of its folder, the same way it builds a project for a folder that has no project file. It always asks first, because what only the project file says, such as the project's references, is lost.

  • You accept. The file as it was is kept next to it, as .rdproj.bak (or .rdproj.1.bak and so on, if that name is taken), and the new file replaces it.
  • The new file cannot be written. The old one is put back as it was, and the project does not open, as if you had not accepted.
  • The old one cannot be put back either. It stays as the .bak file, and RDCore says so, and what to rename it to.
  • You decline. Nothing changes, and the project does not open until the file is fixed.

Who is asked:

  • An IDE asks in its own window, but only if it says it can answer while the project opens (answersDuringInitialize, RD-VBAL §2.0.2.1.3). One that does not say so is not asked, and the project does not open.
  • The rdc shell asks at its prompt, but only when someone is typing at it: a script piped into rdc is not asked, and none of its lines is taken for an answer. A question that comes while you are typing a line waits until you enter it, so your keys stay on the line.
  • Under --unattended, nobody is there to answer, so nothing is asked: the project does not open, and RDCore says why.

2.2.3.1 RDCoreProject

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

{
  "Name": "",
  "References": [RDCoreReference],
  "Modules": [RDCoreModule],
  "OtherFiles": [RDCoreFile],
  "Folders": [],
  "SourceProject": "MyProj.vbp",
  "build": { "entryPoint": "Module1.Main" }
}
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.
SourceProject string, optional The Visual Basic 6 project (.vbp) the project was imported from, by its path relative to the folder of the .rdproj. The import writes it, a second import of the project keeps it, and nothing else changes it. It is what makes a project an imported one: a .vbp next to a .rdproj that does not record it is not an import. Absent for a project that was not imported.
build object, optional What the project builds into, and where its program starts (ProjectBuild). Its outputType is Application, a program, or Library, which is not run. Any other value, or none, is Application. Its entryPoint is the procedure rdc run and rdc build start the program at, as Module.Procedure or Procedure. With none, the program starts at the Sub Main of the one standard module that declares one. A build that is not an object is no section. Absent for a program that starts at its Sub Main. Added in the format 1.1.
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). It is RDCore's own, in every dialect, and is no reference: RDCore writes none to it in a .rdproj - a new project, one a folder makes up, or one imported from a VB6 project. A .rdproj that lists it anyway, with the path of Office's VBE7.DLL, is read without it, and written without it.

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 The identifier of the type library the reference is to, optional. When it is given, the library is the description made from that type library; when it is empty, the library of Name.
AbsolutePath string The full path to the physical location of the referenced library, if it exists. An import of a .vbp resolves the path VB6 writes relative to the .vbp's folder (..\..\Windows\System32\FM20.DLL), so that it names the same file wherever the project is moved.
Major number, optional The major version number of the referenced type library. With a Guid, the description must have this major version. With a Guid and no Major, the library is the description of the highest version of the identifier.
Minor number, optional The minor version number of the referenced type library. With a Guid, the description of exactly this minor version is the library, and otherwise the one of the highest minor version above it. With no Minor, the library is the description of the highest minor version of Major. A Minor with a Guid and no Major is not valid, and the reference is not resolved.
IsUnremovable boolean (false) A soft indicator marking the reference as unremovable from an LSP client.

A reference with a Guid is resolved against the library descriptions that ship with the platform, without the Windows registry: each description states the identifier and version of the type library it was made from. A reference whose identifier and version match no description cannot be resolved, and the library of its name is not used in its place (RD-VBAL §2.3.1.2 Session Services).

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 their reference precedence: a reference that appears earlier has the higher precedence (MS-VBAL §4.1), and the VBA standard library comes before every reference the file lists (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. A standard or class module is its path, relative to the root; a document module is an object that also says its document:

"Modules": [
  "Module1.bas",
  "Shapes/Disc.cls",
  { "RelativeUri": "Sheet1.doccls", "Super": "ExcelWorksheet" }
]
Member Description
RelativeUri The path of the module's source file, relative to the root of the workspace folder, separated by /.
Super A string value that can be parsed as a member of the DocClassType enumeration: "ExcelWorksheet". A number (2) is read the same, and written as the name.

A module whose Super is set is a document module, whatever its text and its file name say: its export (a .doccls, or a .cls from the VBE) has no header that would say so. Any other module is a class module when its text has a VERSION header, and a standard module otherwise. The environment host and the language server decide it the same way (ModuleKinds.Of). An object with no Super, or a null one, is read as the module's path alone.

Important

A module's name must be unique within its project. A project is its own namespace: two projects of a workspace can each have a Module1.

A client can open several folders (LSP 3.17 workspaceFolders). The first is the project the platform runs, and each other folder that is a project's is a project that is analyzed - diagnostics, navigation, completion - and not run. The first folder is always a project. A later folder that holds a .rdproj of its own is a project, imported or native, even when another project lists files in it: a file two projects list is a module of each. A later folder that holds no .rdproj is only a place for sources when a project loaded before it lists files in it, and a project when none does. This is read when the workspace is loaded. The folders are the bounds of the workspace: a module path that climbs out of the project's folder (..\Shared\Util.bas) is accepted when a folder of the workspace holds the file, and is refused, and reported to the client, otherwise. Only the first project is run: the others get the language server's analysis, and not the environment host's. A file that two projects list is one document, and a module of each project - with a copy of its own, as in Visual Basic 6: each project reaches its own copy's Friend members and Private classes, with module-level state of its own. The diagnostics of the document are the first project's that loaded it, since a client keeps one set of diagnostics for a document. A file the client renames (workspace/didRenameFiles) is listed under its new path by every project that lists it, each in its own .rdproj; a project other than the first is not reloaded by the other file operations (create, delete) yet. Known limit: only the first project's libraries are resolved: the other projects see the standard library and their own modules, and a name from a library they reference is not found (nothing tells the client yet).

A module's name is its VB_Name attribute (see RD-VBAL §3.1.1 Attributes), not its file name: a project file doesn't say it.

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 map document modules to the class of the host library their document is an object of (ModuleKinds.HostClassOf):

Name Value Host class
Unknown 0 none: a host RD-VBA does not know
ExcelWorkbook 1 Excel.Workbook
ExcelWorksheet 2 Excel.Worksheet
AccessForm 3 Access.Form
AccessReport 4 Access.Report
WordDocument 5 Word.Document

A name or a number the enumeration does not have reads as Unknown: the project still loads.

Document modules can only be added to a VBA project via the host application that defines them: in MS-VBA, the project lives inside the host's document, and a document module belongs to the host. The VBIDE Extensibility API exports one as a .cls file, which would re-import as a class module. Rubberduck (the VBE add-in) exports what the code pane shows of one, with no attributes, to a .doccls file. Neither says what the module is; the project file does (Super), and nothing else - no module name, file extension or event handler makes a module a document module.

RD-VBA is not hosted: it runs VBA outside of any host application, and automates an application from the outside. A document module is therefore loaded for analysis only:

  • It is a class module, so Me is valid in it. Its code names the members of its host's class: Me.Range("A1") and an unqualified Range("A1") in a worksheet's module bind to Excel.Worksheet.Range, after the module's own members, when the project references the host's library. Those members are found through the library's class; none is declared again as a member of the module.
  • No program creates one of its objects (New Sheet1 is Invalid use of New keyword, as in MS-VBA), it has no default instance (Sheet1.Foo in another module names nothing), and no event of its host is raised for it. Its code never runs.
  • RD-VBA never starts or attaches to the host application on a document module's behalf. An application process starts only when workspace code creates one.
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.

Code that handles a document's events holds the document in a WithEvents variable of the host's class (Private WithEvents AutomationSheet As Excel.Worksheet), from an application the workspace code automates, and handles AutomationSheet_Change instead of Worksheet_Change.

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.

A file is its path, relative to the root of the workspace folder, separated by /:

"OtherFiles": [ "README.md", "docs/LICENCE.md" ]

An object with a RelativeUri member is read the same.

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). VBA, the standard library, is no reference (§2.2.3.1): a .vbp line that references VBA's type library adds none.
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 in its own folder.

A file outside the project's folder (..\Shared\Util.bas) is a module of this project, as in VB6, when a folder of the workspace holds it: qualified by the project's name, and a copy of its own in each project that lists it. The project file lists it by its path relative to the project's folder (../Shared/Util.bas). Its folder, when it holds no .rdproj, is a source folder of the workspace, not a project; a folder that holds one is a project of its own, and the file is a module of each project that lists it. A file at an absolute path is listed the same way, relative to the project's folder, when the project's folder or a folder of the workspace holds it: a project file lists no absolute path. The platform never takes in a folder outside the workspace folders it is given, so rdc import, which has none, carries over no file outside the project's folder.

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 and every folder of the workspace (..\Shared\Utils.bas) The platform never takes in a folder outside the workspace folders it is given: open the folder it is in as a workspace folder too, and import the project again.
A file at an absolute path outside the project's folder and every folder of the workspace A project file lists no absolute path.
The startup object (Startup) A project file does not say it yet.
The project's type (Type=Exe, OleDll, OleExe, Control) A project file does not say it yet: whether the project is run, or used by being referenced.
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. The .rdproj the import writes records the .vbp it was made of (SourceProject).

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).