This chapter describes the process to create a Palm OS application, describes the features provided by Palm OS Developer Suite, and discusses how each of the Palm OS developer tools are used in the process.
Palm OS Developer Suite is an integrated tools package based on Eclipse 3.0.1 and the C/C++ Development Toolkit (CDT) feature, version 2.0.2. This integrated environment simplifies the process for building Palm OS applications while providing support for 68K applications, PACE native objects, and Palm OS Protein applications.
If you choose, you can also use the Palm OS developer tools independently or with other development solutions such as CodeWarrior or gcc
.
This chapter covers the following topics:
- "Palm OS Application Development Tasks"
- "Process for Building Palm OS Applications"
- "Components of Palm OS Developer Suite"
Palm OS Application Development Tasks
Creating a Palm OS application is similar to creating an application for other operating systems:
- Design
- Design the application by determining the functional requirements, the data requirements, and the user interface requirements.
- Develop
- Write the program logic and user interface source code.
- Build
- Compile the source and build the executable application.
- Test
- Run the application, using testing and debugging tools to help identify how the application can be improved.
- Package
- Create installable packages of your application and support files.
Design Considerations
The Palm OS platform supports three application types. One of your primary application design considerations is to decide which application type is right for your application.
- Palm OS 68K Applications
If your goal is to create applications that run on all Palm OS devices and on all supported Palm OS versions, then you want to create Palm OS 68K applications.
The 68K API is the set of functions that spans all Palm OS releases. The 68K functions allow application code compiled for Dragonball processors to access the capabilities of Palm OS. The 68K API is the native API for Palm OS 4 and earlier Palm OS versions. The 68K API operates in PACE (the Palm OS Application Compatibility Environment) on Palm OS Garnet and Palm OS Cobalt.
For more information on creating 68K applications, see "Process for Building Palm OS 68K Applications".
- PACE Native Objects
If you are an experienced developer accustomed to working with the 68K API but you want to take advantage of the ARM CPUs that power Palm OS Garnet and Palm OS Cobalt handhelds, then you can create PACE native objects.
A PACE native object (PNO) is an ARM-native subroutine that your 68K application calls using the
PceNativeCall()
function.For more information on creating PACE native objects, see "Process for Building PACE Native Objects".
- Palm OS Protein Applications
If you want to take advantage of the Palm OS Protein API functions and the features emerging on new Palm OS Cobalt handhelds, you want to create Palm OS Protein applications.
Palm OS Protein applications can be multithreaded, can access schema and extended databases, and can employ Palm OS Cobalt's multimedia framework. However, Palm OS Protein applications only run on Palm OS Cobalt and later.
For more information about creating Palm OS Protein applications, see "Process for Building Palm OS Protein Applications".
Process for Building Palm OS Applications
This section provides a high-level overview of the processes for building the different types of Palm OS applications. The descriptions include references to where you can get more detailed information.
- "Process for Building Palm OS 68K Applications"
- "Process for Building PACE Native Objects"
- "Process for Building Palm OS Protein Applications"
Process for Building Palm OS 68K Applications
For building Palm OS 68K applications, Palm OS Developer Suite includes PRC-Tools
. PRC-Tools
includes patched versions of the GNU packages gcc
, binutils
, gdb
, and various post-linker tools.
- Create a 68K C/C++ Project for your source code. You can choose either a standard make project or a managed make project.
For more information about creating projects, see "Creating a New Project".
- Create your C/C++ source files using the C/C++ editor provided by CDT.
- Create your application's XML resource definition (XRD) files either by using Palm OS Resource Editor or by editing the XML file using the Eclipse text editor. For more information about XRD files and the Palm OS Resource Editor, see "Palm OS Resource Tools."
- Build your project. From Developer Suite, select Build Project or Rebuild Project to build your 68K application.
When you use Palm OS Developer Suite, you do not need to invoke the individual build tools directly. If you manually build your project, you need to take the following steps:
- Use the
m68k-palmos-gcc
compiler to compile and link your source code. - Use the Palm OS resource compiler,
PalmRC
, to compile your XRD file into a temporary resource (TRC) file.PalmRC
is part of the Palm OS Resource Tools component. - Use the Palm OS resource builder,
PRCMerge
, to join your code resources, data resource, and temporary resources into a Palm OS application.PRCMerge
is part of the Palm OS Resource Tools component.
- Use the
- Test your application by running it on Palm OS Emulator, Palm OS Simulator, or a Palm Powered™ device. From Palm OS Developer Suite, select Run > Run to open the Run dialog box, and use the Target tab to select the run target for your application.
- Debug your application, using the debugger integrated with Palm OS Developer Suite. From Palm OS Developer Suite, select Run > Debug to open the Debug dialog box, and use the Target tab to select the debug target for your application.
After your application is built, you can optionally take some additional steps.
- Compare applications using
PRCCompare
.PRCCompare
is part of the Palm OS Resource Tools component. - Create localized overlays for your application using
PRC2OVL
.
For more information about building a project in Palm OS Developer Suite, see "Building a Project" in Chapter 2, "Eclipse Workbench Integration."
Multi-Segment 68K Application Support
Sample code generated by the 68K application wizard contains two files to help you create multi-segment applications, if your application is sufficiently large to require multiple segments. These files are Sections.h
and Sections.def
. You can read the instructions in these files on how to use them.
Process for Building PACE Native Objects
A PACE native object is an ARM-native subroutine that you call from a 68K application. The ARM-native subroutine needs to be compiled with an ARM-based compiler rather than the 68K-based compiler that you use for your 68K application.
- Create a 68K PNO C/C++ Project for your source code. You can choose either a standard make project or a managed make project.
For more information about creating projects, see "Creating a New Project".
- Create the C/C++ source files for your 68K application and the C/C++ source files for your PNO using the C/C++ editor provided by CDT.
- Create your application's XML resource definition (XRD) files either by using Palm OS Resource Editor or by editing the XML file using the Eclipse text editor. For more information about XRD files and the Palm OS Resource Editor, see "Palm OS Resource Tools."
- Build your project. From Developer Suite, select Build Project or Rebuild Project to build your 68K PNO application.
When you use Palm OS Developer Suite, you do not need to invoke the individual build tools directly. If you manually build your project, you need to take the following steps:
- Use Palm OS Protein C/C++ Compiler,
pacc
, to compile your PNO's C/C++ source files into ELF object files for ARM-based devices.Note: To generate PNO targets for Palm OS Simulator, use the GNU x86 compiler instead of Palm OS Protein C/C++ Compiler. For information, see "Using Compiler Tools with the Workbench."
- Use
m68k-palmos-gcc
to compile and link your 68K application's source code. - Use the Palm OS resource compiler,
PalmRC
, to compile your XRD file into a temporary resource (TRC) file.PalmRC
is part of the Palm OS Resource Tools component. - Use the Palm OS resource builder,
PRCMerge
, to join your code resources, data resource, and temporary resources into a Palm OS application. The ELF object files from your PNOs are included as code resources when your 68K application is linked together.
- Use Palm OS Protein C/C++ Compiler,
- Test your application by running it on Palm OS Simulator or a Palm Powered™ device. From Palm OS Developer Suite, select Run > Run to open the Run dialog box, and use the Target tab to select the run target for your application.
- Debug your application, using the debugger integrated with Palm OS Developer Suite. From Palm OS Developer Suite, select Run > Debug to open the Debug dialog box, and use the Target tab to select the debug target for your application.
After your application is built, you can optionally take some additional steps.
- Compare applications using
PRCCompare
.PRCCompare
is part of the Palm OS Resource Tools component. - Create localized overlays for your application using
PRC2OVL
.
For more information about building a project in Palm OS Developer Suite, see "Building a Project" in Chapter 2, "Eclipse Workbench Integration."
Process for Building Palm OS Protein Applications
Figure 1.1 shows the detailed steps for building a Palm OS Protein application. Some of these steps may be optional, depending on the application.
- Create a Palm OS Protein C/C++ Project for your source code. You can choose either a standard make project or a managed make project.
For more information about creating projects, see "Creating a New Project".
- Create the C/C++ source files for your Palm OS Protein application using the C/C++ editor provided by CDT.
- Create your application's XML resource definition (XRD) files either by using Palm OS Resource Editor or by editing the XML file using the Eclipse text editor. For more information about XRD files and the Palm OS Resource Editor, see "Palm OS Resource Tools."
- Create a shared library definition (SLD) file, if necessary, to specify the entry points in your application or shared library. For applications, all code templates already create the required SLD file. But if you use an empty project to import existing source code, you need to create the SLD file.
- Build your project. From Developer Suite, select Build Project or Rebuild Project to build your Palm OS Protein application.
When you use Palm OS Developer Suite, you do not need to invoke the individual build tools directly. If you manually build your project, you need to take the following steps:
- Use Palm OS Protein C/C++ Compiler,
pacc
, to compile your C/C++ source files into ELF object files.pacc
is part of the Palm OS Compiler Tools component.Note: To generate targets for Palm OS Simulator, use the GNU x86 compiler instead of Palm OS Protein C/C++ Compiler. For information, see "Using Compiler Tools with the Workbench."
- Use the Palm OS resource compiler,
PalmRC
, to compile your XRD file into a temporary resource (TRC) file.PalmRC
is part of the Palm OS Resource Tools component. - Use the Palm OS shared library tool,
pslib
, to compile your SLD file into a ELF object file. - Use the Palm OS linker,
palink
, to link your ELF object files, and use the Palm OS post linker,pelf2bin
, to prepare the files to be merged into a Palm OS application. - Use the Palm OS resource builder,
PRCMerge
, to join your code resources, data resource, and temporary resources into a Palm OS application.PRCMerge
is part of the Palm OS Resource Tools component.
- Use Palm OS Protein C/C++ Compiler,
- Test your application by running it on Palm OS Simulator or a Palm Powered™ device. From Palm OS Developer Suite, select Run > Run to open the Run dialog box, and use the Target tab to select the run target for your application.
- Debug your application, using the debugger integrated with Palm OS Developer Suite. From Palm OS Developer Suite, select Run > Debug to open the Debug dialog box, and use the Target tab to select the debug target for your application.
After your application is built, you can optionally take some additional steps. (These steps are not shown in Figure 1.1.)
- Compare applications using
PRCCompare
.PRCCompare
is part of the Palm OS Resource Tools component. - Localize your application using the Palm OS localization tool,
hoverlay
.hoverlay
is part of the Palm OS Resource Tools component. - Create and embed a digital signature and associated certificates in your application using the code signing tools,
PRCCert
andPRCSign
.PRCCert
andPRCSign
are included with the Palm OS Resource Tools component.
For more information about building a project in Palm OS Developer Suite, see "Building a Project" in Chapter 2, "Eclipse Workbench Integration."
Figure 1.1 Palm OS Protein Application Development Process

