Using Linux to Develop Software for the Palm OS Jan Schaumann Abstract Abstract: This article shows you how to set up your Linux box for Palm development and how to write your first application. It is assumed that you know your way around a Linux-system and can get superuser privileges for installing the necessary software. 1 Introduction 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" website (http://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. The procedures outlined in this document have been successful on at least two Linux Mandrake systems, one running RH 6.1, the other RH 6.0. 2 The Palm OS Emulator Before getting into the details of the design and code for an application, 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 manage 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 (short 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 synch 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 http://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 http://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. Most likely you're good to go, but just in case: ``We use pthreads, so you need GNU glibc2 (aka 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. RedHat Linux 6.0 comes with egcs 1.1.2, so you should be OK there. If you are running RedHat Linux 5.2, you will need to download the latest from http://egcs.cygnus.com 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 http://www.fltk.org, but if you happen to be on a RedHat Linux system, you might consider downloading the RPM from http://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 http://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.)" - Phew! 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 check if you have the required tools to build FLTK, such as gcc and make, both available from http://www.gnu.org. After installing the FLTK, you need to finish the POSE install. Go into /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 several ways: * follow the procedure as described under http://www.palmos.com/dev/tech/tools/emulator/ * download the ROM from a handheld that has been placed in the device cradle and connected to the desktop computer * 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 etc. For information on how to set up your Palm device under Linux, refer to http://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 http://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-website, you are offered to download either Windows or Mac format. Simply download the Windows-format--it's 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 file 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. 3 Obtaining and Installing the prc-tools The prc-tools needed to compile your programs into palm-native code can be obtained from http://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 as of 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. You will find that by convention, prc-tools looks for SDKs in /usr/local/palmdev on Unix. 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 http://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 website 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 install" procedure. 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-sdk=3D3.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 http://www.ardiri.com/, or, again, if you prefer, from http://rpmfind.doc.ic.ac.uk/pilrc.html (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 Ok, 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 under http://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 a few changes to the source code of "Hello, World": #include <System/SysAll.h> #include <UI/UIAll.h> are to be substituted with #include <PalmOS.h> 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 applications-menu [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 hit "Delete". Confirm with "Yes" and go back to the main screen with "Done". 4 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, try to build and install 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 document, 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... 5 Resources * ``Programming Palm OS in a Nutshell'' - http://www.palmos.com/dev/tech/docs/palmos/Nutshell.html * ``Palm OS Platform Developers'' - http://www.palmos.com/dev/ * ``The Palm OS Emulator HOWTO'' - http://www.netmeister.org/palm/POSE-HOWTO.html * ``The Palm OS Desktop HOWTO'' - http://www.orbits.com/Palm/PalmOS-HOWTO.html * the documentation which comes with the POSE