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

3    Compiling XML Resource Files

Palm OS® Resource Tools Guide

Palm OS® Developer Suite

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

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.


NOTE: The TRC file is used in the build process to convey the compiled resource data. The TRC file is the output from PalmRC and the input to PRCMerge.

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.