Clean reimport of the build environment directories.

This represents the version released in the Batch 4 "bbe" tarfiles.
Tagged as 'Batch4'

.gitattributes

+*,ffb gitlab-language=bbcbasic linguist-language=bbcbasic linguist-detectable=true
+*,102 gitlab-language=perl linguist-language=perl linguist-detectable=true

Acorn/Docs/amu

+amu
+===
+
+A Make Utility.  Sources in RiscOS/Tools/Sources/amu
+See Acorn C/C++ Manual for further documentation.
+
+Contents:
+  New options (since version 5.06)
+  Bug fixes
+  GNU Extensions
+  Macro Priority
+  Debugging options
+
+Occasionally, this document refers the reader to the GNU make documentation.
+See http://www.gnu.org/manual/make/ for GNU make documentation.
+
+
+New options (since version 5.06)
+================================
+
+-D options added - displays the reasons for executing commands AND executes
+the commands (cf. -n)
+
+-n displays the commands that would have been executed even if the makefile
+contains .SILENT and even if the command has a @ prefix.
+
+-o no longer outputs the message reminding you to *EXEC the output file.
+
+-E enables macro definition priority compatibility with amu 5.00 (see 
+   section on Macro Priority below)
+
+-e enables environment macro override (see section on Macro Priority below)
+
+
+
+
+Bug fixes
+=========
+
+Macro handling has been fixed.  The first rule in the Makefile (specifically,
+the first rule after any macro definition) can be defined in terms of a
+macro.  In fact, see the section on GNU extensions below because a lot of the
+macro stuff has changed.
+
+Extension-less files are no longer run through the rule inference checks
+(stops obscure errors for targets with no filename extensions)
+
+
+
+GNU Extensions
+==============
+
+Some GNU extensions have been added:
+
+Macros
+------
+
+(Also see Directives and Macro Priority sections)
+
+:= does simply extended macro definition (the value is macro expanded there
+and then - forward references do not work, cf. = which does recursively
+expanded macro definition which does permit forward references).
+
+?= does conditional assignment - only assigns if the macro is not yet
+defined.  Macro must not exist at all previously - empty values stop this
+assignment from occurring.
+
++= adds to a macro's definition.  Whether the value is expanded before being
+appended depends on whether the variable being altered is simply and
+recursively expanded (undefined variables default to recursively expanded).
+
+
+Directives
+----------
+
+Macro assignment override is supported with the 'override' directive - this
+allows you to modify macro definitions made on the command-line, which are
+otherwise immutable (also see Macros and Macro Priority sections)
+
+A new "include" directive is understood.  If a line of the Makefile starts
+with the word "include", then the parameters following it are taken to be
+filenames whose contents should be logically inserted in the Makefile at that
+point (ie. just like the C preprocessor's #include).  This means that common
+makefile fragments can be abstracted out of individual component makefiles,
+thus simplifying and standardising the build structure. You can use
+".include" instead.  Preceding include/.include with a hyphen suppresses any
+file not found errors from arguments to the include directive.
+
+The conditional directives are understood.  There are six keywords: ifeq,
+ifneq, ifdef, ifndef, else and endif.  The last two must appear on lines on
+their own. The first four introduce the conditional section of the makefile. 
+Conditionals are evaluated as the makefile is parsed, not when the rules are
+interpreted, so you can use it to alter what amu "sees" in the makefile. If 
+the condition evaluates to a non-empty value (beware values containing just
+spaces - they are not empty!) then the text after the conditional is used,
+otherwise the text after the matching else directive is used (if it exists).
+Conditionals may be nested to an implementation-defined depth (8)
+
+The ifeq and ifneq directives take two parameters.  They make take several
+styles of parameter, but they are all equal:
+
+ifeq (param1,param2)
+ifeq "param1" "param2"
+ifeq 'param1' 'param2'
+ifeq 'param1' "param2"
+
+
+e.g.
+
+ifeq (${MAKECMDGOALS},clean)
+... this text is inserted if that macro expands to the word "clean"
+else
+... this text is inserted if that macro does not expand to the word "clean"
+endif
+
+You do not need to have an else clause.  ifeq compares the two parameters for
+equality.  ifneq compares the two parameters for inequality.  ifdef and
+ifndef take a single parameters which is the *name* of a macro.  ifdef
+returns true if the specified name names a macro with a non-empty value, and
+false otherwise.  ifndef returns the opposite.  The fact than a macro defined
+with an empty value is treated as "undefined" by this directive can be the
+cause of confusion.  If you want to distinguish between undefined macros and
+those with an empty value, you can instead use:
+
+ifeq ($(origin macroname),undefined)
+... then the macro was undefined
+endif
+
+
+Functions and substitutions
+---------------------------
+
+Basic substitutions are supported:  ${VAR:search=replace}.  search and
+replace are simple strings, and the construct represents the value of the VAR
+macro with all occurrences of 'search' replaced by 'replace'.  The more
+advanced % substitutions are also supported.
+
+Some "functions" are supported: e.g. "$(sort one two three)" will expand to
+"one three two".  Functions supported are: words, word, wordlist, firstword,
+strip, sort, subst, patsubst, findstring, filter, filter-out, addsuffix,
+addprefix, join, origin, dir, notdir, if, error, warning, wildcard(*).
+
+(*) The implementation of wildcard does not support wildcards :-)  It can
+be used to test for existence of a specific file or list of files though.
+
+
+Macro priority
+==============
+
+Macro definitions do NOT always take effect any more.  The macro priority
+system mirrors that used by GNU make.  Each macro has an origin (which is
+returned by the origin function) as does each attempted definition.  If the
+existing definition is higher priority, the definition does NOT succeed. 
+This can lead to odd-looking, but correct, behaviour.  By default, the rank
+(from highest to lowest priority) is:
+
+  override, command line, environment override, file, environment,
+  automatic, default, undefined.
+
+An important side-effect of this is macros defined on the command-line now
+OUTRANK those defined in the makefile.  This can cause unexpected behavioural
+changes to the unwary.  If the makefile really wants to beat the CLI
+definition, it must use the override directive.  Note that += is affected by
+this protection too - you cannot add to a CLI macro unless you use the
+override directive.
+
+To aid compatibility with makefiles written for earlier versions of amu, a
+new command-line option -E is supported.  This changes the ranking system to
+more closely mirror that employed by amu 5.06.  However, using this option
+does not prevent the environment being searched for undefined macros. This
+alternative rank is:
+
+  override, file, command line, automatic, default, environment override,
+  environment, undefined.
+
+
+Aside: There is a peculiar behaviour of GNU make which is mirrored by amu
+with regard to environment override macros.  If -e is in effect (environment
+overrides makefile), then the origin of a macro that has come from the
+environment will be just "environment" until another definition is attempted
+in the makefile.  At *that* point, the macro's origin is boosted up to
+"environment override", but not before.  This is not a bug.
+
+
+Debugging Options
+=================
+
+The debugging CLI option (-x) now does something useful. This can be very
+useful for tracking down problems with makefiles.  It is actually a bitfield,
+-x1 sets level 1, -x2 sets level 2, -x4 sets level 3, -x6 sets levels 2 and
+3.  The level assignments are:
+
+1: CLI processing, dependency tree creation & command list assignments
+2: Macro processing, pattern substitutions etc.
+3: 
+4: command execution
+5: command expansion of patterns ($* $< $? etc.)
+6: makefile data structure internal debugging
+7: low-level internal debugging
+
+
+--sbrodie, 18/06/2001

