<?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-79100974-CAE1-5451-9ED7-E06C9B27131B" xml:lang="en"><title>Build

Process</title><prolog><metadata><keywords/></metadata></prolog><conbody>

<ul>

<li id="GUID-1F561425-9B98-544A-A0CB-086E0931313E"><p><xref href="GUID-79100974-CAE1-5451-9ED7-E06C9B27131B.dita#GUID-79100974-CAE1-5451-9ED7-E06C9B27131B/GUID-DDD0A8B3-0375-5245-A019-C9A74575C63F">Introduction</xref>  </p> </li>

<li id="GUID-DE26248D-27DE-5B38-9BFA-FE4CBAB676F6"><p><xref href="GUID-79100974-CAE1-5451-9ED7-E06C9B27131B.dita#GUID-79100974-CAE1-5451-9ED7-E06C9B27131B/GUID-423A00CF-D668-5114-860D-B30185DAB0B2">P.I.P.S. target types</xref>  </p> </li>

<li id="GUID-9EC5C68C-CDFC-5608-A26C-FD6001822217"><p><xref href="GUID-79100974-CAE1-5451-9ED7-E06C9B27131B.dita#GUID-79100974-CAE1-5451-9ED7-E06C9B27131B/GUID-6A50D190-7E5B-5109-BA38-9C962DF8EB1D">Symbol information</xref>  </p> </li>

<li id="GUID-6EDF3969-49B8-5F74-BFBF-C323D2C8480C"><p><xref href="GUID-79100974-CAE1-5451-9ED7-E06C9B27131B.dita#GUID-79100974-CAE1-5451-9ED7-E06C9B27131B/GUID-76C405AE-1AB7-59AE-BCAF-A9E09D17B24E">Mapping POSIX handles to the Symbian platform resource objects</xref>  </p> <ul>

<li id="GUID-30586541-C6EB-5794-8171-2302C53AAE45"><p><xref href="GUID-79100974-CAE1-5451-9ED7-E06C9B27131B.dita#GUID-79100974-CAE1-5451-9ED7-E06C9B27131B/GUID-4AA14ED5-7949-5AAB-A685-87DA43B99AFE">Using non-system calls</xref>  </p> </li>

<li id="GUID-E146BFE8-FDFE-551D-B280-5AD5303996C7"><p><xref href="GUID-79100974-CAE1-5451-9ED7-E06C9B27131B.dita#GUID-79100974-CAE1-5451-9ED7-E06C9B27131B/GUID-FBF12198-B501-5525-86AF-5517A012FDF1">Using the System Call Adaptation Layer</xref>  </p> </li>

</ul> </li>

</ul>

<section id="GUID-DDD0A8B3-0375-5245-A019-C9A74575C63F"><title>Introduction</title> <p>Symbian

currently builds its emulator code with the Metrowerks CodeWarrior compiler.

This is known as the <codeph>WINSCW</codeph> build target. Binaries built

with this compiler are put in the <filepath>epoc32\release\winscw</filepath> and <filepath>epoc32\winscw</filepath> directory

trees. </p> <p>You can build your programs for the emulator using Metrowerks

CodeWarrior. The build tools also support the Microsoft® Visual Studio .NET

2003 and Microsoft Visual Studio v6 IDEs. For further information, see the <xref href="GUID-B21141D4-3BFE-59C9-8D5F-147A93BE1C95.dita">Build tools guide</xref> section.

Note that licensees or third-parties may supply additional tools, or extend

support to additional compilers, which are not described here. </p> <p>The

following sections describe the Symbian platform target types

introduced with P.I.P.S.. For further information see <xref href="GUID-763DCEF4-C960-58A2-99DC-7FFD3187BFD4.dita">the

native build targets</xref> section. </p> <p>When using tool chains for pre-Symbian

OS v9.3, the <filepath>.mmp</filepath> file has to be manually changed to

link in various libraries. </p> <p>For Symbian OS v9.3 onwards the tool chain

supports the new <codeph>STDEXE</codeph> and <codeph>STDDLL</codeph> target

types for P.I.P.S. EXEs and DLLs. See the <xref href="GUID-1560C4FF-82EC-5E5D-A37D-3BBE046F0A5B.dita#GUID-1560C4FF-82EC-5E5D-A37D-3BBE046F0A5B/GUID-5D0338E0-E2D4-5904-9B21-244CA52DD91B">Generation

