buildframework/helium/doc/src/manual/configuring.rst
author y4jin
Tue, 23 Nov 2010 14:07:04 +0800
changeset 705 67449e76cb84
parent 645 b8d81fa19e7d
permissions -rw-r--r--
Fix the illegal word scanned by sfchecksource tools
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
587
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents: 217
diff changeset
     1
..  ============================================================================ 
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents: 217
diff changeset
     2
    Name        : configuring.rst
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents: 217
diff changeset
     3
    Part of     : Helium 
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents: 217
diff changeset
     4
    
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents: 217
diff changeset
     5
    Copyright (c) 2009 Nokia Corporation and/or its subsidiary(-ies).
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents: 217
diff changeset
     6
    All rights reserved.
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents: 217
diff changeset
     7
    This component and the accompanying materials are made available
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents: 217
diff changeset
     8
    under the terms of the License "Eclipse Public License v1.0"
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents: 217
diff changeset
     9
    which accompanies this distribution, and is available
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents: 217
diff changeset
    10
    at the URL "http://www.eclipse.org/legal/epl-v10.html".
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents: 217
diff changeset
    11
    
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents: 217
diff changeset
    12
    Initial Contributors:
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents: 217
diff changeset
    13
    Nokia Corporation - initial contribution.
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents: 217
diff changeset
    14
    
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents: 217
diff changeset
    15
    Contributors:
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents: 217
diff changeset
    16
    
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents: 217
diff changeset
    17
    Description:
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents: 217
diff changeset
    18
    
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents: 217
diff changeset
    19
    ============================================================================
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents: 217
diff changeset
    20
    
1
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    21
.. index::
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    22
  module: Configuring Helium
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    23
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    24
==================
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    25
Configuring Helium
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    26
==================
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    27
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    28
.. contents::
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    29
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    30
Introduction
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    31
============
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    32
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    33
This describes the key aspects of configuring a Helium build and other aspects of using the Helium build toolkit.
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    34
217
0f5e3a7fb6af helium_8.0-r15308
wbernard
parents: 1
diff changeset
    35
