1-by-1 black pixel for creating lines
1-by-1 black pixel for creating lines
EricGiguere.com > Books > Palm Database Programming > Chapter 3
Printer-friendly version Set your preferences
Read my blogs on AdSense and affiliate marketing
Learn about these ads

Palm Database Programming — The Electronic Version

Chapter 3: Development Tools and Software Development Kits

This material was published in 1999. See the free Palm OS Programming online course I developed for CodeWarriorU for some updated material.

Prev Chapter | Prev Section | Next Section | Contents

GCC and the GNU Tools

The second C/C++ development tool is GCC, part of a collection of free tools collectively known as the GNU tools (GNU stands for "GNU's not Unix"). Unlike CodeWarrior, the GNU tools are not officially supported by Palm Computing, and you may find that third-party tools and libraries may not support them either. For example, the Sybase UltraLite deployment technology that we' talk about later in this book only supports CodeWarrior. The GNU tools are command-line based and don't come with a built-in integrated graphical user interface, either, although there are a couple of shareware IDEs that provide you with one. On the other hand, the GNU tools are currently the only way to do Palm development using the Unix/Linux platform. They're also a great way to explore Palm programming for free! The GNU tools can be downloaded from several sites and are also on the book's CD-ROM, in the GNU Tools folder.

The set of GNU tools for the Palm Computing platform is referred to as the prc-tools release. The current version of prc-tools is 0.5.0 and includes support for writing Palm OS 2.0 applications. To write Palm OS 3.0 applications, you'll have to download the latest Palm OS SDK from the Palm Computing Web site and install its files into the prc-tools directory.

What Are the GNU Tools?

The GNU tools are free development tools distributed under the terms of the GNU General Public License. Any program covered by the license must be distributed for free (apart from nominal copying charges, if any) with source code. Any modifications you make to such a program also fall under the terms of the license. A copy of the license is included with the GNU tools and is also available for reading online at the Free Software Foundation's Web site, www.fsf.org. Note that you can use the GNU tools to build programs that are not covered by the GNU Public License. Be sure to read both the GNU Public License and its sibling the GNU Library Public License before using any of the GNU tools or libraries.

The GNU project started in 1984 is one of the first serious attempts at open source code programming. The GNU project's goal is to develop a Unix-compatible software system that is freely available to anyone. The GNU tools in the prc-tools distribution are modified versions designed to build Palm Computing platform applications. The tools run on a number of platforms, including Windows and Linux, and the source is available for porting to any platform you desire, of course.

The GNU tools in the prc-tools distribution include the GCC C/C++ compiler and linker, the GDB line-oriented debugger, the PilRC resource compiler for creating resources from text files, a tool for converting object files into Palm resources, and the build-prc tool for combining all the resources into a Palm executable. The distribution also includes other tools you may find useful, such as a make tool for building projects. The documentation is quite light when compared to all the material available that covers development with CodeWarrior, so be sure to read the tutorial that is included with the pilrc-tools distribution.

Windows users can install the GNU tools using the installation program provided on the CD-ROM.

Starting and Building a Project

If you've only used IDEs like CodeWarrior or Microsoft Visual C++, the GNU tools will seem quite primitive. The tools have no graphical user interface, they're just invoked from the command line of a DOS prompt (Windows) or a shell (Unix/Linux). Make sure that the bin directory is in your search path so that the tools can be found.

In CodeWarrior, a project is a collection of files that are used to build a Palm application, together with the settings for compiling, linking, and processing those files into resources. With the GNU tools this is accomplished using a makefile. A makefile is a text file that is read by the make tool. It lists the series of commands necessary to build an application, such as compiling individual C/C++ files into object files. It also defines the dependencies between various files, so that if one file depends on a second file, changing the second file causes the first file to be rebuilt. Make uses these dependencies to determine the minimal set of operations that will create the application. If no files have changed, nothing is done. If only one C file has changed, then only it is compiled, not the others. A makefile isn't necessary to build an application, but the dependency checking is something a simple batch file or shell script can't easily do and it can save you time when working with large projects.

The easiest way to start a new project with the GNU tools is to simply clone an existing application and modify it. This is very similar to using project stationery in CodeWarrior. On the CD-ROM you'll find the skeleton for a Palm application, GNUSample, in the Samples directory. Create a new directory on your disk and copy the files from the GNUSample directory into it. Although there's a makefile, let's ignore it for now and build the various pieces by hand to understand how applications are created with the GNU tools.

The first step is to compile the two C files in the sample with the GCC compiler. You can do this with the following commands:

m68k-palmos-coff-gcc -O1 -c main.c -o main.o
m68k-palmos-coff-gcc -O1 -c other.c -o other.o

This compiles the main.c and other.c files to produce the main.o and other.o object files. If you had other C or C++ files to compile, you would compile each in a similar fashion. C files should have a .c extension, C++ files a .cc or .cpp extension. The -O1 option tells GCC to optimize the code.

