1 <?xml version="1.0" encoding="utf-8"?> |
|
2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. --> |
|
3 <!-- This component and the accompanying materials are made available under the terms of the License |
|
4 "Eclipse Public License v1.0" which accompanies this distribution, |
|
5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". --> |
|
6 <!-- Initial Contributors: |
|
7 Nokia Corporation - initial contribution. |
|
8 Contributors: |
|
9 --> |
|
10 <!DOCTYPE concept |
|
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
|
12 <concept id="GUID-3527AAEE-210F-524B-A655-A65F1CE86C80" xml:lang="en"><title>How |
|
13 to build a resource file</title><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
14 <p>Resource building is performed by the <filepath>epocrc</filepath> tool. |
|
15 It is a three-stage process:</p> |
|
16 <ul> |
|
17 <li id="GUID-06BFE8CC-6DB9-5FE0-97CF-9176B6832C92"><p>pre-processing</p> </li> |
|
18 <li id="GUID-78EF35B1-B93B-54C7-8991-F1DAA1FB2B39"><p>localised string merging</p> </li> |
|
19 <li id="GUID-C217A7AC-2919-5587-BB58-5744C1FDF5D8"><p>compilation to binary |
|
20 format</p> </li> |
|
21 </ul> |
|
22 <p>The sections below describe each stage in turn.</p> |
|
23 <section><title>Pre-processing</title><p>Resource files can use the familiar |
|
24 pre-processor directives. In particular, <codeph>#include</codeph> is used |
|
25 to include header files; <codeph>#define</codeph> is used to define macros |
|
26 such as numeric constants; and <codeph>#if</codeph> and related directives |
|
27 can be used to perform conditional compilation. Pre-processor arguments for |
|
28 include file paths and macro definitions can be passed to the pre-processor |
|
29 through <filepath>epocrc</filepath>.</p><p>The source file is pre-processed, |
|
30 using the <filepath>cpp</filepath> pre-processor, and an output file produced |
|
31 with an extension <filepath>.rpp</filepath>.</p></section> |
|
32 <section><title>Merging localised strings</title><p>Strings that should be |
|
33 localised should not be defined in the resource file itself, but in separate |
|
34 files with an <filepath>.rls</filepath> extension. The <filepath>.rpp</filepath> files |
|
35 are processed by <filepath>epocrc</filepath> to merge in the localisable strings.</p><p>A |
|
36 flag can also be specified to <filepath>epocrc</filepath> that causes it to |
|
37 copy the <filepath>.rpp</filepath> files into a <filepath>epoc32\localisation\</filepath> directory, |
|
38 from where they can form input into a localisation kit.</p></section> |
|
39 <section><title>Compilation to binary format</title><p>The final |
|
40 stage is to convert the intermediary <filepath>.rpp</filepath> files into |
|
41 the final compiled format. This is done by the <filepath>rcomp</filepath> tool. |
|
42 The resource compiler also produces a header file that contains a symbolic |
|
43 identifier for each resource.</p><p>The names of the output files are specified |
|
44 as parameters to <filepath>epocrc</filepath>. Note though that:</p><ul> |
|
45 <li id="GUID-1575F474-7035-55E8-A37D-1E7CF8B825BC"><p> resource files as built |
|
46 by the project build tools (<filepath>abld</filepath>) have the default extension <filepath>.rsc</filepath>. |
|
47 The additional naming conventions used when you need to supply multiple resource |
|
48 files, each for a different locale, are discussed in <xref href="GUID-F35C5336-907C-5B2A-92C6-F8883D49996E.dita">How |
|
49 to localise resources</xref> </p> </li> |
|
50 <li id="GUID-8940240B-69E5-51B2-9335-67E63822D6FF"><p> by convention, the |
|
51 header file has an extension <filepath>.rsg</filepath> </p> </li> |
|
52 </ul><p>The identifiers in the header file provide symbolic names for index |
|
53 positions in the resource file, so that your source code can be independent |
|
54 of the number and order of resources within the file. For a named resource |
|
55 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 |
|
56 the number is a resource ID which encodes the resource index, and is suitable |
|
57 for passing to the C++ function <codeph>RResourceFile::AllocReadLC()</codeph>.</p><p>In |
|
58 the course of project development, changes to the resource file may not always |
|
59 result in changes to the set of <codeph>#define</codeph> statements generated. |
|
60 If there is no change, the <filepath>rsg</filepath> file is not rebuilt, thereby |
|
61 avoiding unnecessary re-compilation and linking.</p></section> |
|
62 </conbody></concept> |
|