License
=======
Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved.
This component and the accompanying materials are made available under the terms of the License 
"Eclipse Public License v1.0" which accompanies this distribution, 
and is available at the URL "http://www.eclipse.org/legal/epl-v10.html".

Running Symbian Build System with a System Definition file
==========================================================

Introduction
============
This documentation describes how to use Symbian Build System to run Doxygen using a system definition file.
The system definition file contains multiple packages that make up a complete OS.
System definition version 3 splits the System definition into several xml documents. 
These files need to be transformed and merged to be compatible with Symbian Build System.
If the source tree that is being used has an unprocessed system definition file at version 3 Symbian Build System will produce an error stating this.

Prerequisites
=============
Please follow the instructions in install_orb.txt to set up Symbian Build System.
Install Xalan 2.7.1 or above (Download the latest version from  http://www.apache.org/dyn/closer.cgi/xml/xalan-j)
    Add the following to the CLASSPATH environment variable:
        #PathToXalan#\xalan-j_2_7_1\xalan.jar
        #PathToXalan#\xalan-j_2_7_1\serializer.jar
        #PathToXalan#\xalan-j_2_7_1\xml_apis.jar
        #PathToXalan#\xalan-j_2_7_1\xercesImpl.jar
    Any other xslt processor can also be used.
You must have the packages you require from epoc/master/sf in the source tree.
You must also have the system_definition.xml file. This is either in the nokia_system or the foundation_system model directories.

Creating the system_definition.xml file
=======================================

1. Create your system definition file
Open a shell at \EPOC\master\sf

For foundation_system:
Run: java org.apache.xalan.xslt.Process -in os\deviceplatformrelease\foundation_system\system_model\system_definition.xml -xsl os\buildtools\bldsystemtools\buildsystemtools\sysdefdowngrade.xsl -out os\deviceplatformrelease\foundation_system\system_model\new_system_definition.xml

For nokia_system:
Run: java org.apache.xalan.xslt.Process -in os\deviceplatformrelease\nokia_system\nokia_model\system_definition.xml -xsl os\buildtools\bldsystemtools\buildsystemtools\sysdefdowngrade.xsl -out os\deviceplatformrelease\nokia_system\nokia_model\new_system_definition.xml

This runs sysdefdowngrade.xsl on the v3 system_definition.xml. The script will complain bitterly if it cannot find any of the packages, this is normal.

2. Run Symbian Build System
For foundation_system:
sbs -s os\deviceplatformrelease\foundation_system\system_model\new_system_definition.xml -c doxygen -k 
For nokia_system:
sbs -s os\deviceplatformrelease\nokia_system\system_model\new_system_definition.xml -c doxygen -k