Document Status
---------------
  Distribution:  Company Confidential
         Title:  RISC OS StdTools Makefile
Drawing Number:  2503,107/T
         Issue:  A
     Author(s):  Stewart Brodie
          Date:  2001-04-17
 Change Number:  N/A
    Last Issue:  N/A


Contents
--------
Document Status
Issue History
Introduction
Key features
Makefile
Copy and wipe
Standard options



Issue History
-------------

1       17/04/01        Original version


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

This document describes, in outline, the StdTools shared makefile for RISC OS
builds.  It assumes that the reader has some knowledge of the RISC OS system.

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.


Key features
------------

The key features are:

* Avoid duplication by using shared macro definitions
* Consistent sets of tools are used
* Replacing tools with different ones can be achieved in one change


Makefile
--------

StdTools contains the basic macro definitions which determine the core
toolset used in the construction of RISC OS software.  Whilst the StdTools
file (in RiscOS/BuildSys/Makefiles) contains the definitive set, this
document contains information about the most important tools (as of revision
1.11 of the StdTools makefile fragment)

It also contains default flag settings for the assembler, compiler, cmhg and
libfile.

Copying and wiping files are handled in a peculiar way, so they are explained
in a section of their own.

Default options for the core tools are explained in a section on their own.

StdTools does NOT define any rules - only macros.  Thus after including this
Makefile, it is safe to alter any of the macro definitions that have been
provided by StdTools.  However, this should be done with care, as other
makefile fragments may be relying on the definitions made in StdTools for
correct operation.


Tools
=====

The following tools are represented by a capitalised macro of the same name
(e.g. the macro AASM is defined as aasm):

aasm, binaof, cc, c++, cmhg, decaof, do, echo, modgen, modsqz, resgen,
settype, squash, tlink, tokencheck, tokenise, translate, unmodsqz, awk,
rpcgen, sed

There are other tools with specific directory prefixes to enable GNU.* and
Unix.* binaries to be located within the library directory, but with names
that match the tool names.  These are:

chmod, df, diff, egrep, find, gawk, ident, ls, pwd, wc, zip, unzip

Some tools are perl scripts.  The PERL macro is defined as "do perl" to force
system variables on the command-line to be resolved before perl is invoked. 
Tools which are perl scripts invoke perl explicitly via ${PERL} using the
Build:<scriptname> to enable perl to find the script.  These tools are:

FilterComp, GetVersion, Hdr2H, TidyDesc

The MKDIR macro is defined as "do mkdir -p", to ensure that entire directory
hierarchies can be created without having to create the hierarchy one level
at a time.  The 'do' is used to forcibly expand system variables as with
perl.


The other tools macros are:

---------------------------------------------------------------------------
Macro                 RISC OS Tool/*-command
---------------------------------------------------------------------------
AR                    libfile
AS                    objasm
CAT                   print
DATA2AOF              datatoaof
LD                    link
MAKE                  amu
RM                    remove
SQZ                   squeeze
STRIPDEPEND           stripdepnd
TOUCH                 create
CD                    dir
LEX                   GNU.flex
YACC                  GNU.bison
---------------------------------------------------------------------------

Any other tools required should be added to this file.  


Copy and wipe
-------------

The copy macro (CP) and wipe macro (WIPE) are mapped to the RISC OS built-in
*-commands *copy and *wipe.  Because of the ordering of the CLI options,
users of these macros must append the flags to the two (CP) or one (WIPE)
filename parameters.  The default flags for CP are stored in CPFLAGS.  The
default flags for WIPE are stored in WFLAGS.  Usage is thus:

  ${CP} source-filespec destination-filespec ${CPFLAGS}
  ${WIPE} filespec ${WFLAGS}
  
Failure to append the flags macros will result in builds halting awaiting
user input.  The default CPFLAGS and WFLAGS settings can be overridden by
changing the macros after the inclusion of the StdTools makefile:

include StdTools
CPFLAGS = FRV~C~N

In this case, the verbose option is being switched on.  The defaults are for
CPFLAGS to be "FR~C~V~N" and WFLAGS to be "FR~C~V".  *However*, changing
these flags should not be done without good reason, as it may break
cross-compiled builds.  The UNIX version of StdTools will define CP as "cp
-fr" and WIPE as "rm -rf", and make WFLAGS and CPFLAGS as empty.


Standard options
----------------

Additionally, some standard tools have their options preset by StdTools. 
Mostly this involves the DDE tool options.  The macro STDTOOLOPTIONS is
defined to be "-depend !Depend ${THROWBACK}".  THROWBACK will be set to
-throwback by well-behaved TaskObey files and be blank during ROM builds, so
throwback windows do not pop up all over the place during ROM builds, but do
during development.

AASMFLAGS (for aasm), ASFLAGS (for objasm), CFLAGS (for cc) and CMHGFLAGS
(for cmhg), ARFLAGS (for libfile) are defined by StdTools using +=, thus it
will *append* these standard options to any you care to define before
including StdTools.  If you want to add things after StdTools has defined
them, you can use += to add your extra options after including StdTools.

---------------------------------------------------------------------------
Macro        Flags added
---------------------------------------------------------------------------
AASMFLAGS    -Stamp -quit ${STDTOOLOPTIONS} ${AASMDEFINES} ${AASMINCLUDES}
ASFLAGS      -Stamp -quit ${STDTOOLOPTIONS} ${ASMDEFINES} ${ASMINCLUDES}
CFLAGS       -c ${STDTOOLOPTIONS} ${CDEFINES} ${CINCLUDES}
CMHGFLAGS    -p ${STDTOOLOPTIONS} ${CMHGDEFINES} ${CMHGINCLUDES}
AASMFLAGS    -Stamp -quit ${STDTOOLOPTIONS} ${AASMDEFINES} ${AASMINCLUDES}
ARFLAGS      -c
---------------------------------------------------------------------------

==END==