Components of Palm OS Developer Suite
The Palm OS Developer Suite package consists of the following components:
- Workbench Integration
- Palm OS Compiler Tools
- PRC-Tools
- Palm OS Resource Tools
- Testing and Debugging Tools
- Palm OS Package Builder
This section provides a brief overview of each of these components. For a more detailed look into each component, see the remaining chapters of this document.
Workbench Integration
The Workbench integration consists of wizards, project files, libraries, and documentation that allow you to use the Palm OS developer tools in an Eclipse-integrated development environment.
For more information about this component, see Chapter 2, "Eclipse Workbench Integration."
Palm OS Compiler Tools
The Palm OS Compiler Tools component consists of an ANSI C compliant C compiler, a linker, a librarian, and utility tools that you can use to build Palm OS Protein applications:
- pacc
- Palm OS Protein C/C++ Compiler. Compiles C/C++ source files and calls the other compiler tools to produce ELF object files.
- paasm
- Palm OS assembler. Called by
pacc
to produce ELF object files. - palink
- Palm OS linker. Called by
pacc
to produce ELF object files. - palib
- Palm OS librarian. Creates libraries of ELF object files.
- elfdump
- A utility tool for viewing the contents of ELF object files.
For more information about this component, see Chapter 3, "Palm OS Compiler Tools."
PRC-Tools
PRC-Tools
is a collection of tools supporting C and C++ programming for Palm OS application development. Palm OS Developer Suite uses components of PRC-Tools
to compile 68K applications.
- gcc
- The GNU Compiler Collection,
gcc
, which is a collection of compiler front ends and libraries. - Palm OS Developer Suite specifically uses the
m68k-palmos-gcc
compiler for 68K applications. - as
- The GNU assembler,
as
, which is a component of GNUbinutils
. - ld
- The GNU linker,
ld
, which is a component of GNUbinutils
.
For more information about this component, see the documentation at PRC-Tools
web site (http://prc-tools.sourceforge.net/doc/).
Cygwin Packages
Cygwin includes many packages for developing Windows applications. Palm OS Developer Suite uses Cygwin components to compile and debug Palm OS Protein applications targeted for Palm OS Simulator.
- gcc
- The GNU Compiler Collection,
gcc
, which is a collection of compiler front ends and libraries. - Palm OS Developer Suite specifically uses the
i686-pc-cygwin-gcc-3.3.1
compiler for Palm OS Protein applications targeted for Palm OS Simulator. - as
- The GNU assembler,
as
, which is a component of GNUbinutils
. - ld
- The GNU linker,
ld
, which is a component of GNUbinutils
. - pxgdb
The GNU Project symbolic debugger for Windows, pxgdb
, which supports debugging of Palm OS applications that have been compiled to run on Palm OS Simulator.
Palm OS Resource Tools
NOTE: XML resource definition files are called XRD files. For information about XRD files, see the book Palm OS Resource File Formats.
The Palm OS Resource Tools component includes tools for editing, migrating, building, comparing, localizing, and securing resources for Palm OS applications:
- Palm OS Resource Editor
- A visual builder for designing Palm OS user interfaces. Palm OS Resource Editor creates and edits XML resource definition files.
- GenerateXRD
- Converts 68K-based PRC files and Macintosh RSRC files into XML that can be compiled using
PalmRC
. - PalmRC
- Compiles XRD files into TRC files that can be merged into applications using
PRCMerge
. - PRCMerge
- Combines TRC files with code and data resources to make Palm OS applications.
- PRCCompare
- Compares two Palm OS applications (PRCs, BPRCs, OPRCs, or TRCs).
- hoverlay:
- Creates overlays for localized versions of Palm OS Protein applications.
- PRC2OVL
- Creates overlays for localized versions of 68K applications.
- PRCCert
- Creates RSA key pairs and digital certificates for Palm OS applications.
- PRCSign
- Digitally signs applications or embeds digital signatures in applications.
For more information about the resource tools, see Chapter 4, "Palm OS Resource Tools."
Testing and Debugging Tools
Palm OS Developer Suite includes a debugger, a device simulator, and a mobile telephone simulator.
- Palm OS Emulator
- A hardware emulator program for the Palm Powered™ platform. Palm OS Emulator emulates device hardware in software, providing you with the ability to test and debug Palm OS software on a desktop computer.
- You can use Palm OS Emulator to test 68K applications; Palm OS Emulator does not run ARM-native code.
- Palm OS Simulator
- Palm OS recompiled to run on Windows. Palm OS Simulator is simulation tool that allows you to test your Palm OS applications as if they were running on a handheld device. By using Palm Reporter with Palm OS Simulator, you can perform real time trace analysis of your application.
- Palm OS Garnet Simulator is Palm OS Garnet recompiled to run on Windows; Palm OS Cobalt Simulator is Palm OS Cobalt recompiled to run on Windows.
- You can use Palm OS Cobalt Simulator to test Palm OS Protein applications, but the code must be recompiled to run on Windows.
- Palm OS Reporter
- Palm OS Reporter is a trace utility that can be used with Palm OS Simulator and Palm OS Emulator. As an application runs on Simulator or Emulator, the application sends information in real time to Reporter. This information can help pinpoint problems that might be hard to identify when executing code step-by-step or when specifying breakpoints.
- Virtual Phone
- A mobile telephone simulator that allows you to test Palm OS telephony applications. You can use Virtual Phone with Palm OS Emulator, Palm OS Garnet Simulator, and Palm OS Cobalt Simulator.
- Palm OS Debugger
- A full-function, source-level debug tool that you can use to debug Palm OS Protein and 68K applications and shared libraries.
For more information about these components, see Chapter 6, "Palm OS Debugging Tools."
Palm OS Package Builder
Palm OS Developer Suite includes support for building PalmSource Installer (PSI) files using Palm OS Package Builder. Palm OS Package Builder is a developer tool that can automatically create packages for "over-the-air" delivery of Palm OS applications. PalmSource Install packages can specify device-specific features, such as screen sizes or language version, as well as creating a full package for download to the user's desktop. The full package includes all languages and all screen sizes, plus any desktop components or other files too big for OTA delivery.
For more information about Palm OS Package Builder integration, see Chapter 7, "Palm OS Package Builder."