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-6C069F43-207C-5C6A-B9F6-3865BE8E70E8" xml:lang="en"><title>Variant |
|
13 configuration file syntax</title><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
14 <section><title>Purpose</title> <p>A variant configuration file (<filepath>.var</filepath>) |
|
15 defines settings that are specific to a variant. It is used to modify certain |
|
16 aspects of an existing build platform. </p> </section> |
|
17 <section><title>Syntax</title> <p> <varname>KEYWORD</varname> [<varname>OPERATION</varname>] |
|
18 [<varname>VALUE</varname>] </p> <p>A summary of keywords, operations and values |
|
19 is given below: </p> <p><b>Keyword</b> </p> <p>Possible keywords are as follows: </p> <table id="GUID-D6F58101-A22F-5377-9190-B8E609DE35ED"> |
|
20 <tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/> |
|
21 <tbody> |
|
22 <row> |
|
23 <entry><p> <codeph>VARIANT</codeph> </p> </entry> |
|
24 <entry><p>Indicates that <varname>VALUE</varname> is the name of the variant |
|
25 configuration. </p> </entry> |
|
26 </row> |
|
27 <row> |
|
28 <entry><p> <codeph>VIRTUAL</codeph> </p> </entry> |
|
29 <entry><p>Indicates that the variant is meant only for grouping variants and |
|
30 not to be used as a build configuration. </p> </entry> |
|
31 </row> |
|
32 <row> |
|
33 <entry><p> <codeph>EXTENDS</codeph> </p> </entry> |
|
34 <entry><p>Indicates that the variant extends an existing variant configuration. </p> </entry> |
|
35 </row> |
|
36 <row> |
|
37 <entry><p> <codeph>VARIANT_HRH</codeph> </p> </entry> |
|
38 <entry><p>Specifies the pre-included header (<filepath>.hrh</filepath>) file |
|
39 that defines feature macros. </p> </entry> |
|
40 </row> |
|
41 <row> |
|
42 <entry><p> <codeph>BUILD_INCLUDE</codeph> </p> </entry> |
|
43 <entry><p>Specifies the location of the files to be included when building |
|
44 the binary. </p> </entry> |
|
45 </row> |
|
46 <row> |
|
47 <entry><p> <codeph>ROM_INCLUDE</codeph> </p> </entry> |
|
48 <entry><p>Specifies the location of the files to be included when building |
|
49 the ROM image containing the variant binary. </p> </entry> |
|
50 </row> |
|
51 </tbody> |
|
52 </tgroup> |
|
53 </table> <p> <b>Note</b>: If VARIANT_HRH keyword is not present, then <codeph>/epoc32/include/variant/name.hrh</codeph> is |
|
54 used. </p> <p><b>operation</b> </p> <p>The possible operations are <codeph>set</codeph>, <codeph>append</codeph> and <codeph>prepend</codeph>. |
|
55 These operations provide the flexibility of extending the existing include |
|
56 paths within the <filepath>.var</filepath> file. The operations are applicable |
|
57 only to the <codeph>BUILD_INCLUDE</codeph> and <codeph>ROM_INCLUDE</codeph> keywords. </p> <p> <b>Example</b> </p> <codeblock id="GUID-3D6B0229-A64F-52BB-9BDF-10ABDF99F11E" xml:space="preserve"># default.var |
|
58 VARIANT default |
|
59 BUILD_INCLUDE set /epoc32/include |
|
60 BUILD_INCLUDE append /epoc32/include/variant |
|
61 ROM_INCLUDE set /epoc32/rom/include</codeblock> <codeblock id="GUID-91F8392C-C822-5829-BA42-FB8F9AB6AECD" xml:space="preserve"># phone.var |
|
62 VARIANT phone |
|
63 EXTENDS default |
|
64 BUILD_INCLUDE append /epoc32/include/variant/phone |
|
65 ROM_INCLUDE prepend /epoc32/rom/phone</codeblock> <p>For the variant <codeph>phone</codeph> the |
|
66 include lists will be: </p> <codeblock id="GUID-72B415A7-84D6-5818-9E64-B736D505E873" xml:space="preserve">BUILD (/epoc32/include, /epoc32/include/variant, /epoc32/include/variant/phone) |
|
67 ROM (/epoc32/rom/phone, /epoc32/rom/include)</codeblock> <p><b>value</b> </p><p>Value |
|
68 can be a variant name, a file name or a directory name. for example, myphone |
|
69 or /epoc32/tools/variant/name.var. </p><ul> |
|
70 <li><p>Use '/' as the path separator between files and directories.</p></li> |
|
71 <li><p>Begin all paths with '/' implying that they are relative to EPOCROOT.</p></li> |
|
72 </ul> <p><b>Example</b> </p> <p>An example of a variant: </p> <codeblock id="GUID-50190D57-7C49-5697-A858-7626D59B1967-GENID-1-13-1-1-7-1-11-1-2-2-20" xml:space="preserve">VARIANT name |
|
73 VIRTUAL |
|
74 EXTENDS parent |
|
75 VARIANT_HRH /epoc32/include/variant/something.hrh |
|
76 BUILD_INCLUDE set directoryA |
|
77 BUILD_INCLUDE append directoryB |
|
78 BUILD_INCLUDE prepend directoryC |
|
79 ROM_INCLUDE set directoryD |
|
80 ROM_INCLUDE append directoryE |
|
81 ROM_INCLUDE prepend directoryF |
|
82 |
|
83 </codeblock> <p><b>Notes</b> </p> <ul> |
|
84 <li id="GUID-84B8E804-46B8-5422-9CFE-048C9EF0179B-GENID-1-13-1-1-7-1-11-1-2-2-22-1"><p>All <filepath>.var</filepath> files |
|
85 must exist in <filepath>/epoc32/tools</filepath> <filepath>/</filepath> <varname>variant</varname>. </p> </li> |
|
86 <li id="GUID-CDB78FAD-58A6-5464-ACC6-EFBCEDFD5092-GENID-1-13-1-1-7-1-11-1-2-2-22-2"><p>A default variant configuration |
|
87 file (<filepath>default.var</filepath>) must exist in <filepath>/epoc32/tools/variant/</filepath>. </p> </li> |
|
88 <li id="GUID-7216C624-7E28-52A5-BAA7-BB897286AE51-GENID-1-13-1-1-7-1-11-1-2-2-22-3"><p>The name of the variant |
|
89 configuration file (.var) must be same as the variant name. For example, if |
|
90 the variant name is <b>myvar</b>, then the variant configuration file must |
|
91 be named as <filepath>myvar.var</filepath>. </p> </li> |
|
92 <li id="GUID-CADF1047-C92E-5A8C-81FB-64CAA19380B8-GENID-1-13-1-1-7-1-11-1-2-2-22-4"><p>Each variant must have |
|
93 a default <filepath><variant_name>.hrh</filepath> file at <filepath>/epoc32/include/variant/</filepath>. |
|
94 If you want to use any other <filepath>.hrh</filepath> file under EPOCROOT, |
|
95 use the <codeph>VARIANT_HRH</codeph> keyword to specify its name along with |
|
96 the relative path. </p> </li> |
|
97 <li id="GUID-FEEDF642-117E-5E4F-8CD4-B6305B977204-GENID-1-13-1-1-7-1-11-1-2-2-22-5"><p>A default variant cannot |
|
98 be <codeph>VIRTUAL</codeph>. </p> </li> |
|
99 </ul> </section> |
|
100 <section><title>Example</title> <p>An example of a variant: </p> <codeblock id="GUID-50190D57-7C49-5697-A858-7626D59B1967-GENID-1-13-1-1-7-1-11-1-2-3-3" xml:space="preserve">VARIANT name |
|
101 VIRTUAL |
|
102 EXTENDS parent |
|
103 VARIANT_HRH /epoc32/include/variant/something.hrh |
|
104 BUILD_INCLUDE set directoryA |
|
105 BUILD_INCLUDE append directoryB |
|
106 BUILD_INCLUDE prepend directoryC |
|
107 ROM_INCLUDE set directoryD |
|
108 ROM_INCLUDE append directoryE |
|
109 ROM_INCLUDE prepend directoryF |
|
110 |
|
111 </codeblock> </section> |
|
112 <section><title>Notes</title> <ul> |
|
113 <li id="GUID-84B8E804-46B8-5422-9CFE-048C9EF0179B-GENID-1-13-1-1-7-1-11-1-2-4-2-1"><p>All <filepath>.var</filepath> files |
|
114 must exist in <filepath>/epoc32/tools</filepath> <filepath>/</filepath> <varname>variant</varname>. </p> </li> |
|
115 <li id="GUID-CDB78FAD-58A6-5464-ACC6-EFBCEDFD5092-GENID-1-13-1-1-7-1-11-1-2-4-2-2"><p>A default variant configuration |
|
116 file (<filepath>default.var</filepath>) must exist in <filepath>/epoc32/tools/variant/</filepath>. </p> </li> |
|
117 <li id="GUID-7216C624-7E28-52A5-BAA7-BB897286AE51-GENID-1-13-1-1-7-1-11-1-2-4-2-3"><p>The name of the variant |
|
118 configuration file (.var) must be same as the variant name. For example, if |
|
119 the variant name is <b>myvar</b>, then the variant configuration file must |
|
120 be named as <filepath>myvar.var</filepath>. </p> </li> |
|
121 <li id="GUID-CADF1047-C92E-5A8C-81FB-64CAA19380B8-GENID-1-13-1-1-7-1-11-1-2-4-2-4"><p>Each variant must have |
|
122 a default <filepath><variant_name>.hrh</filepath> file at <filepath>/epoc32/include/variant/</filepath>. |
|
123 If you want to use any other <filepath>.hrh</filepath> file under EPOCROOT, |
|
124 use the <codeph>VARIANT_HRH</codeph> keyword to specify its name along with |
|
125 the relative path. </p> </li> |
|
126 <li id="GUID-FEEDF642-117E-5E4F-8CD4-B6305B977204-GENID-1-13-1-1-7-1-11-1-2-4-2-5"><p>A default variant cannot |
|
127 be <codeph>VIRTUAL</codeph>. </p> </li> |
|
128 </ul></section> |
|
129 </conbody><related-links> |
|
130 <link href="GUID-917413FC-0AC0-5768-B5AD-36BD2EDCB1FF.dita"><linktext>How to build |
|
131 feature based variants</linktext></link> |
|
132 <link href="GUID-7FF363B0-B05F-5490-8D9C-59061B905381.dita"><linktext>How to build |
|
133 ROMs with variants</linktext></link> |
|
134 </related-links></concept> |
|