How to build a resource file

Resource building is performed by the epocrc tool. It is a three-stage process:

• pre-processing

• localised string merging

• compilation to binary format

The sections below describe each stage in turn.

Pre-processing

Resource files can use the familiar pre-processor directives. In particular, #include is used to include header files; #define is used to define macros such as numeric constants; and #if and related directives can be used to perform conditional compilation. Pre-processor arguments for include file paths and macro definitions can be passed to the pre-processor through epocrc.

The source file is pre-processed, using the cpp pre-processor, and an output file produced with an extension .rpp.

Merging localised strings

Strings that should be localised should not be defined in the resource file itself, but in separate files with an .rls extension. The .rpp files are processed by epocrc to merge in the localisable strings.

A flag can also be specified to epocrc that causes it to copy the .rpp files into a epoc32\localisation\ directory, from where they can form input into a localisation kit.

Compilation to binary format

The final stage is to convert the intermediary .rpp files into the final compiled format. This is done by the rcomp tool. The resource compiler also produces a header file that contains a symbolic identifier for each resource.

The names of the output files are specified as parameters to epocrc. Note though that:

• resource files as built by the project build tools (abld) have the default extension .rsc. The additional naming conventions used when you need to supply multiple resource files, each for a different locale, are discussed in How to localise resources

• by convention, the header file has an extension .rsg

The identifiers in the header file provide symbolic names for index positions in the resource file, so that your source code can be independent of the number and order of resources within the file. For a named resource such as:

RESOURCE TBUF r_eik_bafl_error_offset { buf="Wrong format resource file"; }

the generated header file will have a #define such as:

#define R_EIK_BAFL_ERROR_OFFSET 0xf3b045

where the number is a resource ID which encodes the resource index, and is suitable for passing to the C++ function RResourceFile::AllocReadLC().

In the course of project development, changes to the resource file may not always result in changes to the set of #define statements generated. If there is no change, the rsg file is not rebuilt, thereby avoiding unnecessary re-compilation and linking.