C H A P T E R 5

PCSL Build System

This chapter describes the targets and options in the PCSL build system. It also includes an overview of the process for performing a PCSL build for your own platform.

PCSL Build Overview

You must define PCSL_PLATFORM to build PCSL. The value of this variable specifies the software layer below PCSL, the target processor, and the compiler type. For example, linux_arm_gcc specifies that PCSL is implemented on top of Linux on an ARM processor, and the build is performed using GCC. Another example is javacall_i386_vc, which means that PCSL is implemented over the JavaCall API on Intel x86 hardware, and Microsoft's Visual C++ compiler is used for the build.

You can find the supported values for PCSL_PLATFORM by looking in the pcsl/makefiles/platforms directory.

The PCSL build system includes four targets which are described in the following table.

TABLE 5-1 PCSL Build Targets
Name	Description
`all` (default)	Builds libraries and public header files in `$PCSL_OUTPUT_DIR`.
`clean`	Removes all output for `$PCSL_PLATFORM` from `$PCSL_OUTPUT_DIR`.
`doc`	Builds API documention in `$PCSL_OUTPUT_DIR/doc`.
`donuts`	Builds unit tests.

The name all is a little misleading, as it does not build the documentation or the unit tests. However, all does build the libraries and headers that are needed to build CLDC and the Java Wireless Client software.

Output

The output of the PCSL build is placed in PCSL_OUTPUT_DIR. If you do not define this variable, the default value is pcsl/output. The PCSL build system creates one output subdirectory per platform (minus the compiler). For example, the output of a javacall_i386_vc build goes in $PCSL_OUTPUT_DIR/javacall_i386.

Building all creates the following directories in the platform output directory:

inc

lib

obj

If you also build donuts, you'll get two additional directories:

bin

generated

CLDC and the Java Wireless Client software use the inc and lib directories.

Debugging Symbols

PCSL is built without debugging symbols by default. Set USE_DEBUG to true to include debugging symbols in the output of the build.

API Documentation

The PCSL build system uses Doxygen to create API documentation for the doc target. Doxygen is available at http://doxygen.org/.

The PCSL build system assumes that Doxygen is located at /usr/bin/doxygen. If this is not true, edit pcsl/makefiles/share/Docs.gmk and change the definition of the DOXYGEN_CMD variable. For example, on Windows, you might have to do something like this:

DOXYGEN_CMD = c:/PROGRA~1/doxygen/bin/doxygen.exe

When the doc build finishes, the top page of the documentation is $PCSL_OUTPUT_DIR/doc/doxygen/html/index.html.

Selecting Modules

PCSL includes five services, as follows:

file

memory

network

print

string

The implementation of a service is a module. When you build PCSL, you can select which module to use for each service. A variable is used to select each service's module.

Each PCSL service has a corresponding directory. In general, modules are represented by the subdirectories of each service directory. For example, the print/file directory contains the file module of the print service.

To build the file module for the print service do something like this:

$ make PRINT_MODULE=file

The following table shows the variable names and possible values for module selection.

TABLE 5-2 PCSL Module Selection
Service Variable	Values
`FILE_MODULE`	`armsd` `javacall` `posix` (default) `ram` simulates a file system in RAM `stubs` `win32`
`MEMORY_MODULE`	`heap` dynamically allocates memory within a chunk of heap. This module has an additional debugging facility to help detect memory leaks and corruption. `malloc` (default) uses standard C `malloc()` `stubs`
`NETWORK_MODULE`	`bsd/generic` uses the BSD implementation. `bsd/qte` (default) uses Qt/Embedded implementation `javacall` `sos` is Server over Serial `stubs` `socket/winsock`
PRINT_MODULE	`file` prints to a log file `javacall` `stdout` (default) `stubs`
STRING_MODULE	`utf8` `utf16` (default)

About Stubs

Each PCSL service includes a stubs module that builds empty versions of its public API. The empty versions of the functions that have a return value return either NULL or an appropriate error code.

The stubs modules make it easy to port the Java Wireless Client software to a new platform, one PCSL service at a time. You can build the Java Wireless Client software before you port all of the services by using stubs for any services that are not yet ported.

Building Individual Services

Each of the build targets (all, clean, doc, and donuts) that you can use at the top level of PCSL can also be applied to builds in the directories for each service. Simply change your working directory to one of the service directories, set variables, and run make.

For example, to build just the print service using the file module, do something like this:

D:\jwc>cd pcsl\print

D:\jwc\pcsl\print>make PRINT_MODULE=file

Network Service

Datagram and server socket support in the network service is controlled by the USE_DATAGRAM and USE_SERVER_SOCKET variables. The default value for both is true. To disable datagrams or server sockets, set the corresponding variable to false.

