Set up your Linux box as a Palm development platform and write your first application.

When I started my summer job a few months ago, I did not know one thing about Palm Pilots, Visors, WAP and all the other buzzwords used ever so frequently when talking about embedded systems and wireless gadgets. But when asked to join the development team, I was excited since it gave me an opportunity to prove that there is no better environment than a solid Linux box for software development.

A quick search on the web will reveal an astonishing amount of information and documentation on this topic. The Palm OS Platform Developer web site (www.palmos.com/dev), for example, is an excellent starting point. But after reading through some of the documents, you will want to actually do something. Thus, I will show how to install all the necessary tools to start writing your first application for the PalmPilot, with the assumptions that you know your way around a Linux system and can get superuser privileges for installing the necessary software. The procedures outlined in this article have been successful on at least two Linux Mandrake systems, one based on Red Hat 6.1, the other Red Hat 6.0.

The Palm OS Emulator

First, we need to set up our environment. You would think that the first thing to do would be to go out and buy one of these gadgets (unless, of course, you are already geeky enough to have this nifty device managing your entire life). But that's not necessary, at least not yet. It is much easier (not to mention cheaper) to download and install the Palm OS Emulator (POSE). The POSE does a decent job of emulating the operations of Palm Computing Platform hardware devices. With it, users can load ROM images, applications, and databases and use them on their desktop computers. This way, there is no need to synchronize your Palm every time you want to test the latest version of your program. Also, by using POSE you have access to all kinds of different devices, and can thus test your application on different platforms right from your desk.

Applications for the Palm OS are most commonly written in C, using a bunch of Palm-specific headers and libraries. These headers and libraries are part of the Palm OS SDK (Software Development Kit), which comes with the prc-tools.

In order to compile the programs you're going to write, you will need the prc-tools, a complete compiler tool chain for building Palm OS applications in C or C++. Additionally, you might want to install PilRC, a little tool to preview the layout of your applications before building them.

POSE for UNIX can be obtained from www.palmos.com/dev/tech/tools/emulator/emulator_src_30a6.tar.gz. However, in order to make sure that you get the most recent version of POSE it is a good idea to go to www.palmos.com/dev/tech/tools/emulator and read carefully through the page and the relevant links.

Once you download the archive, place it in a convenient location and extract it. I usually extract new archives into /tmp/

 mv emulator_src_30a6.tar.gz /tmp
 cd /tmp
 tar zxvf emulator_src_30a6.tar.gz

or, if your system does not have GNU tar installed:

 gzip -cd emulator_src_30a6.tar.gz | tar xvf -

Before building the emulator, we will need to satisfy a few requirements. We use pthreads, so you need GNU glibc2 (a.k.a. Linux libc6) C library and a 2.x kernel on a Linux system. Other operating systems need to support true threads. The source makes heavy use of C++ templates and exceptions. On Linux, you must have egcs-1.1.1 or better to compile it. egcs-1.1 or any gcc below 2.95 may not work. Red Hat Linux 6.0 comes with egcs 1.1.2, so you should be okay there. If you are running Red Hat Linux 5.2, you will need to download the latest from gcc.gnu.org and build it. For other OS's, either use egcs, or be sure your compiler supports these C++ features. (from Emulator_Src_3.0a6/Docs/_Building.txt)

Furthermore, POSE uses the FLTK X toolkit–you will need to download and install it before you attempt to build POSE on your system. The FLTK X toolkit is available from www.fltk.org, but if you happen to be on a Red Hat Linux system, you might consider downloading the RPM from rpmfind.doc.ic.ac.uk/fltk.html or your favorite RPM-mirror and install it (as root):

 rpm -i fltk-x.x/rpm

To install FLTK X toolkit from sources, download the fltk-x.x archive from www.fltk.org, put it in a convenient location and extract it:

 mv fltk-1.0.9-source.tar.gz /tmp
 cd /tmp
 tar zxvf fltk-1.0.9-source.tar.gz

or

 gzip -dc fltk-1.0.9-source.tar.gz | tar xvf -

Change to the FLTK directory and check the README: “FLTK is available under the terms of the GNU Library General Public License. Contrary to popular belief, it can be used in commercial software.” (Even Bill Gates could use it.)

To build and install the FLTK issue the following commands:

 ./configure
 make
 su
 make install

Should any of the above give you errors, then you need to verify that you have the required tools to build FLTK, such as gcc and make, both available from www.gnu.org.

After installing the FLTK, you need to finish the POSE install. Go to /tmp/Emulator_Src_3.0a6/BuildUnix/ and issue the following commands:

 ./configure
 make
 su
 make install

