Initial contribution of the Adaptation Documentation.
<?xml version="1.0" encoding="utf-8"?>
<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->
<!-- This component and the accompanying materials are made available under the terms of the License
"Eclipse Public License v1.0" which accompanies this distribution,
and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->
<!-- Initial Contributors:
Nokia Corporation - initial contribution.
Contributors:
-->
<!DOCTYPE concept
PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<concept id="GUID-E4447BEF-33D2-5099-BCC1-C72FBB3B0463" xml:lang="en"><title>BUILDROM</title><prolog><metadata><keywords/></metadata></prolog><conbody>
<p>BUILDROM is the Symbian platform ROM configuration tool. It is
a unified ROM building front end to prepare the configurations. It
then invokes the ROMBUILD to generate the ROM image or ROFSBUILD to
generate the ROFS image. </p>
<section id="GUID-3E50F8DA-36D3-5E3D-B229-F841EF4AC47D"><title>BUILDROM
command syntax</title><p>If the OBY files are encoded in UTF-8 with
non-ASCII character support, use the following the BUILDROM command
syntax:</p><codeblock id="GUID-379818BF-A17B-5CAF-A311-3EE4142EE51D-GENID-1-2-1-8-1-1-6-1-1-4-1-2-2-3" xml:space="preserve">BUILDROM [options] <–oby-charset=utf-8 obyfile > [<obeyfile2> [obeyfile3 [...</codeblock><p>If the OBY files are encoded in local character set
with non-ASCII character support, use the following the BUILDROM command
syntax:</p><codeblock id="GUID-379818BF-A17B-5CAF-A311-3EE4142EE51D-GENID-1-2-1-8-1-1-6-1-1-4-1-2-2-5" xml:space="preserve">BUILDROM [options] <obeyfile1> [<obeyfile2> [obeyfile3 [...</codeblock><p> <codeph>options</codeph> can be one or more of the following: </p> <table id="GUID-F50B15E9-AA5A-5946-9FD5-024287F2FD6C">
<tgroup cols="2"><colspec colname="col0" colwidth="1.00*"/><colspec colname="col1" colwidth="1.00*"/>
<tbody>
<row>
<entry><p> <codeph>–argfile=<parameter file></codeph> </p> </entry>
<entry><p>Accepts a parameter file, which contains a list of command-line
parameters specific to the ROM tools, as input. </p></entry>
</row>
<row>
<entry><p> <codeph> -Dxxx </codeph> </p> </entry>
<entry><p>C++ preprocessor arguments. A common, but not exhaustive
set is: </p><p><table id="GUID-0FD13125-051C-515A-B595-525B6C03CEA7">
<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>
<tbody>
<row>
<entry><p> <codeph>-D_DEBUG</codeph> </p></entry>
<entry><p>Selects debug versions of some files. </p></entry>
</row>
<row>
<entry><p> <codeph> -D_FULL_DEBUG</codeph> </p></entry>
<entry><p>Selects debug versions of all files. </p></entry>
</row>
<row>
<entry><p> <codeph>-D_ARM4T</codeph> </p></entry>
<entry><p>Specifies the target platform. </p></entry>
</row>
<row>
<entry><p> <codeph>-D_KABI=xxxx</codeph> </p> </entry>
<entry><p>Specifies the target platform for the kernel (for example,
ARMv5). </p></entry>
</row>
<row>
<entry><p> <codeph>-D_EABI=xxxx</codeph> </p> </entry>
<entry><p>Specifies the target for all files (for example, ARMv5). </p></entry>
</row>
<row>
<entry><p> <codeph>-DFEATUREVARIANT=xxxx</codeph> </p> </entry>
<entry><p>Specifies the name of feature-based variant (for example,
myvar). </p> <p>BUILDROM automatically looks for the binary names
and properties of the selected variant, using the data generated by
build system. </p></entry>
</row>
<row>
<entry><p>-D_NAND2 </p> </entry>
<entry><p>Specifies to generate the image for NAND flash. </p></entry>
</row>
<row>
<entry><p>-D_ONENAND </p> </entry>
<entry><p>Specifies to generate the image for ONENAND flash. </p></entry>
</row>
</tbody>
</tgroup>
</table> </p></entry>
</row>
<row>
<entry><p> <codeph>-lowmem</codeph> </p></entry>
<entry><p>Reduces the physical memory consumption during image generation. </p></entry>
</row>
<row>
<entry><p> <codeph>-loglevel<level></codeph> </p> </entry>
<entry><p>Level of information to log file. The following valid log
levels are available: </p> <p><table id="GUID-8275A5E1-141E-56B3-8202-51377AD7CAA4">
<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>
<tbody>
<row>
<entry><p> <codeph>0</codeph> </p> </entry>
<entry><p>Default level of information to log file. </p> </entry>
</row>
<row>
<entry><p> <codeph>1</codeph> </p> </entry>
<entry><p>Logs the host or the ROM filenames, the file size, and the
hidden attribute in addition to the <codeph>loglevel 0</codeph> information. </p> </entry>
</row>
<row>
<entry><p> <codeph>2</codeph> </p> </entry>
<entry><p>Logs the E32 file header attributes such as UIDs, data size,
heap size, stack size, VID, SID, and priority in addition to the <codeph>loglevel 1</codeph> information. </p> </entry>
</row>
</tbody>
</tgroup>
</table> </p></entry>
</row>
<row>
<entry><p> <codeph>-nospi </codeph> </p> </entry>
<entry><p>Instructs <codeph>BUILDROM</codeph> not to produce any static
plug-in information (<codeph>.spi</codeph>) files. See the <xref href="GUID-A27BD4D8-8B0E-57C8-9C15-736109297DEA.dita#GUID-A27BD4D8-8B0E-57C8-9C15-736109297DEA/GUID-92EAD7F7-6524-57BF-9417-B455AF469C7A">__ECOM_PLUGIN</xref> keyword for details of these files. The default
is to produce <codeph>.spi</codeph> files. </p></entry>
</row>
<row>
<entry><p> <codeph>-noimage</codeph> </p> </entry>
<entry><p>Instructs <codeph>BUILDROM</codeph> to suppress only the
generation of any ROM or ROFS images, while allowing generation of
all other relevant files. </p></entry>
</row>
<row>
<entry><p> <codeph> -o<image name> </codeph> </p> </entry>
<entry><p>The name of the ROM image. This overrides any name specified
using the <xref href="GUID-43852F38-4841-5E6F-927B-A38ED4424F0C.dita#GUID-43852F38-4841-5E6F-927B-A38ED4424F0C/GUID-29BEF45C-2361-5245-9184-0261B99B6FB1">romname</xref> keyword in an Obey file. </p></entry>
</row>
<row>
<entry><p> <codeph> -s </codeph> </p> </entry>
<entry><p>The strict option. Specifying this means that any missing
files will stop <codeph>BUILDROM</codeph> without generating a ROM
image. </p> <p>If this option is not specified, then it is possible
to generate a ROM image with missing files. </p></entry>
</row>
<row>
<entry><p> <codeph>-p</codeph> </p> </entry>
<entry><p>Preserves the intermediate files and folders (data drive
and <codeph>Z</codeph> drive) generated by BUILDROM. </p></entry>
</row>
<row>
<entry><p> <codeph>-e</codeph> </p> </entry>
<entry><p>Specifies the external tools that need to be invoked. These
are the names of the Perl modules (without the .pm extension). Multiple
modules names must be separated by commas. This is an optional parameter. </p> <p>Alternatively, external tools can be invoked by using IBY file
keyword <xref href="GUID-A27BD4D8-8B0E-57C8-9C15-736109297DEA.dita#GUID-A27BD4D8-8B0E-57C8-9C15-736109297DEA/GUID-A71135A8-C6A6-50DB-8081-8CCD5B6AC0CB">externaltool</xref>. </p></entry>
</row>
<row>
<entry><p> <codeph>-fm</codeph> =<<varname>feature_manager_database_file</varname> ><filepath>.xml</filepath> </p> </entry>
<entry><p>Parses the specified feature manager database XML files
and generates the features data file(s) (<filepath>features.dat</filepath>) in the present working directory. The number of <filepath>features.dat</filepath> files generated depends on the total number of ROM image partitions
specified in the OBEY file that is used to create the ROM image. </p> <p> <b>Notes</b> </p> <ul>
<li id="GUID-F229ED73-75AF-519F-9121-62E2D340D945"><p>You can provide
multiple feature manager database XML files delimited by commas. </p> </li>
<li id="GUID-885CB92B-7F41-5C55-B251-5955AC1B8D5C"><p>If a feature
manager option (<codeph>-fm</codeph> or <codeph>-nofm</codeph>) is
not passed to <codeph>BUILDROM</codeph> explicitly, the <codeph>-fm</codeph> option is used internally to generate a feature data file using
the default <filepath>featuredatabase.xml</filepath> file in <filepath>\epoc32\rom\include</filepath>. For more information, refer to <xref href="GUID-66708290-1472-5A2C-B6D2-191454ECFE66.dita">Enabling feature
data file generation</xref>. </p> </li>
</ul></entry>
</row>
<row>
<entry><p> <codeph>-nofm</codeph> =<<varname>Existing_features_data_file_name</varname> ><filepath>.dat</filepath> </p> </entry>
<entry><p>Includes the specified features data file in the ROM image. </p> <p> <b>Note:</b> This option is ignored by <codeph>BUILDROM</codeph> if used with the <codeph>-fm</codeph> option. </p></entry>
</row>
<row>
<entry><p> <codeph> -z=xxx or -zdrivepath=xxx </codeph> </p> </entry>
<entry><p>Specifies the location to create the Z drive directory. </p> <p>By default, a Z drive directory is created in the location from
where BUILDROM was invoked. </p></entry>
</row>
<row>
<entry><p> <codeph> -d=xxx or -datadrivepath=xxx </codeph> </p> </entry>
<entry><p>Specifies the location to create data drive directory. </p> <p>By default, the data drive directory is created in the location
from where BUILDROM was invoked. </p></entry>
</row>
<row>
<entry><p> <codeph>-k or -keepgoing </codeph> </p> </entry>
<entry><p>Enables BUILDROM to continue to create the data drive image
even if the SIS file(s), non-SIS file(s), or the Z drive image file(s)
are missing or corrupted. </p></entry>
</row>
<row>
<entry><p> <codeph>-zdriveimage="<image_1.img>,[...,<image_n.img>]"
</codeph> </p></entry>
<entry><p>Specifies the Z drive image (ROM, ROFS, and CORE image). </p></entry>
</row>
<row>
<entry><p> <codeph> –r or -retainfolder </codeph> </p></entry>
<entry><p>Instructs BUILDROM not to delete any pre-existing data drive
folder. </p></entry>
</row>
<row>
<entry><p> <codeph>-pfile=xxx</codeph> </p></entry>
<entry><p>Specifies a parameter file for INTERPRETSIS to take additional
parameters. </p></entry>
</row>
<row>
<entry><p> <codeph>-l=<logfile.txt> or -logimageentry=<logfile.txt></codeph> </p></entry>
<entry><p>Logs all stub-sis and SWI certificate file(s) that are part
of the Z drive image onto a log file. </p></entry>
</row>
<row>
<entry><p> <codeph>-argforinterpretsis </codeph> </p> </entry>
<entry><p>Specifies the command-line argument for the InterpretSIS
tool. These command-line arguments take precedence over the arguments
in the parameter file. </p></entry>
</row>
<row>
<entry><p> <codeph>-i=<optional path></codeph> </p> </entry>
<entry><p>Specifies an optional path in which the IBY files are stored.
This option is case-sensitive. </p> <p> <b>Notes:</b> </p> <ul>
<li id="GUID-549E1869-8D18-5828-A167-F2757AA476FA"><p>If the IBY files
are found both in the default path (<filepath>\epoc32\rom\include</filepath>), and the <optional path>, <codeph>BUILDROM</codeph> uses the
IBY files in the <optional path>. </p> </li>
<li id="GUID-35ABE65C-91A1-54D9-A221-8AE8DE1B8D5E"><p>If the IBY files
are not found in the default path, <codeph>BUILDROM</codeph> uses
the IBY files in the <optional path>. </p> </li>
</ul></entry>
</row>
<row>
<entry><p> <codeph>-j<NUM_OF_WORKING_THREADS></codeph> </p> </entry>
<entry><p>Specifies the number of working threads that can run concurrently
to create a ROM image. The <codeph><NUM_OF_WORKING_THREADS></codeph> must be an integer in the range 1-128. </p><p>If the <codeph>-j</codeph> option is not specified or an invalid value is specified, BUILDROM
automatically takes the number of working threads in the following
ways: </p><ul>
<li id="GUID-918C5655-3D9C-5D55-A0A2-D817ABD8049D"><p>If the <codeph>NUMBER_OF_PROCESSORS</codeph> environment variable is set properly,
BUILDROM uses the number of processors as the number of working threads. </p> </li>
<li id="GUID-A892D1A3-2054-5DE8-98E8-D023C41F5D18"><p>If the <codeph>NUMBER_OF_PROCESSORS</codeph> environment variable is not set or
is invalid, the default value <codeph>8</codeph> is used as the number
of working threads. </p> </li>
</ul></entry>
</row>
<row>
<entry><p> <codeph>-compress</codeph> </p> </entry>
<entry><p>Compresses the ROM image. It supports three types of compression:</p><ul>
<li><p><codeph>-compress</codeph>: Compresses the entire ROM image.</p></li>
<li><p><codeph>-compress=paged</codeph>: Compresses the paged section
in the ROM image.</p></li>
<li><p><codeph>-compress=unpaged</codeph>: Compresses the unpaged
section in the ROM image.</p></li>
</ul></entry>
</row>
<row>
<entry><p><codeph>—w</codeph></p></entry>
<entry><p>Warns if an incorrect input file is selected. For example,
a warning is displayed, if an incorrect binary file is selected when
binary variant is enabled.</p></entry>
</row>
<row>
<entry><p><codeph>-nosymbols</codeph></p></entry>
<entry><p>Suppresses the generation of any ROM or ROFS symbol file.
This option generates all the relevant files except symbol files.</p></entry>
</row>
<row>
<entry><p><codeph>-geninc</codeph></p></entry>
<entry><p>Generates an INC file of ROM image. The INC file contains
size information of the paged and the unpaged section within the ROM
image. The name of the output file is the same as that of the output
ROM image, with <codeph>.inc</codeph> as extension. </p></entry>
</row>
<row>
<entry><p><codeph>-spi</codeph></p></entry>
<entry><p>Creates an SPI file.</p></entry>
</row>
<row>
<entry><p><codeph>-spiplacement</codeph></p></entry>
<entry><p>Enables positioning of the SPI file.</p></entry>
</row>
<row>
<entry><p> <codeph>-compressionmethod [none | inflate | bytepair]</codeph> </p> </entry>
<entry><p>Specifies the compression algorithm to use. The following
options are available with the <codeph>-compressionmethod</codeph> keyword:</p> <p><table id="GUID-34E5FD4C-7B82-5342-85C3-C84A706C8C17-GENID-1-2-1-8-1-1-6-1-1-4-1-2-2-7-1-3-29-2-2-1">
<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>
<tbody>
<row>
<entry><p> <codeph>none </codeph> </p> </entry>
<entry><p>No compression is used. </p> </entry>
</row>
<row>
<entry><p> <codeph>inflate </codeph> </p> </entry>
<entry><p>Compresses executable files using the default (Deflate,
Huffman+LZ77) algorithm. </p> </entry>
</row>
<row>
<entry><p> <codeph>bytepair </codeph> </p> </entry>
<entry><p>Compresses executable files using the bytepair algorithm.
Bytepair compression allows faster decompression than the default
Deflate, Huffman+LZ77 algorithm. It also supports demand paging by
performing compression and decompression of code in independent 4
KB pages. </p> </entry>
</row>
</tbody>
</tgroup>
</table> </p></entry>
</row>
<row>
<entry><p> <codeph>-cache</codeph> </p> </entry>
<entry><p>Enables cache mechanism. It ensures that BUILDROM uses cached
executable files while creating a ROFS image. This allows BUILDROM
to reuse or generate cached files. </p> <p> <b>Notes</b>: </p><ul>
<li id="GUID-9B7056D4-EF5B-533B-9E9F-50AD9A7BF498-GENID-1-2-1-8-1-1-6-1-1-4-1-2-2-7-1-3-30-2-3-1"><p>The cache mechanism
is disabled by default. </p> </li>
<li id="GUID-AF355401-C732-5FB5-A472-D7EEB294E4E0-GENID-1-2-1-8-1-1-6-1-1-4-1-2-2-7-1-3-30-2-3-2"><p>The cached files
are stored on the hard disk. </p> </li>
<li id="GUID-7EEA01CD-E155-535B-915B-DE22C42FEDD0-GENID-1-2-1-8-1-1-6-1-1-4-1-2-2-7-1-3-30-2-3-3"><p>The cache command
line options (<codeph>-cache</codeph>, <codeph>-nocache</codeph>,
and <codeph>-cleancache</codeph>) are mutually exclusive. This means
that you can use only one cache option at a time. </p> </li>
</ul></entry>
</row>
<row>
<entry><p> <codeph>-nocache</codeph> </p></entry>
<entry><p>Disallows BUILDROM from using cached files while creating
a ROFS image. </p></entry>
</row>
<row>
<entry><p> <codeph>-cleancache</codeph> </p></entry>
<entry><p>Deletes all cached files from the hard disk. </p></entry>
</row>
<row>
<entry><p><codeph>-gendep</codeph></p></entry>
<entry><p>Generates dependencies file describing a internal dependencies
among executables or dlls in a ROM image.</p><p><b>Note</b>: You can
only generate dependence information in the paged section of a ROM
image.</p></entry>
</row>
<row>
<entry><p><codeph>-checkcase</codeph></p></entry>
<entry><p>Checks the character case of the path or name in OBY or
IBY files. By default, this option is disabled.</p><p><b>Note</b>:
This option is only valid on Windows.</p></entry>
</row>
<row>
<entry><p><codeph>-workdir <output-location></codeph></p></entry>
<entry><p>Generates the output files at the specified location.</p></entry>
</row>
<row>
<entry><p><codeph>-prependepocroot</codeph></p></entry>
<entry><p>Prepends EPOCROOT to the file location, if the specified
location starts from <codeph>\epoc32</codeph> without <codeph>EPOCROOT</codeph>.</p></entry>
</row>
</tbody>
</tgroup>
</table> <p><b>Note</b>: <codeph><obeyfile1></codeph> and <codeph><obeyfile2></codeph> and are standard text files containing statements
that are used to control the building of ROM images. </p> <p>See the <xref href="GUID-9CF985F1-C100-5999-9410-58B7865A1E18.dita">OBEY files</xref> reference for the full syntax. </p> </section>
<section id="GUID-4436DEEC-DB8A-4FDE-A869-63544C856ED8"><title>Passing
parameters using a file</title> <p>BUILDROM allows to pass parameters
in a file using the <codeph>-argfile</codeph> option. It provides
a solution to the limited command line length. It also reduces the
risk of error and saves time in typing from a command prompt. </p> <p><userinput>BUILDROM –argfile=arg.txt -s</userinput> </p> <p>In
the BUILDROM command above, <filepath>arg.txt</filepath> is the text
file with the parameters. An example of this file is as follows: </p> <codeblock id="GUID-C7412FD1-31CC-5860-9A6F-5A386AF5C658" xml:space="preserve">; sample parameter-file
-fm=\epoc32\rom\include\featuredatabase.xml ;generate features data file.
-noimage -nosymbols -s ;do not generate ROM image and symbol file
;and invoke buildrom in strict mode.
-D_PLAT=ARMV5
; EOF</codeblock> <p>Rules of this argument file are as follows: </p> <ul>
<li id="GUID-BBCBEA65-8DD6-5440-8F9F-E780FE2839AA"><p>Single line
comments begin with a semicolon (<b>;</b>). </p> </li>
<li id="GUID-4322E7DB-E539-5E79-85B8-1CD4C1088BA0"><p>Comments can
also be specified after the parameters. </p> </li>
<li id="GUID-C509C35B-6643-581F-9A78-ECC4E49DD943"><p>Parameters can
be specified either in a single line separated a by space, or in multiple
lines. </p> <p> </p> </li>
<li id="GUID-69B173D5-2501-5D60-8CD3-CC144422CBB7"><p>Parameters provided
in a parameter file override those specified in the command line. </p> </li>
<li id="GUID-48482902-77FE-552B-9D4D-FFC062F41E1B"><p>Environment
variables must be specified in the command line and not in the parameter
file. </p> </li>
</ul> </section>
</conbody></concept>