Initial contribution of the Adaptation Documentation.
<?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-BFE1422D-3B4A-5B25-A757-B5B68D6390F8" xml:lang="en"><title>Port
Implementation Tutorial</title><shortdesc>This topic describes how to customize the Base Starter. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
<section id="GUID-9F925D19-DFAB-5C2A-8A04-E82963F2D221"><title>Creating local
drive mapping files</title> <ol id="GUID-B20B8E9B-2FA5-57F2-9F06-88ED21D24E87">
<li id="GUID-BD13EA0C-81E2-5174-BFB0-1857B17BE85B"><p>Create an ASCII text
file containing your local drive mapping records; see <xref href="GUID-8BA1EEC2-78A3-54CC-95D9-81BF2659963D.dita#GUID-8BA1EEC2-78A3-54CC-95D9-81BF2659963D/GUID-2B95B775-1BD1-5256-86D3-CD3FA12447B9">create local drive mapping files</xref> for information about the syntax
of the file. </p> </li>
<li id="GUID-03BE3694-C78E-5A46-B4FF-FCAF55CED8D4"><p>Put this text file into
your variant source tree. The source tree is typically of the form <filepath>sf/os/boardsupport/.../<your
variant>/estart/</filepath> . Depending on your port, you
might need more than one local drive mapping file. </p> </li>
<li id="GUID-1850EBF2-71EB-53D6-A2AC-2FE33AEC8AE8"><p>In the <filepath>kernel.iby</filepath> file
for your variant, you need to add lines to make sure that your local drive
mapping files are copied into the ROM's <filepath>\sys\data\</filepath> directory
when the ROM is built. For example include a lines in the form </p> <codeblock id="GUID-B7C15498-DB7E-51CF-83D9-25013ABEC3B8" xml:space="preserve">data=\epoc32\rom\youvariant\ESTARTCOMP.TXT \Sys\Data\ESTARTCOMP.TXT</codeblock> </li>
<li id="GUID-2808A5CB-D270-56D7-BE0E-BA476A31AFC6"><p>If you need more than
one mapping file, or your single mapping file has a name other than <filepath>ESTART.TXT</filepath>,
then you need to customise the function <xref href="GUID-9A65BCC6-FC1B-349E-BF8C-AEDE8F2549B7.dita#GUID-9A65BCC6-FC1B-349E-BF8C-AEDE8F2549B7/GUID-F46A932C-8CC0-3F39-8C68-38C2660F86E7"><apiname>TFSStartUp::LocalDriveMappingFileName()</apiname></xref> so
that you can return the appropriate file name at run time. </p> </li>
</ol> </section>
<section id="GUID-51FBCDD1-7DB4-556D-9599-5F8B54837852"><title>Making use
of auto detection</title> <p>To make use of auto-detection, you need to ensure
that your variant cannot find local drive mapping files in your ROM's <filepath>\sys\data\</filepath> directory.
If you are using the default version of <xref href="GUID-9A65BCC6-FC1B-349E-BF8C-AEDE8F2549B7.dita#GUID-9A65BCC6-FC1B-349E-BF8C-AEDE8F2549B7/GUID-F46A932C-8CC0-3F39-8C68-38C2660F86E7"><apiname>TFSStartUp::LocalDriveMappingFileName()</apiname></xref>,
then make sure that no file exists with the full path name <filepath>Z:\sys\data\estart.txt</filepath>. </p> </section>
<section id="GUID-AA916F3A-E8DF-522D-BDD6-18C2FD82AC16"><title>Customising
code</title> <p>The most common customisation is to provide your own implementation
of the <xref href="GUID-7A6C0343-7B98-3429-9162-4C0357594230.dita"><apiname>TFSStartup</apiname></xref> virtual functions. To do this: </p> <ol id="GUID-7C709736-88C7-5770-8799-44C5DE9B78A2">
<li id="GUID-A5CB09C7-C008-5ADA-BC1C-BFDC268570B9"><p>Take a copy of <filepath>ESTARTMAIN.CPP</filepath> from <filepath>sf/os/kernelhwsrv/userlibandfileserver/fileserver/estart/</filepath>, and insert your code into this copy. Typically this will include, but is
not limited to, your implementation of the <xref href="GUID-7A6C0343-7B98-3429-9162-4C0357594230.dita"><apiname>TFSStartup</apiname></xref> virtual
functions. </p> </li>
<li id="GUID-A67D8EB7-A4A7-54DE-A46C-BF44FC6F173C"><p>Place the copy into
your variant's source tree. This is typically of the form <filepath>sf/os/boardsupport/.../<your
variant>/estart/</filepath>. This is the general pattern for the other ports
supplied with Symbian platform. </p> </li>
<li id="GUID-24536FD8-EABF-5E4D-A691-F36FEEBB604C"><p>Create a <filepath>.mmp</filepath> file
to build your variant's version of the Base Starter. This is usually placed
in the <filepath>\<youvariant>\</filepath> directory. The general pattern
looks like this: <filepath>sf/os/boardsupport/.../<your
variant>/estart/estart.mmp</filepath>. Ports to other hardware variants and
the emulator (WINS) variant follow the same general pattern. </p> </li>
<li id="GUID-41111731-D21E-53E8-9728-1F2E8B2977B9"><p>Your <filepath>.mmp</filepath> file
should pick up the Symbian platform generic code from <filepath>sf/os/kernelhwsrv/userlibandfileserver/fileserver/estart/estart.cpp</filepath>,
but should pick up your variant's customised source code from <filepath>sf/os/boardsupport/.../<your
variant>/estart/estartmain.cpp</filepath>. The general pattern is to give
the resulting executable the name <filepath>e32strt.exe</filepath>. </p> </li>
<li id="GUID-FBBE887B-69D6-5904-8BD6-7E67F1B049B7"><p>In the <filepath>kernel.iby</filepath> file
for your variant, you need to add a line that copies your executable into
the ROM's <filepath>\sys\bin\</filepath> directory when the ROM is built.
For example, include a line of the form: </p> <codeblock id="GUID-DF458ADA-69B8-5AC3-92D1-F57B9C14C326" xml:space="preserve">file=\Epoc32\Release\##MAIN##\##BUILD##\_##VARIANT##_e32strt.exe sys\bin\estart.exe HEAPMAX(0x2000)</codeblock> </li>
</ol> </section>
<section id="GUID-92EE546A-2945-55EC-A0C3-4CE2ED7926CF"><title>Removing auto
detect from the Base Starter</title> <p>You do this only if you need to save
code space, and you do not need the autodetect functionality. </p> <p>See
also <xref href="GUID-8BA1EEC2-78A3-54CC-95D9-81BF2659963D.dita#GUID-8BA1EEC2-78A3-54CC-95D9-81BF2659963D/GUID-A195BD51-80C7-5D87-ABA2-8878CC509B84">Use
automatic local drive mapping</xref>. </p> <ol id="GUID-6B18F11A-5271-5E04-A246-3143A856722B">
<li id="GUID-D86AD2FB-EDF7-5A95-949E-3C7BE9B609F0"><p>Create a <filepath>.mmp</filepath> file
to build your variant's version of the Base Starter. This is usually placed
in the <filepath>sf/os/boardsupport/.../<your variant>/estart/</filepath> directory.
This shows the general pattern. Ports to other hardware variants and the emulator
(WINS) variant follow the same general pattern. </p> </li>
<li id="GUID-CFA6F952-2637-5999-8C06-191B8C9B81EB"><p>In your <filepath>.mmp</filepath> file,
define the macro: </p> <codeblock id="GUID-7DCF288E-CF86-550F-95BB-33CDAF342C66" xml:space="preserve">MACRO AUTODETECT_DISABLE</codeblock> </li>
<li id="GUID-3CD0D0C9-5CA5-5CCA-A918-5076DD38C576"><p>The location of all
source files in the <filepath>.mmp</filepath> file will be <filepath>sf/os/kernelhwsrv/userlibandfileserver/fileserver/estart/</filepath>. </p> </li>
<li id="GUID-9D679A09-134A-5E09-9A29-79D52B6BE975"><p>In the <filepath>kernel.iby</filepath> file
for your variant, you need to add a line to make sure that your executable
is copied into the ROM's <filepath>\sys\bin\</filepath> directory when the
ROM is built. For example, include a line of the form </p> <codeblock id="GUID-F893D88D-212A-5396-AB64-918CB48A37A1" xml:space="preserve">file=\Epoc32\Release\##MAIN##\##BUILD##\_##VARIANT##_e32strt.exe sys\bin\estart.exe HEAPMAX(0x2000)</codeblock> <p>This is the general pattern for the other ports supplied with Symbian
platform. </p> </li>
</ol> </section>
<section id="GUID-251E3B54-AB58-4FE4-8E81-0ED48484C1FD"><title>See also</title> <p><xref href="GUID-E5459A54-14BC-55C1-B911-63415E4C61A6.dita">Concepts</xref> </p> </section>
</conbody></concept>