|
1 .. index:: |
|
2 module: Configuring Helium |
|
3 |
|
4 ================== |
|
5 Configuring Helium |
|
6 ================== |
|
7 |
|
8 .. contents:: |
|
9 |
|
10 Introduction |
|
11 ============ |
|
12 |
|
13 This describes the key aspects of configuring a Helium build and other aspects of using the Helium build toolkit. |
|
14 |
|
15 Helium consists of several phases (the stages_ section explains these in detail) these are briefly outlined here: |
|
16 |
|
17 * pre-build - performs several checks on the environment and creates the Bill of Materials (BOM) before copying the relevant files from synergy to the build area and unzipping them. |
|
18 * build - compiles the files. |
|
19 * post-build - creates SIS files (system Installation files), creates ROM images, zips the build area for releasing, publishes releases, creates localised images, produces data packages, reports results to diamonds server. |
|
20 |
|
21 .. _stages: stages.html |
|
22 |
|
23 .. index:: |
|
24 single: Configuration files |
|
25 |
|
26 Configuration files |
|
27 =================== |
|
28 |
|
29 Defining a Helium build configuration can be a simple or complicated task depending on the requirements. Helium supports a lot of build |
|
30 functionality but much of it is optional. All configuration files are based on XML using a number of different XML schemas or formats. |
|
31 Over time more consistency and harmonisation of the formats will be implemented. Below is a list of the key formats: |
|
32 |
|
33 .. csv-table:: Helium configuration file types |
|
34 :header: "Format", "Where used" |
|
35 |
|
36 "Apache Ant", "All build configurations must start with at least a ``build.xml`` file in the directory where builds will be run, that contains the minimum of Helium Ant properties to configure the build." |
|
37 "Common configuration", "Several build stages: ROM build, zipping, SIS file creation." |
|
38 "Environment/shell variables", "Configuring the PATH and other environment settings." |
|
39 "Preparation", "Creation of a build area, using copy and unzip steps." |
|
40 |
|
41 .. index:: |
|
42 single: Ant configuration |
|
43 |
|
44 Ant configuration |
|
45 ----------------- |
|
46 |
|
47 The Ant format is the most important because at least one Ant file is required to run any kind of build command. Read the `Using Ant`_ section of the Ant manual that describes how to write generic Ant files. |
|
48 |
|
49 .. _`Using Ant`: |
|
50 |
|
51 In the context of Helium, some specific elements and properties should be used. Here is an example of a very basic Helium Ant file:: |
|
52 |
|
53 <?xml version="1.0" encoding="UTF-8"?> |
|
54 <project default="product-build"> |
|
55 <!-- Import environment variables as Ant properties. --> |
|
56 <property environment="env"/> |
|
57 |
|
58 <!-- A basic property definition --> |
|
59 <property name="product.name" value="PRODUCT"/> |
|
60 |
|
61 <!-- helium.dir will always refer to the directory of the Helium instance being used. |
|
62 |
|
63 All build configurations must import helium.ant.xml to use Helium. --> |
|
64 <import file="${helium.dir}/helium.ant.xml"/> |
|
65 </project> |
|
66 |
|
67 Note that here the default target is ``product-build`` so this would be used for a product build configuration. In reality it would need many more properties to be complete. |
|
68 |
|
69 Refer to the `configuration reference`_ for a full list of all Helium Ant properties. |
|
70 |
|
71 .. _`configuration reference`: ../api/helium/index.html |
|
72 |
|
73 .. index:: |
|
74 single: Common configuration format |
|
75 |
|
76 .. _common-configuration-format-label: |
|
77 |
|
78 Common configuration format |
|
79 --------------------------- |
|
80 |
|
81 Several parts of the build require more complex configuration than basic ``name=value`` properties. A common format is introduced for these configurations that is closely matching the future Raptor build system format in concept. |
|
82 |
|
83 Currently only \`ROM Image configuration (using iMaker)\`_ and \`SIS files\`_ are configured using this format. |
|
84 |
|
85 Summary: |
|
86 |
|
87 * The XML document format consists of a ``<build>`` root element. |
|
88 |
|
89 * ``<config>`` subelements define specifications (configurations) to be built. |
|
90 |
|
91 * ``<config>`` elements can be nested, i.e. a ``<config>`` element can contain other ``<config>`` elements, etc. |
|
92 |
|
93 * A ``name`` attribute identifies that element. It can be used to select one or a group of configurations. |
|
94 |
|
95 * An ``abstract`` attribute marks that specification as being not directly buildable. Child specifications not marked as abstract may be buildable. |
|
96 |
|
97 * ``<set>`` elements inside ``<config>`` s define property values. A property defined in a child ``<config>`` element overrides the value of a property with the same name in a parent specification. All parent properties are inherited if not overridden. |
|
98 |
|
99 * Comma-separated values or repeated elements will result in a list property value when evaluated. |
|
100 |
|
101 |
|
102 .. index:: |
|
103 single: Passwords |
|
104 |
|
105 Passwords |
|
106 ========= |
|
107 |
|
108 Helium requires access to a few resources that require username and password authentication, like Synergy for SCM operations and a user's network login/password for GRACE upload. To avoid the need for a password dialog request, these details can be entered in a ``.netrc`` file located on the user's HOME drive. The HOME location is one of: |
|
109 |
|
110 Windows |
|
111 H: drive |
|
112 |
|
113 Linux |
|
114 ``/home/user`` |
|
115 |
|
116 A ``.netrc`` file is a standard Unix file format. |
|
117 |
|
118 The following entries are available: |
|
119 |
|
120 Synergy:: |
|
121 |
|
122 machine synergy login <synergy-username> password <synergy-password> |
|
123 |
|
124 ``synergy`` can be replaced by the name of a specific database if the settings should apply only to that database, e.g:: |
|
125 |
|
126 machine vc1s60p1 login <synergy-username> password <synergy-password> |
|
127 |
|
128 Then account could be used to override the default GSCM settings:: |
|
129 |
|
130 machine sa1ido login <synergy-username> password <synergy-password> account /db/path@dbhost |
|
131 |
|
132 Nokia specific |
|
133 -------------- |
|
134 |
|
135 NOE:: |
|
136 |
|
137 machine noe login <network-username> password <network-password> |
|
138 |
|
139 GRACE:: |
|
140 |
|
141 machine grace login <network-username> password <network-password> |
|
142 |
|
143 Lotus Notes:: |
|
144 |
|
145 machine notes login <notes-username> password <notes-password> |
|
146 |
|
147 nWiki:: |
|
148 |
|
149 machine nwiki login <nwiki-username> password <nwiki-password> |
|
150 |
|
151 **Note:- that the nWiki password is different to that used for NOE/Notes/Grace and therefore will typically require the use of the macro macro-netrc.username along with the macro macro-netrc.password.** |
|
152 |
|
153 |
|
154 .. index:: |
|
155 single: Signals notifications |
|
156 |
|
157 Signals notifications |
|
158 ===================== |
|
159 |
|
160 Helium contains a number of signal events that are triggered at various points during the build. These provide the following features: |
|
161 |
|
162 * Determine whether to fail the build immediately, deferred to the end or not at all. |
|
163 * Send an email alert message. |
|
164 * Send an SMS alert message. |
|
165 |
|
166 A default configuration of the signals is defined in ``config/helium_signals_default.xml``. By default the email alerts are sent to the build manager, but each signal can have a custom email list by defining a property ``<signal-name>.email.list``. |
|
167 |
|
168 |
|
169 .. index:: |
|
170 single: Viewing target dependencies |
|
171 |
|
172 Viewing target dependencies |
|
173 =========================== |
|
174 |
|
175 The ``deps`` target can be used to display a list of the target dependencies for a given target. See the `manual page`_ for more information. Also the ``execlist`` command works in a similar way but shows a dialog showing a separated list of all the dependent targets and then just the top-level of dependencies, to help with continuing a build on the command line. |
|
176 |
|
177 .. _`manual page`: ../api/helium/target-deps.html |
|
178 |
|
179 |
|
180 .. index:: |
|
181 single: Automating build number assignment |
|
182 |
|
183 Automating build number assignment |
|
184 ================================== |
|
185 |
|
186 Typically the build number for a build is defined on the command line. However it may be desirable to automate the allocation of a new build number using a simple text database file. To do this, add the property ``read.build.int`` to the configuration or the command line. This will look for a text file in this location:: |
|
187 |
|
188 ${publish.root.dir}/${build.name}/builds/${build.name}_${core.build.version}_${build.tag}_build_int_db.txt |
|
189 |
|
190 If the file is not present it is created with a new build number value of "001". If it does exist the value is read from the file and then incremented and written back for the next build. A ``build.tag`` property can also be defined to start the build number with a text string if needed. |
|
191 |
|
192 |
|
193 .. index:: |
|
194 single: Advanced configuration |
|
195 |
|
196 Advanced configuration |
|
197 ====================== |
|
198 |
|
199 .. index:: |
|
200 single: Custom targets |
|
201 |
|
202 Custom targets |
|
203 -------------- |
|
204 |
|
205 Custom targets are often needed in a configuration to customize, extend or otherwise modify the default behaviour and build sequences of Helium. |
|
206 |
|
207 To override a target inside Helium define a custom target with the same name. The original target will then be named with |
|
208 the prefix of the project (Ant file) name, e.g. ``common.hello``. There are three ways to customize a target: |
|
209 |
|
210 .. index:: |
|
211 single: Completely replace the target |
|
212 |
|
213 Completely replace the target |
|
214 ::::::::::::::::::::::::::::: |
|
215 |
|
216 Just define the custom target:: |
|
217 |
|
218 <target name="hello"> |
|
219 <echo message="Custom hello!"/> |
|
220 </target> |
|
221 |
|
222 .. index:: |
|
223 single: Run custom code after the target |
|
224 |
|
225 Run custom code after the target |
|
226 :::::::::::::::::::::::::::::::: |
|
227 |
|
228 Define the overriding custom target and make it depend on the original target:: |
|
229 |
|
230 <target name="hello" depends="common.hello"> |
|
231 <echo message="After hello!"/> |
|
232 </target> |
|
233 |
|
234 .. index:: |
|
235 single: Run custom code before the target |
|
236 |
|
237 Run custom code before the target |
|
238 ::::::::::::::::::::::::::::::::: |
|
239 |
|
240 This is a little more complicated. Two custom targets are needed, one to implement the custom behaviour, and the 2nd to override the original target and define the dependencies:: |
|
241 |
|
242 <target name="pre-hello"> |
|
243 <echo message="Before hello!"/> |
|
244 </target> |
|
245 |
|
246 <target name="hello" depends="pre-hello,common.hello"/> |
|
247 |
|
248 .. index:: |
|
249 single: Call a target with different params |
|
250 |
|
251 Call a target with different params |
|
252 ::::::::::::::::::::::::::::::::::: |
|
253 |
|
254 In rare situations you may need to override a target in helium or call it with different properties, you should create a target in your config with the same name before you import helium.ant.xml:: |
|
255 |
|
256 <target name="localisation-roms"> |
|
257 <for list="${localisation.makefile.target}" delimiter="," param="target" > |
|
258 <sequential> |
|
259 <antcall target="localisation-32.localisation-roms"> |
|
260 <param name="localisation.makefile.target" value="@{target}"/> |
|
261 </antcall> |
|
262 </sequential> |
|
263 </for> |
|
264 </target> |
|
265 |
|
266 .. index:: |
|
267 single: Using Helium internal tasks and macros |
|
268 |
|
269 Using Helium internal tasks and macros |
|
270 -------------------------------------- |
|
271 |
|
272 Helium contains a number of internal tasks and macros that are defined under a Helium XML namespace. This is to make it easier to distinguish them from standard Ant and 3rd party tasks inside the Helium Ant files. This means that namespaces must be correctly applied to most Helium tasks or macros. |
|
273 |
|
274 Helium tasks start with the prefix ``hlm:``, for example:: |
|
275 |
|
276 <target name="do-signal"> |
|
277 <hlm:signal name="testSignal"/> |
|
278 </target> |
|
279 |
|
280 To include an XML element with a ``hlm:`` prefix the Helium namespace must be defined in the root element of the XML file:: |
|
281 |
|
282 <project name="myproject" xmlns:hlm="http://www.nokia.com/helium"> |
|
283 .... |
|
284 </project> |
|
285 |
|
286 .. index:: |
|
287 single: MC Helium configuration |
|
288 |
|
289 MC Helium configuration |
|
290 ----------------------- |
|
291 |
|
292 Based on the former MC codeline policy the SAL organisation in MC has used a hierarchical structure for the Helium build configuration files. This is an example configuration that can be used as a guideline. |
|
293 |
|
294 .. index:: |
|
295 single: Product family and product properties |
|
296 |
|
297 Product family and product properties |
|
298 ::::::::::::::::::::::::::::::::::::: |
|
299 |
|
300 These are set in hierarchical structure under mc_build:: |
|
301 |
|
302 /mc_build |
|
303 /<SAL> |
|
304 /<product> |
|
305 /<variant> |
|
306 |
|
307 E.g:: |
|
308 |
|
309 /mc_build |
|
310 /mc_4032_build |
|
311 mc_4032_build.ant.xml - product family configuration. |
|
312 /PRODUCT |
|
313 PRODUCT.ant.xml - product configuration. |
|
314 /RM247 |
|
315 build.xml - variant configuration. |
|
316 /RM297 |
|
317 build.xml |
|
318 /PRODUCT |
|
319 /RMxxx |
|
320 /mc_5132_build |
|
321 /PRODUCT |
|
322 /teams |
|
323 juno.ant.xml |
|
324 |
|
325 Ant files at each level contain the configuration for that level. Builds are run from the outermost directories, e.g. RM247 and ``<import>`` statements are used to import the files in the parent directories. The ``mc_4032_build.ant.xml`` file would import ``helium.ant.xml``. |
|
326 |
|
327 For an example of a product build click here. |
|
328 |
|
329 .. toctree:: |
|
330 :maxdepth: 1 |
|
331 |
|
332 product_example.rst |
|
333 |
|
334 |
|
335 .. index:: |
|
336 single: Team properties |
|
337 |
|
338 .. _`Team-Properties-label`: |
|
339 |
|
340 Team properties |
|
341 ::::::::::::::: |
|
342 |
|
343 For the MC build configurations are a number of properties that are related to a team and/or site. |
|
344 These are all combined in a single configuration file. All the team configuration files are stored under ``/mc/mc_build/teams``. |
|
345 This allows different build configurations to be run in different locations, or handle multiple product family configurations at one site. |
|
346 |
|
347 In order for this to work in windows environment you may need to set up an environment variable called TEAM. So click |
|
348 start->settings->control panel and double click on 'system' to open the system properties window. Click on the 'advanced' tab and then click the |
|
349 'environment variables' tab. Create a new variable preferably under the system varaibles but if you do not have permission to add one here then add |
|
350 it to the user variables make the variable name 'TEAM' (note capital letters) and the team name is what ever your team name is. |
|
351 |
|
352 Also see :ref:`Setting-Team_properties-label`: |
|
353 |
|
354 |
|
355 .. index:: |
|
356 single: Setting the team/site |
|
357 |
|
358 Setting the team/site |
|
359 ::::::::::::::::::::: |
|
360 |
|
361 To enable running any build with any team/site configuration, the team must be defined separately from the build configuration files. The team name should be the same as the team configuration file under ``/mc/mc_build/teams`` without the "``.ant.xml``". |
|
362 |
|
363 The team can be set in one of the following ways (using the example of the ``juno.ant.xml`` file): |
|
364 |
|
365 * Define a ``TEAM`` environment variable, e.g. ``TEAM=juno``. |
|
366 * Add an Ant command line parameter to set the team, e.g:: |
|
367 |
|
368 hlm product-build -Dteam=juno |
|
369 |
|
370 .. index:: |
|
371 single: System definition configuration files |
|
372 |
|
373 System definition configuration files |
|
374 ::::::::::::::::::::::::::::::::::::: |
|
375 |
|
376 Sysdef configuration defines the source code you actually want to compile with Helium. More information about the System definition |
|
377 files can be found from: http://developer.symbian.org/wiki/index.php/System_Definition. |
|
378 |
|
379 Under helium/testconfig/mc/mc_build/ibusal_51_build/ is the file IBUSAL51_SystemDefinition.xml which can be examined as a sample definition file. |
|
380 It is used by the Helium test environment to test helium works. It consists of a list of components to compile and some special instructions to |
|
381 perform whilst compiling the components e.g. run toucher.exe on certain directories. You will need to make sure this file exists and contains |
|
382 the correct components when building and especialy for a product which consists of many hundreds of components. It should be possible to use |
|
383 the file supplied by S60, but you may need to copy the component compile lines from the file and add them to the existing file in helium in |
|
384 order to make sure you also get the special instructions which are required to make the builds create a ROM image successfully (or any |
|
385 other action requested). |
|
386 |
|
387 |