Poplar ProductivityWare Articles:
Getting Started with Palm OS Development Using PRC-Tools on Windows
by Jennifer Hodgdon

Introduction

This article is a tutorial guide to getting started developing applications in the C programming language, for handheld devices running Palm OS, using PRC-Tools, on a Windows-based PC. It's written from the perspective of someone who learned C in the 80's, has developed software on both Unix-family and Windows-family computers since then, and uses a Palm OS-based handheld; I've left out most details that I thought were not necessary for someone with a similar background. Also, there is a lot of information on the Web on how to develop Palm OS-based applications. Where possible, I have linked to those sources; what I am trying to do here is to fill in the cracks, by recording what I learned from trial and error, that I didn't think was covered very completely in existing Web sources.

It is assumed here that you have already decided to use PRC-Tools -- probably because of a similar background to mine. I wouldn't recommend that someone who is completely unfamiliar with C or the Unix-family development tools (in Gnu incarnations: gcc, make, gdb, etc.) embark on PRC-Tools. And anyone who has decided to develop Palm OS software might want to visit the official Palm OS development page at Access first, click on Documentation, then choose the Garnet OS platform, and start reading. One recommended resource is the Development Tools Guide, in the Development Tools section. You might also want to check out the Palm Developer Network pages.

Note: Some of this article may be out of date, as I am not doing much Palm development lately... in particular, the ownership of the companies that make Palm OS has been in flux, so the resources mentioned may not be where they used to be. Sorry!

Here's my take on the advantages of PRC-Tools:

• It's free software (the price is right).
• As compared to some Basic-based environments, the applications run faster.
• You have complete flexibility -- some Basic-based environments have limitations on what you can do.
• As compared to many other development tools, the applications are more compact.
• As compared to some Basic and Java-type environments, the application user doesn't have to download an additional run-time library, which saves space.

And the disadvantages:

• Many of the sample programs you'll find on web sites, and much of the older knowledge base available from Access (the current name of the company that makes Palm OS), is oriented towards CodeWarrior. The newer code samples may be oriented towards an Eclipse-based development environment called the "Developer Suite". You can probably adapt the code, though -- the main difference will be in how the user interface is specified.
• PRC-Tools does not have an interactive development environment (IDE), so you have to be familiar with Unix-family command-line tools, and happy to use a text editor to make your application's user interface.

---

Tools and Set-Up

Cygwin and PRC-Tools

In order to use PRC-Tools on Windows, you will first need to install Cygwin (a Unix-like environment for Windows), and the PRC-Tools enhancements to it. The PRC-Tools Windows Installation Page explains how; you should probably at least skim through that page as background information. Here is my version of installation instructions:

1. Visit the Cygwin home page, and click on one of its many "Install Cygwin Now" links. This will start a setup.exe program running. Use the default settings, except:
   • Choose "Install from Internet", when you get to that screen.
   • Choose "C:\PalmDev" as your root directory. You can also install Cygwin in C:\Cygwin, and then put the Palm-specific tools into PalmDev, but I think it's simpler to just put it all in one place, unless you are planning to do a lot of other gcc development with Cygwin.
   • On the "Choose a download site" screen, choose an appropriate nearby site from the list, and then add an additional download site of
     http://prc-tools.sourceforge.net/install
     to the list.
   • After a few moments, you will reach the Select Packages screen. Browse the list and see if there are any tools you want to have (e.g., grep, awk, etc.). To run PRC-Tools, you will also need/want the binaries (but not the source) for:
     • Whatever defaults setup.exe chooses
     • "Base" section: prc-tools (or this may be just in the "Devel" section)
     • "Devel" section: binutils, gcc (you only need the C compiler), gdb, make, prc-tools, and pilrc
     • "Doc" section: cygwin-doc, man
     • "Editors" section: if you don't have one already, you might consider choosing your favorite text editor from this section. However, you can just use any text editor you already have installed in Windows, if you want.
     • "System" section: man
     • "Text" section: less
2. When the installation is done, you need to open a Cygwin window, and mount C:\PalmDev as /PalmDev, by running the following command:
   mount -tf "C:\PalmDev" /PalmDev
