12 <concept id="GUID-79100974-CAE1-5451-9ED7-E06C9B27131B" xml:lang="en"><title>Build

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

    13 Process</title><prolog><metadata><keywords/></metadata></prolog><conbody>

    23 <section id="GUID-DDD0A8B3-0375-5245-A019-C9A74575C63F"><title>Introduction</title> <p>Symbian

    22 <section id="GUID-DDD0A8B3-0375-5245-A019-C9A74575C63F"><title>Introduction</title> <p>Symbian currently builds its emulator code with the Metrowerks

    24 currently builds its emulator code with the Metrowerks CodeWarrior compiler.

    23 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

    25 This is known as the <codeph>WINSCW</codeph> build target. Binaries built

    24 using Metrowerks CodeWarrior. The build tools also support the Microsoft®

    26 with this compiler are put in the <filepath>epoc32\release\winscw</filepath> and <filepath>epoc32\winscw</filepath> directory

    25 Visual Studio .NET 2003 and Microsoft Visual Studio v6 IDEs. Note that licensees or third-parties may supply additional

    27 trees. </p> <p>You can build your programs for the emulator using Metrowerks

    26 tools, or extend support to additional compilers, which are not described

    28 CodeWarrior. The build tools also support the Microsoft® Visual Studio .NET

    27 here. </p> <p>The following sections describe the Symbian platform

    29 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.

    28 target types introduced with P.I.P.S.. </p> <p>When using tool chains

    30 Note that licensees or third-parties may supply additional tools, or extend

    29 for pre-Symbian OS v9.3, the <filepath>.mmp</filepath> file has to

    31 support to additional compilers, which are not described here. </p> <p>The

    30 be manually changed to link in various libraries. </p> <p>For Symbian

    32 following sections describe the Symbian platform target types

    31 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.

    33 introduced with P.I.P.S.. For further information see <xref href="GUID-763DCEF4-C960-58A2-99DC-7FFD3187BFD4.dita">the

    32 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

    34 native build targets</xref> section. </p> <p>When using tool chains for pre-Symbian

    33 explanation of the new target types introduced with P.I.P.S.. </p> </section>

    35 OS v9.3, the <filepath>.mmp</filepath> file has to be manually changed to

    34 <section id="GUID-423A00CF-D668-5114-860D-B30185DAB0B2"><title>P.I.P.S.

    36 link in various libraries. </p> <p>For Symbian OS v9.3 onwards the tool chain

    35 target types</title> <p>P.I.P.S. EXEs require adaptation logic to

    37 supports the new <codeph>STDEXE</codeph> and <codeph>STDDLL</codeph> target

    36 set up the C program environment and the P.I.P.S. run-time C library

    38 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

    37 context - this is performed by the <codeph>CRT0</codeph> library (also

    39 of STDEXE, STDDLL and STDLIB</xref> section for further explanation of the

    38 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.

    40 new target types introduced with P.I.P.S.. </p> </section>

    39 executables are implemented using native Symbian platform executables

    41 <section id="GUID-423A00CF-D668-5114-860D-B30185DAB0B2"><title>P.I.P.S. target

    40 linked statically to the glue code. The new target types for P.I.P.S.

    42 types</title> <p>P.I.P.S. EXEs require adaptation logic to set up the C program

    41 include the glue code by default. The glue code provides the linking

    43 environment and the P.I.P.S. run-time C library context - this is performed

    42 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

    44 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

    43 further information see the <xref href="GUID-1560C4FF-82EC-5E5D-A37D-3BBE046F0A5B.dita">Target Types</xref> section. </p> </section>

    45 code (CRT0)</xref> section for further details). </p> <p>P.I.P.S. executables

    44 <section id="GUID-6A50D190-7E5B-5109-BA38-9C962DF8EB1D"><title>Symbol

    46 are implemented using native Symbian platform executables linked statically

    45 information</title> <p>When building a P.I.P.S. DLL (that is, when

    47 to the glue code. The new target types for P.I.P.S. include the glue code

    46 the target type is <codeph>STDDLL</codeph>), function and data symbols

    48 by default. The glue code provides the linking code between the <codeph>E32Main()</codeph> entry

    47 with <codeph>extern</codeph> linkage will be exported or imported

    49 point and the <codeph>main()</codeph> entry point used in 'C' P.I.P.S. EXEs. </p> <p>For

    48 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

    50 further information see the <xref href="GUID-1560C4FF-82EC-5E5D-A37D-3BBE046F0A5B.dita">Target

    49 files. </p> <p>Exporting of symbols with <codeph>extern</codeph> linkage

    51 Types</xref> section. </p> </section>

    50 is the assumed default on other platforms and enables the source code

    52 <section id="GUID-6A50D190-7E5B-5109-BA38-9C962DF8EB1D"><title>Symbol information</title> <p>When

    51 to be easily ported. Although this may normally be undesirable in

    53 building a P.I.P.S. DLL (that is, when the target type is <codeph>STDDLL</codeph>),

    52 the embedded world, it is supported for <codeph>STDDLL</codeph> to

    54 function and data symbols with <codeph>extern</codeph> linkage will be exported

    53 avoid portable source code having to include excessive decoration

    55 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

    54 (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

    56 in the header or source files. </p> <p>Exporting of symbols with <codeph>extern</codeph> linkage

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

    57 is the assumed default on other platforms and enables the source code to be

    56 <section id="GUID-76C405AE-1AB7-59AE-BCAF-A9E09D17B24E"><title>Mapping

    58 easily ported. Although this may normally be undesirable in the embedded world,

    57 POSIX handles to the Symbian platform resource objects</title> <p id="GUID-4AA14ED5-7949-5AAB-A685-87DA43B99AFE"><b>Using non-system

    59 it is supported for <codeph>STDDLL</codeph> to avoid portable source code

    58 calls</b> </p> <p>Several P.I.P.S. APIs that directly manipulate the

    60 having to include excessive decoration (that is, the <codeph>IMPORT_C</codeph> /<codeph>EXPORT_C</codeph> macros)

    59 Symbian platform (native) resources are implemented in the System

    61 for the Symbian platform. </p> <p> <codeph>STDEXE</codeph> and <codeph>STDDLL</codeph> provide

    60 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

    62 symbol name information. For more information on the Symbian platform target

    61 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

    63 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

    62 manipulated from within <codeph>libc</codeph>. Note that none of these

    64 of STDEXE, STDDLL and STDLIB</xref> section. </p> </section>

    63 APIs allow direct access to the underlying native resources. References

    65 <section id="GUID-76C405AE-1AB7-59AE-BCAF-A9E09D17B24E"><title>Mapping POSIX

    64 to these are wrapped in POSIX-defined data structures. These data

    66 handles to the Symbian platform resource objects</title> <p id="GUID-4AA14ED5-7949-5AAB-A685-87DA43B99AFE"><b>Using

    65 structures are intended to be treated as opaque and no attempt must

    67 non-system calls</b> </p> <p>Several P.I.P.S. APIs that directly manipulate

    66 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

    68 the Symbian platform (native) resources are implemented in the System Call

    67 library. This is a component distinction. The IPC library is logically

    69 Adaptation Layer (SCAL). The exceptions to this are <codeph>pthread</codeph> s,

    68 still part of the SCAL. </p> <p id="GUID-FBF12198-B501-5525-86AF-5517A012FDF1"><b>Using the System

    70 and memory maps. The <codeph>pthread</codeph> APIs use <xref href="GUID-B0E661BC-4058-3256-B9C3-5A4FD52F6DE5.dita"><apiname>RThread</apiname></xref> s

    69 Call Adaptation Layer</b> </p> <p>One of the supports provided by

    71 and <xref href="GUID-C0FEA3A0-7DD3-3B87-A919-CB973BC05766.dita"><apiname>RMutex</apiname></xref> es directly from within <codeph>libpthread</codeph>.

    70 the System Call Adaptation Layer (SCAL) is the mapping of operations

    72 Similarly, <xref href="GUID-326A2F4D-0E99-31C0-A35D-E8BF45913F07.dita"><apiname>RChunk</apiname></xref> s that are used to provide support for

    71 on UNIX® file descriptors to the corresponding Symbian platform resource

    73 memory maps are directly manipulated from within <codeph>libc</codeph>. Note

    72 objects. The section below discusses the file descriptors case. </p> <p id="GUID-1A1FC433-B9F6-5998-9622-14B961F477E2"><b>Creating a

    74 that none of these APIs allow direct access to the underlying native resources.

    73 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

    75 References to these are wrapped in POSIX-defined data structures. These data

    74 handles to native Symbian platform resource objects. The mapping is

    76 structures are intended to be treated as opaque and no attempt must be made

    75 done through a file descriptor table. As a reminder, every application/process

    77 to dereference or use the underlying resource reference directly. </p> <p>All

    76 has its own file descriptor table. </p> <p>This example shows a call

    78 IPC calls enter the SCAL, but are handled in a separate IPC library. This

    77 to the <codeph>fopen()</codeph> function: </p> <codeblock id="GUID-F9681B44-A1E6-5971-9C5E-147D4281DBF0" xml:space="preserve">//myapp.cpp

    79 is a component distinction. The IPC library is logically still part of the

    80 SCAL. </p> <p id="GUID-FBF12198-B501-5525-86AF-5517A012FDF1"><b>Using the

    81 System Call Adaptation Layer</b> </p> <p>One of the supports provided by the

    82 System Call Adaptation Layer (SCAL) is the mapping of operations on UNIX®

    83 file descriptors to the corresponding Symbian platform resource objects. The

    84 section below discusses the file descriptors case. </p> <p id="GUID-1A1FC433-B9F6-5998-9622-14B961F477E2"><b>Creating

    85 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,

    86 below, is a good example of mapping POSIX handles to native Symbian platform

    87 resource objects. The mapping is done through a file descriptor table. As

    88 a reminder, every application/process has its own file descriptor table. </p> <p>This

    89 example shows a call to the <codeph>fopen()</codeph> function: </p> <codeblock id="GUID-F9681B44-A1E6-5971-9C5E-147D4281DBF0" xml:space="preserve">//myapp.cpp

    98 }</codeblock> <p>When <i>myapp</i> tries to open the file with <codeph>fopen()</codeph>,

    86 }</codeblock> <p>When <i>myapp</i> tries to open the file with <codeph>fopen()</codeph>, the application makes a call to the equivalent

    99 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>,

    87 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

   100 and returns the next free entry in the file descriptor table. </p> <p>In each

    88 the next free entry in the file descriptor table. </p> <p>In each

   101 table, the values <codeph>0</codeph>, <codeph>1</codeph> and <codeph>2</codeph> are

    89 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

   102 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>.

    90 shows an example file descriptor table. </p> <fig id="GUID-4CEA6881-49E0-5211-8258-C44A8E8F3CDE">

   103 The figure below shows an example file descriptor table. </p> <fig id="GUID-4CEA6881-49E0-5211-8258-C44A8E8F3CDE">

    91 <image href="GUID-8EE8E38C-7CA1-5F1B-86D0-1A0B03AAC5F2_d0e154936_href.png" placement="inline"/>

   104 <image href="GUID-8EE8E38C-7CA1-5F1B-86D0-1A0B03AAC5F2_d0e149865_href.png" placement="inline"/>

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

   105 </fig> <p>According to the descriptor table the file descriptor equals <codeph>7</codeph>,

    93 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

   106 as this was the next free entry in the table, and the write function will

    94 open file table and represents, for example, an open file, socket

   107 be writing to the file referenced by <codeph>7</codeph>. </p> <p> <b>Note:</b> A

    95 or pipe. A Symbian descriptor represents data which can reside in

   108 POSIX descriptor is an index in the process open file table and represents,

    96 any memory location, either in ROM or RAM. A descriptor object maintains

   109 for example, an open file, socket or pipe. A Symbian descriptor represents

    97 pointer and length information to describe the data. All access to

   110 data which can reside in any memory location, either in ROM or RAM. A descriptor

    98 the data is made through the descriptor object. </p> <p id="GUID-79958B57-8C71-5875-9C5B-8C313A96D13A"><b>Descriptors shared

   111 object maintains pointer and length information to describe the data. All

    99 across multiple threads within the same process</b> </p> <p>Originally

   112 access to the data is made through the descriptor object. </p> <p id="GUID-79958B57-8C71-5875-9C5B-8C313A96D13A"><b>Descriptors

   113 shared across multiple threads within the same process</b> </p> <p>Originally

   115 was achieved using servers and active objects. In other operating systems,

   101 was achieved using servers and active objects. In other operating

   116 such as Linux, resources are process-local and multi-tasking is achieved by

   102 systems, such as Linux, resources are process-local and multi-tasking

   117 multi-threading. The purpose of the POSIX server in the original <codeph>STDLIB</codeph> was

   103 is achieved by multi-threading. The purpose of the POSIX server in

   118 to allow system-wide data, resources and descriptors to be shared across multiple

   104 the original <codeph>STDLIB</codeph> was to allow system-wide data,

   119 threads. This means there was context switching between the calling thread

   105 resources and descriptors to be shared across multiple threads. This

   120 and the server thread which added latency. </p> <p>With the introduction of

   106 means there was context switching between the calling thread and the

   121 the EKA2 kernel, session handles can now be shared across multiple threads

   107 server thread which added latency. </p> <p>With the introduction of

   122 and processes. </p> <p>P.I.P.S. takes advantage of EKA2 and re-factors the

   108 the EKA2 kernel, session handles can now be shared across multiple

   123 SCAL to allow descriptors to be shared across multiple threads within the

   109 threads and processes. </p> <p>P.I.P.S. takes advantage of EKA2 and

   124 same process, without the use of the POSIX server. </p> </section>

   110 re-factors the SCAL to allow descriptors to be shared across multiple

   111 threads within the same process, without the use of the POSIX server. </p> </section>