<?xml version="1.0" encoding="utf-8"?>

<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

<!-- This component and the accompanying materials are made available under the terms of the License 

"Eclipse Public License v1.0" which accompanies this distribution, 

and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

<!-- Initial Contributors:

    Nokia Corporation - initial contribution.

Contributors: 

-->

<!DOCTYPE concept

  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

<concept id="GUID-3527AAEE-210F-524B-A655-A65F1CE86C80" xml:lang="en"><title>How

to build a resource file</title><prolog><metadata><keywords/></metadata></prolog><conbody>

<p>Resource building is performed by the <filepath>epocrc</filepath> tool.

It is a three-stage process:</p>

<ul>

<li id="GUID-06BFE8CC-6DB9-5FE0-97CF-9176B6832C92"><p>pre-processing</p> </li>

<li id="GUID-78EF35B1-B93B-54C7-8991-F1DAA1FB2B39"><p>localised string merging</p> </li>

<li id="GUID-C217A7AC-2919-5587-BB58-5744C1FDF5D8"><p>compilation to binary

format</p> </li>

</ul>

<p>The sections below describe each stage in turn.</p>

<section><title>Pre-processing</title><p>Resource files can use the familiar

pre-processor directives. In particular, <codeph>#include</codeph> is used

to include header files; <codeph>#define</codeph> is used to define macros

such as numeric constants; and <codeph>#if</codeph> 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 <filepath>epocrc</filepath>.</p><p>The source file is pre-processed,

using the <filepath>cpp</filepath> pre-processor, and an output file produced

with an extension <filepath>.rpp</filepath>.</p></section>

<section><title>Merging localised strings</title><p>Strings that should be

localised should not be defined in the resource file itself, but in separate

files with an <filepath>.rls</filepath> extension. The <filepath>.rpp</filepath> files

are processed by <filepath>epocrc</filepath> to merge in the localisable strings.</p><p>A

flag can also be specified to <filepath>epocrc</filepath> that causes it to

copy the <filepath>.rpp</filepath> files into a <filepath>epoc32\localisation\</filepath> directory,

from where they can form input into a localisation kit.</p></section>

<section><title>Compilation to binary format</title><p>The final

stage is to convert the intermediary <filepath>.rpp</filepath> files into

the final compiled format. This is done by the <filepath>rcomp</filepath> tool.

The resource compiler also produces a header file that contains a symbolic

identifier for each resource.</p><p>The names of the output files are specified

as parameters to <filepath>epocrc</filepath>. Note though that:</p><ul>

<li id="GUID-1575F474-7035-55E8-A37D-1E7CF8B825BC"><p> resource files as built

by the project build tools (<filepath>abld</filepath>) have the default extension <filepath>.rsc</filepath>.

The additional naming conventions used when you need to supply multiple resource

files, each for a different locale, are discussed in <xref href="GUID-F35C5336-907C-5B2A-92C6-F8883D49996E.dita">How

to localise resources</xref> </p> </li>

<li id="GUID-8940240B-69E5-51B2-9335-67E63822D6FF"><p> by convention, the

header file has an extension <filepath>.rsg</filepath> </p> </li>

</ul><p>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:</p><codeblock id="GUID-2FC8E745-72D6-5837-84EC-9C275445FFE5" xml:space="preserve">RESOURCE TBUF r_eik_bafl_error_offset { buf="Wrong format resource file"; }</codeblock><p>the generated header file will have a <codeph>#define</codeph> such as:</p><codeblock id="GUID-39701585-375F-529C-A059-4504B420A61E" xml:space="preserve">#define R_EIK_BAFL_ERROR_OFFSET 0xf3b045</codeblock><p>where

the number is a resource ID which encodes the resource index, and is suitable

for passing to the C++ function <codeph>RResourceFile::AllocReadLC()</codeph>.</p><p>In

the course of project development, changes to the resource file may not always

result in changes to the set of <codeph>#define</codeph> statements generated.

If there is no change, the <filepath>rsg</filepath> file is not rebuilt, thereby

avoiding unnecessary re-compilation and linking.</p></section>

</conbody></concept>