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