Acorn/Docs/cc

+cc
+==
+
+Norcroft C compiler.  Sources in Tools/Sources/cc.
+See Acorn C/C++ Manual for further documentation.
+
+Contents:
+  Changes since cc 5.06
+    New warnings and suppressing them
+  Changes in cc 5.11
+  Changes in cc 5.12
+  Changes in cc 5.13 - 5.18
+  List of all pragmas
+  List of debug flags
+  List of all feature flags
+  List of all warning suppression flags
+  List of all error suppression flags
+
+
+Changes since version 5.06 are just the addition
+of new warnings and warning suppression flags:
+
+-Ws   suppression of "module has init to static data"
+-Wr   suppression _swix format warnings
+-Wc   suppression of "use of reserved C++ keyword" warnings
+-Wb   suppression of unknown pragma warnings
+-Wg   suppression of non-const format parameter warnings
+        (..printf, ..scanf, _swix)
+
+The compiler now knows (with #pragma -v4 in swis.h) about _swi
+and _swix and will check that the correct number of parameters
+have been supplied and that they are of suitable types.
+
+The compiler now identifies *which* function parameter it is 
+grumbling about when it has a complaint about one of them.
+
+
+Changes in version 5.11 of the compiler:
+
+-Ws is assumed and ignored, but not faulted.
+
+-ccversion <version * 100> option is supported.  eg. --ccversion 512
+will abort compilation if you aren't using version 5.12 or later.
+
+A new macro __CC_NORCROFT_VERSION with a numeric value equal to the
+version number * 100 is predefined.
+
+
+Changes in version 5.12 of the compiler:
+
+Signed shift right following a bitwise AND with a constant used to do
+a logical shift, not arithmetic.  This is now fixed.  (C standard says
+that the LSR/ASR choice is implementation defined - and our manual
+defines it as ASR)
+
+
+Changes in versions 5.13 through 5.19 of the compiler:
+
+SFMFD instructions generated correctly, and other floating point instr fixes
+too; LDR with writeback to sp as the base register done properly to avoid
+interrupt holes; use of single register LDM and STM instructions minimised;
+more warning suppression stuff added:
+
+"Unused earlier static declaration of '<symbol>'" is only generated in
+fussy mode.
+
+Unused symbols starting with the 6 character prefix __link are no longer
+warned about (because the linker set stuff nearly always should not be
+referenced - that's what the linker does)
+
+The following symbols may be predefined depending on the APCS variant in
+use: __APCS_32, __APCS_FPREGARGS, __APCS_NOFP, __APCS_REENT, __APCS_NOSWST.
+
+
+
+Full set of active pragmas:
+
+The following comes from cfe/pp.c and maps the long pragma names to
+the short versions.  The digit is the value to use with the short
+versions to effect the same thing.  (ie. #pragma -v4 is the same
+as #pragma check_swix_formats).  Do not use -v3 as it is for
+internal use only (by the compiler's own source code).
+
+
+    { "warn_implicit_fn_decls",     'a', 1},
+    { "check_memory_accesses",      'c', 1},
+    { "warn_deprecated",            'd', 1},
+    { "continue_after_hash_error",  'e', 1},
+    { "include_only_once",          'i', 1},
+    { "optimise_crossjump",         'j', 1},
+    { "optimise_multiple_loads",    'm', 1},
+    { "profile",                    'p', 1},
+    { "profile_statements",         'p', 2},
+    { "check_stack",                's', 0},
+    { "force_top_level",            't', 1},
+    { "check_printf_formats",       'v', 1},
+    { "check_scanf_formats",        'v', 2},
+    { "__compiler_msg_format_check",'v', 3},
+    { "check_swix_formats",         'v', 4},
+    { "side_effects",               'y', 0},
+    { "optimise_cse",               'z', 1}
+
+
+
+Debug flags are used with -zq<option>.  Some options are
+counted in that repeating them increases the debug level.
+Such options are marked with <n> in the list below.  It
+is expected that very few people will need to know these
+(only people modifying the compiler itself, probably).
+Options can be combined in a single flag, eg. -zqvvcka
+
+Option       Meaning
+
+-zqa         AETREE
+-zqb         binder
+-zqc  <n>    common sub-expression eliminator
+-zqd         debug data
+-zqf         filename processing
+-zqg         code generator
+-zqh         register spilling
+-zqi         file activity
+-zqk  <n>    local code generator
+-zql         lexer
+-zqm         map storage
+-zqo         object code constructor
+-zqp         pre-processor
+-zqq         DEBUG_Q ??
+-zqr         register allocation
+-zqs         syntax analysis
+-zqt         type checker
+-zqu         storage
+-zqw         storage (2)
+-zqx         DEBUG_X ??
+-zqy         loop analysis
+-zqz  <n>    disable SIGINT signal handler (allows backtraces)
+
+
+List of all feature flags:  (* = documented in Acorn C/C++ manual)
+
+Option       Meaning
+
+-fa          Check for certain data flow anomalies. (*)
+-fb	     Verbose
+-fc	     Limited pcc option (*)
+-fd          Unused.
+-fe          Check 6-char case-insensitive external symbols unique (*)
+-ff          Don't embed function names (cf. -fn) (*)
+-fg          Unused
+-fh          Require pre-declaration of external objects (*)
+-fi          Retain #include "..." statements in listing output (*)
+-fj          Return #include <...> statements in listing output (*)
+-fk          Use K&R include search rules (*)
+-fl          Don't use link register
+-fm          Emit warning for unused preprocessor symbols (*)
+-fn          Embed function names (cf. -ff) (*)
+-fo          Warn about old-style functions
+-fp          Report on explicit casts of integers to pointer (*)
+-fq          Allow counted strings
+-fr          Let longjmp() corrupt register variables
+-fs          Annotate
+-ft          Unused
+-fu          Unexpanded listing (*)
+-fv          Report on all unused declarations including standard headers (*)
+-fw          Allow string literals to be writable (*)
+-fx          Unused
+-fy          Unused
+-fz          Inline calls kill link register.
+
+
+List of all warning suppression flags: (* = documented in Acorn C/C++ manual)
+
+Option       Meaning
+
+-Wa          "Use of = in a conditional context" (*)
+-Wb          Unknown pragma
+-Wc          Use of C++ keyword
+-Wd          Deprecated declaration foo() - give arg types (*)
+-We          Unused
+-Wf          Inventing "extern int foo()" (*)
+-Wg          'format' arg to printf/scanf/_swixs etc. is variable
+-Wh - -Wm    Unused
+-Wn          Implicit narrowing cast (*)
+-Wo          Unused
+-Wp          non-ANSI #include <...> (*)
+-Wq          Unused
+-Wr          (_swix) Format requires x parameters, but y given
+-Ws          Module has init. to static data
+-Wt          Unused
+-Wu          Unused
+-Wv          Implicit return in non-void context (*)
+-Ww - -Wz    Unused
+
+
+List of all error suppression flags:
+
+(* = documented in Acorn C/C++ manual)
+(! = documented in manual, but not actually implemented in the compiler)
+
+Option       Meaning
+
+-Ea          Unused
+-Eb          Unused
+-Ec          Implicit cast (*)
+-Ed          Unused
+-Ee          Unused
+-Ef          Unclean casts (eg. short to pointer) (!)
+-Eg          Unused
+-Eh          Unused
+-Ei          Suppress syntax checking for #if (!)
+-Ej          Unused
+-Ek          Unused
+-El          Unused
+-Em          Same as -Epz -fq
+-En          Unused
+-Eo          Unused
+-Ep          Junk at end of preprocessor line (*)
+-Eq - Ey     Unused
+-Ez          Zero-length array (*)
+
+
+--sbrodie, 26/04/2000

Acorn/Docs/cmhg

+CMHG
+====
+
+C Module Header Generator.  Sources in Tools/Sources/cmhg.
+See Acorn C/C++ Manual for documentation up to version 5.02.
+
+Changes from CMHG 5.02 to 5.10
+==============================
+
+1) CMHG now gets the date for the module header from the datestamp of
+   the CMHG input file, rather than using the current date. This will
+   stop the silly situation of a simple rebuild producing something
+   looking like a later version.
+
+2) The date can be overridden using the new keyword "date-string:".
+   For example:
+   
+       date-string:  26 Jun 1974
+
+3) CMHG's help output (*cmhg -h) now details all command-line options.
+
+4) CMHG can now preprocess the cmhg file using the C preprocessor if you
+   use the "-p" command line option. This allows code like the following:
+   
+       swi-chunk-base-number:   0x82880
+       
+       service-call-handler:    Window_services 0x46, 0x44ec1, 0x44ec2
+   
+   to be replaced by the more readable and maintainable:
+   
+       #include "window.h"
+       #include "services.h"
+       
+       swi-chunk-base-number:   Window_SWIChunkBase
+       
+       service-call-handler:    Window_services Service_ModeChange,
+                                                Service_ToolboxTaskBorn,
+                                                Service_ToolboxTaskDied
+
+       #ifdef DEBUG
+       command-keyword-table:   Window_commands Window_Memory(),
+                                                Window_Tasks()
+       #endif
+
+   In conjunction with this, CMHG now accepts the command-line options 
+   -I and -D. These function in the same way as with the C compiler. Note
+   that the default include path (in the absence of -I) is C:.
+   
+   For example:
+   
+        cmhg -p -DDEBUG -IC:,TCPIPLibs: -o o.InetHdr InetHdr
+   
+5) The header file that CMHG outputs is now much more readable. Changes
+   include:
+   
+   a) The file is now bracketed by "#ifndef __cmhg_<filename>" rather
+      than "#ifndef __cmhg_defs_h".
+      
+   b) CMHG_VERSION is #defined to the version of CMHG that generated
+      the file, allowing the source to ensure its header was built
+      with a new enough version of CMHG.
+   
+   c) Module_Title, Module_Help, Module_VersionString,
+      Module_VersionNumber, Module_Date and Module_MessagesFile are
+      #defined according to what was entered in the module header.
+   
+   d) Function prototypes are defined for each function/veneer
+      mentioned in the CMHG file. Extensive comments (more accurate
+      than those in the Acorn C/C++) are generated.
+   
+   e) Useful constants are defined to simplify the rather nasty
+      command handler interface.
+   
+   f) The #define of SWI names is bracketed by a #ifndef to prevent
+      problems if you include another header file defining your
+      SWIs.      
+   
+6) CMHG now supports throwback if the command-line option "-t" or
+   "-throwback" is specified.
+
+7) Text processing has been slightly altered. \n now inserts ASCII
+   code 13, rather than 10, as this is what OS_PrettyPrint expects.
+   CMHG now accepts the C \x specifier, eg \x07 to insert ASCII
+   code 7.
+
+8) Command descriptions have a new flag "add-syntax:" that signifies
+   that the invalid-syntax string should be appended to the help-text
+   string.
+   
+   This means that the standard idiom
+   
+       MyCommand(help-text: "*MyCommand does something.\r"
+                            "Syntax: *MyCommand",
+                 invalid-syntax: "Syntax: *MyCommand")
+   
+   can now be written as
+   
+       MyCommand(add-syntax:,
+                 help-text: "*MyCommand does something.\n",
+                 invalid-syntax: "Syntax: *MyCommand")
+   
+   Note that modules designed for RISC OS 3.6 or later should use
+   the internationalised help flag ("international:"). This option
+   is then superfluous.
+
+9) CMHG 5.02 (as supplied with Acorn C/C++) had a few undocumented
+   features. These are now documented here:
+   
+   a) The keyword "international-help-file:" to specify the name of
+      the file to look up help text in (RISC OS 3.6 or later - see
+      PRM 5a-34).
+   b) The command description keyword "international:" to set bit 28
+      of a command entry, indicating that this command has
+      internatialised help.
+   c) The command line allows output definitions and object files
+      to be specified using -d and -o respectively instead of
+      relying on the order of the parameters.
+   d) The "-b" flag (b for bodge!). Only used by ShareFS - now
+      removed and superceded by library-enter-code (see below).
+   e) The keyword "module-is-not-re-entrant:" indicates to the
+      C stubs that it need not copy your data into a separate
+      RMA workspace area. This could save memory, but will have
+      many potentially nasty side-effects. If you're considering
+      doing something like this to save memory, you should probably
+      look at using TinyStubs.
+   f) A documentation clarification: "status:" and "configure:"
+      (Acorn C/C++ p286) are exactly synonymous; both set bit 30 of
+      the flags word.
+
+10) The "swi-decoding-code" keyword can now accept a pair of keywords
+    to specify a text->number and number->text conversion pair. This
+    allows nicer prototypes:
+    
+        swi-decoding-code: text_to_number/number_to_text
+    
+        int text_to_number(const char *string, void *pw);
+        int number_to_text(int swi_no, char *buffer, int offset,
+                           int end, void *pw);
+
+11) "irq-handlers" has been deprecated, as IrqV is long obsolete.
+    Instead, the keyword has been replaced by "vector-handlers",
+    and the comment text placed in the definitions file emphasises
+    these veneers use as a general vector hook. "irq-handlers" is
+    still accepted, but a warning is emitted.
+
+12) A new type of veneer has been added, the "generic veneer". These
+    are designed as a replacement for the common use of irq-handlers
+    as general purpose hooks onto OS_AddCallBack etc. They are
+    specified in the same way as irq-handlers, but using the keyword
+    "generic-veneers:". They work in the same way, except they
+    either return preserving processor flags, or set V to
+    return an error:
+    
+       _kernel_oserror *generic_handler(_kernel_swi_regs *r, void *pw);
+
+    The veneer switches to SVC mode, does not alter interrupt status,
+    and preserves R0-R11. R12 is corrupted.
+    
+    In future, generic veneers will be extended to allow them to
+    totally replace vector handlers and event handlers. At present
+    the generic veneer is totally separate from the vector/event
+    veneer in the module header, so using both veneers is slightly
+    wasteful of memory.
+
+13) Bug fix: the swi decoding veneer corrupted R4 and R5.
+
+14) The SWI handler veneer made slightly (one instruction!) faster
+    in the case of a successful SWI.
+
+15) Your SWI handler can now return the magic error code error_BAD_SWI,
+    which will cause the veneer to look up and return the standard
+    internationalised 'SWI value out of range for module XXX' error.
+
+16) CMHG will leave out extraneous header fields, saving a few
+    words of memory.
+
+17) Fast service and event filtering code changed to use TEQ
+    rather than CMP where possible.
+
+18) Fast service filtering code given a few more brain cells.
+    Where CMHG 5.02 produced for the ShareFS module the code: 
+    
+        CMP     R1,#&27            
+        CMPNE   R1,#&40            
+        CMPNE   R1,#&4B            
+        CMPNE   R1,#&4C            
+        CMPNE   R1,#&4F            
+        CMPNE   R1,#&74            
+        CMPNE   R1,#&95            
+        CMPNE   R1,#&96            
+        STMFD   R13!,{R14}
+        MOV     R14,#&C0           
+        ORR     R14,R14,#&0100     
+        ORR     R14,R14,#&00080000
+        CMPNE   R14,R1
+        MOV     R14,#&C1           
+        ORR     R14,R14,#&0100     
+        ORR     R14,R14,#&00080000
+        CMPNE   R14,R1
+        MOV     R14,#&C2           
+        ORR     R14,R14,#&0100     
+        ORR     R14,R14,#&00080000
+        CMPNE   R14,R1
+        MOV     R14,#&C3           
+        ORR     R14,R14,#&0100     
+        ORR     R14,R14,#&00080000
+        CMPNE   R14,R1
+        MOV     R14,#&C5           
+        ORR     R14,R14,#&0100     
+        ORR     R14,R14,#&00080000
+        CMPNE   R14,R1
+        LDMNEFD R13!,{PC}^
+        <rest of veneer>
+    
+    CMHG 5.10 produces:
+    
+        TEQ     R1,#&27
+        TEQNE   R1,#&40
+        TEQNE   R1,#&4B
+        TEQNE   R1,#&4C
+        TEQNE   R1,#&4F
+        TEQNE   R1,#&74
+        TEQNE   R1,#&95
+        TEQNE   R1,#&96
+        STMDB   R13!,{R14}
+        MOVNE   R14,#&01C0
+        ADDNE   R14,R14,#&00080000
+        TEQNE   R1,R14
+        ADDNE   R14,R14,#1
+        TEQNE   R1,R14
+        ADDNE   R14,R14,#1
+        TEQNE   R1,R14
+        ADDNE   R14,R14,#1
+        TEQNE   R1,R14
+        ADDNE   R14,R14,#2
+        TEQNE   R1,R14
+        LDMNEIA R13!,{PC}^
+        <rest of veneer>
+    
+    (CMHG now sorts the list, so the order in the input file is no
+    longer significant).
+
+19) A new keyword "library-enter-code:" has been introduced. This
+    allows you to supply your own assembler veneer routine to be
+    called instead of _clib_entermodule when the module is started
+    as an application. It is analogous to
+    "library-initialisation-code:".
+
+20) CMHG now attempts filename translation in the same way as the
+    C compiler. So ^.cmhg.fred, ^.fred.cmhg, ^.fred/cmhg,
+    ../fred.cmhg etc. will all be accepted as equivalent file
+    specifiers.
+
+21) The !CMHG frontend has been modified to allow setting all the
+    new options.
+
+22) Bug fix: the initialisation and irq-handler veneers did not
+    correctly set fp to 0 before calling the C routines. This would
+    break stack backtraces.
+
+23) Now possible to return the special error 0 (Bad configure
+    option) from a *Configure handler, as the veneer will map the
+    return value -1 to 0.
+    
+24) CMHG now generates a version 3.11 AOF file, rather than a
+    verion 1.50 file with type 1 relocations. The main effect of
+    this is that DecAOF can now successfully disassemble a
+    CMHG-generated object file.
+
+25) New command line option -depend. It is passed on to the C
+    preprocessor so it can generate dependency information for AMU.
+
+Changes from 5.10 to 5.11
+=========================
+
+1) Some more veneers refined.
+
+2) Change 13) above reversed. Documentation is wrong: R4-R6 can be
+   corrupted.
+
+3) Bug fix: service call veneer accessed banked R14 after TEQP.
+
+4) Bug fix: generic-veneers corrupted stack if error returned.
+
+5) Bug fix: generated header would #define Module_VersionNumber
+   to values like 019, which C interprets as octal.
+
+6) If outputting header to a filename with no extension, CMHG
+   will now #define __cmhg_<source root>_h. This makes header files
+   generating using !CMHG make more sense (otherwise it would
+   #define __cmhg_x35e19ab2).
+
+7) Bug fix: typo in definition of error_BAD_SWI.
+
+8) Bug fix: the swi veneer BadSWI error code was incorrectly assembled
+   in small headers.
+
+9) Initialisation veneer streamlined, and hard-coded use of -536
+   etc (instead of _Lib$Reloc$Offset) removed.
+
+Changes from 5.11 to 5.12
+=========================
+
+1) Allow -b flag with a warning, rather than generating an error.
+
+Changes from 5.12 to 5.13
+=========================
+
+Bug fix: Generated C header contained incorrect declarations for
+event handlers.
+
+Changes from 5.13 to 5.14
+=========================
+
+Versions 5.12 and 5.13 generated broken generic veneer and
+vector handler code.
+
+Changes from 5.14 to 5.15
+=========================
+
+The "-b" flag generated the wrong symbol (the leading underscore
+was missing).
+The generic veneer (and vector handler) code included some BLs
+instead of Bs. This was harmless but odd. Now fixed.
+
+Changes from 5.15 to 5.16
+=========================
+
+Lots of tidy-ups in the generated header file, including
+tightened up constness in function declarations.
+
+Changes from 5.16 to 5.30
+=========================
+
+1) CMHG will generate fast service call dispatch tables for Ursula kernels to
+   make use of (see Ursula kernel spec for details).
+
+2) Module titles may be quoted - either in single or double quotes. 
+
+3) Cross-compilation capability added.
+
+4) -U option to undefine symbols to match -D. 
+
+5) Numbers in service call lists etc. may be bracketed.  This means that CMHG
+   files can #include "Global/Services.h" to get service call macros, SWI
+   chunk base; "Global/RISCOS.h" to get event and vector numbers etc to
+   make it more readable.  
+
+6) Pre-processor command-line buffer increased to 1K to avoid overflows
+   (was only 128 bytes)
+
+7) New -26bit and -32bit options to control the APCS variant CMHG will
+   assume that user code is using.
+
+8) _clib_finalisemodule is called during module initialisation if an
+   error is returned by the user's init routine.  This avoid any
+   potential memory leaks, and ensures that the atexit functions are
+   called before the module dies.
+
+Changes from 5.30 to 5.36
+=========================
+
+Minor tweaks to the veneers, including a bug fix to avoid hitting a
+bug in StrongARM in the 32-bit veneers.
+

