The Symbian OS build process

Symbian OS programs are initially developed for a Symbian OS emulator running on Windows, and are then rebuilt for the ARM processor (native) targets used in real Symbian OS phones. Building can be performed from the Windows command line, or from within an IDE if one is available. The descriptions given in this documentation set concentrate on command line building, as documentation for using an IDE is normally distributed with the IDE itself. For example, the Metrowerks CodeWarrior documentation describes in full how to use Metrowerks CodeWarrior with Symbian OS in its Targeting Symbian OS online manual.

This section describes the tools and compilers supported on the kits supplied by Symbian. Note that licensees or third-parties may supply additional tools, or extend support to additional compilers which are not described here.

Symbian build their 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 have support for using the Microsoft Visual Studio .NET 2003, or Microsoft Visual Studio v6 IDEs. See The emulator build targets for more details.

To build code for a phone, a compiler based on the Application Binary Interface (ABI) for the ARM Architecture is needed. This is a standard for the interfaces of binary code running in ARM environments, and is intended to allow inter-operation of binaries produced by different compilers that conform to the standard. The specification is published by ARM at www.arm.com/products/DevTools/abi/bsabi.pdf.

The Symbian OS build tools are configured to work with two compilers in particular:

• ARM's own RealView Compiler Tools (RVCT). This is particularly intended for licensee's building ROMs for phones. For details, see ARM's website at http://www.arm.com/products/DevTools/RealViewDevSuite.html.

  The situation is complicated by there existing two versions of the ARM ABI, referred to as v1 and v2 respectively. The toolchain allows either to be chosen.

• A version of the GNU Compiler Collection (GCC) that supports the ABI for the ARM Architecture. This compiler is delivered on Symbian OS kits, and is freely available. This target is known as GCCE. It can only be used to compile code to v2 of the ARM ABI, not to the earlier v1.

See The native build targets for more details.

Because of the variety of targets and toolchains available, Symbian OS allows projects to be specified in a form not specific to any. These neutral project files are then used by Symbian OS tools to create toolchain-specific project files when these are required.

The key project files are:

• a project definition file (.mmp file) that describes a project to be built. This is an environment neutral file that can be used by the tools to produce make files for any of the supported target environments. It also defines resource file and application information files to be built.

• a component description file (bld.inf), which lists all the projects in a component, and gives additional build instructions.

When you create a new project, you write these files (or typically copy existing similar files and modify them) in a text editor. IDE's may alllow new projects to be created from existing template projects.

See How to build GUI applications, How to build DLLs, and How to build EXEs for guidance on how to write project files for the three most common types of program. See the Build tools reference for details on the file formats and syntax.

You can build for any target from the command line. The procedure is summarised below.

1. Create a project specification (.mmp) file.

2. Create a component definition file (bld.inf). In many cases this will specify a single project mmp file.

3. Run bldmake from the directory where the bld.inf file is located:

   > bldmake bldfiles

   This creates a abld.bat batch file, which you use in the next step.

4. Use abld build to build the project.

   This builds the project for all valid targets and both release and debug variants. To build for a particular target and variant, use abld build target-name variant, for example

   > abld build winscw udeb

   to build for the debug variant of WINSCW.

For more details on using the tools, see How to use bldmake and How to use abld.