Skip to content

GitLab

Commit 76864e8b authored by Ben Avison's avatar Ben Avison
Browse files

Clean reimport of the build environment directories. 

This represents the version released in the Batch 4 "bbe" tarfiles.
Tagged as 'Batch4'
parents
Hide whitespace changes
Inline Side-by-side
Showing with 956 additions and 0 deletions
.gitattributes 0 → 100644
View file @ 76864e8b
*,ffb gitlab-language=bbcbasic linguist-language=bbcbasic linguist-detectable=true
*,102 gitlab-language=perl linguist-language=perl linguist-detectable=true
Acorn/Docs/amu 0 → 100644
View file @ 76864e8b
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 0 → 100644
View file @ 76864e8b
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 0 → 100644
View file @ 76864e8b
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