System Definition File Elements

This section describes the elements and attributes in the system definition XML file.

The system definition file describes the layers, blocks, sub-blocks, collections, and components that constitute the system model.

Note: Besides the system model information, the system definition file also contains build configuration information for different versions of Symbian platform. This document is concerned primarily with the system model elements.

The master system definition file is located at \src\common\Generic\tools\build\variability\vp_data\templates\System_Definition_Template.xml. It is delivered in the tools_utils_cedar CBR package. This version contains all of the components in Symbian platform.

A build-specific version of the file can be found in \epoc32\data\system_definition.xml It is also delivered in the tools_utils_cedar CBR package. This version contains only those components available in the specific build, for example M04676_Symbian_OS_v9.5. This version contains an extra entity for the build system. When it is used to generate the system model, however, the system build entity can be safely ignored.

System model hierarchy

The following screenshot shows the system model part of the system definition file.

System definition file


System definition file

The following figure shows the hierarchy of the system model elements.

System model elements hierarchy


System model elements hierarchy

System model elements

This section explains the system model elements and their attributes.

General rules

Name attribute

Names of system model items are identified using the name="value" pairs. Each item name must be globally unique and meaningful. The item name value can contain spaces and must be human-readable, for example, "Front End Processor".

Boolean values

An attribute with a boolean value is implicitly N–no. To make the system definition file clean, specify the attribute only if its value is Y–yes. For example do not write plugin="N" .

Path values

Paths are used to locate the MRP and bld.inf files. Path values use the network-style separator "/" instead of the Windows-style separator "\".

<SystemDefintion>

Syntax

<!ELEMENT SystemDefinition ( systemModel )>
<!ATTLIST SystemDefinition
  name CDATA #REQUIRED
  schema CDATA #REQUIRED
>

Example

<SystemDefinition name="MCL" schema="2.0.0"> 
                  ...
</SystemDefinition>

Attributes

Element

Attribute

Value description

<SystemDefinition>

name

Required. Any given value following the name attribute rule above.

schema

Required. The version of the current Symbian system definition syntax is 2.0.0.

<systemModel>

Syntax

<!ELEMENT systemModel (layer+)>

Example

<SystemDefinition>
 <sytemModel>
         ....
 </sytemModel>
</SystemDefinition>

Attributes

There are no attributes for this element.

<layer>

Syntax

<!ELEMENT layer (block* | collection*)*>
<!ATTLIST layer
  name CDATA #REQUIRED
  levels NMTOKENS #IMPLIED
  span CDATA #IMPLIED
>

Example

<systemModel>
  <layer name="Tools and Utils and SDKENG" levels="SDK tools test">
   <block name="System Build and Test">

Attributes

Element

Attribute

Value description

<layer>

child elements: <block> or <collection>

name

Required. Any given value following the name attribute rule above.

levels

Optional. A space-separated list of level names. It specifies the vertical sub-layering for the layer.

span

Optional. An integer n other than 1 will make the layer appear to the right of the previous n layers. If not present, the default value is 0.

levels, level and span

The levels, level and span attributes are usually used together on a layer, block or collection. They determine where the elements appear in the system model diagram.

Collections can be stacked on top of each other within their layer, block or sub-block. Blocks can also be stacked on top of each other in a layer. They are shown in different levels in the system model diagram.

The level attribute is an ID for a layer or a block. The level of a child element must be one of the names listed in one of its parent levels. In the example below, layer1 defines three levels: a, b and c. Its blocks must use a, b or c for their level attributes.

<layer name="layer1" levels="a b c">
 <block name="block1" level="a"/>
 <block name="block2" level="b"/>
 <block name="block3" level="c"/>
 <block name="block4" level="b"/>
</layer>

In a collection, if the block does not define the levels, the levels of the layer must be used. If both block and layer define levels, the levels of the element's closest ancestor are used. In the example below, collections under block1 use the levels from layer2, and collections under block2 use the levels of block2.

<layer name="layer2" levels="d e f">

 <block name="block1" >
  <collection name="collection1" level="d">...</collection>
  <collection name="collection2" level="f">...</collection>
  <collection name="collection3" level="e">...</collection>
  <collection name="collection4" level="e">...</collection>
 </block>

 <block name="block2" levels="x y z">
  <collection name="collection5" level="x">...</collection>
  <collection name="collection6" level="y">...</collection>
  <collection name="collection7" level="z">...</collection>
  ...
 </block>

  ...

</layer>

In the system model diagram, levels are drawn from the bottom to the top based on their order in the XML file. In the example below, the blocks in the Kernel Services layer are drawn in two levels: kernel on bottom and user on top.

<layer name="Kernel Services" levels="kernel user">
  <block name="Kernel-side Services" level="kernel">
   ...
  </block>
  <block name="User-side Services" level="user">
   ...
  </block>
