--- a/Symbian3/SDK/Source/GUID-79100974-CAE1-5451-9ED7-E06C9B27131B.dita Fri Jul 16 17:23:46 2010 +0100
+++ b/Symbian3/SDK/Source/GUID-79100974-CAE1-5451-9ED7-E06C9B27131B.dita Tue Jul 20 12:00:49 2010 +0100
@@ -9,8 +9,7 @@
-->
<!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>
+<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>
@@ -20,73 +19,62 @@
<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
+<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
@@ -95,31 +83,30 @@
//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
+}</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>
+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>
\ No newline at end of file