Documentation  |   Table of Contents   |  < Previous   |  Next >   |  Index

4    Building a Palm OS Application

Palm OS® Resource Tools Guide

Palm OS® Developer Suite

This chapter describes how to use PRCMerge to combine a resource TRC or PRC with a code PRC to make a Palm OS® application.

Introducing PRCMerge ^TOP^

PRCMerge builds a Palm OS binary resource file (PRC), typically for a Palm OS application or library. It takes as input a set of Palm OS binary resources specified as one or more input files.

Figure 4.1  PRCMerge Overview

Each input file must be one of the following formats:

  • TRC/PRC file format. The resources from the input file are merged to the output.
  • RSRC (Macintosh binary resource file). The resource data from Macintosh binary resource files is not processed in any form, but only merged into the output, possibly with resource type remapping (for example, mapping CODE to code).

    You use RSRC files when you are building 68K applications with CodeWarrior. The CodeWarrior 68K compiler produces a Macintosh resource file with the CODE resources which are then merged into the Palm OS application file.

  • BIN file. A BIN file specifies the binary data for a single resource. The name of the file must be of the form <resource-type><resource-ID>.bin, where <resource-type> is the 4-letter character resource type and <resource-ID> is a 4-character hexadecimal resource ID. For example "tFRM03E8.BIN" would contain the data for 'tFRM' 1000 (0x3E8 hexadecimal = 1000 decimal).

PRCMerge also takes as input the data used to build the PRC file database header, such as database name, version, type code, creator code. These values must be specified appropriately for the Palm OS application or library being built.

PRCMerge is integrated into Palm OS Developer Suite. When you build a project using Developer Suite, PRCMerge is called as part of the process of building the project.

PRCMerge is available as a command line tool for Windows.

Using the PRCMerge Command Line Tool ^TOP^

PRCMerge is used to merge PRC resources into a Palm OS PRC resource database file, such as a Palm OS application. PRCMerge takes as input one or more PRC format files (PRC, TRC, OPRC, and BPRC), Macintosh resource files, or BIN files.

The command syntax for PRCMerge is:

PRCMerge inputFiles -o outputFile [options]
input_files
One or more files of the following type:
TRC
PRC
Macintosh resource
BIN format
output_file
The -o option is required to specify where the PRCMerge output file is written. The file is in PRC resource database format. Normally you should specify a file with a file name extension of PRC. The output file is overwritten automatically if it already exists.
options
Additional command line options as described in the following section "Specifying Command Line Options."

Specifying Command Line Options ^TOP^

-append
If the -append option is specified and the output file PRC file already exists, then PRCMerge merges the compiled resources into the existing output file. If the output file does not exist, specifying this option has no effect, and the output file is be created as usual.
-b | -dbFlagBackup
Sets the backup flag stored in the PRC database header. Applications should normally specify the -dbFlagBackup option.
-c creatorstr | -dbCreator creatorstr
Specifies the database creator code stored in the PRC database header. This is normally the unique creator code registered for the application.
-dbFlagBundle
Sets the bundle flag stored in the PRC database header.
-dbFlagExecutable
Sets the executable flag stored in the PRC database header.
-dbFlagExtendedDB
Sets the extended database flag to indicate that the database is an ARM-based non-schema database.
-h | -dbFlagHidden
Sets the hidden flag stored in the PRC database header.
-help
PRCMerge displays help information and ignores any other options.
-helpVersion
PRCMerge displays the tool's version information.
-n namestr | -dbName namestr
Specifies the database name stored in the PRC database header. This is normally the name of the application.
-only type
Indicates that you want to input only a particular resource or resources of a particular type. This option is followed by a resource type expression:
type
A resource type to indicate all resources of that type.
type (id)
A resource type followed by a resource ID to indicate a specific resource.
type (id:id)
A resource type followed by an ID range to indicate all matching resources.
This option -type may be specified multiple times, in which case the options are combined. For example, "-only Talt -only tFRM" indicates that the output PRC contains both alert and form resources.
-omit type
Indicates that you want to omit a particular resource or resources of a particular type. This option is followed by a resource type expression:
type
A resource type to indicate all resources of that type.
type (id)
A resource type followed by a resource ID to indicate a specific resource.
type (id:id)
A resource type followed by an ID range to indicate all matching resources.
This option -omit may be specified multiple times in which case the options are combined. For example, "-omit Talt -omit tFRM" indicates that the output PRC contains all resources except for alert resources and form resources.
-p| -dbFlagProtect
Sets the protect flag stored in the PRC database header.
-q | -quiet
PRCMerge suppresses the tool description (tool name and version number) and copyright information.
-r | -dbFlagReset
Sets the reset flag stored in the PRC database header.
-t typestr | -dbType typestr
Specifies the database type code stored in the PRC database header. This is normally 'appl' for Palm OS applications.
-v versionstr | -dbVersion versionstr
Specifies the database version number stored in the PRC database header. Most applications start with database version 1 and increment as necessary when new versions of the application are developed.