</layer>

The span attribute is an integer value. For a layer, the span value n other than 1 makes the layer appear to the right of the previous n layers and equal to them in height. In the example below, the Java J2ME layer has span="2".

<layer name="Kernel Services and Hardware Services">...    </layer>
<layer name="Base Services">...   </layer>
<layer name="OS Services">...    </layer>
<layer name="Application Services">...    </layer>
<layer name="UI Framework">...    </layer>
<layer name="Java J2ME" span="2">...    </layer>

span for a layer


span for a layer

For a block, the span must be set along with the level attribute. A block with both span and level ends at the specified level and has a height of span number of levels. In the example below, the Core Build System block ends at the application level and spans down to the core level.

<layer name="Layer" levels="core apps emulation">
  <block name="Core Build System" level="apps" span="2" levels="lower upper">
      <!-- spans core and apps -->
        ...
  </block>
  <block name="Emulator Build" level="emulation">...       </block>
  <block name="Hardware" level="core"> ...      </block>
  <block name="Libraries" level="apps"> ...      </block>
  <block name="Simulation" level="emulation"> ...      </block>
</layer>

span for a block


span for a block

A sub-block always spans the full height of the block.

Symbian system definition file shows simple and practical use of levels and level. It defines the levels in a layer or a block for a collection to take. The span attribute is not used in the v9.4 and v9.5 Symbian system definition files, but it is used in v9.3 and earlier models.

<block>

Syntax

<!ELEMENT block (subblock* | collection*)*>
<!ATTLIST block
  levels NMTOKENS #IMPLIED
  span CDATA #IMPLIED
  level NMTOKEN #IMPLIED
  name CDATA #REQUIRED>

Example

<layer name="Kernel Services" levels="kernel user">
 <block name="Kernel-side Services" level="kernel">
 ...
 </block>
 <block name="User-side Services" level="user">
 ...
 </block>
</layer>

Attributes

Element

Attribute

Value description

<block>

child elements: <subblock> or <collection>

name

Required. Any given value following the name attribute rule above.

level

Optional. For more information, see the <layer> element.

span

Optional. Used when a block has the level attribute. The value must be 1 or more and cannot be greater than the number of levels in the parent <layer>. If not present, the default value is 1. For more information, see the <layer> element.

levels

Optional. For more information, see the <layer> element.

<subblock>

Syntax

<!ELEMENT subblock (collection)*>
<!ATTLIST subblock name CDATA #REQUIRED>

Example

<layer name="OS Services">
      <block name="Base Services" levels="physical-abstraction app-libs 
                   translation data-services utilities">
        <subblock name="Generic OS Services">
          <collection name="Generic Services" level="utilities">

Attributes

Element

Attribute

Value description

<subblock>

child elements: <collection>

name

Required. Any given value following the name attribute rule above.

<collection>

Syntax

<!ELEMENT collection (component)*>
<!ATTLIST collection
  name CDATA #REQUIRED
  level NMTOKEN #IMPLIED>

Example

<block name="Comms Services" levels="physical-abstraction bearer-manager internal-utils servers extensions utilities">
    <subblock name="Communications Framework">
     <collection name="Comms Process and Settings" level="utilities">
      <component name="Comms Root Server" introduced="7.0s">

Attributes

Element

Attribute

Value description

<collection>

child elements: <component>

name

Required. Any given value following the name attribute rule above.

level

Optional. For more information, see the <layer> element.

<component>

Syntax

<!ELEMENT component (unit)*>
<!ATTLIST component
  name CDATA #REQUIRED
  deprecated CDATA #IMPLIED
  introduced CDATA #IMPLIED
  contract CDATA #IMPLIED
  plugin (Y|N) "N"
  filter CDATA #IMPLIED
  class NMTOKENS #IMPLIED
  supports CDATA #IMPLIED>

Example

<component name="Hardware Resources Manager Config" introduced="9.5" class="config">
 <unit bldFile="common/generic/telephony/hwrm/config"
   mrp="common/generic/telephony/hwrm/config/telephony_hwrm-config.mrp"/>
</component>

Attributes

Element

Attribute

Value description

<component>

child elements: <unit>

name

Required. Any given value following the name attribute rule above.

deprecated

Optional.The release number when the component was deprecated, for example, deprecated="9.5". If not present, the component has not been deprecated.

introduced

Optional. The release number when the component was first added, for example, introduced="9.5". If not present, the age of the component is unknown.

plugin

Optional. A boolean value Y or N to indicate if a component is a plug-in. If not present, the default value is N–not a plug-in.

contract

Deprecated–do not use.

supports

Deprecated–do not use.

class

Optional. A space-separated list of values to indicate functional properties of the component. For information on the class values, see the following table.

filter