Again, if you get an error here, go back and make sure that you have met all the requirements. Please note that the install script of FLTK places fluid per default into /usr/local/bin, so that if you compile POSE as root, you might get an error that fluid was not found. This should be a reminder that you are not supposed to be root at this point in time anyway.

Assuming everything went according to plan, you can now start POSE by simply issuing the command pose, and a window will open on your desktop, showing you a Palm Device. Neat. But this doesn't get us very far yet–in order for POSE to actually work, and in order for you to use POSE to actually emulate a Palm device, you need a ROM image. The ROM image contains all of the code used for a specific version of the Palm OS. You can obtain ROM images in three ways:

1. Follow the procedure as described under www.palmos.com/dev/tech/tools/emulator.
2. Download the ROM from a handheld that has been placed in the device cradle and connected to the desktop computer.
3. Have somebody send you a ROM image.

In order to download a ROM image file from a device, start up POSE and right-click anywhere in the window. A menu will pop up from which you can select File -> Transfer ROM. This assumes, of course, that you have set up your system to talk to the cradle. For information on how to set up your Palm device under Linux, refer to www.orbits.com/Palm/PalmOS-HOWTO.html.

While it is certainly easy to get the file from somebody else, or to transfer it from your Palm device, I still recommend joining the Palm Solution Provider Program as described under www.palmos.com/dev/tech/tools/emulator, since you will gain access to a large variety of different ROM images. When downloading ROM images from the Palm web site, you are offered to download either Windows or Mac format. Simply download the Windows format, which is just a zipped archive. You can extract the ROM image by issuing the following command:

 unzip imagename.zip

At this point I recommend that you set up a directory where you keep all your Palm-related material. The default directory for this should be /usr/local/palmdev, where I created a subdirectory called roms. Place the ROM image files into this directory so you don't lose them. Now start POSE and right click anywhere in the window. Select File -- >New from the menu and choose the location of the ROM file and the appropriate device. For example, if you want to use the ROM image palmvii-dbg-75.rom, you must choose “Palm VII” from the device menu. (Choosing an invalid combination will lead to an error message.) Voila! Now go and play around with your new Palm device.

Obtaining and Installing the prc-tools

The prc-tools needed to compile your programs into Palm native code can be obtained from www.palmos.com/dev/tech/tools/gcc either as a precompiled binary or as a source tarball.

At this point, the excellent documentation provided by Palm starts to get a little confusing, unless you are installing from RPM. If you are installing prc-tools from RPM, you have to keep in mind that, at the time of this writing, the prc-tools RPM contains an earlier SDK. Significant changes have taken place in the development of version 3.5 of the SDK, which might lead to compatibility problems with the examples mentioned here. From now on, it is assumed that you are installing the SDK 3.5 with prc-tools-2.0. If you can't or don't want to install from RPM, you need to download the SDK and the prc-tools and read through their documentation simultaneously, as one depends on the other. After downloading the source for the prc-tools, extract them as usual into a convenient location and read through the README and BUILDING.html files. You will find that by convention, prc-tools looks for SDKs in /usr/local/palmdev. These documents also explain how you can keep different copies of the Palm OS SDK. We will skip this step for now, as we want to get things going. So now would be a good time to create the necessary directory:

 su
 mkdir /usr/local/palmdev/sdk-3.5
 mkdir /usr/local/palmdev/sdk-3.5/lib
 mkdir /usr/local/palmdev/sdk-3.5/include

For convenience, we will also create a symbolic link:

 cd /usr/local/palmdev
 ln -s sdk-3.5 sdk

The Palm OS Software Development Kit 3.5 can be obtained for free from www.palmos.com/dev/tech/tools/sdk35.cgi. As before, place the archive into a convenient location and extract it:

 mv sdk35.tar.gz /tmp
 cd /tmp
 tar zxvf sdk35.tar.gz

or

 gzip -dc sdk35.tar.gz | tar xvf -

