How to use 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 targets used in real Symbian OS phones. Depending on the target, building can be performed from the Windows command line, from the Metrowerks CodeWarrior For Symbian Professional IDE (called henceforth simply CodeWarrior), or from the Microsoft Visual C++ 6.0 IDE.

This page contains an overview of the build process and tools.

Code for an emulator can be built with two compilers:

• CodeWarrior: the output of this is called a WINSCW build. Binaries built with this compiler are put in the epoc32\release\winscw and epoc32\winscw directory trees.

• Microsoft Visual C++: the output of this is called a WINS build. Binaries built with this compiler are put in the epoc32\release\wins and epoc32\wins directory trees.

You can install and build with either, or both, compilers. You cannot however mix their output, e.g. attempt to link an .exe built with Visual C++ to a library built with CodeWarrior. For both compilers, you can build programs from their respective IDEs, or from the command line.

Building for ARM targets is done through the Cygnus GCC toolchain. This is supplied as part of the Symbian OS Development Kit in the epoc32\gcc directory. You can invoke this toolchain from the command line, and also from the CodeWarrior IDE.

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 (.mpp 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. CodeWarrior also alllows new projects to be created from existing template (or stationer) projects.

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.

You can build applications for a WINSCW emulator using the CodeWarrior compiler from the CodeWarrior IDE. You can also build for ARM targets from the IDE: this invokes the Cygnus GCC toolchain, rather than CodeWarrior's own compiler. The CodeWarrior documentation describes in full how to use CodeWarrior with Symbian OS in its Targeting Symbian OS online manual, but a brief summary follows.

The simplest way to use CodeWarrior, is, after defining a bld.inf file and a .mmp file, choose the File | Import project from .mmp file command. CodeWarrior then reads the .mmp file that you select, and generates and opens a CodeWarrior project. You can then use the normal CodeWarrior commands to run, build, and debug the project.

If later you change the .mmp file, you can use the same commands to regenerate the IDE workspace. Changes you make to the project made through the IDE, such as adding a source file, are not automatically written to the .mmp file, but it is good practice to manually keep the .mmp file up to date with any changes made.

The IDE project files have special build steps which invoke the resource compiler, so for projects that use resources, this does not need to be run separately. The IDE does not currently support building of multi-bitmap files and of AIF files: these will need to be built from the command line.

Alternative method

A slightly longer method is available that creates a CodeWarrior IDE project from the command line. To do this, run bldmake bldfiles as described, and then, to generate a CodeWarrior IDE project, use:

> abld makefile CW_IDE

This creates an importable project file project-name.xml in the directory <path>\epoc32\build\absolute_path_to_mmp_file\mmp_basename \winscw\.

You can now tell CodeWarrior to read this file and from it generate a project file of its own native type (an .mcp file). Start CodeWarrior, choose the File | Import Project... command, select the HelloWorld.xml file, and choose a name for the CodeWarrior project (such as HelloWorld again). CodeWarrior will now generate and load the project, which you can build, run, debug, etc. using the normal IDE commands.

Symbian Stationery Wizard

CodeWarrior can create new projects based on supplied template projects (called stationery). To use this, choose File | New... and choose Symbian Stationery Wizard from the Project tab. A wizard then starts that offers you choices from the available development kits and stationery.

It is expected that licensees will provide suitable stationery as part of licensee Development Kits and SDKs. The Symbian OS Development Kit itself does not currently supply any stationery.

You can build applications for a WINS emulator from the Microsoft Visual C++ 6 IDE.

To do either, define a bld.inf file and a .mmp file, and run bldmake bldfiles as described.

To generate a MS Visual C++ IDE workspace, use:

> abld makefile vc6

The .dsw and .dsp files are created in the directory: epoc32\build\absolute_path_to_mmp_file\mmp_basename\wins\.

If later you change the .mmp file, you can use the same commands to regenerate the IDE workspaces without the need to close the workspace first.

The IDE project files have special build steps which invoke the resource compiler, so for projects that use resources, this does not need to be run separately.