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.