Palm Programmer's FAQ

Getting Started with PRC-Tools

by Warren Young

What is PRC-Tools?

PRC-Tools is a free toolchain for building Palm programs. The core of the toolchain is the free GNU Compiler Collection (GCC). In this article, I'll refer to the overall toolchain as PRC-Tools; I'll only use the term GCC when I'm talking about the parts derived from the GNU Project's GCC work.

Getting PRC-Tools

If you're using Windows or Linux, there are several places to get pre-built PRC-Tools packages. I prefer the one hosted at PalmOS.com, because they've got a well-organized set of links to pre-built PRC-Tools packages. They also link you to the SDK and documentation packages you'll need, and for Windows users they link to the Cygwin tools which adds some necessary Unixy functionality to Windows.

If you're on some other OS, like one of the Unixes, you will have to build PRC-Tools from source code. You can get the sources from the home site at SourceForge. You will need a working native version of the GNU GCC toolchain to build PRC-Tools. Once you get PRC-Tools built, you will also need to build a copy of PilRC.

Notice that there are four separate parts to the PRC-Tools system:

The PRC-tools package itself, which contains the Palm OS cross-compilation system.
The native development tools (e.g. GNU make)
The Palm OS SDK, which contains the header and library files you need to write to the Palm OS API.
Auxilliary tools like PilRC and POSE.

Getting POSE

POSE is a Palm device emulator that runs under Windows, Unix and the Macintosh. This is an essential tool for debugging Palm programs. Debugging on the Palm device itself is extremely difficult; debugging with POSE is just mildly difficult. :) You might find Schaumann's "Palm OS Emulator HOWTO helpful, especially if you're using Linux.

Installation Location

You have to set these tools up exactly like the documentation describes. The Windows version of the tools must be installed in c:\palmdev, and the SDK needs to go into c:\palmdev\sdk-3.5 for things to work right. If you try and get creative and put these tools in other directories, you will have to do a lot of work to override the tools' defaults. If instead you put the tools where the docs tell you, they'll work very smoothly.

For Windows, your directory tree should look something like this:

              c:\palmdev
                  bin
                  sdk-3.5
                      include
                      lib
                          m68k-palmos-coff
                  lib
                      m68k-palmos-coff

On Linux, the tree is similar, except that it begins at /usr/local/palmdev. Also, on Linux you can create a symlink called "sdk" that points to the sdk-3.5 directory, so you don't have to give the -palmos3.5 flag to gcc.

If you really must put these tools somewhere other than the default, there are environment variables you can set to tell the main compiler where to find the auxilliary helper programs, but I don't have the list handy. (See the Ardiri article below for how to do this under Windows.) Alternatively, you can rebuild the tools from source. This will let you control many things about the runtime environment, not just the install location.

Which SDK?

I strongly recommend that you use SDK 3.5 with PRC-Tools. This is the only stock version of the Palm OS SDK that works with PRC-Tools. There are patched versions of SDKs 1.0, 2.0 and 3.1 that work with PRC-Tools, but there are several good reasons to use the current SDK and almost no drawbacks.

Other Starting Points

Now that you've got the tools set up, I'll leave you with a list of sites on the net that I found helpful when I was starting out.

Aaron Ardiri has a good tutorial on setting up PRC-Tools under Windows. It mostly parallels this article, but he goes into a few areas that my article doesn't. One useful item in particular is that his article tells you how to install the tools into nonstandard locations, if you want.
There's an online version of the O'Reilly book Palm Programming; A devloper's guide. This is not the most useful of the Palm programming books, but it is the only free one.
The Palm OS SDK Documentation is essential. You can read it online in HTML format, download PDF copies, or buy paper copies of the PDFs.
Dan Parsons' article "A Simple PalmOS Application written in C" is dated, but still helpful if you're willing to overlook some mismatches with respect to current SDKs.
The Palm OS SDK itself has many sample applications. Currently only two of these are fully converted to be compilable by PRC-Tools, but simply reading the others' code might be sufficient. (These samples were originally written for CodeWarrior.)
The POSE HOWTO mentioned above has a very simple "hello world" type program in it.
The GNU GCC manual is very helpful, mainly with the portable, non-Palm aspects of the toolchain.