of STDEXE, STDDLL and STDLIB</xref> section for further explanation of the

new target types introduced with P.I.P.S.. </p> </section>

<section id="GUID-423A00CF-D668-5114-860D-B30185DAB0B2"><title>P.I.P.S. target

types</title> <p>P.I.P.S. EXEs require adaptation logic to set up the C program

environment and the P.I.P.S. run-time C library context - this is performed

by the <codeph>CRT0</codeph> library (also known as glue code, see the <xref href="GUID-6CDDDD1E-BDB9-5C61-8EFD-8B3369F5A12D.dita#GUID-6CDDDD1E-BDB9-5C61-8EFD-8B3369F5A12D/GUID-49C7F951-8317-5F41-B1B9-9F7B8803E655">Glue

code (CRT0)</xref> section for further details). </p> <p>P.I.P.S. executables

are implemented using native Symbian platform executables linked statically

to the glue code. The new target types for P.I.P.S. include the glue code

by default. The glue code provides the linking code between the <codeph>E32Main()</codeph> entry

point and the <codeph>main()</codeph> entry point used in 'C' P.I.P.S. EXEs. </p> <p>For

further information see the <xref href="GUID-1560C4FF-82EC-5E5D-A37D-3BBE046F0A5B.dita">Target

Types</xref> section. </p> </section>

<section id="GUID-6A50D190-7E5B-5109-BA38-9C962DF8EB1D"><title>Symbol information</title> <p>When

building a P.I.P.S. DLL (that is, when the target type is <codeph>STDDLL</codeph>),

function and data symbols with <codeph>extern</codeph> linkage will be exported

or imported by default, without any requirement for <xref href="GUID-BD292953-36BF-3C7D-AA93-98E6CB38968E.dita"><apiname>IMPORT_C</apiname></xref> /<xref href="GUID-2F78C3AC-7330-34C0-8A83-75D7345F2DC8.dita"><apiname>EXPORT_C</apiname></xref> declarations

in the header or source files. </p> <p>Exporting of symbols with <codeph>extern</codeph> linkage

is the assumed default on other platforms and enables the source code to be

easily ported. Although this may normally be undesirable in the embedded world,

it is supported for <codeph>STDDLL</codeph> to avoid portable source code

having to include excessive decoration (that is, the <codeph>IMPORT_C</codeph> /<codeph>EXPORT_C</codeph> macros)

for the Symbian platform. </p> <p> <codeph>STDEXE</codeph> and <codeph>STDDLL</codeph> provide

symbol name information. For more information on the Symbian platform target

types see the <xref href="GUID-1560C4FF-82EC-5E5D-A37D-3BBE046F0A5B.dita#GUID-1560C4FF-82EC-5E5D-A37D-3BBE046F0A5B/GUID-5D0338E0-E2D4-5904-9B21-244CA52DD91B">Generation

of STDEXE, STDDLL and STDLIB</xref> section. </p> </section>

<section id="GUID-76C405AE-1AB7-59AE-BCAF-A9E09D17B24E"><title>Mapping POSIX

handles to the Symbian platform resource objects</title> <p id="GUID-4AA14ED5-7949-5AAB-A685-87DA43B99AFE"><b>Using

non-system calls</b> </p> <p>Several P.I.P.S. APIs that directly manipulate

the Symbian platform (native) resources are implemented in the System Call

Adaptation Layer (SCAL). The exceptions to this are <codeph>pthread</codeph> s,

and memory maps. The <codeph>pthread</codeph> APIs use <xref href="GUID-B0E661BC-4058-3256-B9C3-5A4FD52F6DE5.dita"><apiname>RThread</apiname></xref> s

and <xref href="GUID-C0FEA3A0-7DD3-3B87-A919-CB973BC05766.dita"><apiname>RMutex</apiname></xref> es directly from within <codeph>libpthread</codeph>.

Similarly, <xref href="GUID-326A2F4D-0E99-31C0-A35D-E8BF45913F07.dita"><apiname>RChunk</apiname></xref> s that are used to provide support for

memory maps are directly manipulated from within <codeph>libc</codeph>. Note

that none of these APIs allow direct access to the underlying native resources.

References to these are wrapped in POSIX-defined data structures. These data

