1 BUILDROM.PL extensions to the OBY language

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

     3 

     4 

     5 0. General Comments

     6 

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

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

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

    10 ROM symbol file and directory listing.

    11 

    12 BUILDROM keywords are not case-sensitive.

    13 

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

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

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

    17 substitution facility.

    18 

    19 

    20 

    21 

    22 1. Textual Substitution

    23 

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

    25 conveniently because it inserts whitespace around the substituted text.

    26 

    27     DEFINE name replacement

    28 

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

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

    31 

    32 There are three pre-defined substitutions

    33 

    34     EPOCROOT    = the value of the EPOCROOT environment variable

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

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

    37 

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

    39 

    40 

    41 2. Additional Simple Keywords

    42 

    43 BUILDROM implements the following simple keywords

    44 

    45     ECHO anything at all

    46     WARNING anything at all

    47     ERROR anything at all

    48     ROMBUILD_OPTION command-line-option

    49 

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

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

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

    53 

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

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

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

    57 

    58 

    59 3. Localisation Support

    60 

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

    62 lines referring to distinct language codes.

    63 

    64     LANGUAGE_CODE nn

    65     DEFAULT_LANGUAGE nn

    66     data=MULTILINGUIFY( EXT sourcename destname )

    67 

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

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

    70 

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

    72 as follows

    73 

    74     data=MULTILINGUIFY( EXT sourcename destname )

    75 

    76 becomes

    77 

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

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

    80 

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

    82 similar mapping from language codes to filenames.

    83 

    84 

    85 4. XIP ROM format bitmaps

    86 

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

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

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

    90 BITMAP keyword as follows

    91 

    92     BITMAP=source dest

    93 

    94 becomes

    95 

    96     DATA=source_rom dest

    97 

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

    99 

   100 

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

   102 

   103    COMPRESSED-BITMAP=source dest

   104 

   105 becomes

   106 

   107 

   108     DATA=source_rom dest

   109 

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

   111 

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

   113 

   114 

   115 4.1 XIP and Non-XIP ROM format bitmaps

   116 

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

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

   119 an XIP or non-XIP ROM.

   120 

   121 	AUTO-BITMAP=source dest

   122 

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

   124 

   125 

   126 4.2 XIP and non-XIP ROM format AIF files

   127 

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

   129 

   130 	AIF=source dest

   131 

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

   133 otherwise.

   134 

   135 

   136 5. Source reorganisation for two-section ROMs

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

   138 

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

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

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

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

   143 

   144     SECTION2 anything

   145 

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

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

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

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

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

   151 

   152 

   153 6. Elaborate Example

   154 

   155 For example:

   156 

   157     LANGUAGE_CODE 01

   158     LANGUAGE_CODE 10

   159     DEFAULT_LANGUAGE 10

   160 

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

   162     SECTION2 REM bitmaps for myapp

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

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

   165 

   166     section 0x800000

   167 

   168     file=sourcedir\example destdir\example

   169     SECTION2 data=sourcedir\example2 destdir\example2

   170 

   171 would become

   172     

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

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

   175 

   176     section 0x800000

   177     REM bitmaps for myapp

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

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

   180 

   181     file=sourcedir\example destdir\example

   182     data=sourcedir\example2 destdir\example2

   183 

   184 

   185 

   186 7. Problem suppression

   187 

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

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

   190 presence of build problems.

   191 

   192     ABI_DOWNGRADE   from->to

   193 

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

   195 source file is not available. It is usually used as

   196 

   197     ABI_DOWNGRADE   THUMB->ARMI

   198 

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

   200 

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

   202 file by specifying source.EXT instead.

   203 

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

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

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

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

   208 

   209 

   210 8.  Rom configuration support

   211 

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

   213 ROMs for the same device.

   214 

   215 8.1 First you must specify the ROM devices

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

   217 

   218 Syntax:

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

   220 where:

   221 id = 0 .. 7

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

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

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

   225 compress = Compress an XIP ROM.

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

   227 

   228 8.2 Including files

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

   230 ROM_IMAGE[<id>]

   231 eg.

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

   233 

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

   235 eg.

   236 ROM_IMAGE[2] {

   237 #include "calc.iby"

   238 #include "word.iby"

   239 }

   240 

   241 8.2.3 File blocks can be nested eg.

   242 ROM_IMAGE[2] {

   243 	#include "calc.iby"

   244 	ROM_IMAGE[0] {

   245 		#include "word.iby"

   246 	}

   247 	#include "video.iby"

   248 }

   249 

   250 

   251 8.3 Automatic generation of extension header for XIP ROM

   252 

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

   254 will automatically be added to the obey file. 

   255 

   256 extensionrom=<name>

   257 romsize=<rom max size>

   258 

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

   260 

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

   262 from the obey file.

   263 

   264 9. Strict checking of missing files.

   265 

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

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

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

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

   270 

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

   272 

   273 The following tests are executed to check that functionality for

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

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

   276 

   277 Test 1 : Buildrom normal behaviour with missing files.

   278 

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

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

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

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

   283 missing and that rom image is generated.

   284 

   285 Test 2 : Buildrom missing files behaviour with strict option

   286 

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

   288 selected then buildrom terminates the generation of the rom image and

   289 reports the missing files.

   290 

   291 Test 3 : Produce a kernel rom image with extension rom

   292 

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

   294 then the obey file generated by buildrom contains the correct header

   295 information to generate an extension rom.

   296