Resource compiler

Contents

• Overview
• Integrating the resource compiler into the C++ IDE
• The resource compilation process
• Example

Overview

Resource files contain data in numbered resources. The index can be used to efficiently find a resource given its numeric id. There can be from 1 to 4095 resources in a resource file. A resource file has the following format:

There are four main reasons for using resource files:

• resource files make it easier for applications to run in more than one language. The resource text may be changed and the resources recompiled, without altering or recompiling the C++ program.
• they are convenient for specifying and modifying some aspects of application layout and design. Applications that use the EIKON framework must have a resource file.
• keeping data in a separate resource file may reduce RAM requirements because text strings will only be loaded into RAM when needed
• resource files may be compressed, thereby reducing program size

Resource files are produced by compiling a text source file, extension .rss, using the EPOC resource compiler, eikrs. The resource compiler also produces a header file, extension .rsg, which is required when the project is compiled using a C++ compiler.

For more information on the resource compiler invocation syntax, see the topic Simple resource compiler interface.

Integrating the resource compiler into the C++ IDE

When programming EPOC in C++, developers can integrate the resource compiler into the Visual Studio IDE. This process, which is described in the C++ SDK, allows the resource compiler to be invoked from a Visual Studio menu.

The resource compilation process

Resource compilation is a two-stage process:

• The pre-processor stage
• The main resource compilation stage

The pre-processing stage operates on the resource file statements and uses the cpp pre-processor supplied with the GNU C++ compiler. The GCC compiler is located in the directory \epoc32\gcc\bin, as downloaded from the SDK. If you also have a cpp from a different vendor on your system, make sure that the directory in which it resides follows \epoc32\gcc\bin in the path.

The main resource compilation stage generates:

• the header file, extension .rsg
• the compiled resource file, extension .rsc

The header file contains #define statements for each resource defined in the source file. In the course of project development, changes to the resource file may not always result in changes to the set of #define statements generated. Consequently eikrs.bat checks whether the set of #define statements in the header file differ from the set in the existing .rsg file. If there is no change, the .rsg file is not rebuilt, thereby avoiding unnecessary re-compilation and linking.

The compiled resource file contains the resource data, and is the file that is referred to at run-time by the application..

Example

The following example illustrates the use of the resource compiler. Consider the bahello project. The resource compiler is invoked using the eikrs.bat batch file.

    eikrs bahello xx

This takes the bahello.rss source file and converts it into two output files: the symbol file bahello.rsg, and the resource file bahello.rxx.

The two letter code passed as the second parameter to eikrs is appended to the character r to generate the file extension. Any two letters may be used in the two letter code, and these can be used as flags for conditional compilation of the resource file. For example, a source resource file containing definitions in both French and Italian can be compiled into either language, depending on the code passed to eikrs.

Whatever code is used, at run time resource files must be re-named to have the extension rsc. Where multiple resource files are provided with apps, e.g. for different languages, the required renaming is managed as part of install process.