1.1 - What other online sources of Palm programming answers are there?

Newsgroups

The main set of newsgroups are the pilot.* groups, hosted at news.falch.net. Your main Usenet server might have provided a copy of these newsgroups, but this is only good for reading. If you want to post to the newsgroups, you need to post to the official server.

Mailing Lists

• The Pilot Unix mailing list is for users of GCC and PilRC.
• The Palm Developer Forums are a series of mailing lists on a variety of topics. These mailing lists are also gatewayed to a dedicated Usenet server, if you prefer reading discussion groups that way. There are also searchable archives: your question may already have been asked and answered, so search the archives before posting.

Web Sites

Palm's Development Support site is an excellent resource, being very deep and broad. One section in particular you should visit is their FAQ-like Developer Knowledge Base.

You may also find some of the web pages linked in the FAQ's Resources section useful.

1.2 - What development tools are available?

Most Palm programs are written in C or C++, since these languages excel at keeping programs small, an essential quality given all of the platform's limits. Additionally, virtually all Palm programs have a GUI, which plays to one of C++'s strengths.

If your Favorite Language isn't C or C++, you're probably still in luck. By my count, there are Palm OS compilers for 9 different languages, not counting C/C++ and the various database tools: Java, Pascal, Basic, Python, Forth, Scheme, Smalltalk, CASL, and assembly language. And, many of those languages are represented in multiple development suites. The only popular language I can think of that doesn't yet have a Palm OS compiler is Perl.

For more details on these and other tools, see the FAQ's Tools section.

1.3 - Are there any GUIs for PRC-Tools?

PRC-Tools proper is a command-line tool chain. If you want a GUI IDE, there are several to choose from: Falch.Net, VFDIDE, and PilotMAG. All of these include a GUI designer and a colorizing code editor, and they interface to the PRC-Tools tool chain. The former also interfaces to the GNU gdb debugger. Falch.net is $280. with a 30-day free trial available. The full version of VFDIDE costs $55, with cheaper versions available that have less features. PilotMAG is $20.

1.4 - What [printed] documentation is available?

The primary documentation you need is the Palm OS SDK Documentation set. You can read this online in HTML format, download it in PDF format, or buy printed versions.

You should also consider reading one or more of the various Palm programming books out there. You can find information about them in the Reviews section. Note that one of them, O'Reilly's Palm Programming; A developer's guide is freely-available in an online version.

1.5 - What is POSE, and why do I need it?

POSE is the Palm OS Emulator, a free program from Palm Computing which runs on any Win32, Macintosh or Unix/Linux system. (POSE is sometimes called POSER, and is still sometimes called by the name of its predecessor, CoPilot.) POSE runs most Palm OS programs, most probably including yours. Since it uses real device ROM files, you can make it behave like any Palm device. This is useful for compatibility testing, especially with older devices.

POSE doesn't ship with any ROM files though: you have to download a ROM image from a real Palm device. However, there's an exception to this rule for developers, so you can test your programs with ROMs for devices you don't actually own. See the next question for info on getting ROM files.

POSE has other nice features, too:

1. The download/test cycle is shorter with POSE than a real device since you can load your app into POSE instantly instead of going through a synch process with a real device.
2. POSE lets you save the state of the machine to a file, so you can quickly restore the emulator to a known state. During debugging, it's easy to crash your Palm unit or to corrupt its memory; it's much less painful to crash or corrupt a POSE session than your actual Palm unit.
3. POSE can use special debugging ROMs, which can detect several common Palm programming errors. Again, see the next question for info on getting these special debug ROMs.
4. It's much easier to do source-level debugging with POSE than with a real Palm unit.
5. POSE has a built-in stress tester called Gremlins, which is the electronic version of a sugared-up two-year old with an infinite attention span. It randomly bangs on your program until you tell it to stop, or your program crashes.

There are some things POSE can't do as well as a real Palm device. Depending on the speed of your PC, POSE might not be as fast as a real Palm unit. Also, POSE support for infrared, wireless networking, serial ports, or hardware expansion features (Springboard, etc.) ranges from hackish to nonexistent.

If you plan on using POSE on a Linux system, there is a HOWTO document that you will probably find helpful.

1.6 - Where can I get ROM files for POSE?

The simplest way is to download them from your real Palm device, using the RomTransfer.prc program that comes with POSE. This only works easily with serial-based devices. Falch.net has an article that shows how to do this with a USB device, like most Visors.

