symbian system model xml syntax

© 2009 Symbian Foundation1

System Definition PkO training

Part 2:XML Syntax

<SystemDefinition sch

<systemModel name

<layer id="os" name

<package id="kerne

<package id="boar

<package id="ossrv

<package id="secur

<package id="persi

<SystemDefinitio <package id="re <collection id=" <component <unit bldFile </componen </collection>


Overview

• Basic System Definition XML syntax • Meaning and usage

• Common attributes and metadata

• Distributed system definitions

• The root system definition file• Syntax and contents: layers and packages

• Package definition files• Syntax and contents: packages, collections, components and units

• Non-Foundation system definitions• Vendor-specific models

• Merging system definitions


System Definition

basic syntax


Basic XML syntax

System Definition Syntax

• Uses XML format• Lots of existing tools for writing, processing, and validating

• Can validate XML by loading in any web browser

• Most sysdef tools written in Perl, Python or XSLT

• <SystemDefinition> is always root element• Specifies syntax version and defines namespaces

• Always has a single child:<systemModel> (root) system definition = system_definition.xml

<layer> layer definition = layer_definition.xml

<package> package definition = package_definition.xml

<collection> collection definition = collection_definition.xml

<component> component definition = component_definition.xml


Basic XML syntax

Document order

• Order of items in system definition indicates build order• Usually not significant, but sometimes proper order is essential

• Necessary for layers

• Order also shown on system model diagram• Bottom to top and left to right

• By convention, Foundation items are sorted by

1.Build practicalities (some items need to be forced to be built first)

2.Technology domain (for legibility)

3.Generic to specific (e.g. frameworks before plugins)

gene

ric

gene

ric

gene

ric

gene

ric

com

ms

com

ms

com

ms

com

ms

UIUI

UIUI

Runt

imes

Runt

imes

Runt

imes

Runt

imes

Tool

sTo

ols

Tool

sTo

ols


Basic XML syntax

System definition files in the Foundation• Stand-alone system definition

• All links are absolute paths and there are no links to sysdef fragments

• Contains all ranks of system definition elements• Generated – not hand-maintained

• Root system definition• Contains <systemModel>, <layer> and <package>

elements• Plus root <SystemDefinition> and optional <meta>

• Packages link to package definitions (all links are relative)• Defines the overall structure, but none of the content

• Sometimes called a skeleton• Maintained centrally

• Package definition files• Contains <package>, <collection>, <component>

and <unit> elements• Plus root <SystemDefinition> and optional <meta>

• Units link to MRP file and bld.inf directory• Most links are relative, but some can be absolute paths

• Defines only the internal package structure with no external context

• Maintained by the package owner• Other types of fragment system definitions are not

used in the Foundation

<SystemDefinition schema="3.0.0"> <systemModel name="Symbian^3"> <layer id="os" name="OS" levels="hw services"> <package id="kernelhwsrv" name="Kernel and Hardware Services" ...> <collection id="brdbootldr" name="Board Boot Loader" level="hw-if" > <component id="ubootldr" name="Boot Loader" ...> <unit mrp="/os/kernelhwsrv/brdbootldr/ubootldr/base_ubootldr.mrp" /> </component> </collection>

<SystemDefinition schema="3.0.0"> <systemModel name="Symbian^3"> <layer id="os" name="OS" levels="hw services"> <package id="kernelhwsrv" level="hw" tech-domain="hb" href="../../../../os/kernelhwsrv/package_definition.xml"/> <package id="boardsupport" level="hw" tech-domain="hb" href="../../../../os/boardsupport/package_definition.xml"/> <package id="buildtools" level="hw" tech-domain="to" href="../../../../os/buildtools/package_definition.xml"/>

<SystemDefinition schema="3.0.0"> <package id="kernelhwsrv" name="Kernel and Hardware Services"> <collection id="brdbootldr" name="Board Boot Loader" level="hw-if" > <component id="ubootldr" name="Boot Loader" ...> <unit mrp="brdbootldr/ubootldr/base_ubootldr.mrp" /> </component> </collection>


Basic XML syntax

Basic system definition syntax<SystemDefinition schema="3.0.0" id-namespace="http://www.symbian.org/system-definition"> <systemModel name="Symbian^3"> <layer id="os" name="OS" ...> <package id="kernelhwsrv" name="Kernel and Hardware Services" ...> <collection id="baseintegtests" name="Base Integration Testing" ...> <component id="baseintegrationtest" name="Base Integration Test" ...> <unit .../> </component> </collection> <collection id="brdbootldr" name="Board Boot Loader" ...> <component id="ubootldr" name="Boot Loader" ...> <unit .../> </component> </collection> <collection id="bsptemplate" name="BSP Template" ...> <component id="asspandvariant" name="Template ASSP and Variant" ...> <unit .../> </component> </collection> <collection id="kernel" name="Kernel Architecture" ...> <component id="eka" name="Kernel Architecture" ...> <unit .../> </component> </collection> <collection id="kerneltest" name="Kernel Test" ...> <component id="e32utils" name="E32 Utilities" ...> <unit .../>

• The root element• Contains entire document

• Defines syntax version + ID namespaces

• Common attributesid – unique identifier for referencing items

name – human-readable name describes items

href – include a sysdef fragment

before – controls position when merging

• Container elements<systemModel> contains <layer>

<layer> contains <package>

<package> contains <collection>

<collection> contains <component>

<component> contains <unit>

• All can contain <meta>• Except <unit> and <SystemDefinition>


Basic XML syntax

Unique IDs

• All items in a system definition must have a globally unique ID• i.e., Layers, Packages, Collections and Components

• Globally unique means……tools can easily and unambiguously reference any item…all system model items (anywhere in the Foundation ecosystem) with the same ID are

implicitly the same item• Used for merging models together