Acorn/Docs/resgen

+The ResGen tool
+---------------
+
+ResGen is a tool for creating resource file data in a form suitable for
+use by ResourceFS from a set of input files and corresponding resource
+file names.
+
+The format of the ResGen command is:
+
+ResGen <Area name> <Object file> { <Binary file> <Resource file> }
+
+<Area name> is the name of an AOF AREA in which the resource file data is
+to be placed. A function of this name is exported as an external symbol which
+can be used in C or assembler code to access the resource data.
+
+<Object file> is the name of the object output file to be produced.
+
+<Binary file> is the name of a file to be included in the resource file
+data.
+
+<Resource file> is the name within the ResourceFS which is used by the
+application to refer to a file within the resource file data.
+
+A <viafile> is a file containing a list of <Binary file> <Resource file> pairs
+one per line. This may be used for convenience or to circument the 256
+character command line length limit.
+
+Example usage in C
+------------------
+
+...
+
+extern int resourcefsfiles(void);
+
+#define ADFSPATH  "ADFSFiler$Path"
+#define FILERPATH "Resources:$.Resources.ADFSFiler."
+
+OS_ErrorBlock *init(char *envstr, int instantiation, WorkSpace **r12)
+{
+    ...
+    s = ADFSPATH;
+/* Set up ADFSFiler$Path variable which may be changed by user to point to
+ * a different messages file.
+ */
+    if (!xos_readvarval(s, 0, -1, 0, 0))
+        xos_setvarval(s, FILERPATH, sizeof(FILERPATH), 0, 0);
+/* Register the block of data generated by the ResGen tool with the ResourceFS.
+ * This will create a file "Resources:Resources.ADFSFiler.Messages" which
+ * contains the message data.
+ *
+ * 'resourcefsfiles' is a function which returns the address of the resource
+ * data.
+ */
+    xresourcefs_registerfiles(resourcefsfiles());
+    ...
+}
+
+...
+
+
+Extract from MakeFile to build resources
+----------------------------------------
+
+...
+
+filer: o.adfsfiler o.messages o.lib
+    link -m -o ADFSFiler o.filer o.messages o.lib
+
+o.messages: m.messages
+    resgen resourcefsfiles o.messages m.messages Resources.ADFSFiler.Messages
+
+...

