--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/buildframework/helium/sf/java/sbs/doc/sbs.rst Fri Aug 13 14:59:05 2010 +0300
@@ -0,0 +1,254 @@
+.. index::
+ module: Configuring Raptor (SBS)
+
+========================
+Configuring Raptor (SBS)
+========================
+
+.. contents::
+
+This document describes requirements and how to run sbs builds using helium. Now it is
+possible to pass directly pass all the raptor input directly and there are no mapping of
+raptor parameter specific to helium.
+
+
+SBS Requirements
+-----------------
+
+Before starting the build, SBS needs to be updated for s60 related changes, please follow the instructions from the link below,
+
+`How to Build Raptor <http://s60wiki.nokia.com/S60Wiki/How_To_Build_With_Raptor>`_
+
+1. SBS_HOME environment variable needs to be set
+2. PATH environment variable needs to be updated with SBS related exe::
+
+ path(SBS_HOME\\BIN;SBS_HOME\\win32\\mingw\\bin;SBS_HOME\\win32\\msys\\bin)
+
+3. RVCT requirement for raptor is 22_686 or higher, in IDO config / product config batch file the env variable needs to be set to `HLM_RVCT_VERSION=22_686`
+
+For Example: ::
+
+ set HELIUM_HOME=E:\Build_E\ec_test\helium-trunk\helium
+ set PATH=e:\svn\bin;E:\sbs\bin;c:\apps\actpython;%PATH%
+ set SBS_HOME=E:\sbs
+ set MWSym2Libraries=%MWSym2Libraries%;C:\APPS\carbide\x86Build\Symbian_Support\Runtime\Runtime_x86\Runtime_Win32\Libs
+ set TEAM=site_name
+
+(Note: For IDOs, these environment variables are set automatically, for S60 option is proposed).
+
+Required SBS input for Helium
+------------------------------
+
+SBS Input consists of SBSInput and SBSBuild types:
+
+1. SBSInput - SBS Input stores the list of raptor arguments both the sbs options and
+sbs make options. Nested sbs input option is also possible, for details please see the
+antdoclet information for sbsInput.
+
+2. SBSBuild - SBS Build is the collection of SBSInput. Each SBSInput refering within
+SBSBuild corresponds to a single invocation of raptor with the corresponding sbs arguments
+refered within the sbsInput. Each sbsInput refered within SBSBuild roughly corresponds to
+the abld commands associated with corresponding abld configurations. <configuration> </configuration>
+is corresponds ot SBSBuild. This is there only for backward compatibility and will be removed
+once the mighration is completed for schema 3.0, in which case, abld mapping of configuration
+is not required and sbsInput could be directly used. Example is as below,
+
+.. code-block:: xml
+
+ <hlm:sbsbuild id="sbs.dfs_build_export">
+ <sbsInput refid="dfs_build_export_input" />
+ </hlm:sbsbuild>
+
+
+1. To run using SBS mode (schema 1.4.0)
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+
+List of SBSInput one to one mapping with corresponding abld commands mapped for a configuration.
+
+example is below,
+
+.. code-block:: xml
+
+ <!-- tools common sbs options -->
+ <hlm:sbsoptions id="commonSBS">
+ <arg line="-k" />
+ </hlm:sbsoptions>
+
+ <hlm:sbsoptions id="exportSBS">
+ <argset refid="commonSBS" />
+ <arg line="--export-only" />
+ </hlm:sbsoptions>
+
+ <!-- sbs input for export -->
+ <hlm:sbsinput id="export-sbs">
+ <sbsoptions refid="exportSBS" />
+ </hlm:sbsinput>
+
+ <hlm:sbsbuild id="sbs.dfs_build_export">
+ <sbsInput refid="dfs_build_export_input" />
+ </hlm:sbsbuild>
+
+Assuming there is a dfs_build_export schema configuration 1.4.0 system definition file.
+Then there should be a corresponding <hlm:sbsbuild> type defined prefixing with sbs
+as sbs.dfs_build_export as above which contains a reference to sbsinput. The sbsInput
+contains actual raptor commands equivalent to abld commands to be executed for that
+configuration, in this case it is referring exportSBS, which in turn referring to commonsbs
+so finally the command generated would be
+
+.. code-block:: xml
+
+ sbs -k --export-only
+
+This command is executed for all the components specified in the dfs_build_export
+configuration.
+
+No change from the configuration is required, except the new raptor input needs to be imported.
+
+2. To run using SBS mode (schema 3.0.0)
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+
+For schema 3.0, required inputs are,
+ a. sbs arguments
+ b. package definition files
+ c. filters to filter the component (check sysdefFilterSet under Helium Antlib documentation)
+ d. patternset - specifying specific set of layers to be executed (deprecated, will be replaced by id filtering).
+
+As Raptor does not support yet schema 3.0 parsing, the system definition file
+should be downgraded before being passed to the tool. This feature is controlled by
+the ***sbs.downgrade.sysdef.enabled*** boolean property.
+
+Filtering can be configured by defining a hlm:sysdefFilterSet type with a specific reference id based on the following
+naming convention: sbs.filters.<configuration_name>
+
+This example shows how to configure a filterset for the build_export configuration:
+
+.. code-block:: xml
+
+ <!-- sbs input for export -->
+ <hlm:sbsbuild id="sbs.build_export">
+ <sbsInput refid="dfs_build_export_input" />
+ </hlm:sbsbuild>
+
+ <hlm:sysdefFilterSet id="sysdef.filters.build_export">
+ <filter filter="!test,os" type="has" />
+ </hlm:sysdefFilterSet>
+
+With a similar configuration approach a set of layer can be selected or excluded, by defining a patternset following this naming convention:
+sbs.layers.<configuration_name>
+
+Example:
+
+.. code-block:: xml
+
+ <patternset id="sysdef.layers.build_export">
+ <include name="mw" />
+ <exclude name="os" />
+ </patternset>
+
+
+Customizing raptor input
+------------------------
+
+Different scenario the user might need to provide the raptor inputs, (required to map raptor
+commands for abld configuration which is not there in the default raptor input xml file,
+want to override the default raptor input to pass additional parameters), below section covers
+how these can be customized.
+
+Mapping raptor commands for new configuration from system definition file (1.4.0)
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+
+First step is to identify the abld commands executed by the new configuration. Correspondingly the
+raptor commands need to be identified for that. Then need to check from the common raptor input
+is there any input which can be reused. If any raptor input could be re-usable, the just refering
+that input and adding additional arguments would provide the exact raptor command arguments to be
+executed.
+
+
+For example, if the new configuration for which the raptor command input is to be created is,
+os, which is not there in the default raptor input, then abld commands executed are
+(to be simpoer - bldmake, export, tools_rel, winscw, armv5). The corresponding raptor input would
+be
+
+
+.. code-block:: xml
+
+ <hlm:sbsinput id="build_input_os_export">
+ <sbsInput refid="export-${build.system}" />
+ <sbsOptions>
+ <arg name="--logfile" value="${compile.log.dir}/${build.id}_export_os_build.log" />
+ <arg name="--makefile" value="${temp.build.dir}/${build.id}_export_os_build" />
+ </sbsOptions>
+ </hlm:sbsinput>
+
+ <hlm:sbsinput id="build_input_os_tools">
+ <sbsInput refid="tools-${build.system}" />
+ <sbsOptions>
+ <arg name="--logfile" value="${compile.log.dir}/${build.id}_tools_rel_os_build.log" />
+ <arg name="--makefile" value="${temp.build.dir}/${build.id}_tools_rel_os_build" />
+ </sbsOptions>
+ </hlm:sbsinput>
+
+ <hlm:sbsinput id="build_input_os_winscw">
+ <sbsInput refid="winscw-${build.system}" />
+ <sbsOptions>
+ <arg name="--logfile" value="${compile.log.dir}/${build.id}_winscw_os_build.log" />
+ <arg name="--makefile" value="${temp.build.dir}/${build.id}_winscw_os_build" />
+ </sbsOptions>
+ </hlm:sbsinput>
+
+
+ <hlm:sbsinput id="build_input_os_armv5">
+ <sbsInput refid="armv5-${build.system}" />
+ <sbsOptions>
+ <arg name="--logfile" value="${compile.log.dir}/${build.id}_armv5_os_build.log" />
+ <arg name="--makefile" value="${temp.build.dir}/${build.id}_armv5_os_build" />
+ </sbsOptions>
+ </hlm:sbsinput>
+
+The default raptor input for each build target (tools, winscw, armv5) are reused here and just the
+log file names are changed.
+
+Next the sequence of command execution needs to be defined for the corresponding os confoguration as below.
+
+.. code-block:: xml
+
+ <hlm:sbsbuild id="sbs.os">
+ <sbsInput refid="build_input_os_export" />
+ <sbsInput refid="build_input_os_tools" />
+ <sbsInput refid="build_input_os_winscw" />
+ <sbsInput refid="build_input_os_armv5" />
+ </hlm:sbsbuild>
+
+For configuration name os in the system definition file, it will take the list of raptor input
+as defined with sbs.os, then it will execute each sbsinput as separate sbs calls with the arguments
+extracted from the corresponding reference id.
+
+Overriding default raptor arguments
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+
+In case the default argument is not enough for the user requirements, this could be overriden by
+redefining the reference of a particular sbsoptions will provide the user to change the arguments.
+
+For example, if the user just wants to pass debug flag for armv5 raptor inputs, the raptor input
+
+.. code-block:: xml
+
+ <!-- Mainbuild common sbs options -->
+ <hlm:sbsoptions id="armv5CommonSBS">
+ <argset refid="commonSBS" />
+ <arg line="-c armv5" />
+ </hlm:sbsoptions>
+
+
+could be redefined as below in the user configuration,
+
+.. code-block:: xml
+
+ <!-- Mainbuild common sbs options -->
+ <hlm:sbsoptions id="armv5CommonSBS">
+ <argset refid="commonSBS" />
+ <arg line="-c armv5" />
+ <arg line="-d" />
+ </hlm:sbsoptions>
+
+This would add the debug flag in all the raptor configuration which is using armv5CommonSBS.
\ No newline at end of file