Plugin Debugging

One of the other new features in REALbasic 2007r4 was a quiet, sneaky one -- the ability to debug plugins on any platform. In years past, you could debug plugins if you knew the special magic dance for a given platform. But there was never any officially sanctioned way to debug plugins, and the magic dance would change from release to release. For instance, the move from 5.5 to 2005 totally broke plugin debugging on Windows. I don't think Linux ever had a way to debug plugins, and Mach-O was certainly not a walk in the park. However, those days are now long gone! What's more, this new functionality isn't just limited to plugin debugging -- REALbasic users who don't have plugins can also get some benefit as well.

The development tools used to write plugins need a way to interface with REALbasic to be able to run plugins under their source-level debuggers. Generally, they do this by building a shared library into a certain location, and then launching an executable (of the user's choice) which is responsible for loading the shared library. In previous versions of REALbasic, there was no simple way to debug plugins because the RB compiler would embed the plugin code into its output instead of using the original plugin file on disk. REALbasic 2007r4 now allows you to specify "debugging" plugins, so that RB's compiler links its executables against the original file instead of copying the plugin code into the output app.

This feature set is designed to cover two use cases: debugging plugin code, and debugging plugin code while debugging REALbasic code.

You specify a debugging plugin by placing the plugin file into a special directory next to the IDE called "Debug Plugins." The REALbasic IDE loads any plugins in this directory and makes them accessible as if they were regular plugins. When compiling an application which uses one of these plugins, the resulting executable contains absolute path or alias information so that the application can load the plugin when it is launched.

Specific instructions about development environment setup are beyond the scope of this post, but the general approach is that you would place the plugin to be debugged into the Debug Plugins directory and launch the IDE. Create a test application which utilizes the plugin and build it. Then, in your plugin development environment, designate that the shared library should be built into the Debug Plugins directory, and that the newly created REALbasic executable should be launched after the shared library has been built.

The second use for this feature is to debug a plugin at the same time as debugging the REALbasic code using the plugin. If the IDE finds a Debug Plugins directory in the proper location, then the Project menu will contain a new "Run Paused" menu item. Selecting this item will build a debug version of the project and start up the debugger, but will not launch the debug executable. This allows you to debug the REALbasic project, but have an external entity be responsible for launching the executable. Frequently, this will be the plugin development environment.

Caveats:
1) Only "native" plugins can be debugging plugins. Don't put RBX files into the Debug Plugins folder as this is not supported functionality. Instead, put the native shared library (dll, dylib, so, etc) into the Debug Plugins directory. Cross-compiling is not supported.

2) Watch out for duplicate plugins. This can happen when you have the same plugins in both the Plugins and Debug Plugins folder. The IDE does not attempt to warn you of this situation, and it can result in hard-to-diagnose compile errors.

3) Be certain to remove any files from your Debug Plugins folder when making release builds of applications. Failing to do so will mean that the released application will not launch anywhere but the original development machine.

4) Note that a project does not need to use a plugin in the Debug Plugins folder in order to get the Run Paused command. The presence of the folder determines whether the menu item will appear or not.

This last caveat is actually a very useful piece of functionality for non-plugin debugging situations, especially on Windows. Let's say you are working on a project that requires admin privileges in order to function properly. You can do a Run Paused to build a debug application, and then right-click the resulting application and select "Run As Administrator."

I'm really tickled for this functionality because it makes my life so much easier. I've used it several times already to locate and fix bugs in the compiler, SSLSocket and XML plugins as well as some for my own personal use. And I use the Run Paused very frequently so I can Run as the resulting application, as well as to debug the REALbasic framework code. So this "stealth" feature is a big one for me.