3. After you've downloaded the Palm SDK (see the Downloads from Palm/Access section below), you will also need to run the palmdev-prep utility from the Cygwin prompt.

If your installation fails, try again -- setup.exe should pick up where it left off. If you're having trouble downloading, you might try a different mirror for the main part of Cygwin. If the problem is in downloading PRC-Tools, you might try this instead (I recently had this problem, and used the steps below to complete the install):

1. Run the Cygwin installation until it fails. This should leave an installation file folder, in the location you specified, with a lot of percent signs and "prc-tools.sourceforge.net" in the folder name. It should also have two subfolders: pilrc and prc-tools. Don't delete this yet.
2. Run Cygwin installation again, but leave out the prc-tools packages and the special prc-tools download site. It should run to completion (if not, try a different download site).
3. Visit the PRC-Tools downloads page, and download the latest versions of prc-tools, prc-tools-arm, and prc-tools-htmldocs. Make sure to get the files with "cygwin" in the name, and "bz2" extension. Save all three files into the prc-tools subfolder.
4. Visit the pilrc downloads page, and download the latest version of pilrc (cygwin/bz2 versions of files) to the pilrc subfolder.
5. Start up the Cygwin setup.exe program again. Tell it to install from a local installation, and point it to the installation folder where you just saved the files. Select all 4 packages, and run the installation.

Downloads from Palm/Access

Once you have installed Cygwin and PRC-Tools, you will need to visit the Palm OS (Garnet) Developers site at Access and get some additional downloads [Note: these will be under "Garnet OS" sections of the site]:

• Register as a developer: You may need to do this in order to (see below) download the SDK, to download ROMs to use with the Emulator, and to register Creator IDs for your programs. It may take some time to be approved, so get this started now, and when you can, go ahead and download the items you need. To register, click on the Register link on the Palm OS Developers site. After that, you'll need to log in.
• The Core Palm OS SDK: You should get the latest version, and you'll find it in the login section of the Palm OS Developers site at Access. Access offers this in several packages. My experience was that the Windows Installer version did not work -- it was set up for use with CodeWarrior. Instead, I suggest you find the tar or zip archive that states it contains the SDK header files and static libraries and is suitable for a Unix-like OS (Cygwin is sufficiently Unix-like!). Download this, and unzip/untar so that there is a directory under C:\PalmDev whose name starts with "sdk", that has under it an "include" and a "lib" directory.
• Documentation: You will probably want to download "Palm OS Companion and Reference" (both the Companion and the SDK reference), to your PC. You can read them on the Internet, but it's better to have your own PDF copies. These are available from the Documentation section of the Palm OS Developers site (under SDK documentation). You may also want to skim through some other documentation while you're there, or at least bookmark the page for later reading.
• Simulator and Emulator: these are two programs for testing your Palm application on the PC. They are somewhat similar, but the Emulator is for older Palm OS versions, and the Simulator is for newer ones. You might as well get both, in debug versions; they are available from the login section of the Palm OS Developers site, and you just download them to a directory that you can find again (such as C:\PalmDev\Emulator and C:\PalmDev\Simulator). In order to use the Emulator, you will also need a Palm OS ROM. If you own a Palm, you may be able to download the ROM from it, but (a) this doesn't work for all Palm devices, and (b) you may want to test your application on different versions of the operating system. Read on...

---

Creating Applications

Hello World

On the very useful TWiki FAQ for Palm development, there is a "Hello World" program in the "Example Code" section. We'll use this program as a starting point for creating our first Palm application. Here are the steps you will need to take:

