BUILDROM.PL extensions to the OBY language

Copyright (c) 2009 Nokia Corporation and/or its subsidiary(-ies).  All rights reserved.

0. General Comments

BUILDROM processes OBY files written in a superset of the language supported by ROMBUILD.EXE,

producing an OBY file which is directly acceptable to ROMBUILD. BUILDROM then invokes

ROMBUILD.EXE on the final OBY file and performs a number of post-processing steps to produce a

ROM symbol file and directory listing.

BUILDROM keywords are not case-sensitive.

The C++ preprocessor is applied to the file(s) before processing, and the C++ #define, #ifdef 

and #include facilities should be used to control the inclusion and exclusion of source lines.

The modifications to the content of those lines should be done using the BUILDROM textual 

substitution facility.

1. Textual Substitution

BUILDROM.PL implements a simple textual substitution scheme: the C++ preprocessor can't be used

conveniently because it inserts whitespace around the substituted text.

    DEFINE name replacement

All subsequent instances of "name" will be replaced by "replacement". 

BUILDROM will also replace "##" with an empty string.

There are three pre-defined substitutions

    EPOCROOT    = the value of the EPOCROOT environment variable

    TODAY       = today's date as dd/mm/yyyy

    RIGHT_NOW   = the exact time as dd/mm/yyyy hh:mm:ss

There is no "UNDEFINE" facility, and the substitutions are applied in an unspecified order.

2. Additional Simple Keywords

BUILDROM implements the following simple keywords

    ECHO anything at all

    WARNING anything at all

    ERROR anything at all

    ROMBUILD_OPTION command-line-option

The ECHO keyword simply prints the rest of the line to standard output. The WARNING and ERROR 

keywords report the source file and line number as well as printing the message, and any ERRORs

will cause BUILDROM to abort without attempting to create the ROM.

The ROMBUILD_OPTION keyword can be used multiple times if desired, and adds additional commandline

parameters to the eventual invocation of ROMBUILD.EXE. It is primarily used to specify the 

"-no-header" option for platforms which don't want the 256-byte REPRO header.

3. Localisation Support

BUILDROM implements the MULTILINGUIFY() macro that can expand a single source line into multiple

lines referring to distinct language codes.

    LANGUAGE_CODE nn

    DEFAULT_LANGUAGE nn

    data=MULTILINGUIFY( EXT sourcename destname )

The LANGUAGE_CODE keyword can be used multiple times to specify the Symbian 2-digit codes for

languages to be supported in this ROM. The DEFAULT_LANGUAGE keyword should be used only once.

During the localisation pass, the MULTILINGUIFY lines are expanded into a line per language code,

as follows

    data=MULTILINGUIFY( EXT sourcename destname )

becomes

    data=sourcename.Enn destname.EXT	    for the default language code nn

    data=sourcename.Enn destname.Enn	    for all other language codes nn

This provides support for the BafUtils::NearestLanguageFile() function, which is performing a

similar mapping from language codes to filenames.

4. XIP ROM format bitmaps

MAKMAKE normally generates EPOC MBM files in a compressed format, but there is an alternative 

uncompressed format which allows an MBM to be used directly from the ROM filesystem. BUILDROM

supports on-the-fly generation of ROM format MBM files from compressed MBM files using the

BITMAP keyword as follows

    BITMAP=source dest

becomes

    DATA=source_rom dest

and source_rom is generated from source using BMCONV /q /r source_rom /msource

If the files are already compressed then the COMPRESSED-BITMAP keyword has to be used in the same way

   COMPRESSED-BITMAP=source dest

becomes

    DATA=source_rom dest

in this case source_rom is generated from source using BMCONV /q /s source_rom /msource

BUILDROM will use an existing source_rom file if if is newer than the corresponding source file.

4.1 XIP and Non-XIP ROM format bitmaps

BUILDROM provides a keyword to automatically select between XIP and non-XIP versions of bitmaps.

This is used when it is not known by the application author if the bitmap is to be included in

an XIP or non-XIP ROM.

	AUTO-BITMAP=source dest

This keyword will use "compressed-bitmap=" for XIP ROMs and "data=" for non-XIP ROMs.

4.2 XIP and non-XIP ROM format AIF files

A keyword is provided to automatically select between XIP and non-XIP versions of AIF files.

	AIF=source dest

This keyword will use the _xip version of the specified AIF for XIP ROMs or the originaly supplied file

otherwise.

5. Source reorganisation for two-section ROMs

(see also section 8 "ROM Configuration support").

ROMBUILD.EXE has the ability to create ROMs divided into two sections, such that the upper section 

can be replaced without needing to change the lower section. This facility is most often used to

put localised resource files into the upper section, so BUILDROM provides support for gathering

marked OBY source lines and placing them in the upper section of the ROM.

    SECTION2 anything

All lines beginning with the SECTION2 keyword are removed from the OBY file, and placed into 

a separate list with the SECTION2 keyword removed. When BUILDROM encounters the SECTION keyword, 

