Plugins Can Be Fun (Part One: Visual Studio 2005)

Everyone knows that there is nothing more enjoyable than writing plugins, right? I know I certainly enjoy it, depending on the day, how the planets line up, how much I've had to drink and what I need to accomplish. ;-) But seriously, writing plugins for REALbasic isn't nearly as hard as a lot of people make it out to be. The API documentation is lacking (to say the least), but that has been rectified for the next SDK release. The "how to get started", however, has not been updated in ages, and you can assume it's all lies, lies and more lies. Not because it's wrong, mind you -- but because it's old and refers to ancient development environments which no one uses anymore. Pascal with MPW? Uh... CodeWarrior? VS 6? Yeah, like I said, it's out-dated, to be sure. Hopefully that issue will be addressed in a future release as well (but I can assure you it won't be addressed in the next release, unfortunately).

As a way to sort of formalize the process of writing a new plugin, I'm going to write a blog posting about how to write a plugin using Visual Studio 2005. You can think of this as sort of a precursor to actual documentation. This will help me to solidify my thoughts, as well as find out what areas still confuse people (which tends to make for more robust documentation in the long run). If everything goes well, then I may cover gcc or even XCode. We'll see though; one fish at a time, so to speak.

Before we can really begin with the whole "setup" topic, you need to have a bit of background information about how plugins work in REALbasic. You don't need to know much of anything about the SDK itself to follow along, so for beginners, this is a good starting point.

Every REALbasic plugin ever made is nothing more than a fancy shared library. So on Windows, you make a DLL, on the Mac it's some weird .dylib (I think), and on Linux it's a .so file. The .rbx file format is what you ultimately want to get your plugin into, but that's just a virtual volume that can be created with the anciently-named "Plugin Converter" project that comes with the SDK. The virtual volume just houses the plugin "parts" (the shared libraries) in such a way that the REALbasic IDE can grok them.

Note that the IDE will *only* load a plugin for its architecture. So if you are running a Windows IDE, it will only load up the DLL plugin part for Windows. If you want your plugin to be usable on any platform, you must make shared library for it (even if the shared library does nothing more than expose your plugin's API to REALbasic). More on this later, though.

All plugins begin their life in a function called REALPluginMain (or simply "main", depending on the platform). When the IDE or application loads a plugin, this is the entrypoint. Thankfully, you don't need to care about it too much because this entrypoint will be in every single plugin using the SDK -- it's defined for you in PluginMain.cpp. This entrypoint does a bunch of setup, some housekeeping, etc and it eventually calls the part *you* need to care about: PluginEntry.

The PluginEntry function is where all of your "registration" code will go. It is the place where you tell the loader "I have a class named Foo, and it has these code items in it." -- your plugin's API.

This registration code it what tells the IDE what classes, modules, and other pieces of code exist so that things like autocomplete and the compiler will work. The user will use your plugin in the IDE to design their application, and when they hit Build (or Run), your plugin is wrapped up into the final executable -- but not your entire plugin. Only the plugin part that is needed for the executable (why would a Windows .exe file need a Linux .so plugin part, after all?).

When the user launches that executable, your plugin is loaded up just like it was with the IDE, and the same registration code is called. This registration code also tells the framework "hey, when you need this functionality, it lives right here."

Ok, that's enough background about how plugins work at a high level. Now we can talk about how to make a very, very basic plugin using Visual Studio 2005. We're going to make this plugin from scratch, but it assumes you have the latest version of the plugins SDK. I am using Visual Studio Team Suite, but the steps should be the same for all but possibly the Express version (I've not used that version, but I hear it has some differences from the non-free siblings).

First, go to File->New->Project. and select Visual C++, Win32 Project and give the project whatever name is appropriate for you (mine is called simply, REALbasic Plugin). This will bring up the project creation wizard. You want to select DLL as the project type, and click the Empty Project checkbox. Click the Finish button, and you will have the skeleton empty DLL project.

Now we are going to add in the files you need for the SDK. At this point, I usually copy the plugin SDK into my project's directory (I do this so I can ensure that grabbing a new SDK will never affect older projects unless I want it to). The only code you need to copy over resides in the Glue Code and Includes directories of the SDK. Once you have the SDK code next to the project, you need to add some of the SDK files directly to the project.

We are going to add PluginMain.cpp to the Source Files folder -- this is the guts of the SDK functionality which provides the implementation details. Then we are going to add the rb_plugin.h, REALplugin.h and WinHeader++.h files to the Header Files folder. This is the declaration guts of the SDK. Now we've got the SDK included into the project!

The next step is to configure the project settings so that it matches our needs. To do this, you go up to Project->Properties, and into the Configuration tree. Our first stop is the C/C++ section, under the General item. We need to add some additional include directories for the header files we included (since VS is a little pedantic about header files and includes, which is a good thing). We want to add the SDK's includes directory, relative to the project itself. This is what my configuration looks like (note, I also turned off 64-bit porting issues because I don't care about them):

The next step is to change some preprocessor settings. Since most plugins don't use QuickTime on Windows (and the ones that do should highly reconsider, in my not-so-humble opinion!), you want to set IGNOREQT as one of the preprocessor settings. You must do this in order for the SDK to entirely ignore QuickTime. Forgetting to do this will yield some very cryptic errors dealing with the QT namespace and movies.

The last required step is to include WinHeader++.h in all of our files. We can do this from the Advanced tab, under the Force Includes field. You have to have WinHeader++.h included before any of the other include files in any source file in order for the project to function properly since it defines some of the very basic types used by the SDK.

The final steps that I usually take (but it is technically optional) is to statically link in the C runtime library instead of using a dynamic version of it. I do this so that older versions of Windows can still use my plugin without needing the newer runtime. You do this in the Code Generation pane by changing Multi-threaded Debug DLL to Multi-threaded Debug. I also disable exceptions and run time type info (which is in the Language pane).

Now we're ready for the "meat" of your own plugin. Go up to Project->Add->New Item and add a new C++ source code file (I named my Main.cpp). This file should look like this:

#include "rb_plugin.h"

 

void PluginEntry( void )

{


}

As you can see, it wasn't nearly as hard and scary as you might have imagined. And sometimes, starting off from one of the example projects doesn't really teach you anything because it's easy to miss the setup steps. It's also easy to not understand why you have to do the setup steps.

One final note is that there would be a template for a REALbasic plugin, but Microsoft has crippled Visual Studio 2005 for no good reason. It is impossible to make any templates for C++ projects at all (it's only supported for the .NET projects). Thank you so much Microsoft. :: sighs :: The good news is that you can easily copy what we've created today and save it off as your own "template" of sorts. It's nothing more than a blank plugin project, so it can be used for any of the plugins you want to write.

So -- how did I do? Did I leave you wondering "but how do I set up this?"