Then change into the newly created directory and issue the following commands:

 su
 cp GCC Libraries/m68k-palmos-coff/* /usr/local/palmdev/sdk/lib
 cp -R Incs/* /usr/local/palmdev/sdk/include

Additionally you might want to download a few programming examples and some documentation from Palm's Developers web site and place them in /usr/local/palmdev/examples and /usr/local/palmdev/docs.

Next you need to install the prc-tools. The actual installation of the prc-tools is somewhat more complicated than the regular ./configure; make; make installprocedure. You will find detailed instructions on building the tools in /tmp/prc-tools-2.0/BUILDING.html. The installation of the prc-tools from source consists of downloading and patching of binutils-2.9.1, gdb-4.18 and gcc-2.95.2. It is important that you follow these instructions exactly, downloading the required version, as otherwise the patches might not work. Then you will need to configure these tools as specified by the manual (Note: on my system it was necessary to specify --with-build-sdk3D3.5 in addition to the other options when configuring–otherwise the system would have configured the tools for the SDK Version 2.0) and finally build these tools and the prc-tools in a predefined order. As usual, I started to build the tools without reading carefully through the documentation, failed, tried to fix it myself, failed again and finally did read the manual, followed it and succeeded. Save yourself some time and frustration–read the manual first and then follow it.

You will also need to download and install PilRC. PilRC is an application that takes a resource script file and generates one or more binary resource files that are to be used when developing an application. PilRCUI gives you a preview of your resource file, thus enabling you to design the user-interface without having to build the entire application again and again.

PilRC is available as source-code from www.ardiri.com or, again, if you prefer, from rpmfind.net (or your favorite mirror). Follow the standard procedure for extracting the archive. To build and install PilRC, go into the root directory of the distribution and issue the following commands:

 ./configure
 make
 su
 make install

Running Your First Program

Okay, so we've installed a whole bunch of new packages and/or updated a few. Before we go on and start writing our first real application, you should test to see if everything works as we expect. To do so, I recommend you try to either build the ubiquitous “Hello World” (as described at www.netmeister.org/palm/POSE/POSE-HOWTO.html #5) example, or one of the examples you downloaded earlier. If you choose to build “Hello, World”, please note that the POSE-HOWTO assumes you have installed prc-tools-0.5.0 and that we use prc-tools-2.0, meaning you will want to change the makefile accordingly. Furthermore you will need to make the following changes to the source code of “Hello, World”:

 #include 
 #include 

are to be substituted with

 #include 

and

 DWord PilotMain(Word cmd, Ptr cmdPBP, Word launchFlags)

becomes

 UInt32 PilotMain (UInt16 cmd, MemPtr cmdPBP, UInt16 launchFlags)

After making these changes you can compile and link the program with the following commands:

 m68k-palmos-gcc -O2 -g hello.c -o hello
 m68k-palmos-obj-res hello
 build-prc hello.prc "Hello, World" WRLD *.hello.grc

If all goes well and you don't get any error messages you can now install this new application on your POSE.

Start pose and right click anywhere on the window. Then select File - >Install Application/Database from the menu. Search through the directories to find our little application hello.prc. Now tap (palmspeak for click) the Applications icon and you should see a new icon labeled “Hello, World”. (Note: if you already were in the applicationsmenu (i.e., all the application icons were displayed on your screen), you need to switch to another screen (for example, tap “calculator”) and switch back — tap “Applications” — for the new icon to show.) Tap this icon and…Success! You will see the words “Hello, World!” displayed in your POSE-window.

One of the good things about POSE is that you can save as many profiles as you want, thus enabling you to save the newly installed application. To do so, right click on the window and choose File - >Save as... Choose a directory and enter the name for this profile. (POSE usually saves profiles with a .psf ending.) The next time you start POSE, you can choose File - >Open from the menu and load this profile, and you will find your “Hello, World” application right where it was.

If you get tired of Hello, World — after all, it does not do anything — you can delete the application from POSE by tapping the “Menu” button and choosing “Delete”. (If you want to get fancy, you can try to invoke the command by drawing a diagonal line followed by a “D” with your mouse in the little “Graffiti” area). Choose “Hello, World” and select “Delete”. Confirm with “Yes” and go back to the main screen with “Done”.

Where to Go from Here

Now that you have installed all the tools, headers, libraries, documentation and examples, you are quite well prepared to start developing your own applications. But before doing so, I recommend you take a look at the examples, building and installing them on the POSE to get a general idea of how the environment works. Outlining the steps when developing a new application from the start would go beyond the scope of this article, but you can find a lot of good documentation in your /usr/local/palmdev/doc and on the web. You will find that your Linux system now is ideal for developing software for the Palm OS. So go ahead and code, code, code.

Resources

---

About the author: Jan Schaumann ([email protected]) was born in Iserlohn, Germany. He grew up in Altena, Germany and studied for two years towards a masters in “Modern German Literature and Media” and “American Studies” in Marburg, Germany. He moved to New York City in Summer 1998. Due to the differences in educational systems between Germany and the US he was forced to go to college here instead of Grad School — they wouldn't accept the German equivalent to a BA.

---

Copyright © 2001 Specialized Systems Consultants, Inc. All rights reserved. Embedded Linux Journal Online is a cooperative project of Embedded Linux Journal and LinuxDevices.com.

 
This article was originally published on LinuxDevices.com and has been donated to the open source community by QuinStreet Inc. Please visit LinuxToday.com for up-to-date news and articles about Linux and open source.