If you are a developer and you're in the US, you can get ROM files for Palm Computing and Symbol Technology devices by signing up for the Palm Alliance Program. Once you're a member, you just click through a license agreement, which gets you into the ROM download area. They have ROMs for everything from ancient OS 1.0 devices up through the latest ROMs in released devices. You can also get access to "debug" ROMs, which have code in them to detect when a program uses an OS or device feature in an unsupported or possibly dangerous way. These faults often cause no problems on current Palm OS devices, but may well fail to work correctly on future devices. Other times, a debug ROM will point out a real flaw in your code that can cause dodgy behavior on a real Palm device. Debug ROMs are the best reason for a programmer to use POSE, in my opinion.

If you're not in the US, you can still get ROM files after joining the Palm Alliance Program, but you have to fill out some paper forms and mail them to Palm before they'll give you online access to the ROM files area. This will take a few weeks.

If you want ROMs for Handspring, TRG or Sony units, you will have to go to their developer sites instead. They usually have similar conditions about being in the US or requiring signed paper documents to be mailed to them.

And don't bother asking on newsgroups if someone would please, please, please send you a ROM file. Don't ask me, either. We're all software developers, people who have a vested interest in making sure the copyright laws are upheld. I wouldn't lecture like this if I didn't see this question come up on the various newsgroups about once a week....

1.7 - Which Palm OS unit should I buy for development?

This is a very simple question to answer, because a typical program runs on all current Palm OS devices. Unless you need some uncommon hardware feature or exorbitant amounts of memory or processor speed, any current unit will do. You might even be able to get away with using an older, used unit. You will probably be doing most of your development and testing on your PC, so platform speed is not a critical concern with Palm development as it is for most other kinds of development.

It is possible to develop a program solely with POSE, never actually running your program on a real Palm OS device. But, POSE has real limits, so it can't give you a fully accurate picture of how your program will behave on real devices.

1.8 - What are the Palm platform limits I'll likely encounter?

(Accuracy Note: Roughly every six months or so, a new Palm OS device is released that makes some item or other below inaccurate. This item was last checked for factual accuracy on 2001.09.02.)

The current Palm processor is a derivative of the Motorola 68000, a mixed 16/32 bit processor. This makes Palm devices feel like mid-80's Macintoshes in many ways. This so-called "Dragonball" processor is hobbled from that baseline by a few [reasonable] OS design decisions:

1. 8 MB addressable memory The Dragonball EZ and eariler CPUs can only address 8 MB of memory at a time. This is not a limit in the CPU's instruction set, it's a limit in the CPU's DRAM controller. This limit can be worked around by having more than one separate 8 MB chunk of memory you see this technique used in the original Visor and the Sony Clie, both of which have 8 MB add-on cards available. The TRG units can use even larger Compact Flash cards, but they don't directly access this memory: they move blocks of data to and from the CF card like your desktop computer uses its hard drive. The newer Dragonball VZ chip supports up to 32 MB of memory, but currently no released device has more than 8 MB.

2. 32 KB jump size When you do something like a function call, it resolves to a "short jump" machine language instruction. Short jumps on this processor are signed 16-bit relative jumps, you can only go a maximum of 32 KB forward or backward from the current memory location. There are also "long jumps" that have no effective limits on code distance, but they're slower and make the program bigger. So, current development systems make you jump through a few hoops to use these longer jumps.

3. 64 KB resource size Due to the way the current HotSync mechanism works, no one resource in a Palm database can be larger than 64 KB. Since your program's code is in a single resource by default, your PRC file can't get much bigger than 64 KB without resorting to multi-segmenting. (If you use PRC-Tools, you can see how big your main code resource is by looking at the code0001.coffname.grc file. In my current project, for example, the PRC file is 53 KB, but the main code resource is only 33 KB. The balance is in UI and other resources.)

4. 12-36 KB dynamic heap for most devices Depending on the OS version, the dynamic heap size is quite small. OS 3.5 goes beyond the 36 KB cap in OS 3.0-3.3, allowing sizes up to 184 KB, but that's still pretty small. The dynamic heap is where dynamic variables and malloc()'d objects are placed. Your development tool of choice may use the heap for other things, as well; CodeWarrior uses the dynamic heap for C++ exception information, for example.

5. Stack size The stack size defaults to 3.25 KB on OS 3.0 and up, and it's hard-limited to 2.5 KB on older OSes. This limits how many function calls deep you can go, and how large your local variables can be. Recursive functions are almost entirely out of the question on the Palm. (You can increase the stack size in OS 3.0 and up, but be warned that the stack eats into the dynamic heap, which as we've seen is quite small already.)

The definitive article on these issues is the Memory technical article at palmos.com.

1.9 - What should I beware of when using C++ for Palm programming?

The main thing to beware of is that all Palm OS devices have several limits which make it imperative to pay close attention to your program's size. There are many ways to bloat your code through careless use of C++ features. This FAQ item will point out some of the pitfalls, particularly with GNU C++, with which I'm most familiar.

