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.