View
117
Download
0
Category
Tags:
Preview:
DESCRIPTION
The Symbian System Model XML Syntax
Citation preview
© 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>
© 2009 Symbian Foundation2
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
© 2009 Symbian Foundation3
System Definition
basic syntax
© 2009 Symbian Foundation4
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
© 2009 Symbian Foundation5
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
© 2009 Symbian Foundation6
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>
© 2009 Symbian Foundation7
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>
© 2009 Symbian Foundation9
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
© 2009 Symbian Foundation11
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
© 2009 Symbian Foundation12
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
© 2009 Symbian Foundation13
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"…>
=
© 2009 Symbian Foundation14
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”
© 2009 Symbian Foundation15
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/ / / /
© 2009 Symbian Foundation16
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
© 2009 Symbian Foundation17
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
© 2009 Symbian Foundation18
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
© 2009 Symbian Foundation19
The Root System
Definition
© 2009 Symbian Foundation20
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>
© 2009 Symbian Foundation21
Root system definitions
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>
© 2009 Symbian Foundation22
Root system definitions
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
© 2009 Symbian Foundation23
Root system definitions
• 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
© 2009 Symbian Foundation24
Root system definitions
• 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
© 2009 Symbian Foundation26
Root system definitions
<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
© 2009 Symbian Foundation27
Root system definitions
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
© 2009 Symbian Foundation29
Root system definitions
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" …>
© 2009 Symbian Foundation30
Package Definition
Files
© 2009 Symbian Foundation31
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
© 2009 Symbian Foundation32
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>
© 2009 Symbian Foundation33
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
© 2009 Symbian Foundation34
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
© 2009 Symbian Foundation37
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
© 2009 Symbian Foundation38
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)
© 2009 Symbian Foundation39
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
© 2009 Symbian Foundation40
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)
© 2009 Symbian Foundation41
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
© 2009 Symbian Foundation42
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
© 2009 Symbian Foundation43
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
© 2009 Symbian Foundation44
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”
© 2009 Symbian Foundation45
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" …>
© 2009 Symbian Foundation46
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
© 2009 Symbian Foundation47
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">
© 2009 Symbian Foundation48
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
© 2009 Symbian Foundation49
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
© 2009 Symbian Foundation53
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)
© 2009 Symbian Foundation54
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">
© 2009 Symbian Foundation55
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
© 2009 Symbian Foundation56
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
© 2009 Symbian Foundation57
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
© 2009 Symbian Foundation58
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
© 2009 Symbian Foundation59
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
© 2009 Symbian Foundation60
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"/>
© 2009 Symbian Foundation61
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
© 2009 Symbian Foundation63
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"
© 2009 Symbian Foundation64
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
© 2009 Symbian Foundation65
Vendor System
Definitions
© 2009 Symbian Foundation66
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
© 2009 Symbian Foundation67
Vendor system definitions
Vendor system definitions
•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
© 2009 Symbian Foundation68
Vendor system definitions
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
© 2009 Symbian Foundation69
Vendor system definitions
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
© 2009 Symbian Foundation70
Vendor system definitions
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">
© 2009 Symbian Foundation71
Vendor system definitions
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
© 2009 Symbian Foundation72
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
Recommended