Building REALbasic plug-ins with MPW

REALbasic plug-ins

REALbasic plug-ins are a way for programmers to extend the functionality of REALbasic. REAL Software provides a plug-in SDK designed to allow developers to write their own plug-ins in C++ and compile them with CodeWarrior. Until recently, neither the official SDK nor Thomas Tempelmann's plug-in starter would compile without modification under MPW. However, in version 4.5a1, the official SDK was updated to make it more compatible with MPW.

For an example of a plug-in built with MPW, see my own CompfacePlugin for displaying X-Faces. It was written before REAL Software incorporated my changes into the official SDK.

RB-MPW Plug-ins Kit

I have prepared a kit to show how to compile plug-ins under MPW using the official SDK. The main makefiles are designed to work with SDK version 4.5a1 or later, but my kit also includes makefiles and scripts for modifying older SDKs to work with MPW.

Using the RB-MPW Plug-ins Kit

To use my RB-MPW Plug-ins Kit, you will need an unmodified copy of the official plug-ins SDK (preferably version 4.5a1 or newer). At the time of writing, the latest SDK is version 5.5.3. Instructions for using SDK 4a1 or older are included in my kit's documentation. The rest of this page assumes you're using SDK 4.5a1 or newer.

Naturally, you will also need a working installation of MPW. MPW is very simple to install, but you will also need to download the CarbonStdCLib update. You can read my instructions for installing everything you need to build REALbasic plug-ins with MPW.

When you have unpacked the official SDK and my kit, you should put my RB-MPW Plug-ins Kit folder inside the official SDK folder, and fix the 'REALbasic' alias so that it points to the folder containing the REALbasic application itself. Then launch MPW, change its working directory to the Kit folder and run the supplied script 'BuildPlugins'.

Having done this, you are ready to build your own plug-ins. There is limited documentation included in the RB-MPW Plug-ins Kit (although the makefiles themselves are well commented). The full documentation, including discussion of the issues involved in building REALbasic plug-ins, is available as a separate download. This has now been updated to bring it in line with the release of SDK 5a1. One day, I will get around to checking that it still works with the latest version.

The new plug-in file format

With SDK version 5a1, REAL Software introduced a new file format for plug-ins. It uses a directory structure containing standard PEF shared libraries ('for development') and a proprietary data-fork based file ('for deployment'). This change permits the use of plug-ins in the new Windows version of the REALbasic IDE.

The 5a1 SDK includes an application for converting resource-based plug-ins to the new format. It should be straightforward to generate `structured directory plug-ins' with MPW, and I hope to implement this in future versions of my Kit. Meanwhile, you can use REAL Software's translator to convert MPW generated plug-ins to the new format.

Downloads

You can download and use my RB-MPW Plug-ins Kit for free. The current version is 1.1b3 and it includes makefiles for both the newer and older SDKs.

	File	Size	Version	Date	Format
	RB-MPW Plug-ins Kit	65 kB	1.1b3	15th January 2003	Stuffit
	Documentation	34 kB	1.1b3		PDF

Freeware

My RB-MPW Plug-ins Kit is freeware, so you may use them freely, but it is copyright ©2002-3 by Peter Robinson. Please let me know if you find it useful. I would be very glad to hear any comments, bug reports and suggestions you might have. I will also be glad to help if you have any problems using MPW to build REALbasic plug-ins. I would be particularly interested to hear about any problems (or success!) using this kit with the latest version of the official SDK.

Installing MPW and my RB-MPW Plug-ins Kit

MPW is very simple to install on its own, but it is complicated by the need to install some extras before building REALbasic plug-ins. This is my attempt at a definitive guide to what is required.

Here's what you need to download:

You don't need to install any other MPW updates.

Here's what you need to do.

To install MPW

Mount the MPW-GM compressed disk image.
Copy the MPW-GM folder to your hard disk.

Opening the 'MPW Shell' application launches MPW into Classic under OS X.

To install my RB-MPW plug-ins kit:

Decompress the official plug-ins SDK and my RB-MPW plug-ins kit.
Put my RB-MPW plug-ins kit inside the official SDK.
Replace the REALbasic alias inside my RB-MPW plug-ins kit with one pointing to the folder containing your REALbasic application.

To install CarbonStdCLib

Uncompress the Stuffit archive. It contains one library ('CarbonStdCLib.o') and some header files ('stdio.h' etc.).
Put the library inside MPW's 'PPCLibraries' folder.
Put all the header files inside MPW's 'CIncludes' folder (replacing any versions already there). These folders are nested inside 'MPW-GM:Interfaces&Libraries:'

To build the example plug-ins (mine and REAL's):

Make sure REALbasic isn't running (it loads plug-ins during startup only)
Use MPW's Directory command to change directory to the folder of my RB-MPW kit. To execute a command, type it in to an MPW window (or put the insertion point on an existing command's line) and press enter (not return). Dropping a file on an MPW window inserts a valid path to that file.
Execute my 'BuildPlugins' command.

MPW should compile all the example plug-ins and install them into REALbasic's 'Plugins' folder.

To test the plug-ins

Load the example projects into REALbasic and run them.

If you have trouble, do ask.