Helium consists of several phases (the   stages_ section explains these in detail) these are briefly outlined here:
1
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    36
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    37
* 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.
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    38
* build       - compiles the  files.
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    39
* 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.
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    40
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    41
.. _stages: stages.html
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    42
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    43
.. index::
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    44
  single: Configuration files
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    45
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    46
Configuration files
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    47
===================
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    48
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    49
Defining a Helium build configuration can be a simple or complicated task depending on the requirements. Helium supports a lot of build 
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    50
functionality but much of it is optional. All configuration files are based on XML using a number of different XML schemas or formats. 
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    51
Over time more consistency and harmonisation of the formats will be implemented. Below is a list of the key formats:
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    52
    
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    53
.. csv-table:: Helium configuration file types
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    54
   :header: "Format", "Where used"
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    55
   
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    56
    "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."
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    57
    "Common configuration", "Several build stages: ROM build, zipping, SIS file creation."
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    58
    "Environment/shell variables", "Configuring the PATH and other environment settings."
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    59
    "Preparation", "Creation of a build area, using copy and unzip steps."
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    60
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    61
.. index::
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    62
  single: Ant configuration
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    63
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    64
Ant configuration
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    65
-----------------
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    66
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    67
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.
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    68
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    69
.. _`Using Ant`: 
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    70
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    71
In the context of Helium, some specific elements and properties should be used. Here is an example of a very basic Helium Ant file::
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    72
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    73
    <?xml version="1.0" encoding="UTF-8"?>
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    74
    <project default="product-build">
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    75
        <!-- Import environment variables as Ant properties. -->
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    76
        <property environment="env"/>
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    77
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    78
        <!-- A basic property definition -->
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    79
        <property name="product.name" value="PRODUCT"/>
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    80
        
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    81
        <!-- helium.dir will always refer to the directory of the Helium instance being used.
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    82
        
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    83
        All build configurations must import helium.ant.xml to use Helium. -->
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    84
        <import file="${helium.dir}/helium.ant.xml"/>
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    85
    </project>
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    86
645
b8d81fa19e7d helium_12.0.0-63b64366f9cf
wbernard
parents: 588
diff changeset
    87
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.
1
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    88
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    89
Refer to the `configuration reference`_ for a full list of all Helium Ant properties.
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    90
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    91
.. _`configuration reference`: ../api/helium/index.html
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    92
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    93
.. index::
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    94
  single: Common configuration format
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    95
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    96
.. _common-configuration-format-label:
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    97
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    98
Common configuration format
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    99
---------------------------
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   100
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   101
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.
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   102
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   103
Currently only \`ROM Image configuration (using iMaker)\`_ and \`SIS files\`_ are configured using this format.
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   104
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   105
Summary:
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   106
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   107
 * The XML document format consists of a ``<build>`` root element.
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   108
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   109
 * ``<config>`` subelements define specifications (configurations) to be built.
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   110
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   111
   * ``<config>`` elements can be nested, i.e. a ``<config>`` element can contain other ``<config>`` elements, etc.
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   112
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   113
   * A ``name`` attribute identifies that element. It can be used to select one or a group of configurations.
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   114
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   115
   * An ``abstract`` attribute marks that specification as being not directly buildable. Child specifications not marked as abstract may be buildable.
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   116
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   117
 * ``<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.
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   118
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   119
   * Comma-separated values or repeated elements will result in a list property value when evaluated.
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   120
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   121
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   122
.. index::
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   123
  single: Passwords
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   124
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   125
Passwords
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   126
=========
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   127
587
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents: 217
diff changeset
   128
Helium requires access to a few resources that require username and password authentication, like Synergy for SCM operations. 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:
1
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   129
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   130
Windows
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   131
  H: drive
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   132
  
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   133
Linux
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   134
  ``/home/user``
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   135
  
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   136
A ``.netrc`` file is a standard Unix file format.
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   137
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   138
The following entries are available:
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   139
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   140
Synergy::
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   141
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   142
  machine synergy login <synergy-username> password <synergy-password>
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   143
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   144
``synergy`` can be replaced by the name of a specific database if the settings should apply only to that database, e.g::
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   145
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   146
  machine vc1s60p1 login <synergy-username> password <synergy-password>
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   147
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   148
Then account could be used to override the default GSCM settings::
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   149
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   150
  machine sa1ido login <synergy-username> password <synergy-password> account /db/path@dbhost 
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   151
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   152
Nokia specific
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   153
--------------
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   154
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   155
NOE::
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   156
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   157
  machine noe login <network-username> password <network-password>
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   158
  
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   159
Lotus Notes::
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   160
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   161
  machine notes login <notes-username> password <notes-password>
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   162
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   163
nWiki::
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   164
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   165
  machine nwiki login <nwiki-username> password <nwiki-password>
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   166
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   167
**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.**
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   168
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   169
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   170
.. index::
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   171
  single: Signals notifications
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   172
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   173
Signals notifications
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   174
=====================
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   175
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   176
Helium contains a number of signal events that are triggered at various points during the build. These provide the following features:
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   177
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   178
* Determine whether to fail the build immediately, deferred to the end or not at all.
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   179
* Send an email alert message.
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   180
* Send an SMS alert message.
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   181
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   182
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``. 
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   183
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   184
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   185
.. index::
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   186
  single: Viewing target dependencies
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   187
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   188
Viewing target dependencies
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   189
===========================
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   190
645
b8d81fa19e7d helium_12.0.0-63b64366f9cf
wbernard
parents: 588
diff changeset
   191
The :hlm-t:`deps` target can be used to display a list of the target dependencies for a given target. Also the :hlm-t:`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.
1
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   192
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   193
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   194
.. index::
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   195
  single: Automating build number assignment
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   196
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   197
Automating build number assignment
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   198
==================================
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   199
587
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents: 217
diff changeset
   200
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 :hlm-p:`read.build.int` to the configuration or the command line. This will look for a text file in this location::
1
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   201
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   202
    ${publish.root.dir}/${build.name}/builds/${build.name}_${core.build.version}_${build.tag}_build_int_db.txt
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   203
    
587
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents: 217
diff changeset
   204
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 :hlm-p:`build.tag` property can also be defined to start the build number with a text string if needed.
1
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   205
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   206
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   207
.. index::
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   208
  single: Advanced configuration
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   209
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   210
Advanced configuration
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   211
======================
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   212
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   213
.. index::
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   214
  single: Custom targets
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   215
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   216
Custom targets
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   217
--------------
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   218
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   219
Custom targets are often needed in a configuration to customize, extend or otherwise modify the default behaviour and build sequences of Helium.
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   220
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   221
To override a target inside Helium define a custom target with the same name. The original target will then be named with
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   222
the prefix of the project (Ant file) name, e.g. ``common.hello``. There are three ways to customize a target:
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   223
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   224
.. index::
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   225
  single: Completely replace the target
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   226
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   227
Completely replace the target
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   228
:::::::::::::::::::::::::::::
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   229
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   230
Just define the custom target::
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   231
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   232
    <target name="hello">
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   233
        <echo message="Custom hello!"/>
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   234
    </target>
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   235
    
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   236
.. index::
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   237
  single: Run custom code after the target
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   238
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   239
Run custom code after the target
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   240
::::::::::::::::::::::::::::::::
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   241
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   242
Define the overriding custom target and make it depend on the original target::
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   243
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   244
    <target name="hello" depends="common.hello">
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   245
        <echo message="After hello!"/>
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   246
    </target>
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   247
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   248
.. index::
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   249
  single: Run custom code before the target
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   250
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   251
Run custom code before the target
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   252
:::::::::::::::::::::::::::::::::
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   253
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   254
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::
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   255
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   256
    <target name="pre-hello">
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   257
        <echo message="Before hello!"/>
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   258
    </target>
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   259
    
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   260
    <target name="hello" depends="pre-hello,common.hello"/>
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   261
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   262
.. index::
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   263
  single: Call a target with different params
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   264
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   265
Call a target with different params
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   266
:::::::::::::::::::::::::::::::::::
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   267
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   268
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::
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   269
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   270
    <target name="localisation-roms">
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   271
        <for list="${localisation.makefile.target}" delimiter="," param="target" >
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   272
            <sequential>
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   273
                <antcall target="localisation-32.localisation-roms">
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   274
                    <param name="localisation.makefile.target" value="@{target}"/>
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   275
                </antcall>
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   276
            </sequential>
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   277
        </for>
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   278
    </target>
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   279
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   280
.. index::
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   281
  single: Using Helium internal tasks and macros
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   282
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   283
Using Helium internal tasks and macros
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   284
--------------------------------------
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   285
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   286
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.
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   287
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   288
Helium tasks start with the prefix ``hlm:``, for example::
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   289
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   290
    <target name="do-signal">
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   291
        <hlm:signal name="testSignal"/>
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   292
    </target>
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   293
    
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   294
To include an XML element with a ``hlm:`` prefix the Helium namespace must be defined in the root element of the XML file::
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   295
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   296
    <project name="myproject" xmlns:hlm="http://www.nokia.com/helium">
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   297
    ....
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   298
    </project>
