Contributing

bclothier edited this page Aug 11, 2018 · 19 revisions

Initial Setup

Thank you for forking our project! Before you can submit a pull request, there are a number of steps that need to be completed.

Building

Because we have custom build system and some dependencies, it is best to build the whole solution. The debug release will be based on the Rubberduck.Deployment project and because that project depends on several other projects it is almost the last to build. Though the actual files used for addin come from other projects (e.g. Rubberduck.Core), the registration will be done using the Rubberduck.Deployment's path. The project additionally will do some configurations, including executing powershell scripts and editing the registry to maintain the COM registration automatically. We try to make that project automated as much as contributors should not have to tweak it to get building. For those interested, refer to Build Process for details within the Rubberduck.Deployment project.

If you have a release version installed, you need to uninstall it first. The installer registers COM components against the release build, in the install folder. You'll manually re-register these COM components in a minute, but first you need a build.

Building Rubberduck solution should automatically install the following Nuget packages (which may be changed as codebase develop):

  • Antlr4.4.6.4
  • Antlr4.CodeGenerator.4.6.4
  • Antlr4.Runtime.4.6.4
  • Castle.Core.4.1.1
  • Castle.Windsor.4.0.0
  • EasyHook.2.7.6578.1
  • Moq.4.2.1507.118
  • NLog.4.4.12
  • NLog.Schema.4.4.12
  • NUnit.3.9.0
  • NUnit3TestAdapter.3.9.0
  • System.ValueTuple.4.4.0

IMPORTANT: If you want to debug Rubberduck by F5'ing, you might run Visual Studio in non-admin mode to avoid issues with Rubberduck registration. Because the registration will be in HKCU, running the VBE host as an administrator might prevent it from seeing the registration and thus give an error about being unable to locate the Rubberduck addin. If you must run Visual Studio as an administrator, consider attaching to the VBE host instead of F5'ing.

Once you've built the solution, make sure the Rubberduck.Deployment project is the solution's startup project, and that it's configured to launch your favorite VBE host on startup, so that Visual Studio automatically attaches its debugger to the process when you hit F5 to launch the solution:

Project Properties / Debug / Start Action

If there were any build errors, it is possible that your debug session is loading the previous build of that assembly.

To prevent this, tweak the debugger settings:

Projects and Solutions > Build and Run


Registering the COM types

Building the Rubberduck solution should normally perform a registration of the COM types automatically for you. Refer to Build Process for full details.

Note: for historical information you can read about registering with regasm.exe. It is STRONGLY recommended that you do NOT use this with the current build process however.

Registering the add-in

Registering the COM types isn't enough. Every VBE host application will be looking for installed addins under a specific registry key in the HKCU hive.

Copy the commands below into a text editor and save as Rubberduck.reg, and then open the file to have Windows automatically add the entries to the registry, or see below for step-by step instructions:

Windows Registry Editor Version 5.00

[HKEY_CURRENT_USER\Software\Microsoft\VBA\VBE\6.0\Addins\Rubberduck.Extension]
"Description"="Rubberduck"
"FriendlyName"="Rubberduck"
"LoadBehavior"=dword:00000003

[HKEY_CURRENT_USER\Software\Microsoft\VBA\VBE\6.0\Addins64\Rubberduck.Extension]
"Description"="Rubberduck"
"FriendlyName"="Rubberduck"
"LoadBehavior"=dword:00000003

Alternatively, bring up the Windows Registry Editor, and depending on the bitness of the VBE host(s) you want to register Rubberduck with, create a Rubberduck.Extension key:

32-bit hosts:

HKCU/SOFTWARE/Microsoft/VBA/VBE/6.0/Addins/Rubberduck.Extension

64-bit hosts:

HKCU/SOFTWARE/Microsoft/VBA/VBE/6.0/Addins64/Rubberduck.Extension

The Rubberduck.Extension COM type was registered when you ran the regasm.exe command in the previous step. If you have both 32-bit and 64-bit VBE host applications and you want both to load the Rubberduck add-in, you'll need to create the two keys. Otherwise, just create the key that you need for the bitness of your VBE host.

Define the following values under the Rubberduck.Extension key:

  • Description (string value): "Rubberduck"
  • FriendlyName (string value): "Rubberduck"
  • LoadBehavior (DWORD): 3

Rubberduck.Extension 64-bit registry key values

Registering the add-in

If you'd like to delete the registry entries, copy the commands below into a text editor and save as RubberduckUnregister.reg, and then open the file to have Windows automatically remove the entries from the registry, or see below for step-by step instructions:

Windows Registry Editor Version 5.00

[-HKEY_CURRENT_USER\Software\Microsoft\VBA\VBE\6.0\Addins\Rubberduck.Extension]

[-HKEY_CURRENT_USER\Software\Microsoft\VBA\VBE\6.0\Addins64\Rubberduck.Extension]

Alternatively, open the Registry Editor and delete the keys:

32-bit hosts:

HKCU/SOFTWARE/Microsoft/VBA/VBE/6.0/Addins/Rubberduck.Extension

64-bit hosts:

HKCU/SOFTWARE/Microsoft/VBA/VBE/6.0/Addins64/Rubberduck.Extension

Project convention

The Rubberduck project has several projects which divides the responsibility and concerns. Not all projects are ultimately consumed by the users of the RD.

Those projects that are used in the final release version will typically have a prefix Rubberduck., with a period. Those that are internal for supporting the development will have prefix of Rubberduck, without the period. Note that all user-facing projects must reference the RubberduckCodeAnalysis project. See here for more details.


Not sure where or how to start? See Architecture Overview.

Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.