[tux, with pda]

Linux PalmOS Development

Chances are you got here after a web search after spending some time beating your head against the wall trying to follow Palm's instructions on setting up the gcc-based prc-tools. They don't work, do they? What is Palm thinking? I have no idea. But some of us would like to develop PalmOS stuff on Linux whether or not Palm supports the idea (we've got the device already, might as well make use of it), and after way too much time wasted I finally got a working setup, so I'm putting together this page to help fellow Linux developers.

More recently, the prc-tools sourceforge page has been updated and includes information about how to install from RPM. It may be helpful, as may this article on Setting Up the PRC Tools in Linux". Both of these are more modern than my howto, and describe newer versions of the tools, which may or may not make things easier. (If you're developing for ARM architectures, then you definitely need the newer howtos; the versions I describe here won't work.)

First, forget about the PRC-tools link Palm gives you. It's hopeless, doesn't work at all as far as I can tell. Palm is doing a great disservice to Linux developers by keeping that link on their site.

First, get prc-tools

As it happens, the prc-tools project is alive and well, and the latest builds work fine, with any sdk. Go get it from the sourceforge page. I installed the RPM prc-tools-2.0.92-1.i386.rpm, which worked fine.

Pick up the tarball of sample programs while you're there.

Next, get pilrc

I haven't hit any weird version problems with pilrc. I just checked it for install in my Redhat 7.1, and ended up with pilrc-2.5b7-4. Seems to work. Previously I used pilrc-2.7b-1mdk.i586.rpm, which also worked fine. Probably any pilrc you can find at rpmfind should be fine.

Get a PalmOS SDK

This is a bit harder. You do need to get that from Palm -- it's not open source. The current version as of this writing is SDK 4.0, and SDK 3.5 is still supported on Palm's site. There's also a tar file containing SDKs 1, 2, and 3.1 (no libraries, just header files; it turns out you don't need libraries for these earlier SDKs).

My advice is to get them all. If you end up collaborating with other Palm developers, there's no telling what version they will have (more on that below), and it's easy enough to sign Palm's form a few more times and just pick up everything.

The documentation that comes with the SDKs is sparse. 4.0 comes two ways: First, a tarball which, when extracted, gives you a few useless directories plus an RPM -- you can install the RPM and throw the rest away. (Save the tarball, you may need to do this again some day.) Second, a different tarball which contains the same files again, which extracts into Palm\ OS\ Support/Incs/ and Palm\ OS\ Support/GCC\ Libraries (Palm is just in love with long directory names with spaces in them; I think these are the Mac CodeWarrior paths) which then have to be copied into /opt/palmdev/sdk-4/{include,lib} 3.5 comes only in the latter form (i.e. the Mac directory names). The older three SDK versions come together in a single tarball which you can extract in /opt/palmdev with no further hassles.

With any SDK, what you want to end up with is a directory called /opt/palmdev/sdk-xx (where xx is the version number, e.g. 2, 4, 3.5). Some tools look in /opt/palmdev, some look in /usr/local/palmdev, but I'm told that /opt is the correct place and /usr/local is only for backward compatibility. The palmdev/sdk-x directory should end up having two subdirectories, include and lib.

Now pick one SDK (probably 4.0 or 3.5, flip a coin) and make it the default. If you list the files in the RPM (rpm -ql prc-tools) you'll find that it installed various documentation files. One of them is a README, and one of the things it suggests is to make a symlink from /opt/palmdev/sdk-version to /opt/palmdev/sdk. Do this if you want sample apps to compile. (You probably shouldn't rely on this in your own code, though; I'll tell you why later.)

Now you have a working Palm development environment. Let's compile some code!

Compiling a program

Don't pay any attention to the sample apps that come with the SDK -- they're set up for CodeWarrior or something and don't even have Makefiles, so for a beginning Linux Palm programmer they're more hassle than they're worth. Instead, extract that prc-tools sample tarball you downloaded earlier.

As of 2.0.92, I find that errorcodes and multiapp don't compile (I'll work that out with the prc-tools folks), but gausstest, gdbpanel and syslib do. So cd into one of those directories and type make. gdbpanel uses pilrc, so try that one if you want to make sure you have a working pilrc as well as prc-tools.

Or, if you don't like the prc-tools samples, you can look at my Palm astro software page or my Marsmap page, where I have code for some planetary simulation apps, some of which also compiles to a linux binary using Xlib, in case you're interested in sample code that works in both environments. I find it a lot faster to test algorithms on Linux than to download a new .prc to the Palm each time.

If this works, your development environment is working and you can start working on your own code.

Tips and problems to be aware of

Why did you tell me to pick up old SDK versions? Shouldn't I program with the newest one?

First, it turns out that many people who are still programming with the prctools (especially on Linux) are using very old SDKs -- 3.1 or earlier. They're leery that upgrading might break things; or they're just lazy and don't want to go fill out more of Palm's forms. They also know that Palm changed all the include files for SDK 3.5, and if they upgrade, all their includes will break and they'll have to rewrite their projects. So they just stick with whatever working environment they have. Who can blame them?

If you find yourself collaborating with other developers, you either need to agree on an SDK, or fill your code with ifdefs which handle all the includes and APIs which changed between versions (this is true from 3.5 to 4.0, too, not just from pre-3.5 to 3.5).

There are also some differences in functionality. 4.0 can do some things that 3.5 can't, like more advanced color support (supposedly; I have a IIIxe so I'll never see that). Some of the 4.0 APIs cause crashes on machines running older versions of the OS, like the Visor Deluxe. As far as I can tell, 3.5 and 4.0 work equally well with linux prctools (once you use the right includes).

You'll probably run into plenty of sample code built for pre-3.5 SDKs. A quick fix to get older code to run on newer SDKs is to remove the lines for Pilot.h, NewFloatMgr.h, and ScrDriverNew.h, and replace them all with an include of PalmOS.h.

A better approach, in case you ever need to share code with anyone on a different SDK, is something like this:

#  if defined(SDK_31)
#    include 
#    include 
#    include 
#  else /* SDK 3.5 and later */
#    include 
#  endif /* SDK versions */
Then, in your project's Makefile, do this:
# Set SDK_VERSION to whichever SDK is being used on this machine
Now the compiler (which calls a program called sdkfind) will look in the appropriate directory, and you can do #ifdefs in your program if you need to call APIs which differ between SDKs. I'm told sdkfind is going away, but -palmos will continue to work in prc-tools through other mechanisms.

Q: What about emulators?
A: I've had a lot of trouble getting older versions of POSE, xpilot and xcopilot to work, but I did once manage to get EmulatorSrc_3.3 working. Unfortunately it stopped working when I upgraded fltk for the Agenda toolchain, and I've never managed to go back to a set of tools under which POSE works. (fltk seems to change a lot between versions, alas.)

If you do get it running, you'll have to download skins for it (the README tells you where), and you'll have to get a ROM image -- you can get debug ROM images from Palm somehow (registering for their developer program, which I did, then going through a secret handshake which I haven't learned) or you can use pi-getrom from the excellent pilot-link tools. (I assume you already know about pilot-link, if you've gotten this far; if not, download it immediately.) Be patient: pi-getrom took about an hour for me over a serial line (at 9600 baud, though later I found I could run much faster). Make backup copies of your ROM once you have it so you'll never have to do that again.

Some Links

General Palm Pilot Links
Linux info
Shallow Sky Home