588
c7c26511138f helium-10.0.0-bc45d50958fe
wbernard
parents: 587
diff changeset
   299
    
c7c26511138f helium-10.0.0-bc45d50958fe
wbernard
parents: 587
diff changeset
   300
If it is necessary to use the Helium tasks before importing ``helium.ant.xml``, first import ``helium_preinclude.ant.xml``, e.g::
c7c26511138f helium-10.0.0-bc45d50958fe
wbernard
parents: 587
diff changeset
   301
c7c26511138f helium-10.0.0-bc45d50958fe
wbernard
parents: 587
diff changeset
   302
    <project name="helium-test" default="test" xmlns:hlm="http://www.nokia.com/helium"> 
c7c26511138f helium-10.0.0-bc45d50958fe
wbernard
parents: 587
diff changeset
   303
        <description>
c7c26511138f helium-10.0.0-bc45d50958fe
wbernard
parents: 587
diff changeset
   304
        Helium pre include test.
c7c26511138f helium-10.0.0-bc45d50958fe
wbernard
parents: 587
diff changeset
   305
        </description>
c7c26511138f helium-10.0.0-bc45d50958fe
wbernard
parents: 587
diff changeset
   306
        <property environment="env"/>
c7c26511138f helium-10.0.0-bc45d50958fe
wbernard
parents: 587
diff changeset
   307
        <import file="${helium.dir}\helium_preinclude.ant.xml"/>   
c7c26511138f helium-10.0.0-bc45d50958fe
wbernard
parents: 587
diff changeset
   308
            
c7c26511138f helium-10.0.0-bc45d50958fe
wbernard
parents: 587
diff changeset
   309
        <target name="test">
c7c26511138f helium-10.0.0-bc45d50958fe
wbernard
parents: 587
diff changeset
   310
           <hlm:logtoconsole action="stop"/>
c7c26511138f helium-10.0.0-bc45d50958fe
wbernard
parents: 587
diff changeset
   311
                <echo>Should not print anything.</echo>
c7c26511138f helium-10.0.0-bc45d50958fe
wbernard
parents: 587
diff changeset
   312
           <hlm:logtoconsole action="resume"/>
c7c26511138f helium-10.0.0-bc45d50958fe
wbernard
parents: 587
diff changeset
   313
           <echo>Should print something.</echo>       
c7c26511138f helium-10.0.0-bc45d50958fe
wbernard
parents: 587
diff changeset
   314
        </target>
c7c26511138f helium-10.0.0-bc45d50958fe
wbernard
parents: 587
diff changeset
   315
        
c7c26511138f helium-10.0.0-bc45d50958fe
wbernard
parents: 587
diff changeset
   316
        <import file="${helium.dir}\helium.ant.xml"/>           
c7c26511138f helium-10.0.0-bc45d50958fe
wbernard
parents: 587
diff changeset
   317
    </project> 
c7c26511138f helium-10.0.0-bc45d50958fe
wbernard
parents: 587
diff changeset
   318
1
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   319
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   320
.. index::
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   321
  single: System definition configuration files
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   322
587
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents: 217
diff changeset
   323
System Definition configuration files
1
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   324
:::::::::::::::::::::::::::::::::::::
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   325
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   326
Sysdef configuration defines the source code you actually want to compile with Helium. More information about the System definition
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   327
files can be found from: http://developer.symbian.org/wiki/index.php/System_Definition. 
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   328
587
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents: 217
diff changeset
   329
``helium/tests/minibuilds/qt/minibuild_compile.sysdef.xml`` can be examined as a sample definition file.
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents: 217
diff changeset
   330
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 
1
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   331
perform whilst compiling the components e.g. run toucher.exe on certain directories. You will need to make sure this file exists and contains 
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   332
the correct components when building and especialy for a product which consists of many hundreds of components. It should be possible to use 
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   333
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 
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   334
order to make sure you also get the special instructions which are required to make the builds create a ROM image successfully (or any
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   335
other action requested).
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   336