structures are intended to be treated as opaque and no attempt must be made

to dereference or use the underlying resource reference directly. </p> <p>All

IPC calls enter the SCAL, but are handled in a separate IPC library. This

is a component distinction. The IPC library is logically still part of the

SCAL. </p> <p id="GUID-FBF12198-B501-5525-86AF-5517A012FDF1"><b>Using the

System Call Adaptation Layer</b> </p> <p>One of the supports provided by the

System Call Adaptation Layer (SCAL) is the mapping of operations on UNIX®

file descriptors to the corresponding Symbian platform resource objects. The

section below discusses the file descriptors case. </p> <p id="GUID-1A1FC433-B9F6-5998-9622-14B961F477E2"><b>Creating

a new file descriptor</b> </p> <p>The porting of the 'C' POSIX <xref href="GUID-64886CC6-072F-3542-855A-5D733FC761E8.dita"><apiname>fopen()</apiname></xref> function,

below, is a good example of mapping POSIX handles to native Symbian platform

resource objects. The mapping is done through a file descriptor table. As

a reminder, every application/process has its own file descriptor table. </p> <p>This

example shows a call to the <codeph>fopen()</codeph> function: </p> <codeblock id="GUID-F9681B44-A1E6-5971-9C5E-147D4281DBF0" xml:space="preserve">//myapp.cpp

int foo()

{

   //open the test.tx , fd=7 in this example

   int fd = fopen("c:/test.txt", "r+");

   ...

   //writes to file referenced by the file descriptor  

   ret = write (fd, buf, size_t);

}</codeblock> <p>When <i>myapp</i> tries to open the file with <codeph>fopen()</codeph>,

the application makes a call to the equivalent Symbian platform function, <xref href="GUID-BE0804F6-4375-3C8A-8C83-968F510466E0.dita#GUID-BE0804F6-4375-3C8A-8C83-968F510466E0/GUID-72470A68-7E07-30EF-A3C8-AA855CDAF60E"><apiname>RFile::Open()</apiname></xref>,

and returns the next free entry in the file descriptor table. </p> <p>In each

table, the values <codeph>0</codeph>, <codeph>1</codeph> and <codeph>2</codeph> are

reserved for <xref href="GUID-C0C1D22B-298F-3E8D-A1E9-6F5EFA81F9E8.dita"><apiname>stdin()</apiname></xref>, <xref href="GUID-0441C351-4A8B-3A23-9255-D7C8CEA2A67F.dita"><apiname>sdtout()</apiname></xref> and <xref href="GUID-4FF97B50-2C1E-37EC-888B-FB8D3F14B5B8.dita"><apiname>stderr()</apiname></xref>.

The figure below shows an example file descriptor table. </p> <fig id="GUID-4CEA6881-49E0-5211-8258-C44A8E8F3CDE">

<image href="GUID-8EE8E38C-7CA1-5F1B-86D0-1A0B03AAC5F2_d0e149865_href.png" placement="inline"/>

</fig> <p>According to the descriptor table the file descriptor equals <codeph>7</codeph>,

as this was the next free entry in the table, and the write function will

be writing to the file referenced by <codeph>7</codeph>. </p> <p> <b>Note:</b> A

POSIX descriptor is an index in the process open file table and represents,

for example, an open file, socket or pipe. A Symbian descriptor represents

data which can reside in any memory location, either in ROM or RAM. A descriptor

object maintains pointer and length information to describe the data. All

access to the data is made through the descriptor object. </p> <p id="GUID-79958B57-8C71-5875-9C5B-8C313A96D13A"><b>Descriptors

shared across multiple threads within the same process</b> </p> <p>Originally

on the Symbian platform, resources were thread specific and multi-tasking

was achieved using servers and active objects. In other operating systems,

such as Linux, resources are process-local and multi-tasking is achieved by

multi-threading. The purpose of the POSIX server in the original <codeph>STDLIB</codeph> was

to allow system-wide data, resources and descriptors to be shared across multiple

threads. This means there was context switching between the calling thread

and the server thread which added latency. </p> <p>With the introduction of

the EKA2 kernel, session handles can now be shared across multiple threads

and processes. </p> <p>P.I.P.S. takes advantage of EKA2 and re-factors the

SCAL to allow descriptors to be shared across multiple threads within the

same process, without the use of the POSIX server. </p> </section>