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