A quick note about the tool names. Some of the GNU tools are unique to the pilrc-tools distribution and these have simple names like pilrc or build-prc. Other tools are common to several different platforms and have longer names. In this case the name m68k-palmos-coff-gcc refers to the version of GCC that generates Motorola 68000 code for the Palm Computing platform and uses the COFF format for object files and executables.

After compiling the files you should link them into an executable with the following command:

m68k-palmos-coff-gcc -O1 main.o other.o -o GNUSample.tmp

The object files from the previous step are combined with any library functions to form a COFF executable called GNUSample.tmp. This executable is not a Palm application, however, which is why we didn't call it GNUSample.prc. The executable must be converted into a set of resources that are later combined to form a Palm database:

m68k-palmos-coff-obj-res GNUSample.tmp

This produces a set of files with .grc extensions, each of which represents an individual code or data resource in the application database. The next step is to use the pilrc tool to convert the static user interface elements (discussed in the next chapter) defined in GNUSample.rcp into resources:

pilrc GNUSample.rcp

This produces a set of files with .bin extensions, one for each user interface element. These are combined with the code and data resources from the previous step to form a Palm application:

build-prc GNUSample.prc "GNU Sample" ERIC *.bin *.grc

The arguments to the build-prc tool are the name of the generated executable, the name of the application, the creator ID, and the set of resource files that combine to form the application. (The application icon is not one of the arguments, it's a static user interface element defined in the .rcp file we ran through pilrc.) The final .prc file can be installed and run on your Palm device or the Palm OS Emulator.

TIP: If when you link the COFF executable you get the message "relocation truncated to fit: DISP 16 funcname" that's usually GCC's obscure way of telling you it couldn't find the function funcname, which will occur if you've misspelled the function name. It can also occur, however, when one function calls another function and more than 32K of code sits between them  see the following section on building multisegment applications.

Unless you're a very skilled typist, you won't want to type all those commands every time you want to build a project. The sample project includes a makefile that performs these steps for you. To build the project you would simply type the following:

make GNUSample.prc

or even just:


If you add, remove, or rename files you'll have to modify the makefile appropriately. Read the comments in the file for instructions on how to do this.

Debugging with GDB

If your program crashes, you'll want to debug it. With the GNU tools this means using the GDB debugger. Unlike the CodeWarrior debugger, GDB does not have a graphical user interface, but instead responds to text commands that you type at the GDB command prompt. GDB does integrate somewhat with the Emacs text editor that comes with the GNU tools, however, so if you're an Emacs fan be sure to read through the tutorial that accompanies the pilrc-tools distribution for instructions on how to integrate the two.

Applications that are to be debugged must be compiled and linked with the -g option to gcc, as in:

m68k-palmos-coff-gcc -g -dDEBUG -c main.c -o main.o
m68k-palmos-coff-gcc -g -dDEBUG -c other.c -o other.o
m68k-palmos-coff-gcc -g main.o other.o -o GNUSample.tmp

For best results, turn off all optimizations when compiling the debugging version of your application.

To debug with GDB under Windows you' need to use the Palm OS Emulator and a freeware tool called gdbplug, which acts as a relay between GDB and the Emulator. Start the Emulator as discussed later in this chapter and load the application you just built. If the Emulator was launched by CodeWarrior, shut it and CodeWarrior down and start the Emulator separately  CodeWarrior will interfere with the debugging process otherwise. Now run the gdbplug application from a second DOS window:

gdbplug -port 2000 -enable

The relay opens a TCP/IP port that GDB will communicate with, so be sure to specify a port number that does not conflict with one already in use by another application. Once gdbplug is running, return to the main DOS window and start GDB with the COFF executable (not the final .prc file) as an argument:

m68k-palmos-coff-gdb GNUSample.tmp

After GDB starts you need to connect it to the gdbplug relay. Type the following command at the GDB prompt:

target pilot localhost:2000

Substitute the TCP/IP port you specified when you started gdbplug if it's different than 2000. At this point you should see a message that says remote debugging of the Palm OS Emulator is underway. Return to the Emulator and start your application. The application is stopped immediately by GDB, which prompts you for a command. Type the following:


This lists the complete set of commands that GDB supports. You can step in and over functions, set breakpoints, print the call stack, and so on. It's not as convenient or as simple to use as the CodeWarrior debugger, but it gets the job done.

Prev Chapter | Prev Section | Next Section | Contents

Copyright ©1999 by Eric Giguere. All rights reserved. From Palm Database Programming: The Complete Developer's Guide. Reprinted here with permission from the publisher. Please see the copyright and disclaimer notices for more details.

If you find the material useful, consider buying one of my books, linking to this site from your own site or in your weblog, or sending me a note.

Google Web www.ericgiguere.com   
1-by-1 black pixel for creating lines
Copyright ©2003-2012 Eric Giguere | Send mail about this page | About this site | Privacy policy
Site design and programming by Eric Giguere | Hosting by KGB Internet Solutions
This site is Java-powered
Other sites: The Unofficial AdSense Blog | Google Suggest Explorer | Invisible Fence Guide | Synclastic
This page was last modified on November 23, 2003
1-by-1 black pixel for creating lines
1-by-1 black pixel for creating lines