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

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

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

</conbody></concept>