Document Status
---------------
         Title:  Cross compiling C modules
Drawing Number:  2503,105/T
     Author(s):  RISC OS Open Ltd
          Date:  2015-07-27
 Change Number:  N/A


Contents
--------
Document Status
Introduction
Makefile


Introduction
------------

This document describes, in outline, the changes that must be made to RISC OS
C module components to permit them to build on hosts other than RISC OS.

THIS IS NOT A REVIEWED DOCUMENT - MERELY NOTES TO PROGRAMMERS WHO NEED THE
BENEFIT OF OUR PRIOR EXPERIENCES.

Because of this, not all the technical terms are explained fully, and there
is no glossary.


========
Makefile
========

Resources
---------

CModule provides the "resources" rule invoked by srcbuild to export
resources.

Most modules will have messages for use with MessageTrans, in which case no
action need be taken - CModule will handle this for you.  It will append
any CmdHelp file containing the syntax and help messages for *-commands in the
module (looking in LocalRes:CmdHelp) to the message tokens (looking
in LocalRes:Messages).

If srcbuild has set CMDHELP=None then the CmdHelp file will not be appended,
this could be used to pass a predefine into CMHG (using CMHGDEFINES) to select
between message tokens and hardwired English messages suitable for
pre RISC OS 3.60.

If there are no resources at all, define CUSTOMRES as "no".  CModule will
merely echo a message saying that there are no resources for this component
during builds.

More complex modules might have sprites files, Toolbox resources, templates,
or similar data files beyond the default 'Messages' mentioned above. These
extra files can be listed in INSTRES_FILES and they will be copied alongside
the messages file during the resources phase. If these files need some
pre processing, for example squashing sprites files, then INSTRES_DEPENDS can
be set to assert a dependency on the intermediate file before CModule copies
it last. Compare this with INSTAPP_FILES and INSTAPP_DEPENDS in the CApp
makefile.

Should the standalone/debug (RAM) variant and ROM variant require different
resources for some reason, INSTRAM_FILES/INSTROM_FILES can be used instead
to select between the two. This is expected to be rarely useful, for example
to omit a sprites file when it is known to be in the ROM Wimp sprite pool and
to include one for RAM loading on older OS versions where the Wimp pool has
the required sprite missing. 

If you want to prevent CModule's rule from being invoked, you must define
the macro CUSTOMRES to "custom" and provide your own.

The 'resources' rules provided assume that the ResourceFS target directory
for any messages is Resources.${TARGET}.  If it is not this, then you must
set the macro RESFSDIR to be the target directory.  You can use the macro
RESDIR in your definition (it will point to the Resources directory - hence
the default of ${RESDIR}.${TARGET}).

These schemes cater for the most common idioms
  a) There are no resources at all when CUSTOMRES=no
  b) There are only default resources (Messages+CmdHelp)
  c) There are extra resources listed in INSTRES_FILES in addition to
     the default resources (Messages+CmdHelp)
  d) There are entirely custom resources when CUSTOMRES=custom


ROM / Standalone / Debug
------------------------

The 'rom' rule builds the module destined for ROM, the makefile will
add the contents of ROMCDEFINES to the compiler command line switches. This
is most often useful to add -DROM so that your source can add or remove code
as required with

  #ifdef ROM
  things-for-rom
  #else
  things-for-standalone
  #endif

standalone and debug builds destined for RAM will use RAMCDEFINES similarly,
though the 'ifdef ROM/else/endif' construct suggested above does the same
thing.

During the 'rom' phase of srcbuild the module will be linked against the
ROM C stubs for the ANSI C library, plus any optional libraries specified
by the master makefile in LIBS or ROM_LIBS. The later 'rom_link' phase of
srcbuild statically links the module against the ROM C library.

The 'standalone' rule builds the module destined for softload (or
extension ROM or expansion card).  An AOF object file is generated containing
a ResourceFS area called 'Resources' (by default) which allows the C code
to get the address of the area for registering/deregistering with ResourceFS.
To generate this ResourceFS area the 'resources' rule is run with the output
directed to a temporary directory, the contents of this temporary directory
are then given to ${RESGEN} - so whatever would have appeared in ResourceFS
in the ROM case will appear in the generated resource area.

The 'debug' rule builds a standalone module linking against DBG_LIBS in
addition to the C library and LIBS.


==END==
