By David Garcea
This article is intended to show you how you to create applications that run on the Palm OS using Mac OS X. The majority of the tools used in this article are free and open source, the rest are inexpensive shareware or donationware. You do not need any previous Palm OS programming experience to understand the material in this article.
For years, Palm OS development on Macintosh was done using the Metrowerks CodeWarrior integrated development environment. CodeWarrior is very powerful, but that power comes at a great expense – $399. In addition, Metrowerks has dropped support for Macintosh computers in the latest version – CodeWarrior Development Studio for Palm OS Version 9.0. Thankfully, there is an alternative that is just as powerful, and free. It’s called PRC-Tools and it’s an open source project available at a repository called SourceForge.net.
PRC-Tools is a collection of unix based tools for creating Palm OS applications using C and C++. Luckily for us, MacOS X is also based on unix, an open source derivative of FreeBSD called Darwin to be exact. This means that we too can use these tools. In order to do this, the PRC-Tools package needs to be compiled on MacOS X. If you are comfortable with the command line and building unix applications, you can do this yourself, but as Mac users we expect things to be easier. Thanks to a group of Mac developers called Zenonez, we can install PRC-Tools using a standard MacOS X installer package.
Make sure you have installed the latest version of Xcode from the Xcode Tools (Aka Developer Tools) CD that accompanies MacOS X. You can also download the latest version from Apple. This article assumes you are using Xcode 1.5 or later. Then download the PRC-Tools installer package from here:
http://www.zenonez.com/prctoolsx/index.html.
Install PRC-Tools by double clicking on the package and running through the installer.
Once you have downloaded and installed the PRC-Tools package, you have almost everything that you need to develop Palm OS applications using the command line, which is accessible from the Terminal application. But using a Mac means we shouldn’t have to work with the command line and we don’t. Instead, we can use Xcode, Apple’s free integrated development environment.
Launch Xcode and create a new project using the File menu. In the New Project Assistant, select the “GNU Make” option and click Next. Selecting “GNU Make” means that Xcode will use the command line utility called make to perform the operations needed to build your application. Name the project and select a directory to keep it in, then click Finish.
Create a new file using the File menu. In the dialog that appears, select “Empty File in Project.” Name the file “Makefile”, making sure to use the same capitalization, and then click Finish. This is the file that Xcode will pass to the make utility to tell it how to compile your application. Click on the Makefile in Groups & Files list to edit it. If the editor does not appear, select “Toggle Embedded Editor” from the “View” menu or click the Editor button in the toolbar.
Enter this code into the file and save.
MacPalmDev.prc: MacPalmDev.c MacPalmDev.h MacPalmDev.rcp
m68k-palmos-gcc MacPalmDev.c -o MacPalmDev
m68k-palmos-obj-res MacPalmDev
pilrc MacPalmDev.rcp
build-prc MacPalmDev.prc "MacPalmDev" XXXX *.grc *.bin
The first line specifies that in order to build the file MacPalmDev.prc, it needs to have MacPalmDev.c, MacPalmDev.h and MacPalmDev.rcp. If those files are not present, an error will occur when you try to build the application. The remaining lines are the commands that will be executed on the command line to build the application. This is a very simple Makefile that was made specifically for this project. You may want to learn how to create you own Makefiles so that you can create a generic one for all of your applications. For more information on creating Makefiles, read the make manual at:
http://www.gnu.org/software/make/manual/make.html
Create another new file using the File Menu. This time, make it a C file, and name it MacPalmDev.c. Make sure the checkbox for creating the MacPalmDev.h file is checked and then click Finish.
Click on the MacPalmDev.h file in the Groups & Files list to edit it. Remove the line that contains “#include ” because it is inappropriate for Palm OS development. Then add this code to the bottom:
#define MainForm 1000
#define MessageLabel 1001
Click on the MacPalmDev.c file and add this code at the bottom:
#include
Boolean MainFormHandleEvent( EventPtr theEvent )
{
FormType *frmP;
if( theEvent->eType == frmOpenEvent )
{
frmP = FrmGetActiveForm();
FrmDrawForm( frmP );
return true;
}
return false;
}
Boolean AppHandleEvent( EventPtr theEvent )
{
FormPtr frmP;
if( theEvent->eType == frmLoadEvent )
{
frmP = FrmInitForm( theEvent->data.frmLoad.formID );
FrmSetActiveForm( frmP );
FrmSetEventHandler( frmP, MainFormHandleEvent );
return true;
}
else if( theEvent->eType == appStopEvent )
{
frmP = FrmGetActiveForm();
FrmEraseForm( frmP );
FrmDeleteForm( frmP );
return true;
}
return false;
}
UInt32 PilotMain(UInt16 cmd, MemPtr cmdPBP, UInt16 launchFlags)
{
EventType theEvent;
if( cmd == sysAppLaunchCmdNormalLaunch )
{
FrmGotoForm( MainForm );
do
{
EvtGetEvent( &theEvent, evtWaitForever );
if (! SysHandleEvent( &theEvent ))
if (! AppHandleEvent( &theEvent ))
FrmDispatchEvent( &theEvent );
} while( theEvent.eType != appStopEvent );
}
return errNone;
}
This code has been compacted for use in this article. It is not intended to demonstrate good programming practices. All this code does is display a single form. To learn more about programming for Palm OS, visit:
http://www.palmos.com/dev/tech/overview.html.
Create an empty file in the project and name it MacPalmDev.rcp. Then add this code to it:
#include "MacPalmDev.h"
FORM ID MainForm AT (0 0 160 160)
BEGIN
TITLE "Made With A Mac"
LABEL "This application was made on MacOS X!" ID MessageLabel AT (1 50)
END
This is a resource file that defines the user interface elements that will be displayed by your application. Your Makefile calls the PilRC command line application and passes it this file, which is converted into binary resource files.
This file only displays a message on the screen. A real Palm OS application will have much more code in this file. You could write the entire file yourself, if you first study the PilRC User Manual, or you could use an application that is currently under development called PalmBuilder. The version available on their website is still in the beta stage but we hope that it will be available in a final release soon because it is very useful.
If you are migrating an existing project from CodeWarrior, you will probably already have resource files in the form of Constructor files. There is another open source project called rsrc2rcp that will convert the files for you. You may have to review the resulting .rcp files to make sure they are correct, but this application will save you a lot of time.
You are now ready to create the application. Select Detailed Build Results from the Build menu. This will open a window that contains three panes, although some may be closed. You want to make sure the center pane is visible because this is where all the action will be. The top pane shows simplified results of the build process, the center pane contains a log of what is actually occurring on the command line, and the bottom pane allows you to fix errors in your code.
Click the Build button in the toolbar and watch the center pane. It should look similar to the Makefile that we created earlier. If the build fails, check the center pane for clues to the cause. In this case, there is most likely a typo in your code. Check the code and try again. When the build succeeds, switch to the Finder and look in the project’s folder. You will see several files that were not there before. The one you want to focus on is the MacPalmDev.prc file. This is your Palm OS application. Now you have to test it.
To run your Palm OS application, you could install it onto an actual Palm OS device but that is too time consuming, especially since you will probably be recompiling and installing the application dozens if not hundred of times before the application is perfect.
It would make things much easier if you could just run the application on your Mac, and you can. You will need to download POSE, the PalmOS Emulator, from here:
http://www.palmos.com/dev/tools/emulator/
You will also need to acquire a ROM file. Instructions for doing so are included in the link above and in the POSE documentation included with the downloadable archive.
Once you have POSE installed and running, drag the MacPalmDev.prc file and drop it onto POSE. This will install the application into the emulator. You may have to refresh the display to see the application. Try selecting the Unfiled category, that is where your application should be. Click on the application to launch it and you should see a form that says “This application was made on MacOS X!”
Most of the time, your application will not behave as desired the first time. In this case you will have to use a debugger to find the problems. PRC-Tools comes with a special version of the gdb command line debugger but Xcode can not provide a user interface to it. As a Mac user, I like to avoid using the command line whenever possible, so I created an application called Bug Off, which acts as a graphical user interface to the PRC-Tools version of gdb. Bug Off is shareware, which means you can use it for an evaluation period (30 days) before you decide if you want to purchase it. The only limitation you will encounter while evaluating the software is that you can only have three breakpoints at one time. You can find information on purchasing Bug Off here:
http://www.trinfinitysoftware.com/bugoff.shtml#purchase
If you are experienced with using gdb, you may prefer using the command line as it is faster, otherwise you may find Bug Off very useful.
There are several online communities available that can help you develop Palm OS applications on MacOS X. Here are a few:
Zenonez Forums
Palm Source: Mac Development Forum
Palm OS: Programming Recipes