<?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">#&lt;BSF&gt;#                    : 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">#&lt;bsf&gt;#

# 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>