This chapter describes how to use PalmRC to compile XML resource files (XRD files).

• "Introducing PalmRC" describes the basic functions of the PalmRC tool.
• "Using the PalmRC Command Line Tool" describes how to specify the PalmRC command line arguments to compile an XRD file.

Introducing PalmRC ^TOP^

PalmRC compiles XRD resource files into Palm OS® resource binary format. The resource compilation typically does not include the code resources necessary to produce the final Palm OS application resource file.

Figure 3.1  PalmRC Overview

PalmRC is usually an intermediate step in the build process. PalmRC generates an output file with a TRC extension (for "temporary resource file") rather than a PRC file. The only difference between a PRC file and a TRC file is that a TRC file does not contain the code resources and database header that are required in a PRC file.

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

PalmRC is available as a command line tool for Windows.

Using the PalmRC Command Line Tool ^TOP^

PalmRC is used to compile an XRD file (or files) into PRC resources. The command syntax for PalmRC is:

PalmRC inputFiles -o outputFile [options] 

input_files

One or more XRD files.

output_file

The -o option is required to specify where the PalmRC output file is written. The output file is in PRC resource database format. Normally you should specify a file with a file name extension of TRC, but in some cases for testing, you might specify a file name extension of PRC, BPRC, or OPRC. 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 PalmRC 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 created as usual.

-densityTarget target

Specifies target density configuration for bitmaps and fonts. The supported values of target are 1X, 1.5X, and 2X.

-help

PalmRC displays help information and ignores any other options.

-helpTargets

PalmRC displays supported targets.

-helpVersion

PalmRC displays version information and ignores any other options.

-i dirpath

Specifies a directory to be searched when header files are using during compilation.

Note: PalmRC does not currently support symbolic identifiers, so this option is ignored.

-locale xxYY

Filters resources using the LOCALE attribute. Resources with locale attributes that do not match the specified locale are omitted from the output file.

Locale-independent resources (resources with an empty locale attribute) are included or omitted depending on the value specified for the -overlayFilter option. By default, locale-independent resources are included in the output file.

PalmRC requires that the locale value specified be in the form xxYY, where xx is a lowercase two-character alphabetic language code and YY is an uppercase two-character alphabetic country code.

When you specify a non-standard locale value (a locale value that is not defined by Palm OS), then you must specify the
-noLocaleCheck option. See the description of
-noLocaleCheck below for more information.

The locale xxYY is either an empty string (""), to indicate forcing base locale, or a specific locale code. PalmRC recognizes the following specific locale codes:

enUS

English

frFR

French

itIT

Italian

deDE

German

esES

Spanish

jaJP

Japanese

zhCN

Simplified Chinese

zhTW

Traditional Chinese

koKR

Korean

-makeDeps

Specifies that PalmRC should generate a list of all external data files (such as bitmap files) that the compilation depends on. The list of files is written to the specified output file in platform native text format, one file per line, with each file specified as a full path name. If the specified dependency already exists and the dependencies are unchanged, the file is not changed; otherwise it is overwritten.

-noLocaleCheck

When the -locale option is used, if the specified locale code is not one of the currently recognized codes, PalmRC issues a warning message. The purpose of this warning is only to guard against accidentally specifying an incorrectly locale code. When you need to specify a non-standard locale code, you should also specify this option to suppress any warning messages.

-noWarnSize

By default, PalmRC displays a warning if the size of the resource it creates is greater than 64K. But if you specify -noWarnSize, PalmRC does not display the warning.

-overlayFilter filter

The -overlayFilter option is used in conjunction with the -locale option to filter resources for overlay stripping. There are three options that may be specified for filter:

BASE

Only locale-independent resources (resources with an empty locale attribute) are placed in the output file.

OVERLAY

Only resources matching the specified locale are output; locale-independent resources are not output.

FULL

Both locale-independent resources and resources matching the specified locale are output.

-p proc

Specifies the target resource format. proc is one of the following values:

68K

To build resources for 68K applications (in the format used by Palm OS 4.1 and prior), specify the "-p 68K" option.

This is the option you should use for all 68K applications, even for 68K applications that are targeted for Palm OS releases after Palm OS 4.1.

PalmRC also provides the option "-p PalmOS4" as a synonym for the "-p 68K" option.

ARM

To build resources in the native format used by Palm OS Cobalt and later, specify the "-p ARM" option.

PalmRC also provides the option "-p PalmOS6" as a synonym for the "-p ARM" option.

-q /-quiet

PalmRC suppresses the tool description (tool name and version number) and copyright information.

-strictLocale

PalmRC issues an error messages if a resource locale setting in the XRD file is different from the target locale setting.

-strictTextEncoding

PalmRC issues an error messages if conversion to the output text encoding fails.

By default, PalmRC issues a warning message when an input character cannot be represented in the target text encoding. With this option, PalmRC issues an error message and then stops processing.

-target palmOS

Specifies the text encoding of the output resources. palmOS must be one of the following targets:

4.0

Indicates Palm Latin R2 text encoding. This is the default.

4.0J

Indicates Palm ShiftJIS (Japanese) text encoding. When working with Japanese resource files, it is important to specify the "-target 4.0J" option. Otherwise, the Japanese text is corrupted.

4.0CS

Indicates PalmGB text encoding. This is the Simplified Chinese encoding format.

4.0CT

Indicates Traditional Chinese encoding.

4.0KR

Indicates Korean encoding.

For locales that are not explicitly supported, you can specify a Microsoft Windows code page.

If you do not specify the target that matches the input files text encoding, the text in the output XRD is garbage.

For Macintosh resource files, the target is also used to determine the fonts that are used to calculate the width of menus and certain controls.