Optional build-related attribute. A comma-separated list of filters. The Symbian build system uses the filters to control the build contentsfor a specific platform, such as "techview" or "gt".

The following table lists the valid class values for a component:

class Value

Definition

doc

The component contains only documentation. Doc components are hidden by default in the System Model.

test

The component contains only tests. The component is hidden by default in the System Model.

config

The component contains configuration files used by another component. The component is hidden by default in the System Model.

placeholder

The component has not been delivered. The entry in the system definition file is to capture the proposed properties and location of the component. A placeholder component does not have units.

PC

The component is intended to be run on a PC, not a phone. Applications such as M-Router are run on a PC and not intended for a phone.

<unit>

Syntax

<!ELEMENT unit EMPTY>
<!ATTLIST unit
  mrp CDATA #IMPLIED
  filter CDATA #IMPLIED
  bldFile CDATA #IMPLIED
  root CDATA #IMPLIED
  version NMTOKEN #IMPLIED
  prebuilt NMTOKEN #IMPLIED
  late (Y|N) #IMPLIED
  priority CDATA #IMPLIED>

Example

<component name="After Market Application Starter" introduced="9.5">
 <unit bldFile="common/generic/app-framework/amastart/group"
   mrp="common/generic/app-framework/amastart/group/app-framework_amastart.mrp"/>
</component>

Attributes

Element

Attribute

Value description

<unit>

mrp

Optional and build-related attribute. The name and location of the MRP file.

filter

Optional and build-related attribute. For more information, see the <component> element.

bldFile

Optional and build-related attribute. The directory containing the bld.inf file.

root

Optional and reserved for future use.

version

Optional and build-related attribute. A word (no spaces) identifier to differentiate multiple units in a component. The value must be unique within the component. Usually there is a single unit for each component. The system definition allows any number of units for a component, but the units are a list of alternatives. In this case, a unit is uniquely identified by a combination of the component name and the unit version.

For prebuilt components the attribute is mandatory and its value must be the CBR version, for example M04066_Symbian_OS.

For non-prebuilt components, the attribute is only mandatory if there is more than one unit. In this case the version can be any unique value. Usually, it is given a number in the form of version="1", version="2" or version="3.1.4".

See more unit examples below.

prebuilt

Optional and build-related attribute. The name of the pre-built CBR package to be used in the build, for example, <unit version="93_161_Symbian_OS" prebuilt="MAS"/>. This is only valid for pre-built components. If it is present a version must also be specified. .

late

Optional and build-related attribute. A boolean value. If the late attribute is set to Y for a pre-built component the build system ensures the rest of the system has no compile-time dependencies on this component. It also means the component can only be acquired via CBR’s getrel command after all non-prebuilt components are built.

priority

Optional and build-related attribute. A numeric value to indicate to the build system the order of processing the bld.inf when building all components.

Single unit example

The most commonly used unit element is a single unit. The component has only a single version delivered by the system definition.

<component name="After Market Application Starter" introduced="9.5">
 <unit bldFile="common/generic/app-framework/amastart/group"
   mrp="common/generic/app-framework/amastart/group/app-framework_amastart.mrp"/>
</component>

Zero unit example

An empty component contains no units. The component is not built but appears in the system model diagram unless it is filtered out. It is a placeholder for a future component. The component has been defined but has not delivered any code yet. A placeholder can have any attributes, for example class or plug-in. Comments about its usage are usually provided.

<collection name="Logical Device Drivers">
 <component name="Ethernet Driver" class="placeholder">
    <!-- common to EKA1 and EKA2   -->
 </component>
 <component name="Other LDDs" class="placeholder">
    <!-- unit name="" bldFile="" mrp="" -->
 </component>
 <component name="USB Driver" class="placeholder">
    <!-- unit name="" bldFile="" mrp="" -->
 </component>
</collection>

          

Multiple units example

The system definition allows any number of units for a component but the units are a list of alternatives. Multiple units are used to point to different MRP files or to specify different properties in the XML, such as filters or priorities. Filters and variation point bindings in the build system ensure that at most one unit is built for a CBR component.

<component name="ESock Server Configuration" introduced="9.1" class="config">
 <unit mrp="common/generic/comms-infras/esock/version2/group/comms-infras_esock-config.mrp" version="2">
 <unit mrp="common/generic/comms-infras/esock/group/comms-infras_esock-config.mrp" version="1">

Single package example

A package component has an MRP file, but no bld.inffiles. This means that it is not built as part of a production build, but is packaged as part of the delivery.

<component name="IP Administration Tool" class="test" introduced="7.0">
 <unit mrp="common/generic/networking/ipadm/group/networking_ipadm.mrp"/>
</component>

Prebuilt packages example

<component name="Mobile Active Sync">
 <unit prebuilt="MAS" version="M04372_Symbian_OS"/>
</component>