…ID collisions are avoided by using namespaces

• A system model ID is……an abbreviated form of the human-readable name

…The ID must be recognisably similar, but can be altered for claritye.g. httpfilterproxy “HTTP Proxy Filter” (it’s a filter that acts as an HTTP proxy, not a proxy for an HTTP filter)

…a valid XML ID (it cannot begin with a number)

…lowercase and without any periods (.) or dashes (-)• Colons (:) can only be used for namespaced IDs. • Underscores (_) should be avoided, but are acceptable to avoid a name collision

…used for the item’s directory name


Basic XML syntax

Namespacing IDs

• All IDs have a namespace, either explicit or implicit

• Namespaces are used to avoid ID collisions between vendors and the Foundation

• Within a document, the ID can be treated as an opaque unique identifier

• Processors dealing with stand-alone sysdefs do not need to understand namespaces

• It is an error to define the same namespace twice in a single document

• Between documents, the namespace must also be compared• Merging system definitions

• Merging element’s content

• Controlling order using “before” attribute

• Resolving references for XML overlays e.g. sysinfo’s “ref” attribute


Basic XML syntax

ID namespaces

• IDs are namespaced using the standard XML namespace syntax – this can take one of two forms:

• Prefixed: an ID with a colon in the form “prefix:id ” • prefix is the namespace identifier – The namespace itself must be declared in the

same element or an ancestor of that element• Declarations are recommended to be done in the root element, although that is not always

practical

• Processors must throw a fatal error when missing a namespace declaration

• id is the local part of the ID and must be unique within the defined namespace

• Default: an ID in the form “id ” with no colon • When no namespace prefix is present, the ID uses the namespace URI as defined in

<SystemDefinition id-namespace="uri">• or “http://www.symbian.org/system-definition” if id-namespace is not present

! The default namespace for IDs is not the same as the default XML namespace as specified by xmlns="…"

• Processors can handle namespaces as they see fit when merging or joining documents, as long as the result has the same meaning

• However, it is recommended that:• When joining sysdefs, the namespace prefixes of the root document are used

• When merging sysdefs, the namespace prefixes of the upstream document are used

http://www.w3.org/TR/xml-names


Basic XML syntax

ID namespaces (cont)

• By convention, Foundation system definitions only use the default ID namespace.

• No prefixed IDs appear in a Foundation sysdef, since all items are owned by the Foundation.

• Vendor-specific sysdefs will generally choose one of these options:

1. Use the Foundation namespace as the default, and prefix their own items

2. Use their namespace as the default and prefix foundation items

<SystemDefinition id-namespace="http://www.nokia.com/schema/drd/system-definition" xmlns:sf="http://www.symbian.org/system-definition"

<package id="sf:netprotocols"…>

<collection id="wapstack"…>

<SystemDefinition id-namespace="http://www.symbian.org/system-definition" xmlns:nokia="http://www.nokia.com/schema/drd/system-definition"

<package id="netprotocols"…>

<collection id="nokia:wapstack"…>

=


Basic XML syntax

Naming• The name attribute is a brief human-readable description of an item’s content

• The name is used when documenting the item

• By convention, must be set for all Foundation items• Optional for vendor-specific models

• If name is not set, id will be used for documentation

• Foundation names use US-English spelling (like when coding)• Vendor specific names can be in any language, but using US-English makes them easier to share

• Localisation tools should be used to translate to other languages , eg on a System Model diagram

• Names should be in "title" case• Capitalise the first letter of all words except conjunctions ("and"), prepositions ("for") and case-