Acorn/Docs/rpcgen

+RPCGEN
+======
+
+Remote Procedure Call generator.  This code takes RPC protocol definition
+files (.x files) and generated data translation routines (XDR routines),
+client and server stubs.
+
+This build is capable of generating ANSI C/C++ compatible headers and code.
+Generation of ANSI code is ON by default.  Use -k to force old-style K&R
+code to be generated.
+
+Version 0.03 and later accept a -debuglib command-line parameter to make
+client stub code contain calls to DebugLib to notify it as each procedure
+call is made.
+
+--sbrodie, 15/03/2000
+

Acorn/Docs/squeeze

+squeeze
+=======
+
+squeeze takes an ARM executable image file and compresses it, usually
+to about half the size, adding decompression code so that the image
+will automatically expand itself when it is run.
+
+[sbrodie note:
+  the code is not (yet) suitable for StrongARM, so the UnsqueezeAIF
+  module patches the decompress code generated by this tool so that
+  it does work.  You must not change the unsqueeze code without
+  similarly informing xpand and RiscOS/Sources/HWSupport/UnsqueezeAIF
+  of the change too.
+]
+
+Briefly, the image is treated as a sequence of 32-bit words, and each
+word is encoded in one of four ways, specified by a 4-bit nibble:
+
+  zero -> nibble 0
+  the 7*256 most common word values are encoded with one byte extra as
+  an index into a table
+  the 7*256 most common upper-3-byte values are encoded with one byte
+  extra as index into another table, with the low byte separate
+  anything else is given in full as 4 bytes.
+
+The tables of common values are sorted into ascending order
+and encoded in a devious way.
+
+
+As of version 5.02, the code appended to the AIF imagine checks
+that there is sufficient memory to unsqueeze the data without
+data aborting (exceeding the Wimp slot) or overwriting any caller
+application (eg. if squeezed app is a subtask launched by amu)
+
+Sources in Tools/Sources/squeeze (originally on Aquarius)
+
+--sbrodie, 21 Jun 1999