Note - The serial subdirectory of the network service is not a module. The files in the serial subdirectory are used by the sos module.

If you choose the Server over Serial (sos) module, the build is slightly more complicated. The sos module is based on the Java Communications API. you will need a Java Communications API implementation for your platform, and you will need a Java platform compiler.

First, set JDK_DIR to point to your JDK software.

Next, install the Java Communications API implementation for your operating system. Implementations for Linux and the SolarisTM Operating System are available at http://java.sun.com/products/javacomm/.

Follow the Downloads link.

Implementations for other platforms are available at http://www.rxtx.org/.

Once the JDK softwrae and Java Communications API are available, you can build the sos module.

Running Unit Tests

Building the unit tests creates the executable for running the tests. The executable is bin/donuts in the output directory for your platform. Use it to run all the tests or an individual test and to list the unit tests.

To run all the tests, just run donuts. This example shows how to run unit tests for the linux_i386 platform:

$ cd $PCSL_OUTPUT_DIR/linux_i386

$ bin/donuts

List the unit tests like this:

$ bin/donuts -list

Run a test by naming it. This example runs testString:

$ bin/donuts testString

Extending the Build System

The PCSL build system uses a top-level platform-specific makefile in the
pcsl/makefiles/platforms directory. It also uses makefiles for specific operating systems and CPUs. These makefiles are in pcsl/makefiles/share.

The makefiles, which have .gmk extensions, define all of the variables exported to the subsystem makefiles. The variables usually specify directories. The makefiles also define OS-specific commands, such as CC_OUTPUT, and subsystem targets.

This section outlines the steps for extending the build system to support a new platform, or extending the build system for a new service module.

You can find more information in pcsl/makefiles/README.build_port.

Creating a New Platform Makefile

First, create a platform makefile in pcsl/makefiles/platforms. Use an existing makefile as a template. Choose one that is close to your platform and compiler. Name the new file using the file naming convention of OS, processor, and compiler names, separated by underscores.

For example, if you want to build for Symbian OS, using the ARM processor, with the GCC compiler, copy the linux_arm_gcc.gmk file. Name your new file symbian_arm_gcc.gmk.

Next, define PCSL_OS, PCSL_CPU, and other platform-specific variables in your new makefile.

For example, if you are configuring the build system for the Linux OS and are using the ARM CPU, set the following variables:

PCSL_OS=linux

PCSL_CPU=arm

If you wish to override the PCSL_CHUNKMEM_DIR and PCSL_CHUNKMEM_IMPL values that are defined in pcsl/makefiles/top.gmk, define them in your platform makefile.

Include the matching OS and compiler makefiles from pcsl/makefiles/share in your platform makefile. The next section describes how to create OS and compiler makefiles if they are not available.

Creating New OS and Compiler Makefiles

If your platform includes an OS which does not have a corresponding makefile in pcsl/makefiles/share, you must create a new one. Use an existing makefile as a template. Give the new file your operating system name.

For example, if you are configuring the build system for the Symbian OS, use linux.gmk as a template to create symbian.gmk.

The OS makefile defines operating-system specific variables. For example, EXE is the suffix for executables.

Likewise, if your platform includes a compiler that does not have a corresponding makefile in pcsl/makefiles/share, create a new one. Use an existing makefile as a template. Give the new file your compiler name.

Define the compiler commands and flags in the compiler makefile. The following variables must be defined:

CC - Compilation command for C files (such as gcc)

CPP - Compilation command for C++ files (such as g++)

LD - Link command for C++ and C files (such as g++)

AR - Archiving command (such as ar -rc)

CC_OUTPUT - Output flag for C and C++ files (such a, -o)

AR_OUTPUT - Output flag for the archiver (such as /OUT:)

LD_OUTPUT - Output flag for the linker (such as -o)

LIB_EXT - Suffix for library files (such as .a)

CFLAGS - Compiler flags (such as -c -O3)

LD_FLAGS - Linker flags, if any

If your target platforms have the same OS on all devices, but different CPUs, add compiler flags based on the CPU of your target platform.

Creating a New Module

To create a new module for a service, first create a subdirectory in the service directory. For example, if you create a new platform implementation, my-platform, of the file service, create its implementation directory, file/my-platform.

Create a file named GNUmakefile file in the new directory. Use an existing GNUmakefile from another module directory as a template. For example, in the file service module, the posix and ram directories have GNUmakefile files you can use as a model

Keep these points in mind when you use an existing GNUmakefile as a template:

You do not need to change the donuts and doc target definitions and rules.

You might need to change the file names in the all and clean target definitions.

You might need to change the compilation rules for the files, but existing rules work in many cases.