buildframework/helium/doc/src/manual/sysdef3.rst
author wbernard
Sun, 10 Oct 2010 15:22:15 +0300
changeset 645 b8d81fa19e7d
parent 628 7c4a911dc066
permissions -rw-r--r--
helium_12.0.0-63b64366f9cf
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
587
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
     1
System Definition v3 support
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
     2
============================
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
     3
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
     4
Helium is now supporting System Definition v3 to achieve build. This document explains how to configure Helium and 
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
     5
 how input files are handled in the tool.
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
     6
 
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
     7
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
     8
How to configure the feature?
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
     9
-----------------------------
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    10
628
7c4a911dc066 helium_11.0.0-e00f171ca185
wbernard
parents: 588
diff changeset
    11
In order to enable the support you first need to define the **sysdef3.enabled** property to true. Then define a resource ant element to either 
587
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    12
point to root definition file or package_definition.xml file.
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    13
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    14
e.g:
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    15
::
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    16
   
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    17
   <path id="system.definition.files">
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    18
      <pathelement path="${build.drive}/sf_sytem_definition.xml" />
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    19
      <fileset dir="${build.drive}" includes="root/*/*/package_definition.xml" />
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    20
   </path>
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    21
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    22
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    23
The previous example shows how you can configure your build to includes packages pointed by the sf_sytem_definition.xml, and a
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    24
set of additional packages directly referenced (root system definition will then be generated automatically, see package_map.xml section).
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    25
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    26
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    27
Package_map.xml
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    28
---------------
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    29
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    30
The package_map.xml provides mapping information between the package and it physical location under the build environment. The following
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    31
example show how to write a package_map.xml file for a package that should be placed under sf/mw:
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    32
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    33
::
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    34
   
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    35
   <?xml version="1.0"?>
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    36
   <PackageMap root="sf" layer="mw" />
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    37
   
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    38
This information is also required to build from package_definition.xml file directly, so a valid root system model file can be generated
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    39
automatically.
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    40
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    41
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    42
The package_map.xml must be placed under the root directory of the package. **package_definition.xml** without package_map.xml are considered
628
7c4a911dc066 helium_11.0.0-e00f171ca185
wbernard
parents: 588
diff changeset
    43
as invalid by the copying step and the automatic root system definition file generation. Only exception to that rule is for the vendor 
7c4a911dc066 helium_11.0.0-e00f171ca185
wbernard
parents: 588
diff changeset
    44
package_definition.xml which must be placed exactly two level under the root of the package.
587
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    45
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    46
Example of package structure:
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    47
::
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    48
   
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    49
   + <root>
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    50
        + <layer>
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    51
             + <package>
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    52
                      - package_definition.xml
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    53
                      - package_map.xml
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    54
                      + component
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    55
                              + nokia_<component>_metadata
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    56
                                  - package_definition.xml  
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    57
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    58
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    59
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    60
Canonical system definition generation workflow
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    61
-----------------------------------------------
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    62
The following diagram describes the workflow of the canonical System Definition file generation.
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    63
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    64
.. image:: sysdefv3_workflow.png
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    65
    :align: center
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    66
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    67
The input of the workflow is the Ant resource identified by the **system.definition.files** id. Its content is then divided in two parts:
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    68
 * package_definition.xml files
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    69
 * other files considered as root system definition file.
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    70
 
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    71
The package_definition.xml (and package_map.xml) will be used to generated a root system file, which will be used
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    72
as any other root system definition file. The package_definition.xml will then be ignored from other operations.
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    73
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    74
Then workflow converges into the following regular operations:
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    75
 * joining each root system definition file into standalone model.
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    76
 * merging each root files.
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    77
 
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    78
The order of merging is defined by the order inside the resource, so to guaranty that order it is advised to use Ant path
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    79
element rather than filesets. Also the generated model is always included at then end. 
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    80
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    81