<concept id="GUID-79100974-CAE1-5451-9ED7-E06C9B27131B" xml:lang="en"><title>Build Process</title><prolog><metadata><keywords/></metadata></prolog><conbody>

<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

}</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

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>