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


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 the CD-ROM.

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 dialog.


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 Creator field.

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.

TIP: 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 the project.

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 quick editing.

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 OS Emulator.

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 chapter).

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