<?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. 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.. </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_d0e154936_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>
</conbody></concept>