--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/Symbian3/SDK/Source/GUID-5B442231-6E71-5F35-A27E-B14AEC2FC105.dita Thu Jan 21 18:18:20 2010 +0000
@@ -0,0 +1,66 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- 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". -->
+<!-- Initial Contributors:
+ Nokia Corporation - initial contribution.
+Contributors:
+-->
+<!DOCTYPE concept
+ PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
+<concept id="GUID-5B442231-6E71-5F35-A27E-B14AEC2FC105" xml:lang="en"><title>ARMV5
+build customisation</title><prolog><metadata><keywords/></metadata></prolog><conbody>
+<p>The ARMV5 build supports the notion of customisation. This allows a programmer
+to define a new build target that is derived from the ARMV5 build. A new build
+target is defined via a <filepath>.BSF</filepath> file. The build system becomes
+aware of a customised build by the presence of its .BSF file in <filepath>epoc32\tools\</filepath>.
+Such customisations are referred to by the name of their <filepath>.BSF</filepath> file:
+e.g. the file <filepath>XScale.bsf</filepath> defines the build target <codeph>XScale</codeph>.
+This name can be used in exactly the same way as built-in names such as ARMV5. </p>
+<section><title>BSF Syntax </title><p>It is intended that the syntax of a
+.BSF file is toolchain specific with the exception of the obligatory header:</p><codeblock id="GUID-3CF96A81-8710-5044-8AF0-A9D568822045" xml:space="preserve">#<BSF># : token to identify this as a BSF file must appear at start of first line.
+CUSTOMIZES build : identitifies which build is customized by this spec e.g. ARMV5.</codeblock><p>Currently,
+only ARMV5 can be customised. The ARMV5 specific .BSF syntax is as follows:</p><codeblock id="GUID-6E4208DE-3B44-5055-8DF5-943210B83779" xml:space="preserve">THUMB_OPTIONS opt1 opt2 ... : compiler options used by default for user side code (expected to be THUMB mode)
+ARM_OPTIONS opt1 opt2 ... : compiler options used when BUILD_AS_ARM etc are specified (expected to be ARM mode)
+KERNEL_OPTIONS opt1 opt2 ... : compiler options used to compile kernel side code
+COMMON_OPTIONS opt1 opt2 ... : compiler options that are added to all the above</codeblock><p>The
+above four keywords specify compiler options that can be overriden in an MMP
+file through<codeph>OPTION</codeph>. For example: </p><codeblock id="GUID-EDE9A728-34C2-546F-B93D-77B8CD8BFA0D" xml:space="preserve">OPTION ARMCC -Ospace</codeblock><p>A final keyword specifies the system-wide options that cannot be overridden
+in an MMP file via <codeph>OPTION</codeph>. Typically, these specify options
+within the EABI e.g. the SOFTVFP calling convention. They are called invariant
+since code compiled with different settings will not be binary compatible.</p><codeblock id="GUID-B6AB5699-2C5A-5B39-83B2-56ED9976D5B9" xml:space="preserve">INVARIANT_OPTIONS opt opt2 ... : these options are appended to all compiler command lines</codeblock></section>
+<example><p>The following is an example bsf file: </p><codeblock id="GUID-9CDC9BA6-9A59-55F7-8950-184DF26BF10D" xml:space="preserve">#<bsf>#
+
+# Example build specialization file
+#
+# NB currently specialization only applies to ARMV5 build using RVCT.
+
+# This file customizes the default ARMV5. It specifies a build that
+# always uses optimization level O1 rather than the default O2.
+customizes ARMV5
+
+# The following options that can be overridden by MMP files
+
+# Use these options when compiling user-side THUMB code
+thumb_options -thumb -O1
+
+# Use these options when compiling user-side ARM code
+arm_options -arm -O1
+
+# Use these options when compiling Kernel code
+kernel_options -arm -O1
+
+# This just factors out common (contingent) options from the above.
+# These options can also be overridden by MMP files.
+common_options --diag_suppress 1,161,654,1135,1152,1300 --diag_error 1267
+
+# Fixed options for this build. These options should only be changed with great care since
+# they have the potential to introduce incompatible ABI (or machine) level effects.
+# -cpu 5T - this build just targets a generic 5T
+# -Ono_known_library - we use our own library so tell the compiler not to make assumptions about its implementation
+# -fpu softvfp - some system code explicitly assumes this variant of the EABI (softvfp+vfp could be used on say XScale)
+# --dll_vtbl - this switches on class exporting and is needed to support Symbian platform DLL model
+# -apcs /inter - redundant on 5T, but worth saying anyway
+invariant_options -cpu 5T -fy -Ono_known_library -fpu softvfp --dll_vtbl -apcs /inter</codeblock></example>
+</conbody></concept>
\ No newline at end of file