
$Id$


romlinker
=========


General Information
===================

romlinker provides a ROM image construction service.  It takes multiple
components, together with meta-information about the target image and
generates the target image.  romlinker can create three different types of
image:

* "rom"    - a normal RISC OS ROM image
* "extrom" - a standard RISC OS Extension ROM image
* "exprom" - a standard RISC OS Expansion card ROM image


Interface
=========

The invocation syntax for romlinker is:

  romlinker [options] [module [module ...]]

Some options are mandatory, some are optional.  The presence of some
parameters makes other parameters mandatory.

After the options code the list of files to be combined into the image. 
These may be preceded by a decimal number parameter indicating a fixed offset
from the start of the image at which the following component should be
placed.


Mandatory options
=================

-format:  Specifies the type of image that is being created.  This can be
          rom, extrom or exprom.  Failure to specify any format is an error;
          failure to specify a known format is an error.
          
-imagename: The name of the file to contain the generated image.

-imagesize: The size of the image in bytes (in decimal).


If the format is extrom or exprom, then there is a further mandatory
parameter:

-poduleproduct: The product code of the extension/expansion ROM.


Optional options
================

-via: The following parameter is the name of a file which contains extra
      command-line arguments.  The file is parsed and each logical line is
      treated as if it had been specified as a single command-line
      parameter.  NOTE that this means that lines containing whitespace will
      be treated as ONE parameter, not split at spaces.


For "rom" images:

-sigstr: The next parameter is a 4-letter signature string for the image
         which acts as a 32-bit identity string.

-signum: The next parameter is a numeric representation of the 32-bit
         value which acts as the image identity string.


For "exprom" and "extrom" images:

-poduledescription: The description string chunk contents

-poduleserial: The serial number chunk contents

-podulemanufacture: The place of manufacture chunk contents

-podulepart: The part number chunk contents

-poduledate: The date chunk contents (will be automatically generated as
             the local date by romlinker if this parameter is omitted)
             
-podulestatus: The revision status chunk contents


Adding new options
==================

In future, other options may be added.  Any product which needs to pass
options through to the romlinker may do so by inserting them into the
components file prefixed by %.

e.g.

%myoption Hello

will arrive as two arguments, "-myoption" and "Hello" in the romlinker
argument list.

Not all arguments are passed through - srcbuild will have stripped things
like %image (it replaces it with -imagename), %messages, %joiner,
%joinerformat, %include and %log


==END==
