--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/Adaptation/GUID-E4447BEF-33D2-5099-BCC1-C72FBB3B0463.dita Fri Oct 15 14:32:18 2010 +0100
@@ -0,0 +1,365 @@
+<?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>
\ No newline at end of file