Predefined Variables
====================

This document aims to act as a reference for the different predefined variables
or #defines that the BuildSys makefiles define.

RISCOS_HAL (C & asm)
--------------------

This is defined (C) or set to {TRUE} (asm) when code is being built for
inclusion in the RISC OS HAL.

This implies lots of things about the execution environment (see the HAL design
documents) - code which supports multiple execution environments should use
these defines as appropriate in order to tailor their implementation/behaviour
as appropriate.

Currently, these defines are only enabled when building C or assembler to an
object file which has the .oh file name suffix. For the CLibrary makefile
fragment, this can be achieved by adding ${LIBRARYH} to the list of LIBRARIES
to build.

Currently, these defines are not enabled when using the HAL makefile fragment.

RISCOS_KERNEL (C & asm)
-----------------------

This is defined (C) or set to {TRUE} (asm) when code is being built for
inclusion in the RISC OS kernel.

This implies lots of things about the execution environment (e.g. code may need
to cope with being called before the MMU is enabled, or before SWIs can be
used) - code which supports multiple execution environments should use these
defines as appropriate in order to tailor their implementation/behaviour as
appropriate.

Currently, these defines are only enabled when building C or assembler to an
object file which has the .ok file name suffix. For the CLibrary makefile
fragment, this can be achieved by adding ${LIBRARYK} to the list of LIBRARIES
to build.

Currently, these defines are not enabled when building the kernel itself.

RISCOS_MODULE (C & asm)
-----------------------

This is defined (C) or set to {TRUE} (asm) when code is being built for
inclusion in a RISC OS module.

This implies lots of things about the execution environment (e.g. code may run
in a supervisor mode, malloc() may allocate from the RMA) - code which supports
multiple execution environments should use these defines as appropriate in
order to tailor their implementation/behaviour as appropriate.

Currently, these defines are only enabled when building C or assembler to an
object file which has the .oz file name suffix. For the CLibrary makefile
fragment, this can be achieved by adding ${LIBRARYZM} to the list of LIBRARIES
to build.

Currently, these defines are not enabled when using the AAsmModule makefile
fragment.

RISCOS_ZM (asm), zM (asm)
-------------------------

This is set to {TRUE} for code which is intended to be interoperable with C
code which has been compiled with the -zM flag.

Note that although most modules will be built with -zM, and most -zM code will
be placed into a module, RISCOS_ZM / zM should not be used as synonyms for
RISCOS_MODULE. Where possible, RISCOS_ZM should be used to deal with the code
generation differences that -zM introduces (how C code accesses static data),
and RISCOS_MODULE should be used for other, more general aspects of modules
(e.g. whether code may be running in a privileged mode).

The CLibrary and CModule makefile fragments will enable this as appropriate.
Currently it will not be enabled when using the AAsmModule makefile fragment.

The zM define is deprecated; code should transition to using the new RISCOS_ZM
define instead, because RISCOS_ZM is easier to search for. zM will be removed
in 2024.

APCS (asm)
----------

This is a string variable which will be set to the value of the 'APCS' makefile
variable.

The StdTools makefile fragment adds this to the ASFLAGS variable, so it will be
present by default when building almost all assembler code.

Machine (asm)
-------------

This is a string variable which will be set to the value of the 'Machine'
makefile variable.

The StdTools makefile fragment adds this to the ASFLAGS variable, so it will be
present by default when building almost all assembler code.

UserIF (asm)
------------

This is a string variable which will be set to the value of the 'UserIF'
makefile variable.

The StdTools makefile fragment adds this to the ASFLAGS variable, so it will be
present by default when building almost all assembler code.

standalone (asm)
----------------

This is set to {TRUE} for "standalone" builds of modules. Typically this means
the module should be self-contained.

This is primarily used to control the handling of ResourceFS files that belong
to the module. For non-standalone modules, the assumption is that the
ResourceFS files will already be registered (e.g. ROM builds of modules, where
the Messages module contains a pre-populated copy of ResourceFS for the ROM).
Conversely, a standalone build of the same module would need to contain
embedded copies of the ResourceFS files, and register/unregister them with
ResourceFS at runtime.

Currently, only the AAsmModule makefile fragment implements this define.

MergedMsgs (asm)
----------------

For standalone modules, this will be a string variable containing the filename
of the Messages file which should be embedded in the module (see the MERGEDMSGS
makefile variable).

Currently, only the AAsmModule makefile fragment implements this define.

debugging (asm)
---------------

The AAsmModule makefile sets this to {TRUE} for debug builds of modules
(DBG_MODULE / 'debug' makefile target)

Currently, only the AAsmModule makefile fragment implements this define.

international_help (asm)
------------------------

This is a boolean variable which may be passed into modules, to dictate whether
the module should advertise itself as using internationalised text in its
command table (i.e. the help & syntax strings are message file tokens).

Currently, only the AAsmModule makefile fragment implements this define.
