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