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 |
The official C/C++ development tool for the Palm Computing platform
is CodeWarrior for Palm Computing platform, a commercial product.
Although developed by Metrowerks, CodeWarrior for Palm Computing
platform is now sold and supported exclusively by Palm Computing. As
the official platform, you can expect more support for it than any
other development tool. The current version of CodeWarrior at the time
of writing is Release 5 and includes support for writing Palm OS 3.0
applications. Release 5 is required to run the CodeWarrior samples on
In this section we'll explore the basics of how to build and debug
applications with CodeWarrior. For more details on CodeWarrior,
consult the documentation that comes with the product. You can also
download a Palm programming tutorial from the Palm Computing Web site
that also doubles as an introduction to CodeWarrior.
The Origins of CodeWarrior
CodeWarrior is actually a family of development tools from
Metrowerks. Originally a C/C++ compiler for Macintosh development,
CodeWarrior can now also run on Microsoft Windows and generate code
for a number of platforms and processors, including the Motorola 68000
series, the Intel 80x86 series, and embedded systems such as the Sony
PlayStation. On some platforms, the CodeWarrior family supports
programming in Java and Pascal as well as C/C++.
CodeWarrior for Palm Computing platform includes a C/C++ compiler,
the CodeWarrior integrated development environment (IDE), a Motorola
68000 code generator, and other related tools. Also included are the
Palm OS header files and a version of the Palm OS Emulator. In short,
everything you need to write C or C++ for the Palm Computing platform.
Although it runs on Windows, CodeWarrior was first developed for
and on the Macintosh, so it doesn't always follow Windows user
interface guidelines. For example, a CodeWarrior message box looks
like Figure 3.1. These differences are mostly annoyances, although
references in the documentation to Macintosh-only tools such as
ResEdit can sometimes be confusing. Macintosh programmers will feel
right at home on either platform.
Figure 3.1 A Macintosh-like CodeWarrior dialog.
A Note for Windows Users
The Macintosh user interface model uses an approach similar to the
multiple document interface (MDI) in Windows. In MDI, the child
windows are contained in a parent window and share the parent's
menubar. On the Macintosh windows do not have their own menubars,
instead they all share the menubar at the top of the screen. Just as
in MDI, the active window on the Macintosh determines the contents of
the menubar. Although CodeWarrior on the Windows platform is not,
strictly speaking, an MDI application (the windows are not contained
within a parent window), it has a single menubar on its main window
that all the windows share. As on the Macintosh, the contents of the
menubar change depending on which window is active when you activate
the main window. To use menu items with a particular window in mind,
remember to activate the window before selecting an item from the
menubar. If you find this too confusing, you can configure CodeWarrior
to run as a true MDI application using a setting in the Preferences
CodeWarrior versus CodeWarrior Lite
Metrowerks makes an evaluation version of CodeWarrior available for
downloading from its Web site. The evaluation version is known as
CodeWarrior Lite and is also available on the CD-ROM that accompanies
this book. It has all the features of the regular CodeWarrior except
that it can only modify existing projects — it can't
create new projects or add new files to existing projects. It's an
option to consider if you want to try the software before buying it.
Starting a Project
You launch CodeWarrior just like any other Windows or Macintosh
program. To start a new project, select the New Project menu item from
the main window, which we'll refer to as the IDE window. You'll be
presented with a dialog asking you what kind of project you want to
create, as shown in Figure 3.2. Although you can create a new,
completely empty project, CodeWarrior comes with some predefined
project templates called project stationery. Selecting a
project stationery creates a new project with some boilerplate C/C++
code and predefined project settings. Project stationery is included
for building Palm applications in C or C++, as is stationery for
building multisegment targets (discussed later in this chapter).
You'll find it easy to get started with a new application if you
always base your new projects on the Palm OS project stationery.
Figure 3.2 Selecting project stationery in CodeWarrior.
Once you've created a new project, CodeWarrior opens a project
window with views listing the files, segments, and targets in the
project, as shown in Figure 3.3. You switch between views by clicking
on the tabs at the top of the window. The files view lists all the
source files, runtime libraries, and resources used to build the
application. The files view can also include other files, such as text
files with documentation about the project. The segments view
organizes the files in the project into segments, which are the
individual code and data resources that comprise the final
application. Segments are discussed in more detail later in this
chapter. The final view is the targets view, which lets you control
the tool settings for building your application. Applications have a
single target, a .prc target.
Figure 3.3 The CodeWarrior project window.
The first thing to do with any new project is to change the target
settings to reflect the name of the application and its creator ID.
Get into this habit now and you won't run into problems with
applications overwriting each other on installation. Obtaining a
creator ID is simple and is discussed in the next chapter.
To change the application name, several steps are required. Select
the targets view and bring up the settings for the lone target (either
by pressing the Target Settings button on the project window toolbar
or by selecting the equivalent item from the Edit menu on the IDE
window). The settings window shown in Figure 3.4 consists of two
panes, with a tree view on the left and a details view on the right.
In the tree view, select the "Target Settings" item. Change
the Target Name shown in the right-hand pane to a descriptive name for
your application. Then, back in the tree view, select the "68K
Target" item and change the File Name in the right-hand pane to
the name of your application suffixed with ".tmp." This is
not the final name of your application, it's only the name of a
temporary file used to build the application. Go back to the tree view
and select the "PalmRez Post Linker" item. In the right-hand
pane, enter the name of the temporary file (the one you just set in
the "68K Target" item) in the Mac Resource Files field.
Enter the application name suffixed with ".prc" in the
Output File field — this is the name of the file you'll
install on your Palm device. Finally, enter your creator ID in the
Figure 3.4 The CodeWarrior settings window.
You'll probably want to change the name of the C/C++ source file as
well. To do this, return to the files view, select the file and
double-click to edit it. Activate the editor window, select the
"Save As..." item from the File menu (Windows users remember
that the menubar is on the IDE window, not the editor window; just
make sure the editor window is open and active before you access the
menubar) and type in the new name. The file will be renamed on disk
and in the project.
If at this point you were to build the application and install the
newly built .prc file onto your device, you would notice that the old
name was still being used. The name of the .prc file does not
determine the name of the application shown to the user by the Palm
device. That application's name and icon are in fact stored as
resources in the .prc file. In CodeWarrior, resources are edited with
the Constructor tool.
Modifying Resources with Constructor
Although resources on the Palm platform can hold any kind of data,
including the compiled code for your application, on a platform like
Windows, resources usually hold a program's static user interface
elements — such things as windows, menus, and strings.
Constructor is a resource editor for creating these user interface
elements for the Palm platform. It's a separate tool that you can
launch from your desktop or from within the CodeWarrior environment.
Constructor reads and writes resource files, which end in a .rsrc
extension, and which it refers to as project files. (Don't confuse
Constructor project files with CodeWarrior project files.)
Another Note for Windows Users
On the Macintosh, files have two parts, called forks: a data
fork and a resource fork. When you move a Macintosh file to another
platform, each fork is a separate file. CodeWarrior on Windows uses
the two-file approach for .rsrc files. The file you see on disk is the
data fork and is empty. In the same directory as the data fork is a
(possibly hidden) directory called Resource.frk which holds the
resource fork. The resource fork has the same name as the data fork.
CodeWarrior manages these files for you automatically, but if you ever
need to copy files from a project to another directory or another
machine, be sure to copy both forks.
To edit the resources for your new project, double-click on the .rsrc
file shown in the project window's file view. The resource editor is
shown in Figure 3.5. Like CodeWarrior itself, on the Windows platform
the menubar for Constructor is in a separate window, so if you're
editing several resource files simultaneously, be sure to activate the
correct editor before selecting a menu item.
Figure 3.5 The Constructor resource editor.
The resource editor window has two parts to it. The upper part of
the window lists all the resource types that are available for
editing. The bottom part is for Constructor project settings, which is
where you set the name, icon, and version number of the application.
The project settings also control the name of the header (.h) file
that Constructor generates to map resource identifiers (which are
integers) into more meaningful names.
For now all we'll do is change the name and icon for the
application. To change the name, click on the existing name (to the
left of the "Application Icon Name" field) and type the new
name. Keep the name short but descriptive. To change the icon, click
on the small button (labeled "Create" or "Edit")
to the right of the "Application Icon" field. This brings up
a small bitmap editor, shown in Figure 3.6, for creating monochrome
icons. Create a simple icon and quit the bitmap editor.
Figure 3.6 Constructor's bitmap editor.
The final step is to change the name that the application displays
in its titlebar. Return to the resource editor window and find the
"Forms" resource type. There should be a single form listed
there. Double-click on it to open the form editor shown in Figure 3.7.
In the form editor, click on the field to the right of "Form
Title" and change the title to the name of the application. Quit
the form editor. Go to the menubar and save the resources you've just
modified. Now you're ready to compile your project.
Figure 3.7 Constructor's form editor.
Since Constructor and CodeWarrior are actually separate tools,
changes you make to a resource file with Constructor are not
automatically reflected in the CodeWarrior project. Always save your
resource file before building your project.
To rename a resource file, load it in Constructor and save it under
a different name. Then return to CodeWarrior, select the files view
for your project, and add the resource file to the project using the
"Add Files" menu item in the Project menu. Finally, select
the old resource file in the files view and select "Remove
Selected Items" from the Project menu to remove the old file from
Building the Project
After changing the target settings and the resources, the next step
is to build and run your project using the "Make" menu item
or the equivalent button on the project window or IDE window toolbars.
The application is compiled and linked to build a .prc file. Any
errors and warnings appear in a separate window, as shown in Figure
3.8. Errors are easily fixed by selecting an error message and making
the appropriate changes in the text editor at the bottom of the
window. You can also double-click on the error message to open a
separate editor window. In either case, the text editor jumps to the
line in the source file where the error occurred, which makes for
Figure 3.8 Error messages when compiling.
Download the .prc file to your Palm device in the usual manner and
run it. You've just built your first application with CodeWarrior!
Debugging with CodeWarrior
At some point your application is going to crash and you're going
to wonder why. CodeWarrior includes a full source-level debugger that
is integrated into the development environment. With it you can debug
your programs from your desktop computer as they run on the PalmPilot.
The debugger can also debug programs running in the Palm OS Emulator.
Even if you're planning on using the Emulator for most of your testing
and debugging (most developers do), you should try a live debugging
session with an actual device.
The debugger has to be configured before you can use it. On
Windows, for example, it needs to know which serial port to use to
communicate with the device. Or if you're using the Emulator, it needs
to know where to find it. To configure the dialog, select the
"Preferences" item from the Edit menu in the IDE window. In
the resulting window, select the "Palm Connection Settings"
in the tree view on the left side of the window, as shown in Figure
3.9. On the right side you can choose whether you want to debug with a
device or the Emulator and configure either option.
Figure 3.9 Configuring CodeWarrior to use the Emulator.
To debug an application, load its project file into CodeWarrior and
build it to make sure it's up to date. Select the "Debug"
menu item from the Project menu to start the debugging process. What
happens next depends on whether you're using a real device or the Palm
If you're debugging with a real device, CodeWarrior will prompt you
to place the device in console mode. Console mode is a
low-level debugging mode that is available in each device, and which
we discuss later in this chapter. When console mode is active,
CodeWarrior can communicate with the device through its HotSync cradle
to install and debug your application. Place the device in its cradle
and then write a sequence of Graffiti characters: the shortcut
sequence (shown in Figure 3.10) followed by a period (two taps) and
the number 2. Once you've done this, the device listens on its serial
port for the debugger. Return to your desktop computer and dismiss the
dialog. CodeWarrior will transfer the application to the device and
start it running. If it doesn't, there could be a problem with your
connection settings, consult the CodeWarrior documentation for steps
on how to fix the problem.
Figure 3.10 The Graffiti shortcut stroke.
If you're debugging with the emulator, there's no need to place the
emulator in console mode. CodeWarrior transfers the application and
starts it running without your help.
TIP: If you're having trouble with the Graffiti shortcut sequence, press
the Find button before writing the shortcut. The shortcut character
will appear in the Find dialog's text field if you're doing it right,
otherwise another character will appear. This makes it much easier to
correct writing problems.
Once the application is running, CodeWarrior brings up the debugger
window, shown in Figure 3.11. The debugger stops at the entry point to
the application, the PilotMain function, which we'll be discussing in
some detail in the next chapter. The debugger window allows you to
perform all the normal source-level debugging functions you're used to
in other development tools: stepping in and out of functions, viewing
the call stack, viewing local variables, and so on.
Figure 3.11 The CodeWarrior debugger window.
Although you can set and remove breakpoints from the debugger
window, it's easier to manage your breakpoints before you start
debugging. To set a breakpoint, open the code editor for the source
file in question and simply double-click in the gutter on the left
side of the window. This installs or removes a breakpoint at the given
line. Breakpoints get saved with the project.
If you don't have any breakpoints installed, you can interrupt an
application that is being debugged at any time with the following
sequence of Graffiti characters: the Graffiti shortcut character, a
period, and the number 1.
When you're done debugging, use the "Kill" menu item in
the Debug menu to stop the debugger. This will also perform a soft
reset of the device or the Emulator. The application is still
installed and if it's crashing in its startup sequence, then you'll
have to manually perform a modified soft reset (in the case of a real
device) or else perform an Emulator recovery (discussed later in this
Prev Chapter |
Prev Section |
Next Section |
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
and disclaimer notices for more details.
If you find the material useful, consider buying one of
linking to this site from your own site or in your weblog,
or sending me a note.