1. Download and extract the Hello World code to its own directory, under C:\PalmDev.
2. In the Makefile that comes with the sample code, remove the "-palmos3.5" flag from the CFLAGS line -- assuming you have run palmdev-prep (see the Cygwin installation section above), the C compiler will automatically detect the SDK you have installed.
3. Open a Cygwin window, and change to the directory where you put the files.
4. At the Cygwin prompt, type "make". This should make "hello.prc"
5. Start the Emulator or Simulator program. To run the Simulator, just double-click Simulator.exe (from Windows explorer), wherever you downloaded it. To run the Emulator, double-click on the ROM file whose version you want to use for testing.
6. After the initialization sequence for Emulator/Simulator is done (you should end up on the Preferences screen), right-click on the Emulator/Simulator window, and choose Install. Find the "hello.prc" file you just made, and install it.
7. You should now have "Hello!" somewhere in the Applications list on the Emulator/Simulator's Palm OS screen (you may need to click Applications a few times to make the list refresh, and/or find the category it's in). Click on its icon to run it. You should see a short Hello message on the screen. Click the Menu button, and choose the About menu item, to see an informational message.
8. To close the application, click Applications and choose another application. At this point, if you were running your own application that had a memory leak or other shut-down issue, you would see a warning message.
9. If you would like to run Hello World with the gdb debugger, use the following steps (this assumes that you have compiled and linked it with the -g debug flag):
   1. Start the Emulator (I haven't had any success doing this with the Simulator v. 5.0, so I just use the Emulator).
   2. At the Cygwin command prompt, type in the command:
      m68k-palmos-gdb.exe hello
   3. At the gdb prompt, type target pilot
   4. In the Emulator, load and start the "Hello!" application (see instructions above on how to load applications in the Emulator). Note that you can leave the Emulator running, and enter/exit gdb at will.
   5. gdb should automatically stop in PilotMain whenever you start the "Hello!" application. You can now set breakpoints, examine variables, etc. In addition, if the Emulator detects a problem while you are debugging a program, it puts up a dialog box that will allow you to choose a "debug" option, which will break into gdb at the point where the problem occurred.

Your Next Application

When you are ready to start your next application, here are some random hints and resources:

• Starting Point: Obviously, you can use the Hello World application as a starting point -- it contains program code (hello.c), a user interface resource file (hello.rcp), a resource include file (resource.h) that is used by both, and a Makefile. I would also strongly suggest reading (or at least skimming) through the relevant sections of the Palm OS Companion (see the Downloads from Palm/Access section above), in order to understand the main Palm programming concepts and considerations.
• General Information Sources: My favorite places to go for information are as follows:
  • The official "Palm OS Companion and Reference" files (see the Downloads from Palm/Access section above)
  • The TWiki FAQ for Palm development
  • There is also quite a bit of additional information, including a knowledge base and sample code, on the Palm development page
  • The O'Reilly book "Palm Programming: The Developer's Guide", by Rhodes and McKeehan. .
  • For information specific to PRC-Tools, including instructions on creating multi-segment code, visit the PRC-Tools documentation page.
• User Interface: User interfaces for PRC-Tools development are made by creating input files for PilRC; the very thorough manual that comes with PilRC should be consulted for details. If you cannot find the manual, you may need to revisit the PilRC downloads page (see above), get another archive, and specifically put the documentation files in it somewhere you can find again.
• Persistence Expectation: Palm users expect to be able to be working in one application, switch to another, and have the first application come back just where they left it when they come back. Unfortunately, this capability is not built into Palm OS -- you have to put it into your application yourself. Basically, this involves storing the current program state in a database you create for your application, and restoring the stored state when the application starts up.
• Creator ID: Each application you create should have a unique Creator ID, which is a 4-character code. All persistence and other data your application stores should be stored in databases with that same Creator ID. You can register your own unique codes for your applications on the Palm OS development page, after you register as a developer with them (see the Downloads from Palm/Access section above). Once you do that, your Creator ID is an argument to the build-prc step in the Makefile (if you use the Hello World Makefile as an example, it is the APID define). It should also be defined in your resource file, in the Application section.
• Testing Beaming: If you want to test the beaming functions of an application, but you only have one Palm device, you can use the Simulator. Basic steps:
  1. Start the Simulator.
  2. In the right-click menu, find "Communications", in the "Settings" menu, and open the "Communication Ports" screen. Edit the Infrared setting, setting it to TCP/IP. The Simulator should choose a port for you -- make sure it is set to something.
  3. Start up another Simulator window, so you have two totally separate instances running. Verify that the second Simulator has the same Infrared settings.
  4. Install the application doing the beaming on one Simulator, and any applications needed to receive the beam on the other Simulator. Use the Preferences application to enable Beam Receive on the receiving Simulator (just as you would on an actual Palm device).
  Now, if you invoke the beaming function in one instance of the Simulator, it should simulate beaming to the other running Simulator.

---