Build Process

Introduction

Symbian currently builds its emulator code with the Metrowerks CodeWarrior compiler. This is known as the WINSCW build target. Binaries built with this compiler are put in the epoc32\release\winscw and epoc32\winscw directory trees.

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.

The following sections describe the Symbian platform target types introduced with P.I.P.S..

When using tool chains for pre-Symbian OS v9.3, the .mmp file has to be manually changed to link in various libraries.

For Symbian OS v9.3 onwards the tool chain supports the new STDEXE and STDDLL target types for P.I.P.S. EXEs and DLLs. See the Generation of STDEXE, STDDLL and STDLIB section for further explanation of the new target types introduced with P.I.P.S..

P.I.P.S. target types

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 CRT0 library (also known as glue code, see the Glue code (CRT0) section for further details).

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 E32Main() entry point and the main() entry point used in 'C' P.I.P.S. EXEs.

For further information see the Target Types section.

Symbol information

When building a P.I.P.S. DLL (that is, when the target type is STDDLL ), function and data symbols with extern linkage will be exported or imported by default, without any requirement for IMPORT_C / EXPORT_C declarations in the header or source files.

Exporting of symbols with extern 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 STDDLL to avoid portable source code having to include excessive decoration (that is, the IMPORT_C / EXPORT_C macros) for the Symbian platform.

STDEXE and STDDLL provide symbol name information. For more information on the Symbian platform target types see the Generation of STDEXE, STDDLL and STDLIB section.

Mapping POSIX handles to the Symbian platform resource objects

Using non-system calls

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 pthread s, and memory maps. The pthread APIs use RThread s and RMutex es directly from within libpthread . Similarly, RChunk s that are used to provide support for memory maps are directly manipulated from within libc . 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.

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.

Using the System Call Adaptation Layer

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.

Creating a new file descriptor

The porting of the 'C' POSIX fopen() 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.

This example shows a call to the fopen() function:

       
        
       
       //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);

}
      

When myapp tries to open the file with fopen() , the application makes a call to the equivalent Symbian platform function, RFile::Open() , and returns the next free entry in the file descriptor table.

In each table, the values 0 , 1 and 2 are reserved for stdin() , sdtout() and stderr() . The figure below shows an example file descriptor table.

According to the descriptor table the file descriptor equals 7 , as this was the next free entry in the table, and the write function will be writing to the file referenced by 7 .

Note: 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.

Descriptors shared across multiple threads within the same process

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

With the introduction of the EKA2 kernel, session handles can now be shared across multiple threads and processes.

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.