<?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] &lt;–oby-charset=utf-8 obyfile &gt; [&lt;obeyfile2&gt; [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] &lt;obeyfile1&gt; [&lt;obeyfile2&gt; [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=&lt;parameter file&gt;</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&lt;level&gt;</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&lt;image name&gt; </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> =&lt;<varname>feature_manager_database_file</varname> &gt;<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> =&lt;<varname>Existing_features_data_file_name</varname> &gt;<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="&lt;image_1.img&gt;,[...,&lt;image_n.img&gt;]"

                  </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=&lt;logfile.txt&gt; or                   -logimageentry=&lt;logfile.txt&gt;</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=&lt;optional path&gt;</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 &lt;optional path&gt;, <codeph>BUILDROM</codeph> uses the

IBY files in the &lt;optional path&gt;. </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 &lt;optional path&gt;. </p> </li>

</ul></entry>

</row>

<row>

<entry><p> <codeph>-j&lt;NUM_OF_WORKING_THREADS&gt;</codeph>  </p> </entry>

<entry><p>Specifies the number of working threads that can run concurrently

to create a ROM image. The <codeph>&lt;NUM_OF_WORKING_THREADS&gt;</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 &lt;output-location&gt;</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>&lt;obeyfile1&gt;</codeph> and <codeph>&lt;obeyfile2&gt;</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>