the accumulated section2 list is inserted after the SECTION line, and subsequent SECTION2 keywords

are removed as they occur. If no SECTION line is encountered, the accumulated section2 list is

emitted after the end of the input file(s).

6. Elaborate Example

For example:

    LANGUAGE_CODE 01

    LANGUAGE_CODE 10

    DEFAULT_LANGUAGE 10

    file=sourcedir\myapp.dll destdir\myapp.dll

    SECTION2 REM bitmaps for myapp

    SECTION2 bitmap=MULTILINGUIFY( MBM sourcedir\myapp destdir\myapp )

    file=sourcedir\myengine.dll destdir\myengine.dll

    section 0x800000

    file=sourcedir\example destdir\example

    SECTION2 data=sourcedir\example2 destdir\example2

would become

    file=sourcedir\myapp.dll destdir\myapp.dll

    file=sourcedir\myengine.dll destdir\myengine.dll

    section 0x800000

    REM bitmaps for myapp

    data=sourcedir\myapp.M01_rom destdir\myapp.M01

    data=sourcedir\myapp.M10_rom destdir\myapp.MBM

    file=sourcedir\example destdir\example

    data=sourcedir\example2 destdir\example2

7. Problem suppression

BUILDROM does a number of things which probably aren't appropriate for producing production devices, 

but which increase the chance of Symbian internal development builds producing a ROM in the

presence of build problems.

    ABI_DOWNGRADE   from->to

The ABI_DOWNGRADE keyword allows BUILDROM to substitute a compatible executable if the specified

source file is not available. It is usually used as

    ABI_DOWNGRADE   THUMB->ARMI

and will substitute \ARMI\ for \THUMB\ if a specified source file can't be found.

In the localisation support, problem suppression allows BUILDROM to handle a missing source.Enn 

file by specifying source.EXT instead.

In a final pass, if any file is still not available after applying these downgrades then BUILDROM

will simply comment out the line in the OBY file, in the hope that the missing file is not vital

to the ROM. If this behaviour is not required the command line option -s can be used to enforce

stricter behaviour and cause BUILDROM to terminate after the final pass. 

8.  Rom configuration support

BUILDROM has ROM configuration features to support building of multiple xip and non-xip

ROMs for the same device.

8.1 First you must specify the ROM devices

The ROM_IMAGE keyword specifies a ROM image.  There can be up to 8 images.

Syntax:

ROM_IMAGE <id> <name> [size=<rom max size>] [xip | non-xip] [compress | no-compress] [extension]

where:

id = 0 .. 7

name = a name suitable as a suffix for the ROM image, oby and logs

xip = specifies an XIP ROM.  This is the default.

size = max size of the ROM.  Not required for XIP roms.

compress = Compress an XIP ROM.

extension = Indicates this image as an extension to the previous image.

8.2 Including files

8.2.1 To mark a file for inclusion in a ROM it is prefixed with the keyword

ROM_IMAGE[<id>]

eg.

ROM_IMAGE[2] data=ZSYSTEM\Apps\Calc\calc.INSTCOL_MBM 	    System\Apps\Calc\Calc.mbm

8.2.2 A Block of files can be included using '{' '}' braces.

eg.

ROM_IMAGE[2] {

#include "calc.iby"

#include "word.iby"

}

8.2.3 File blocks can be nested eg.

ROM_IMAGE[2] {

	#include "calc.iby"

	ROM_IMAGE[0] {

		#include "word.iby"

	}

	#include "video.iby"

}

8.3 Automatic generation of extension header for XIP ROM

If the ROM_IMAGE specifices an XIP image with an extension, than the following header

will automatically be added to the obey file. 

extensionrom=<name>

romsize=<rom max size>

The <name> and <rom max size> are as specified in the ROM_IMAGE keyword. 

The addition of the header will result in rombuild tool producing multiple images

from the obey file.

9. Strict checking of missing files.

BUILDROM will normally ignore any missing files specified in the obey files. To

prevent the generation of the ROM when files are missing the -s option is used. This

ensures that BUILDROM terminates after all the files have been checked and some are

found missing. The error message indicates how many files are missing.

10. Tests for strict checking and automatic generation of extension header for XIP ROM.

The following tests are executed to check that functionality for

strict checking of missing files (section 9) and automatic generation

of extension header for XIP ROM (section 8.3) functions correctly.

Test 1 : Buildrom normal behaviour with missing files.

This test shows that if files are missing then the rom image is still

generated if the -strict option is not used. The test involves

renaming some files so that the standard obey file cannot find them.

Run buildrom and then check that the appropriate files are reported as

missing and that rom image is generated.

Test 2 : Buildrom missing files behaviour with strict option

This test shows that if the files are missing and the strict option is

selected then buildrom terminates the generation of the rom image and

reports the missing files.

Test 3 : Produce a kernel rom image with extension rom

This test shows that if an extension rom is specified in the obey file

then the obey file generated by buildrom contains the correct header

information to generate an extension rom.