The first problem I discovered is that when you rebuild a straight-C program with the GNU C++ compiler, it adds about 8 KB to your program binary. To get rid of this, you need to build your C files with the -fno-exceptions flag. The -fno-rtti flag is also said to be helpful, but in my one test, it didn't change the size of my executable. If you use the new and delete operators, you also need to link with libnoexcept: that's the -lnoexcept option on the linker command line. Obviously all this advice only applies if your program doesn't use exceptions or RTTI. Since there are real costs to using those mechanisms, I do suggest that you avoid them for Palm programming.

Another easy way to chew up a lot of space is to use templates. I've seen 50 KB binaries become 200 KB binaries when I moved from C style to C++-with-templates. This is tolerable on a "real computer" with 64 MB of memory and several gigabytes of hard disk space, but on a device with the Palm OS's limits, it's not something to take lightly.

A final warning is that polymorphism has drawbacks, too. The main way to do polymorphism in C++ is to new objects and then pass around base class pointers. Unfortunately, on all but the newest Palm devices, the dynamic memory heap is 36 KB or less, and that heap is also used by things like global variables. How many objects can you allocate in that tiny pool? Consider also the costs of vtables and virtual inheritance.

I no longer believe that you should completely avoid C++ for Palm programming, but at this point I'm strictly limiting myself to using the "C++ as a better C" subset of the language.

1.10 - What's a creator ID, why do I need one, and how do I get it?

Every Palm application needs to have a unique creator ID. This is a four byte number that's usually shown as a series of 4 characters. (e.g. unsigned long crid = 'xFoo';) This is what the Palm uses to determine which app is which. If two applications have the same creator ID, the second one hot-synched to the device will overwrite the first one.

To make sure that there are no conflicts, Palm Computing maintains an online database of creator IDs. It's your responsibility to check this database and add a unique ID for any Palm program you produce. I recommend that you do this for any Palm program, even if you don't plan to release it to the rest of the world.

1.11 - How do I create an icon for my program?

by Wade Hatler

The icon for a Palm app is a 22x22 pixel bitmap. You can actually use a 32x32 bitmap, but it gets clipped to the top-center 22x22 pixels. On all but the color Palm devices, the icon needs to be a 1-bit (black and white) image. On the color devices, you can use an 8-bit bitmap. You can also include one of each, and let the launcher pick the right one depending on the device's capabilities.

• All of the development systems except CodeWarrior use ordinary Windows bitmaps (BMP files) for icons. There are many BMP editors out there; Windows comes with a basic one called Paint, or you can get a shareware program that will be easier to use.
• Metrowerks Software's CodeWarrior has it's own resource editor, and its own resource format; there is no separate BMP file holding the icon image. You can either create your icon within Constructor, or you can cut and paste an image in from a regular paint program.
• If you're running under Unix/Linux you can get the Palm Icon Editor from Darrin Massena's Palm Development Tools and Articles page. The PRC-tools package also comes with txt2bitm, which takes a text file containing a 32x32 square of '-'s and '#'s, and makes a BMP file out of it. You can also get PPM2BMP which converts PPMs to a BMP file bitmaps and back. You can find a link to it and other Unix stuff at the Palm stuff from the ISAAC Group.

1.12 - How can I get detailed info on Palm OS device features?

There's a table at http://www.palmos.com/ with details on all the current Palm OS units, from both Palm and all its licensees:

http://www.palmos.com/dev/tech/hardware/compare.html

1.13 - Which SDK version should I use?

You should always use the latest SDK, even if you're programming for an older version of Palm OS. The SDK has changed quite a bit over the years, so you'll want to be familiar with the current version of the SDK. You can still program for older OS versions with the current SDK: you just have to avoid calling functions that only exist in new versions of the OS. The SDK Reference Manual has a section near the end called the Compatibility Guide which tells you what functions and such exist in various OS versions. It will also tell you where a "glue" library exists to let you call some newer functions while still running on older devices. These glue modules link in extra code which emulates the new mechanisms when necessary. A good example of this is the new internationalization features in OS 3.1; the glue library lets you use these features on OS 2.0 and OS 3.0 devices, at the expense of making your program larger.

The only reason to use an old SDK that I can think of is if you have some old code that was written for an old SDK, and that old code won't work with the current SDK. You might want to seriously consider updating the code so that it works with the current SDK, however.

1.14 - I'm trying to build a program and the compiler says it can't find the SysAll.h, Pilot.h, UI.h, etc. headers. How do I fix this?

This happens when trying to build code written for an older SDK with a newer SDK. Since it's better to go ahead and use the newer SDK, there is a complete guide at Palm's Developer Support site to converting a project from an older SDK to SDK 3.5.