Build-time variants in Build tools guide

It is a common requirement to be able to build more than one variant of a program from a single set of source code. For example, you might have evaluation and full variants of a program that are identical in most respects, but which differ in a few features; or might want to build a program for more than one platform, with some features being present on platform but not on the other.

A traditional way to handle this requirement is to use the pre-preprocessor to conditionally include sections of code depending on whether a macro is set or not. For example:

#ifdef MY_FLAG // code that is compiled if MY_FLAG exists #else // code that is compiled if MY_FLAG doesn't exists #endif

Note that this is not always the best approach, as it can make code difficult to read and maintain. Alternative approaches to consider can include:

run-time detection: e.g. unless a file with a registration key is present, restrict the available options to those for the evaluation version
plug-in architectures: e.g. if you want to write a program that runs on platforms that may or may not have Bluetooth, then isolate all Bluetooth code in a plug-in that can be dynamically loaded at run-time if appropriate

However, if conditional compilation is needed, you can configure the build tools to read a file that defines the macros to use. To do this:

create a file that defines the macros as #define statements. By Symbian OS convention, such files should have an .hrh extension. The file can be anywhere on the same drive as the epoc32\ directory.
create a sub-directory of epoc32\tools\ called variant\, and create in it a text file called variant.cfg. The file must specify the full path to the .hrh macro file. Perl-type comments (marked with #) are also allowed.

When you use bldmake or abld on the command line, the build tools look for the variant.cfg file, and set any macros defined in the specified file. By adding/removing/changing the variant.cfg file in your build environment, you can alter which macros are set, and so how your project is built.

For IDE builds, the macros are set when the IDE project file is created, and not changed unless you recreate the IDE project file.

Note that you can use the macros in bld.inf and .mmp files as well as in C++ files: this allows you to conditionally specify projects, source files, etc.