specific terms (“vCard")

• A word should not be in uppercase unless it's an acronym

• Names should be able to make sense to someone not familiar with Symbian OS• Understandable in context to someone in your field, but not in your company

• Avoid using Symbian or company-specific jargon

• Industry standard jargon is acceptable

• The higher the item's rank, the more general the name should be• Component and collection names can describe specific implementations

• Packages and layers should describe their content or technology

Example: “SQL” is in “Persistent Data Services”


Basic XML syntaxRelationship between items and the filesystem• Foundation requires system model items match their filesystem location

• File location:

• The directory name must match the item ID (without namespace) exactlyExample: <package id="sf:helps"> must be in the directory /app/helps

• Component build files are usually in the component’s group directoryExample: <component id="bteng"…>

<unit bldFile="/mw/btservices/bluetoothengine/bteng/group"/></component>

• Foundation files are required to be in standard locations• The sysdef syntax allows arbitrary file locations to avoid build breaks while non-conformant

code is being moved to the correct location

• Filesystem root is not visible in the system definition file• Absolute paths begin with the layer directory• Filesystem root is determined from the unit’s root attribute

• Layer and package levels provide additional organisation not present in the filesystem

•Model description:

<layer id="layer"> <package id="package"> <collection id="collection"> <component id="component">

layer package collection component/ / / /


Basic XML syntax

Metadata• <meta> is used to extend the system definition with custom information

• No standard usage in the Foundation yet• Planned for use with ConfML

• Vendors are free to use for their own purposes, however, do not submit vendor private data to the Foundation

• Metadata can be attached to any system model item from <systemModel> down to <component>

• Cannot be used in <SystemDefinition> or <unit> • Syntax

• Embedded metadata: <meta rel="usage-type" type="content-type">any content

</meta>• Linked metadata: <meta href="link" rel="usage-type" type="content-type"/> • Usage type (rel) describes the meaning of the information

• Default value is “Generic”, ie it has no well-defined meaning• Other values can be “Ownership”, “Dependencies”, etc

• Content type (type) describes the syntax of the content• Default value is “auto”, ie try to deduce from the context• Other values can be a MIME type (application/docbook+xml) or a well-known value (dita)

• Hyperlink (href) can be a relative path or absolute URI• Processors which cannot resolve the URI should ignore the link• Stand-alone system definitions should embed relative links and may embed other linked metadata


Basic XML syntax

Distributed system definitions

• Fragments can be included using the href attribute• Valid on <layer>, <package>, <collection> and <component> • Foundation only uses <package>• Either relative path or absolute URI• There are no items with hrefs in a stand-alone sysdef

• Linking item is combined with the topmost item in the fragment• IDs in linking element and linked fragment must match

• ID mismatch is a fatal error

Example: • Root doc: <package id="mm" … href="…/package_definition.xml"/>• Linked doc: <package id="mm" name="Multimedia" …>

• Duplicate attributes in the fragment are ignored• i.e., parent document always “wins”

• Creating a single system definition from multiple distributed system definitions is called joining


Basic XML syntaxJoining system definitionsExample

<SystemDefinition schema="3.0.0"> <systemModel name="Symbian^3"> <layer id="os" name="OS" levels="hw services"> <package id="kernelhwsrv" level="hw" tech-domain="hb" href="../../../../os/kernelhwsrv/package_definition.xml"/>

<SystemDefinition schema="3.0.0"> <package id="kernelhwsrv" name="Kernel and Hardware Services" levels="hw-if adaptation framework test"> <collection id="baseintegtests" name="Base Integration Testing" level="test"> <component id="baseintegrationtest" name="Base Integration Test" introduced="9.3" purpose="development"> <unit bldFile="baseintegtests/baseintegrationtest/group" mrp="baseintegtests/baseintegrationtest/group/base_integration_test.mrp"/> </component>

<SystemDefinition schema="3.0.0"> <systemModel name="Symbian^3"> <layer id="os" name="OS" levels="hw services"> <package id="kernelhwsrv" level="hw" tech-domain="hb" name="Kernel and Hardware Services"

levels="hw-if adaptation framework test"> <collection id="baseintegtests" name="Base Integration Testing" level="test"> <component id="baseintegrationtest" name="Base Integration Test" introduced="9.3" purpose="development"> <unit bldFile="/os/kernelhwsrv/baseintegtests/baseintegrationtest/group" mrp="/os/kernelhwsrv/baseintegtests/baseintegrationtest/group/base_integration_test.mrp"/> </component>

parent

child


The Root System

Definition


Root system definitions

Root System Definition

• Stores only the layers and package information under control of the Foundation

• Global• Syntax version • ID namespaces • Model name

• Layers• ID• Name• Levels

• Packages• ID• Tech domain

• Level + Span

• Link or name

<SystemDefinition schema="3.0.0"id-namespace="http://www.symbian.org/system-definition">

<systemModel name="Symbian^3"> <layer id="os" name="OS" levels="hw services"> <package id="kernelhwsrv" level="hw" tech-domain="hb"

href="../../../../os/kernelhwsrv/package_definition.xml"/> <package id="boardsupport" level="hw" tech-domain="hb"

href="../../../../os/boardsupport/package_definition.xml"/> <package id="buildtools" level="hw" tech-domain="to"

href="../../../../os/buildtools/package_definition.xml"/> …

</layer>

<layer id="mw" name="Middleware" levels="generic specific">

<package id="appsupport" level="generic" tech-domain="rt" href="../../../../mw/appsupport/package_definition.xml"/>

<package id="securitysrv" level="generic" tech-domain="se" href="../../../../mw/securitysrv/package_definition.xml"/>

…. </layer> <layer id="app" name="Applications" levels="services apps"> <package id="location" level="apps" tech-domain="lo"

href="../../../../app/location/package_definition.xml"/> <package id="mmsharinguis" level="services" tech-domain="vc" href="../../../../app/mmsharinguis/package_definition.xml"/> <package id="phone" level="apps" span="2" tech-domain="vc" href="../../../../app/phone/package_definition.xml"/> <package id="videotelephony" level="apps" tech-domain="vc"

href="../../../../app/videotelephony/package_definition.xml"/> <package id="poc" level="apps" tech-domain="vc" name="PoC"/>

… </layer> </systemModel> </SystemDefinition>



System Model name

• Overall name for the model is in the name attribute of the systemModel element in the root system definition file

<systemModel name="modelname">• The name can be any text. By convention is usually a single word• For Foundation models the name is Symbian^n

Example: <systemModel name="Symbian^3">• Vendor models can use their name, a codeline name, a release name, a

product name, etcExamples:

• <systemModel name="My model"> (arbitrary name)• <systemModel name="MCL"> (codeline name)• <systemModel name="Bravo"> (product name)

• Merging tools add an origin-model attribute to each component, containing the name of the model it came from

Example: <collection id="csxhelp" name="Context Sensitive Extended Help" level="if"> <component id="aiwhelpprovider" … origin-model="Symbian^3"> … </component> <component id="myhelp" … origin-model="MCL"> … </component></collection>



Layers

• Valid attributes: id, name, href, levels, span, before<layer id="id" name="name" levels="list" span="int" href="link" before="id-

ref">

• Layer name (name="name")• Brief description of overall purpose of layer’s content

• Layer ID (id="id" ) mandatory attribute• Abbreviated form of the name• Should be short (ideally 2-3 chars) to avoid overly long path names• Vendor-specific layers must be namespaced

• Links (href="link")• By convention, not used in Foundation system definitions.• Can link to a layer_definition.xml file

• Merging control (before="id-ref")• Specify the ID of a layer in an upstream sysdef that this layer is beforeExample: before="mw" this layer will be placed after os and before mw



• A layer’s levels attribute is used to control the vertical stacking of its packages

• Lower levels are closer to hardware• Higher levels are closer to the user / developer

• A layer with no levels has no vertical stacking• Equivalent to a layer with one level

• SyntaxExample:

<layer id="os" name="OS" levels="hw services">

• Space-separated list of names (XML NMTOKENS)

• Ordered from bottom to top (e.g. “hw” is under “services”)• Referenced from a contained package’s or collection’s level attribute

Layer levels



• Foundation layers have two levels each

• Foundation levels are associated with System State Domains

• System State Domains exist within an ordered hierarchy

• The position of the Domain within the hierarchy indicates the order state change notifications are sent to registered executables

• State changes propagate either up or down the hierarchy

e.g. lower levels are started first and terminated last

• Executables in a package that spans levels can use domain constants from any of the levels the package spans

Foundation layer levels

KSM2UiApplicationDomainn

KSM2UiServicesDomainn

KSM2AppServicesDomainn

KSM2GenMiddlewareDomainn

KSM2OSServicesDomainn

KSM2KernelServicesDomainnKSM2HALDomainn

Only used in boardsupport

Package

Level name Domain constant n = 1 ..

5



<package id="id" level="level" span="int" tech-domain="domain" href="link" version="version" before="id-ref"

name="name" levels="list">

Packages in the root system definition• Valid attributes: id, name, level, span, tech-domain, href, version, levels, before

• name and levels defined in the package_defintion.xml file• Other attributes are defined in the root sysdef since they’re not controlled by the Package

Owner• Names for placeholder packages should be specified in the root system definition

• Placeholder package = a future package with no package_defintion.xml file (yet)Example: <package id="poc" level="apps" tech-domain="vc" name="PoC"/> (no href)

• Package ID (id="id" ) mandatory attribute• Abbreviated form of the name• Should be short to avoid overly long path names• Vendor-specific packages must be namespaced

• Links (href="link")• Links to a package_definition.xml file• By convention all packages and their contents are defined in a package definition file

• Merging control (before="id-ref")• Specify the ID of a layer in an upstream sysdef that this layer is beforeExample: before="drm" this layer will be placed after securitysrv and before drm

• Package version (version="version" )• Reserved for future use



Package Names

• The name must be unique and self-explanatory• Must make sense to someone familiar with mobile phone

technology• Avoid industry jargon

• Standard names:• “xxx Apps” = user-facing applications• “xxx App Suite” = a set of related user-facing applications• “xxx UIs” = user interface elements for use within

user-facing applications• “xxx Daemons” = application-layer servers with no UI• “xxx Support” = essential utilities• “xxx Services” = provides an interface to a technology• “xxx Framework(s)” = provides the basis for a

technology,but not the implementation

• “xxx” = The lowest level implementation of a technology

Camera Apps, Home Screen Apps

Organizer Application Suite

Web UIs, Settings UIs

Content Control Daemons, Device Control Daemons

Generic App SupportBluetooth Services, Camera Services

OS Security, Graphics

Comms Framework, Service API Framework



Package level and span

• A package’s level attribute is used to specify its vertical stacking within its layer

<package level="level" span="int"> • Spanning packages have properties of

more than one level, but are associated with the highest level

• level and span are defined in same file as layer’s levels to ensure they stay in sync

• A package with no level spans the full range of the layer’s levels

• level with no span is equivalent to span="1"

! It is an error to have a span with no level! It is an error to have a level if the layer

has no levels

• Syntax• Must be defined in layer’s levels attribute

• Defined as XML NMTOKEN

• level indicates the topmost level for the package, span indicates number of levels downward

Examples:• Package at a single level

• Example package spanning two levels

OS

Kernel & HW

Services hw

s

ervi

ces

<layer id="os" name="OS" levels="hw services">

<package id="kernelhwsrv" level="hw"...>

Ex

am

ple

La

ye

r

My Apps

othe

rse

rvic

esap

ps

mor

e

<layer id="ex" name="Example Layer" levels="other services apps more">

<package id="myapps" level="apps" span="2" …>


Package Definition

Files


Package definitions

Package Definitions

• A “package definition” file is a system definition fragment which defines the content of a single package

• Also called a pkgdef file

• Stores the information under control of the package owner:• packages, collections and components

• By convention:• The filename is package_definition.xml

• It’s stored in the packages' root directory e.g. layer/package/package_definition.xml

• Vendor-owned pkgdefs live in a vendor-specific component in package_info

e.g. layer/package/package_info/vendor_package_metadata/package_definition.xml

• It does not link to any other system definition fragments


Package definitions

Package Definition syntax

• Global• Syntax version

• ID namespaces

• Package• ID

• Name

• Levels

• Collections

• Components

• Units

<SystemDefinition schema="3.0.0"id-namespace="http://www.symbian.org/system-definition">

<package id="ossrv" name="Generic OS Services" levels="physical-abstraction app-libs encoding translation data-services utilities">

<collection id="utilitylibraries" name="Utility Libraries" level="encoding"> <component id="libutils" filter="s60" name="Utility Library"> <unit bldFile="utilitylibraries/libutils/group"/> </component> </collection> <collection id="ofdbus" name="Open Foundation D-Bus" level="utilities"> <component id="dbus" filter="s60" name="D-Bus"> <unit bldFile="ofdbus/dbus/group"/> </component> <component id="dbus-glib" filter="s60" name="D-Bus GLib"> <unit bldFile="ofdbus/dbus-glib/group"/> </component>

… </collection> <collection id="compressionlibs" name="Compression Libraries"

level="data-services"> <component id="ziplib" name="Zip Compression Library" introduced="6.0" purpose="mandatory"> <unit bldFile="compressionlibs/ziplib/group" mrp="compressionlibs/ziplib/group/syslibs_ezlib2.mrp"/> </component> </collection> <collection id="genericopenlibs" name="Generic Open Libraries" level="translation"> <component id="cstdlib" name="C Standard Library"

introduced="ER5" purpose="optional">…

</component> …

</collection> </package> </SystemDefinition>


Package definitions

The package in a package definition

• Standard attributes: id, name, levels

<package id="id" name="name" levels="list" before="id-ref" version="version" level="level" span="int" tech-domain="domain">

• By convention, level, span, tech-domain and before are only set in the root system definition

• version is not in current use

• Package ID (id="id" ) mandatory attribute

• Must match the ID in the root system definition

• Abbreviated form of the name

• Should be short to avoid overly long path names

• Vendor-specific packages must be namespaced


Package definitionsPackage internal levelsaka collection levels• levels controls the vertical stacking of a

package’s collections• Lower levels interface hardware or layers below

• Highest provides, UIs, APIs, metadata and documentation

• Middle layers tend to be frameworks, engines, servers, plugins, internal tools, etc

• Syntax: <package … levels="list">

• Space-separated list of names (XML NMTOKENS)

• Referenced in a contained collection’s level attribute

Example: <package … levels="adaptation engines internal-adaptations device-interface internal-utils app-if">

• Ordered from bottom to top (e.g. “engines” is under “device-interface”)

Drivers

Interfaces for higher layers

Low-level implementation

High level device

abstraction

Low level interfaces

High-level utils


Package definitionsFoundation layer levels and package levels• Number of internal

levels in a package depends on its layer and level

• Spanning packages in App layer expose services and provide user-facing applications

apps

services

specific

generic

services

hw≤5 levels•Bottom reserved for dev. boards

≤6 levels

•Bottom reserved for device drivers

≤6 levels

≤5 levels•UI (if any) on top level

≤4 levels

≤4 levels

span=

"2"

≤8 levels


Package definitions

Collection syntax

• Valid attributes: id, name, level, href, before• href and before are not used in Foundation pkgdefs

• Contains only <component> and (optional) <meta> • Can only be used inside <package>

• Can be used in <SystemDefinition> in a collection definition file (not standard)

<collection id="id" name="name" level="level" before="id-ref" href="link">

Mandatory collection ID

Human-readable name

Named level for stacking

Reference for merging control(not used in Foundation pkgdefs)

Collection definition file (not used in Foundation pkgdefs)


Package definitions

Collection naming (name and id)

• The collection ID must be unique• The name should be unique

• Name describes the purpose or the content:• Purpose:

e.g. File Handling, Policy Management

• Content:e.g. USB Function Drivers• Names can be plural if it contains more than one type of the item

e.g. “xxx Tests”

• The ID should be singular e.g. “xxxtest”

• Name must make sense to someone familiar with the package’s technology

• Industry jargon is acceptable if there’s no terser way to describe it• The ID is an abbreviated form of the name

• Name and ID must be recognisably similar

• Vendor-specific collections must be namespaced

• Standard names:…Xxx Info…Xxx Examples…Xxx Tests…Xxx Plugins…Xxx Interfaces…Xxx Tools


Package definitions

Collection Level

• Syntax: <collection … level="level">• The level must be defined in the collection’s package or layer

• Collection level is named grouping of collections which indicate their relationship to each other

• Basic order of levels is: least externally visible on bottom, most “visible” on top

• Levels should follow existing or planned dependencies

• Collections containing APIs, tests, documentation, configuration, etc should be at or higher than the collections they describe

• Package-wide tests, APIs, etc should be on the top level

• Collections which are intended to "hide" other collections should be above them

• If a set of plugins are called automatically from a framework, the framework should be above the plugins

• Levels may also be used in a technology-specific wayExample: to describe the OSI comms stack (networkingsrv)

Example: to group applications by type (techview)


Package definitions

Component syntax

• Standard attributes: id, name, deprecated, introduced, class, target, purpose, filter,

• Other attributes: href, before, origin-model

• Contains only <unit> and (optional) <meta>

• Can only be used inside <collection>

<component id="id" name="name"

deprecated="deprecated" introduced="introduced"

class="class-list" target="target" purpose="purpose"

filter="filter"

href="link" before="id-ref" origin-model="name">

Mandatory ID

Human-readable name

Reference for merging control

informational

Generated when merging

Component definition file

Build-related


Package definitions

Component name and ID

• The component ID must be unique• The name should be unique

• The ID is an abbreviated form of the name• Name and ID must be recognisably similar

• Vendor-specific components must be namespaced• The name must make sense to someone well versed in the package’s technology

• Well-known (to a technology) acronyms, jargon are acceptable, eg HTTP, TTS, PoC, SUPL

• Component names should be brief – try to keep under 6 words• Component names should avoid Symbian-specific acronyms

• A component can use an internal acronym if it's spelled out in the collection or packageExample: <collection … name="Multimedia Host Process">

<component … name="MMHP Video Client">

• Symbian-specific terms can be used if it’s essential to the implementationExample: "SIS Installer" is better than "Package Installer" since it uses only SIS filesExample: "Camera Framework" is better than "ECam" since ECam is an internal

development name


Package definitions

Component naming conventions

• Components which provide package-wide data or information are commonly named after the package:

• “Package-name Documentation”, “Package-name Metadata” , “Package-name Platform Interfaces”, “Package-name ROM”, etc

• The name describes the functionality, not how that functionality is implemented• Avoid terms like "files", "code", "types", "classes", etc.

• Instead of "xxx Example Code", use "xxx Examples“

• Instead of "xxx IBY Files" call it "xxx ROM" (since it’s the component used to build a ROM)

• Instead of "types" and "classes", use "API", "Library" or "Utilities“

• Avoid “common” and “generic” in component names• They’re ambiguous terms that could be used anywhere to describe anything

• Could mean “core to the technology” or “supports the technology”• Use “Core” or “Utils” instead

• Package owners should not accept components with the word "common" or "generic" in the name without strong justification


Package definitions

Component naming (cont)

• Singular or plural?• Component names should be singular, while collections can be plural. • A component could be called "xxx API", while its collection, could be called "yyy APIs".

(or “yyy Interfaces”)• "API", "Engine", "Framework", "Library”, etc should not be plural in a component

name (but can be in a collection)• Rule of thumb: if you are tempted to call a component "xxx Engines", then it’s likely

you should make more than one component• "Grab bag" components (ie ones that hold sets of related items) can be plural

• Acceptable plural components: "... Examples", "... Tests", "... Plugins", "... Utils“• Note: these words are not required to be plural, it is just acceptable if they are

• Abbreviations and other popular terms• Avoid abbreviations – the human-readable name should be full and complete

• Words can appear abbreviated on the System Model by using an abbreviation dictionary• Acceptable abbreviations: "Utils" or "Utilities", "App" or "Application" • Preferred forms: use "Config" instead of “Configuration”, “Plugin” instead of “plug-in”

• Either “Plug-in” or “plugin” is acceptable in documentation• Do not use "&", always use “and”

• Except in terms like “R&D”


Package definitions

Introduced

• Syntax: <component … introduced="release"> • Value is the release number when the component was first produced

• Older values are Symbian-release based (eg. ER5, 6.0, 7.0s, 8.1b, 9.3, etc)• New components should use Foundation caret syntax (eg. ^3, ^4, etc)• Vendor-specific components can use internal versions (eg. tb92, tb101, etc)

• If not set, the age of the component is unknown• Always set when creating a new component• Primarily used to identify which components are new for given release

• Identifies planned future release for placeholder components• Also helps identify mature or potentially obsolete components

Examples:<component id="httptransportfw" name="HTTP Transport Framework" introduced="6.2" …

>

<component id="massstoragemgr" name="Mass Storage Manager" introduced="^3" …>

<component id="connectivityfw" name="Connectivity Framework" introduced="7.0s" …>


Package definitions

Deprecated

• Syntax: <component … introduced="release">

• Value is the release number when the component was first deprecated

• Syntax is the same as introduced

• Deprecated components are provided for backwards compatibility or developer convenience

• Always document with an alternative for developers

• Usually removed one major release after official deprecation

Examples:• <component id="connectivityfw" name="Connectivity Framework"

deprecated="^2" …>

• <component id="plpremotelink" name="PLP Remote Link" deprecated="9.0" …>

• <component id="dial" name="Dial" deprecated="9.1" …>

Foundation caret notation

Old Symbian release

numbers


Package definitions

Purpose

• Syntax: <component … purpose="purpose"> • Advises developers and device manufacturers where and how a component can be used • Value is one of the following set:

"mandatory"• Provides core functionality for a package• Strongly recommended to appear on all commercial devices

• Developers can safely statically link to mandatory DLLs

• Mandatory components cannot depend on optional ones• A non-contributed component cannot be mandatoryExample: <component id="euser" name="User Library" purpose="mandatory">

"optional"• Production quality component that can be used on a commercial device or end-user's desktop• Includes development tools for third party developers which can appear on a commercial device• DLLs should be dynamically linked against or tested for at install timeExample: <component id="cstdlib" name="C Standard Library" purpose="optional" …>

"development"• Intended for development (R&D) use only• Must not appear on a commercial device

• Not production quality, may have significant security risks, or may not be practical for a real device

• Most tests fall into this category• Also tools necessary for building, but not shipping, a deviceExample: <component id="e32utils" name="E32 Utilities" purpose="development">


Package definitions

Target

• Syntax: <component … target="target"> • The type of platform where the component's deliverables are intended to be

used• Value is one of the following set:

"device" (default value – implied if not set)• Provides at least one deliverable for use on a device

• Includes components that just export header files used for building device components• Can be test or production

• A component with both device and desktop deliverables, should be classed as “device”e.g. a component which has scripts which are necessary for building device binaries would be classified

as “device

Example: <component id="userpromptutils" name="User Prompt Utils" target="device" …>

"desktop" • The deliverables are intended to be installed or run on a desktop

• Usually build tools used on a developer's desktop• Also includes deliverables intended for an end-user's desktope.g. end-user documentation or a desktop suite

Example: <component id="securitytools" name="Security Tools" target="desktop" …>

"other" • In case the above do not adequately describe the component's intended target• Avoid using if possible• Include a comment in the XML if it’s not obvious


Package definitions

Classes

• Syntax: <component … class="class1 class2 class3 …">

• The class is a set of standard informational tags which indicate functional properties

• A component can have any number of classes• Most components have no specified class

• The list is space-separatedExample: class="plugin tool" – indicates component provides a tool that’s a plugin

• Syntax is the same as HTML class attribute

• Standard classes are: plugin, doc, config, tool, api

• Avoid using custom classes in the Foundation system definition• Vendors can add extra classes to their own components, but should publish

their meaning if they are shared with downstream vendors

• New standard classes should be agreed with the Foundation


Package definitions

Filter

• Syntax: <component … filter="filter1,filter2,filter3,…"> • Filters is a list of build properties of component and is used to configure out

components or units from a specific type of build• List is a comma-separated list of tokens• Order does not matter• Can be prefaced by “!” to indicate it’s only to be used when the specified filter is off

• Can be used to……divide the system into build phases – used when dependencies can’t be described

via layers or deduced from the build filesExample: The Tools Model contains “build_SFPhase1” and “build_SFPhase2”, etc to split the

build up and force components to be built in the proper order

…define an optional additional buildExample: filter="test" is to ensure test components are not built as part of a normal

system build, but are optionally built after production components

…define a mutually exclusive set of components to turn on or off a significant featureExample: filter="java" was used to identify components to be built only when java is

turned on. The opposite, filter="!java", was used for components to be built only when java was turned off (usually stub implementations)


Package definitions

Origin model

• Syntax: <component … origin-model="name">

• The origin-model attribute is added to a component when system definition files are merged

• The value comes from the name in <systemModel name="name">

• When both models have the same name, the origin-model value will be upstream or downstream depending on which model it comes from

• Tools can provide the option to set to arbitrary values

• This attribute should never be set manually

• Examples:• Foundation component:

<component id="usbmsfs" name="USB Mass Storage File System" … origin-model="Symbian^3">

• Vendor-specific:<component id="n:evalid" name="Evalid" … origin-model="Nokia TB9.2">


Package definitions

Unit syntax

• Standard attributes: bldFile, mrp, base, root, version, filter, prebuilt, late

• Unused attributes: priority

• Empty element

• Can only be used inside <component>

<unit bldFile="bldinf" mrp="mrpfile" base="dir"

root="rootvar"

version="verson" filter="filter"

prebuilt="cbrname" late="yesno"

priority="priority"/>

For building across filesystems

File locations

deprecated

For importing components

For simple configuration


Package definitions

One unit per component

• The component is the persistent architectural entity that spans releases• The unit is the implementation-specific build definition that may change significantly

between releases• A component can only have a single unit for any given build or release

• Multiple units will only occur on vendor’s filesystems which contain code from more than one release

• Foundation components have one unit since the codeline only covers a single release• Multiple units in a component must be mutually exclusive

• A single unit must be selected by filter, version or other configuration mechanism

Rule of thumb: if both versions of a component can be built at the same time, they should be separate components with one unit each

• Selection should be done at ROM-build time, install time or run time.Example: BT HCI v1 and BT HCI v2 could both be built at the same time, but only one

would be included in the ROM

Corollary: if only version can be built at a time, then it should use a single component with multiple units

• Selection should be done at build timeExample: OpenMAX IL Core has two separate build files: …/omxilcore/group/bld.inf

and …/omxilcore/group2/bld.inf – these are captured in separate units


Package definitions

Unit paths

• Paths can be relative to the sysdef file (relative), or the root of the system (absolute)

• Syntax• All paths use network-style forward slash (/) for directory separator• Paths that specify directories must leave off the trailing / (for bldFile and base)• Absolute URIs are not allowed (eg no file: or http: schemes)

Relative paths• Never begin with /• Relative to the current file

(ie package_definition.xml) • By convention, a Foundation system definition

fragment should use only relative paths

Examples: • bldFile="locationmgmt/networkgateway/group"

pkgdef in the package’s root dir• bldFile="../../windowing/windowserver/group"

pkgdef in a subdirectory

Absolute paths• Always begins with /• Relative to the root of the filesystem• Top directory is always the layer• A stand-alone system definition can only have

absolute paths, ie relative paths are an error• A stand-alone sysdef is independent of the

filesystem

Examples:bldFile="/os/ossrv/genericopenlibs/cppstdlib/group"

directory pathmrp="/os/networkingsrv/tcpiputils/dnd/group/networking_dnd.mrp"

file path


Package definitions

The filesystem root• Syntax: <unit … root="variable"> • Provides a way to track and build components across multiple filesystems

• E.g. to build both a vendor and the Foundation systems at the same time

• Root is a named variable which maps the sysdef directory structure to the filesystem on a specific machine

• The default is the variable SRCROOT, which will be “/sf” for the Foundation Device Model and “/sftools” for the Foundation Tools Model

• The variable’s value is provided to build or analysis tools to find the unit’s files• Root can only be used with absolute paths

• A single sysdef will usually have a common root for the entire file• root not explicitly used in those cases

• Root is needed to track merging sysdefs from different filesystems• The root attribute can be generated when merging files

Example (from Tools Model):<component id="symport" name="SymPort" …> <unit bldFile="/dev/hostenv/cpptoolsplat/symport/group" … /> </component> <component id="pccenrep" name="Central Repository PC Port" …> <unit root="MCL" bldFile="/os/persistentdata/persistentstorage/centralrepository/pccenrep/group" …/> </component>

Tools Model component usesDefault filesystem, ie root="SRCROOT"

Component imported from Device Model’s filesystem

MCL maps to /sfSRCROOT maps to /sftools


Package definitions

The location of the bld.inf file

• Syntax: <unit … bldFile="directory">

• The directory containing a component’s bld.inf file• The file in the specified directory must be named bld.inf

• Always leave off the trailing /

Example: bldFile="genericopenlibs/cppstdlib/group"

• The bld.inf file specifies how to build the component• Defines exports, target platforms, MMP and makefiles to build, etc

• bldFile is left off components with no bld.inf

Examples:• Documentation

• Data files not exported

• When not present, mrp, base or prebuilt must be used


Package definitions

The MRP file

• Syntax: <unit … mrp="mrp-file">

• The location of a component’s MRP file• Definition file used by legacy Component Based Release packaging system

• Describes the content of the component in terms of source code, binaries, exports, tests, etc.

• Not used by the Foundation

• Used by all ex-Symbian components

Examples:• Pkgdef:

• <unit bldFile="tcpiputils/dnd/group" mrp="tcpiputils/dnd/group/networking_dnd.mrp"/>

• Generated sysdef:• <unit … mrp="/os/networkingsrv/tcpiputils/dhcp/group/networking_dhcp.mrp"/>


Package definitions

Base

• Syntax: <unit … base="directory">

• Used to specify the “base” directory of the component• All source in that directory and under belongs to that component

• If mrp is also present, then that file is used to determine the exports, tests and binaries

• Alternatively, exports, tests and binaries are inferred from bldFile (if present)

• If neither mrp or bldFile are present, the unit is not buildable and contains only un-exported source code or data


Package definitions

Prebuilt• Syntax: <unit prebuilt="cbr-name" version="cbr-release" late="yesno">

• Specifies a component to import for systems that support CBR• Used to import already built components from other filesystem or from another

vendor

• Use root to import and build a component from another filesystem

• prebuilt contains the name of the CBR component to acquire• Imported into a build using CBR's getrel command

• version contains the CBR release of the component to be imported• If not present, the most recent is used

Example: version="M04066_Symbian_OS"

• late is used to ensure the rest of the system has no compile-time dependencies on this component

• Only valid on pre-built components

• Valid valuesThe component should be acquired after building all the non-prebuilt components

The component should be acquired before building any components

"yes"

"no"


Package definitions

Version

• Syntax: <unit … version="name">

• Used to differentiate between multiple units in a component

• Each unit has a version value unique within that component• By convention, this takes the form of a number corresponding the major

version number of the component, e.g. version="2"

• Can also be release-specific value, e.g. version="^3"

• With prebuilt, this must be the CBR release name

Example: version="M04066_Symbian_OS"

• When there’s only one unit, this can be used as an informative version identifier

• Configuring by version number is not currently used in the Foundation• For future use


Vendor System

Definitions


Vendor system definitions

Vendor-specific system definitions

• Vendor system definitions allow vendors to use Foundation standard build and configuration tools for their own non-contributed components

• Gives common vocabulary for understanding, discussing the system• A vendor sysdef is always a downstream model

• i.e., it is built on top of the Foundation offering• Should use vendor’s namespace for own items

• Example vendor system definition

• Merged with Foundation sysdef to build entire combined asset• Foundation rules relaxed or do not apply

• Can add custom layers, levels, packages etc• Should avoid creating own containers when Foundation equivalent already exists

<SystemDefinition xmlns:sf="http://www.symbian.org/system-definition"id-namespace="http://www.example.org/sysdef/mydef"schema="3.0.0">

<package name="Package Name" id="sf:pkgid" levels="levels-list"> … <collection id="collid" >

… </collection>

… </package> </SystemDefinition>

Foundation items have explicit namespace

Foundation prefix on package ID

Own items use default namespace

No prefix on own ID

/layerid/pkgid/pkgid_info/vendor_pkgid_metadata/package_definition.xml




•Vendor models should follow the same hierarchy and the Foundation (os, mw, app)

• Own items fill in “holes” in the Foundation delivery

• Or build on top of the Foundation

•Vendor components can depend on Foundation components, but Foundation cannot depend on vendor's

Foundation

Vendor

depe

nden

ci

es

depe

nden

ci

es



Merging system definitions

• Reasons to merge system definitions:• To generate a single sysdef to build the system

• To diagram the “full” system (ie Foundation + vendor)

• Combine assets for analysis of a platform or device

• What gets merged• Containers

• Levels

• Components

• Full details in http://developer.symbian.org/wiki/index.php/System_Definition/Merging

http://developer.symbian.org/wiki/index.php/System_Definition/Merging



Merging model items

• <systemModel> always takes the name from the upstream model• The Foundation is the ultimate “source” , so it is the most upstream model• Vendors are downstream from the Foundation

• <layer> through <component> are merged using the following rules:

• The order of upstream items is never changed• Any before attributes in the upstream sysdef are ignored• A downstream item with valid before, appears in the merged sysdef before

its referenced item and after all preceding siblings in the upstream sysdef• before controls position: specifies the ID of an item of the same rank in the

same parent item, in the upstream sysdef • Multiple items with the same before value, will appear next to each other in

downstream document order

• A downstream item which appears between two items in the upstream sysdef will be placed between them in the merged sysdef

• Any other downstream item will appear at the end of its parent collection

Collection

A B C DCollection

A X B

Collection

A B C DX

+

=

UpstreamDownstream



Merging levels

• Levels in an upstream document can be adjusted by using “-” in the levels attribute to indicated levels are to be appended or preprended

• Allows vendors to add clarity on top of the existing structure

• It is an error to use “-” as a level name (i.e. level="-" is always illegal)

Examples• Upstream sysdef: <layer id="app" levels="services apps">

• Downstream sysdef 1: <layer id="app" levels="- oem"> <layer id="app" levels="services apps oem">

• Downstream sysdef 2: <layer id="app" levels="engines -"> <layer id="app" levels="engines services apps">



Merging components and units

• Components and units have special rules when merging

• The origin-model attribute is added to all components after a merge• Takes the name from the systemModel element in sysdef the component came from

• This makes it clear where every component in the generated model came from

• When merging two releases, it shows which components have been removed between the two releases

• When merging a vendor model, it shows which came from the Foundation and which are vendor-specific

• When merging models with different source roots, the root attribute can be added to track which filesystem the code lives in

• This is used to build models which have parts in different filesystems

• When two identical components are merged, the downstream unit replaces the upstream unit

• This allows a vendor variant of a component to replace the Foundation one

• Can be used to branch and extend functionality of the Foundation component


System Definition Resources

• Root System Definition locations/sf/os/deviceplatformrelease/foundation_system/system_model/system_definition.xml

/sftools/depl/toolsplatformrelease/tools_system/tools_model/system_definition.xml

• Foundation Package Definition locations/sf/layer/package/package_definition.xml

/sftools/layer/package/package_definition.xml

• Vendor Package Definition locations/sf/layer/package/package_info/vendor_package_metadata/package_definition.xml

/sftools/layer/package/package_info/vendor_package_metadata/package_definition.xml

• System Definition specificationhttp://developer.symbian.org/wiki/index.php/System_Definition

• System Model overview and meaninghttp://developer.symbian.org/wiki/index.php/Symbian_System_Model

• PkO Training MaterialPart 1: The architecture of the System Model

Part 3: Using the System Definition

http://developer.symbian.org/wiki/index.php/System_Definition

http://developer.symbian.org/wiki/index.php/System_Definition

http://developer.symbian.org/wiki/index.php/Symbian_System_Model

symbian system model xml syntax

Documents

xml syntax1