Acorn/Docs/xpand

+xpand
+=====
+
+xpand reverses the effect of squeeze, possibly adding up to 4 extra zero
+bytes to the end of the image.
+
+
+Sources in Tools/Sources/squeeze (originally on Aquarius)
+
+--sbrodie, 10 Feb 1999

Acorn/debugaif,feb

+| Copyright 2008 Castle Technology Ltd
+|
+| Licensed under the Apache License, Version 2.0 (the "License");
+| you may not use this file except in compliance with the License.
+| You may obtain a copy of the License at
+|
+|     http://www.apache.org/licenses/LICENSE-2.0
+|
+| Unless required by applicable law or agreed to in writing, software
+| distributed under the License is distributed on an "AS IS" BASIS,
+| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+| See the License for the specific language governing permissions and
+| limitations under the License.
+|
+|
+| DDT Desktop debugger version 1.72
+| (C) Copyright Acorn Computers Ltd. 1995
+|
+| --- Ensure the correct versions of various modules needed by DDT
+| --- Any ColourTrans
+*RMEnsure ColourTrans 0 System:Modules.Colours
+| --- Any FPEmulator will do
+| --- FPE must be Loaded not run (run code prints banner)
+*RMEnsure FPEmulator 0 RMLoad System:Modules.FPEmulator
+| --- Load the debugger module
+*/<Build$Dir>.Modules.DDT
+*RMEnsure DDT 1.72
+| --- Re-execute the DebugAIF command which should now be handled by the
+| --- debugger module
+*DebugAIF %*0