Feature variants

Symbian OS can be built for multiple product configurations (variants). Each variant can include, enable or disable various features

A variant-specific .hrh file is used to configure each different product. For example, the following .hrh files define features for products phone1, phone2 and phone3 respectively:

• /epoc32/include/variant/Phone1.hrh

• /epoc32/include/variant/Phone2.hrh

• /epoc32/include/variant/Phone3.hrh

The .hrh files contain macros which are used throughout the Symbian OS source. A DLL containing variant macros may be built differently for certain variants. It may also be common for certain variants. In order to identify variant DLLs, and to establish before compilation whether a variant DLL will be unique, a checksum value is calculated based on the combination of variant macros and appended to the DLL filename. If the checksum matches an existing DLL, already built for a different variant, that DLL is shared.

For example, a my.dll with checksum appended appears as follows:

/epoc32/release/armv5/urel/my.685dfabca1f1d90889ef4ac115c01a14.dll

Support for variant builds is included in the Symbian OS build tool-chain as follows:

• The configuration information specific to each product is defined in a .var file. The .var file is placed in the /epoc32/tools/variant/ folder. For more information on .var file syntax, refer to variant configuration file syntax.

• The .hrh file containing the feature macro definitions is placed in the /epoc32/include/variant/ folder, and is referred in the .var file.

• A DLL for a variant is built by specifying the variant name on the command-line using abld. For example, the following abld command builds the DLL for the variant var1:

  > abld build armv5.var1

• The build tool-chain generates a checksum for each variant (including the default variant) and appends it to the DLL name.

• BUILDROM is modified to build a ROM image for a variant using the option -DFEATUREVARIANT. For example, the following command builds ROM image for var1:

  > buildrom [options] – DFEATUREVARIANT=var1 <obey1> [<obey2> ...]

If no .var file is specified the default.var file is used. The checksum will still be calculated and appended. You may avoid the checksum calculation by using the -invariant (or -inv) option with abld. This will build a default DLL with no checksum in the filename. If a DLL has FEATUREVARIANT specified in its mmp file, however, the -invariant option will be ignored.

• The .var file name must be same as the variant name.

• If the .var file does not include an .hrh file, the build system uses default.hrh in /epoc32/include/variant/.

• A DLL can be explicitly marked as a feature variant using the MMP keyword FEATUREVARIANT.

• The DLLs built for a variant are placed in the appropriate folder under /epoc32/release/. For example, for all urel builds of ARMV5 variants the DLLs are stored in /epoc32/release/armv5/urel/.

• The -inv or -invariant abld option is effective only if the DLL is not marked as feature variant explicitly.

• How to build feature based variants

• How to build ROMs with variants