# Compiler options and equations

A rich set of XDS compiler options allows you to control the source language, the generated code, and the internal limits and settings. We distinguish between boolean options (or just options) and equations. An option can be set ON (TRUE) or OFF (FALSE), while an equation value is a string.

- Options
- Options reference
- Equations
- Equations reference
- Error message format specification
- The system module COMPILER

## Options

Options control the process of compilation, including language extensions, run-time checks and code generation. An option can be set ON (TRUE) or OFF (FALSE).

A compiler setup directive (See Options) is used to set the option value or to declare a new option.

Options may be set in a configuration file, on the command line, in a project file). or in the source text (See Source code directives). At any point of operation, the last value of an option is in effect.

Alphabetical list of all options along with their descriptions may be found in the section Options reference.

Table 1. Run-time checks

Option | Meaning
ASSERT | enable ASSERT generation
CHECKDINDEX | check of dynamic array bounds
CHECKDIV | check for a positive divisor
| (DIV and MOD)
CHECKINDEX | check of static array bounds
CHECKNIL | NIL pointer dereference check
CHECKPROC | check of a formal procedure call
CHECKRANGE | range checks
| (range types and enumerations)
CHECKSET | range check of set operations
CHECKTYPE | dynamic type guards (Oberon-2 only)

Table 2. Source language control options

Option | Meaning
M2ADDTYPES | add SHORT and LONG types
M2BASE16 | use 16-bits basic types in Modula-2
M2CMPSYM | compare symbol files in Modula-2
M2EXTENSIONS | enable Modula-2 extensions
O2ADDKWD | enable additonal keywords in Oberon-2
O2EXTENSIONS | enable Oberon-2 extensions
O2ISOPRAGMA | enable ISO Modula-2 pragmas in Oberon
O2NUMEXT | enable Oberon-2 scientific extensions
STORAGE | enable default memory management in Modula-2
??? | enable Topspeed Modula-2-compatible extensions

Table 3. Code generator control options

Option | Meaning
__GEN_C__ | ANSI C code generation
__GEN_X86__ | code generation for 386/486/Pentium/PentiumPro
COMMENT | copy comments into a generated C code
CONVHDRNAME | use file name in the `#include` directive
CSTDLIB | definition of the C standard library
DIFADR16 | SYSTEM.DIFADR returns 16-bits value
GENCDIV | generate C division operators
GENCPP | generate C++
GENCONSTENUM | generate enumeration as constants
GENCTYPES | generate C types
GENDATE | insert a date in a C file
GENDEBUG | generate code in the debug mode
GENFULLFNAME | generate full name in `#lineno` directive
GENHISTORY | enable postmorten history
GENKRC | generate K&R C
GENPROCLASS | generate a specification of a procedure class
GENPROFILE | generate additional code for profiling
GENSIZE | evaluate sizes of types
GENTYPEDEF | generate typedef's for types
INDEX16 | index is of 16-bits
LINENO | generate line numbers in C code files
NOEXTERN | do not generate prototypes for external C functions
NOHEADER | disable generation of a header file
NOOPTIMIZE | disable a set of opimizations
PROCINLINE | enable in-line procedure expansion
TARGET16 | C `int` type is of 16-bits
VERSIONKEY | append version key to the module initialization

Table 4. Miscellaneous options

Option | Meaning
BSCLOSURE | browse control option
BSREDEFINE | browse control option
CHANGESYM | permission to change a symbol file
FATFS | limit file names to 8.3
GCAUTO | enables implicit call of the garbage collector
LONGNAME | use long names in batch files
M2 | force the Modula-2 compiler
MAIN | mark an Oberon-2 main module
MAKEDEF | generate definition
MAKEFILE | generate makefile
O2 | forces the Oberon-2 compiler
OVERWRITE | create a file, always overwrites the old one
VERBOSE | produce verbose messages
WERR | treat warnings as errors
WOFF | suppress warning messages
XCOMMENTS | preserve exported comments

## Options reference

This section lists all options in alphabetical order. Those options that may be arbitrarily placed in the source code are marked as inline options (See also Source code directives). There are also options which can be placed in a source file, but only in a module header (i.e. before any of the keywords `"DEFINITION"`, `"IMPLEMENTATION"`, and `"MODULE"`) These options are marked as header. If an option is not marked either as header or inline, then the result of setting it in the source text is undefined.

Operation modes in which an option has effect are listed in square brackets ([]) after the option name; the character '*' stands for all operation modes. For example, [browse] means that the option is used by the compiler in the BROWSE operation mode only.

Note: in the MAKE and PROJECT modes the compiler switches to the COMPILE mode to compile each module.

Run-time check options are ON by default. If not explicitly specified, other options are OFF (FALSE) by default.

- __GEN_X86__ - code generation for 386/486/Pentium/PentiumPro
- __GEN_C__ - ANSI C code generation
- ASSERT - enable ASSERT generation
- BSCLOSURE - browse control option
- BSREDEFINE - browse control option
- CHANGESYM - permission to change a symbol file
- CHECKDINDEX - check of dynamic array bounds
- CHECKDIV - check for a positive divisor (DIV and MOD)
- CHECKINDEX - check of static array bounds
- CHECKNIL - NIL pointer dereference check
- CHECKPROC - check of a formal procedure call
- CHECKRANGE - range checks (range types and enumerations)
- CHECKSET - range check of set operations
- CHECKTYPE - dynamic type guards (Oberon-2 only)
- COMMENT - copy comments into a generated C code
- CONVHDRNAME - use file name in the '#include' directive
- CSTDLIB - definition of the C standard library
- DIFADR16 - SYSTEM.DIFADR returns 16-bits value
- FATFS - limit file names to 8.3
- GCAUTO - enables implicit call of the garbage collector
- GENCDIV - generate C division operators
- GENCPP - generate C++
- GENCONSTENUM - generate enumeration as constants
- GENCTYPES - generate C types
- GENDATE - insert a date in a C file
- GENDEBUG - generate code in the debug mode
- GENFULLFNAME - generate full name in '#lineno' directive
- GENHISTORY - enable postmortem history
- GENKRC - generate K&R C
- GENPROCLASS - generate a specification of a procedure class
- GENPROFILE - generate additional code for profiling
- GENSIZE - evaluate sizes of types
- GENTYPEDEF - generate typedef's for types
- INDEX16 - index is of 16 bits
- LINENO - generate line numbers
- LONGNAME - use long names in batch files
- M2 - force the Modula-2 compiler
- M2ADDTYPES - add SHORT and LONG types
- M2BASE16 - use 16-bits basic types in Modula-2
- M2CMPSYM - compare symbol files in Modula-2
- M2EXTENSIONS - enable Modula-2 extensions
- MAIN - mark an Oberon-2 main module
- MAKEDEF - generate definition
- MAKEFILE - generate makefile
- NOEXTERN - do not generate prototypes for external C functions
- NOHEADER - disable generation of a header file
- NOOPTIMIZE - disable a set of opimizations
- O2 - force the Oberon-2 compiler
- O2ADDKWD - enable additonal keywords in Oberon-2
- O2EXTENSIONS - enable Oberon-2 extensions
- O2ISOPRAGMA - enable ISO Modula-2 pragmas in Oberon
- O2NUMEXT - enable Oberon-2 scientific extensions
- OVERWRITE - create a file, always overwrites the old one
- PROCINLINE - enable in-line procedure expansion
- STORAGE - enable the default memory management in Modula-2
- TARGET16 - C 'int' type is of 16 bits
- VERBOSE - produce verbose messages
- VERSIONKEY - append version key to the module initialization
- WERR - treat warningns as errors
- WOFF - suppress warning messages
- XCOMMENTS - preserve exported comments

### __GEN_X86__ - code generation for 386/486/Pentium/PentiumPro

Modes: COMPILE

The compiler sets this option ON, if the code generation for 386/486/Pentium/PentiumPro is in operation.

The option can be used for compiling different text fragments for different targets. See also Conditional compilation.

### __GEN_C__ - ANSI C code generation

Modes: COMPILE

The compiler sets this option ON, if the C code generation is in operation.

The option can be used for compiling different text fragments for different targets. See also Conditional compilation.

### ASSERT - enable ASSERT generation

Modes: COMPILE (inline)

If the option is OFF, the compiler ignores all calls of the standard procedure `ASSERT`.

Warning: Ensure that all `ASSERT` calls in your program do not have side effects (i.e. do not contain calls of other function procedures) before setting this option OFF.

The option is ON by default.

### BSCLOSURE - browse control option

Modes: BROWSE

Include all visible methods.

If the option is set ON, the browser includes all defined and inherited type-bound procedure declarations with all record declarations when creating a pseudo-definition module. See also Creating a definition.

### BSREDEFINE - browse control option

Modes: BROWSE

Include all redefined methods.

If the option is set ON, the browser includes original definitions of any overwritten type-bound procedures with record declarations. See also Creating a definition.

### CHANGESYM - permission to change a symbol file

Modes: COMPILE (header)

Permission to change a module interface (a symbol file).

The Oberon-2 compiler creates a temporary symbol file every time an Oberon-2 module is compiled, compares this symbol file with the existing one and overwrites it with the new one if necessary. When the option is OFF (by default), the compiler reports an error if interface of a module (and, hence, its symbol file) has been changed and does not replace the old symbol file.

Note: if the M2CMPSYM option is set, the same is valid for compilation of a Modula-2 definition module, i.e., the CHANGESYM option should be set ON for the compilation to succeed if a module interface has been changed.

### CHECKDINDEX - check of dynamic array bounds

Modes: COMPILE (inline)

A check of dynamic array bounds.

If the option is set ON, the compiler generates index checks for dynamic arrays (`POINTER TO ARRAY OF T`).

The option is ON by default.

### CHECKDIV - check for a positive divisor (DIV and MOD)

Modes: COMPILE (inline)

If the option is set ON, the compiler generates a check if a divisor is positive in `DIV` and `MOD` operators.

The option is ON by default.

### CHECKINDEX - check of static array bounds

Modes: COMPILE (inline)

A check of static array bounds.

If the option is set ON, the compiler generates index checks for all arrays except dynamic (See the CHECKDINDEX option).

The option is ON by default.

### CHECKNIL - NIL pointer dereference check

Modes: COMPILE (inline)

If the option is set ON, the compiler generates NIL checks on all pointer dereferences.

The option is ON by default.

### CHECKPROC - check of a formal procedure call

Modes: COMPILE (inline)

If the option is set ON, the compiler generates a NIL check when calling a procedure variable.

The option is ON by default.

### CHECKRANGE - range checks (range types and enumerations)

Modes: COMPILE (inline)

If the option is set ON, the compiler generates range checks for range types and enumerations.

The option is ON by default.

### CHECKSET - range check of set operations

Modes: COMPILE (inline)

If the option is set ON, the compiler generates range checks for set operations (`INCL`, `EXCL`, set aggregates).

The option is ON by default.

### CHECKTYPE - dynamic type guards (Oberon-2 only)

Modes: COMPILE, Oberon-2 only (inline)

If the option is set ON, the compiler generates dynamic type guards.

The option is ON by default.

### COMMENT - copy comments into a generated C code

Modes: COMPILE (header)

If the option is set ON, the compiler copies comments to appropriate places in the generated C code. Comments from an Oberon-2 module are only inserted into the C code file and not into the header file.

### CONVHDRNAME - use file name in the '#include' directive

Modes: COMPILE

If the option is set ON, the compiler uses a file name in the `#include` directive. Otherwise the compiler generates a module name postfixed by the header file extension.

### CSTDLIB - definition of the C standard library

Modes: COMPILE,foreign definition only (header)

The option should be set when compiling a foreign definition module, otherwise it will be ignored. If the option is set ON, the compiler uses angle brackets `<>` in the `#include` directive, when importing the foreign definition. Otherwise the compiler uses quotes.

        #include <stdio.h>
        #include "MyLib.h"

### DIFADR16 - SYSTEM.DIFADR returns 16-bits value

Modes: COMPILE

If the option is set ON, the compiler assumes that the difference between addresses on the target platform is a 16-bit integer value, otherwise a 32-bit integer value.

The correct setting of the option is required for the `ADDADR`, `SUBADR`, and `DIFADR` system functions to work correctly.

See Describing platform for further details.

### FATFS - limit file names to 8.3

Modes: *

Forces the compiler to limit file names to FAT "8.3" convention.

### GCAUTO - enables implicit call of the garbage collector

Modes: COMPILE,top-level module only (header)

Enables implicit calls of the garbage collector in the generated program. The option is ignored for all modules except the top-level module of the program. We recommend to set the option in the project or configuration file.

See also Memory management.

### GENCDIV - generate C division operators

Modes: COMPILE (header)

If the option is set ON, the compiler translates `DIV` and `MOD` operators to C division operators `/` and `%`. By default, XDS generates ???.

### GENCPP - generate C++

Modes: COMPILE (header)

If the option is set ON, the compiler generates C++ code. By default, ANSI C code is generated. (See also GENKRC).

### GENCONSTENUM - generate enumeration as constants

Modes: COMPILE (header)

If this option is set ON, a Modula-2 enumeration type is translated to a set of integer constants. Otherwise, it is translated to a C enumeration (`enum`).

### GENCTYPES - generate C types

Modes: COMPILE (header)

If the option is set ON, the compiler generates standard C type names whenever possible, otherwise names defined in run-time support are used.

See Code generation for further details.

### GENDATE - insert a date in a C file

Modes: COMPILE

If the option is set ON (by default), the compiler inserts the current date into a generated C file.

### GENDEBUG - generate code in the debug mode

Modes: COMPILE (header)

If the option is set ON, the compiler generates code in debug mode. If your program is compiled in this mode, the run-time system prints a stack of procedure calls (a file name and a number of a line) on abnormal termination of your program. If the option LINENO is also ON, the stack is printed in terms of original (Oberon-2/Modula-2) source files, otherwise a file name and a number of a line of generated C files is printed.

Note: Setting the option ON will significantly enlarge your program and slow it down.

See Code generation for further details.

### GENFULLFNAME - generate full name in '#lineno' directive

Modes: COMPILE

If the option is set ON, the compiler generates full file names, including file paths from redirection directives, in `#lineno` directive.

### GENHISTORY - enable postmortem history

Modes: COMPILE (header)

If the option is set ON, the run-time system prints a stack of procedure calls (a file name and a line number) on abnormal termination of your program. It should be set when compiling a main module of the program. In this case the required part of the run-time system will be added to the program. The option LINENO should be set for all modules in the program.

See Debugging a program for an example.

### GENKRC - generate K&R C

Modes: COMPILE (header)

If the option is set ON, the compiler generates K&R C (no types in function prototypes, etc). It can be useful when porting software to platforms for which ANSI C compilers are not available. By default, the compiler generates ANSI C code.

See Procedure declarations and Code generation for further details.

Note: Seeting this option ON removes the line length limit in the generated C text (see GENWIDTH).

### GENPROCLASS - generate a specification of a procedure class

Modes: COMPILE (header)

If the option is set ON, the compiler inserts a special macro `X2C_PROCLASS` call in function prototypes for Modula-2 and Oberon-2 procedures. The option is set ON by default.

See Procedure declarations and Code generation for further details.

### GENPROFILE - generate additional code for profiling

Modes: COMPILE (header)

If the option is set ON, the compiler generates additional code to provide a profile of the program. See Code generation for further details.

### GENSIZE - evaluate sizes of types

Modes: COMPILE (header)

As specified in the language reports the call of standard function SIZE can be used in constant expression. Due to the specific of compilation to an intermediate language, the compiler does not know the sizes of most types during compilation.

When the option is OFF, the compiler will report an error if an attempt is made to use SIZE of almost all types in a constant expression:

`CONST size = SIZE(MyRecord);`

Note: sizes of whole types, `BOOLEAN`, `CHAR`, and set types are known to the compiler.

See Evaluating size of types for further details.

### GENTYPEDEF - generate typedef's for types

Modes: COMPILE (inline)

There are two possible ways to generate a declaration of a record (`struct`) type in C -- by using `typedef` of not. In most cases the way used by the compiler is of no concern. However, when writing a foreign language interface module (See Chapter Multilanguage programming) it is desirable to control type declarations.

When the option is ON, the compiler uses the `typedef` form for all the types declared. The option can be used in the source text, e.g:

        <* GENTYPEDEF + *>
        TYPE FILE = RECORD END;
        <* GENTYPEDEF - *>

See Code generation for further details.

### INDEX16 - index is of 16 bits

Modes: COMPILE

If the option is set ON, the compiler assumes that an index is of 16 bits on the target platform. By default, an index is of 32 bits.

See Describing platform for further details.

### LINENO - generate line numbers

Modes: COMPILE (header)

If the option is set ON, the compiler inserts a line of the form

`#line lineno [module]`

into the generated C code or header file for every generated statement, forcing the C compiler and other tools (such as a debugger) to refer to the original Modula-2 or Oberon-2 source text instead of the generated C code.

Note: Seeting this option ON removes the line length limit in the generated C text (see GENWIDTH).

### LONGNAME - use long names in batch files

Modes: MAKE,PROJECT

Use long names.

If the option is set ON, the compiler uses full path as a prefix for all module names in the generated batch files. See also BATCH submode.

### M2 - force the Modula-2 compiler

Modes: COMPILE

Force the Modula-2 compiler.

If the option is set ON, the Modula-2 compiler is invoked regardless of file extension. The option is ignored in MAKE and PROJECT modes.

### M2ADDTYPES - add SHORT and LONG types

Modes: COMPILE,Modula-2 only (header)

Add short and long modifications of whole types.

If the option is set ON, the compiler recognizes the types `SHORTINT`, `LONGINT`, `SHORTCARD` and `LONGCARD` as pervasive identifiers .

Warning: Usage of additional types may cause problems with the software portability to other compilers.

### M2BASE16 - use 16-bits basic types in Modula-2

Modes: COMPILE,Modula-2 only (header)

If the option is set ON, the basic types `INTEGER`, `CARDINAL`, and `BITSET` are 16 bits wide in Modula-2. By default, they are 32 bits wide.

### M2CMPSYM - compare symbol files in Modula-2

Modes: COMPILE,Modula-2 only

If the option is set ON, the Modula-2 compiler compares the symbol file generated for a definition module with the old version exactly as the Oberon-2 compiler does. If the symbol files are equal, the old one is preserved, otherwise the compiler overwrites symbol file, but only if the CHANGESYM option is set ON.

### M2EXTENSIONS - enable Modula-2 extensions

Modes: COMPILE,Modula-2 only (header)

If the option is set ON, the compiler allows XDS Modula-2 language extensions, such as line comment ("`--`"), read-only parameters, etc., to be used in the source code.

Warning: Extensions usage may cause problems with porting to third-party compilers.

### MAIN - mark an Oberon-2 main module

Modes: COMPILE, Oberon-2 only (header)

Mark the Oberon-2 main module.

If the option is set ON, the compiler generates a program entry point (`main' function) for the Oberon-2 module (See Program structure). Recommended to be used in a module header.

### MAKEDEF - generate definition

Modes: COMPILE,Oberon-2 only

Forces the Oberon-2 compiler to generate a (pseudo-) definition module after successful compilation of an Oberon-2 module. The compiler preserves the so-called exported comments (i.e. comments started with ``(**`') if the XCOMMENTS option is set ON.

See Creating a definition.

### MAKEFILE - generate makefile

Modes: PROJECT

Forces the compiler to generate a makefile after successful compilation of a project. See also GEN mode and Template files.

### NOEXTERN - do not generate prototypes for external C functions

Modes: COMPILE (inline)

If the option is set ON, the compiler does not generate C declarations for procedures defined as external.

See External procedures specification for further details.

### NOHEADER - disable generation of a header file

Modes: COMPILE,MAKE,PROJECT (header)

If the option is set ON, the compiler does not create a C header file.

See also Foreign language interface.

### NOOPTIMIZE - disable a set of opimizations

Modes: COMPILE If the option is set OFF (by default), the compiler performs a set of optimizations, including constant expression evaluation, constant propagation, etc. If the option is ON, the compiler produces less efficient, but more readable text.

We recommend to switch the option ON only if you are using XDS as a translator, i.e. if you will read or maintain the generated code.

### O2 - force the Oberon-2 compiler

Modes: COMPILE

Force Oberon-2 compiler.

If the option is set ON, the Oberon-2 compiler is invoked regardless of the file extension. The option is ignored in MAKE and PROJECT modes.

### O2ADDKWD - enable additonal keywords in Oberon-2

Modes: COMPILE,Oberon-2 only (header)

Allows Modula-2 exceptions and finalization to be used in Oberon-2 programs, adding keywords `EXCEPT`, `RETRY`, and `FINALLY`.

Warning: Usage of this extension will prevent your program from porting to other Oberon-2 compilers.

### O2EXTENSIONS - enable Oberon-2 extensions

Modes: COMPILE,Oberon-2 only (header)

If the option is set ON, the compiler allows Oberon-2 language extensions to be used (See Language extensions).

Warning: Extensions usage will affect portability to third-party Oberon-2 compilers.

### O2ISOPRAGMA - enable ISO Modula-2 pragmas in Oberon

Modes: COMPILE,Oberon-2 only

If the option is set ON, the compiler allows the ISO Modula-2 style pragmas `<* *>` to be used in Oberon-2. See Source code directives and Source code directives.

Warning: Usage of ISO Modula-2 pragmas may cause problems when porting source code to third-party Oberon-2 compilers.

### O2NUMEXT - enable Oberon-2 scientific extensions

Modes: COMPILE,Oberon-2 only (header)

If the option is set ON, the compiler allows the Oberon-2 scientific language extensions to be used (See Language extensions), including `COMPLEX` and `LONGCOMPLEX` types and the in-line exponentiation operator.

Warning: Usage of additional types may cause problems with portability to other compilers.

### OVERWRITE - create a file, always overwrites the old one

Modes: *

The option changes the way the compiler selects a directory for output files. If the option is OFF, the compiler always creates a file in the directory which appears first in the search path list correspondent to a pattern matching the file name. Otherwise, the compiler overwrites the old file, if it does exist in any directory of that list. See also Redirection file.

### PROCINLINE - enable in-line procedure expansion

Modes: COMPILE

If the option is ON, the compiler tries to expand procedures in-line. In-line expansion of a procedure eliminates the overhead produced by a procedure call, parameter passing, register saving, etc. In addition, more optimizations become possible because the optimizer may process the actual parameters used in a particular call.

A procedure is not expanded in-line under the following circumstances:

- the procedure is deemed too complex or too large by the compiler.
- there are too many calls of the procedure.
- the procedure is recursive.

### STORAGE - enable the default memory management in Modula-2

Modes: COMPILE, Modula-2 only (header)

If the option is set ON, the compiler uses the default memory allocation and deallocation procedures for the standard procedures `NEW` and `DISPOSE`.

Warning: Usage of this option may cause problems with software portability to other compilers.

### TARGET16 - C 'int' type is of 16 bits

Modes: COMPILE

If the option is set ON, the compiler assumes the C `int` type to be 16 bits wide on the target platform.

See Describing platform for further details.

### VERBOSE - produce verbose messages

Modes: MAKE,PROJECT

If the option is set ON, the compiler will report a reason for each module (re)compilation (See Smart recompilation).

### VERSIONKEY - append version key to the module initialization

Modes: COMPILE

This option may be used to perform version checks at link time. If the option is set ON, the compiler generates a name of a module body as composition of

- a module name
- a string "`_BEGIN_`"
- a time stamp
- values of options TARGET16, INDEX16 and DIFADR16 in the packed form

If a Modula-2 definition module or an Oberon-2 module imported by different compilation units has the same version, the same name is generated for each call of the module body. In all other cases unresolved references will be reported at link time.

If the option is OFF, the compiler generates module body names in a form: `<module_name>_BEGIN`.

Note: the option should be set when compiling a Modula-2 definition module or an Oberon-2 module.

See Identifiers for further details.

### WERR - treat warningns as errors

Modes: * (inline)

When the option `WERRnnn` (e.g. `WERR301`) is set ON, the compiler treats the warning `nnn` (301 in the above example) as error. See the xm.msg file for warning texts and numbers.

`-WERR+` forces the compiler to treat all warnings as errors.

### WOFF - suppress warning messages

Modes: * (inline)

When the option `WOFFnnn` (e.g. `WOFF301`) is set ON, the compiler does not report the warning `nnn` (301 in the above example). See the xm.msg file for warning texts and numbers.

`-WOFF+` disables all warnings.

### XCOMMENTS - preserve exported comments

Modes: COMPILE,Oberon-2 only

If the option is set ON, the browser includes so-called exported comments (i.e. comments which start with "`(**`") into a generated pseudo definition module.

See also Creating a definition.

## Equations

An equation is a pair (`name`,`value`), where `value` is in general case an arbitrary string. Some equations have a limited set of valid values, some may not have the empty string as a value.

A compiler setup directive (See Options) is used to set an equation value or to declare a new equation.

Equations may be set in a configuration file, on the command line and in a project file). Some equations may be set in the source text, at an arbitrary position (marked as inline in the reference), or only in the module header (marked as header). At any point of operation, the most recent value of an equation is in effect.

Alphabetical list of all equations may be found in the section Equations reference.

Table 5. File extensions

Name | Default | File type
BATEXT | `.bat` | recompilation batch file
BSDEF | `.odf` | pseudo-definition file created by browser
CODE | `.c` | generated C code file
DEF | `.def` | Modula-2 definition module
HEADER | `.h` | generated C header file
MKFEXT | `.mkf` | makefile
MOD | `.mod` | Modula-2 implementation or main module
OBERON | `.ob2` | Oberon-2 module
OBJEXT | `.o` | object file
PRJEXT | `.prj` | project file
SYM | `.sym` | symbol file

Table 6. Code generator equations

Name | Default | Meaning
ALIGNMENT | `4` | data alignment (please read details below)
COPYRIGHT |  | copyright note
ENUMSIZE | `4` | default size of enumeration types
GCTHRESHOLD |  | garbage collector threshold (obsolete)
GENIDLEN | `30` | length of an identifier in the generated C text
GENINDENT | `3` | indentation
GENWIDTH | `78` | line width in the generated C text
HEAPLIMIT | `0` | generated program heap limit
SETSIZE | `4` | default size of small set types
STACKLIMIT | `0` | generated program stack limit

Table 7. Miscellaneous equations

Name | Default | Meaning
ATTENTION | `!` | attention character in template files
BATNAME | `out` | batch file name
BATWIDTH | `128` | maximum line width in a batch file
BSTYLE | `DEF` | browse style (See Creating a definition)
COMPILERHEAP |  | heap limit of the compiler
COMPILERTHRES |  | compiler's garbage collector threshold (obsolete)
DECOR | `hrtp` | control of compiler messages
ENV_HOST |  | host platform
ENV_TARGET |  | target platform
ERRFMT | See Error message format specification | error message format
ERRLIM | `16` | maximum number of errors
FILE |  | name of the file being compiled
LINK |  | linker command line
LOOKUP |  | lookup directive
MKFNAME |  | makefile name
MODULE |  | name of the module being compiled
PRJ |  | project file name
PROJECT |  | project name
TABSTOP | `8` | tabulation alignment
TEMPLATE |  | template name (for makefile)

## Equations reference

Operation modes in which an equation has effect are enclosed in square brackets ([]) after the equation name; the character '*' stands for all operation modes. For example [browse] means that the equation is used by the compiler in the BROWSE operation mode only. Note: the compiler switches from the MAKE and PROJECT mode to the COMPILE mode to compile a module.

- ALIGNMENT - data alignment
- ATTENTION - attention character in template files
- BATEXT - recompilation batch file extension
- BATNAME - batch file name
- BATWIDTH - maximum line width in a batch file
- BSDEF - pseudo-definition file created by browser extension
- BSTYLE - browse style
- CODE - generated C code file extension
- COMPILERTHRES - compiler's garbage collector threshold (obsolete)
- COMPILERHEAP - heap limit of the compiler
- COPYRIGHT - copyright note
- DECOR - control of compiler messages
- DEF - Modula-2 definition module extension
- ENUMSIZE - default size of enumeration types
- ENV_HOST - host platform
- ENV_TARGET - target platform
- ERRFMT - error message format
- ERRLIM - maximum number of errors
- FILE - name of the file being compiled
- GCTHRESHOLD - garbage collector threshold (obsolete)
- GENIDLEN - length of an identifier in the generated C text
- GENINDENT - indentation
- GENWIDTH - line width in the generated C text
- HEADER - generated C header file extension
- HEAPLIMIT - generated program heap limit
- LINK - linker command line
- LOOKUP - lookup directive
- MKFEXT - makefile extension
- MKFNAME - makefile name
- MOD - Modula-2 implementation or main module extension
- MODULE - name of the module being compiled
- OBERON - Oberon-2 module extension
- OBJEXT - object file extension
- PRJ - project file name
- PRJEXT - project file extension
- PROJECT - project name
- SETSIZE - default size of small set types
- STACKLIMIT - generated program stack limit
- SYM - symbol file extension
- TABSTOP - tabulation alignment
- TEMPLATE - template name (for makefile)

### ALIGNMENT - data alignment

Modes: COMPILE (inline)

This equation sets the data alignment. Valid values are: 1,2,4, or 8. See Evaluating size of types for further details.

### ATTENTION - attention character in template files

Modes: PROJECT,GEN

The equation defines an attention character which is used in template files ("!" by default). See Template files.

### BATEXT - recompilation batch file extension

Modes: MAKE,PROJECT,batch submode

Sets the file extension for recompilation batch files (by default .bat). See BATCH submode.

### BATNAME - batch file name

Modes: MAKE,PROJECT,batch submode

Sets the batch file name.

The name of the project file will be used if no batch file name is explicitly specified. See BATCH submode.

### BATWIDTH - maximum line width in a batch file

Modes: MAKE,PROJECT,batch submode

Sets the maximum width of a line in a generated batch file (by default 128). See BATCH submode.

### BSDEF - pseudo-definition file created by browser extension

Modes: BROWSE

Sets the file extension for pseudo-definition modules created by the browser (by default .odf). See BROWSE mode.

### BSTYLE - browse style

Modes: BROWSE

Sets the style of generated pseudo-definition modules. See Creating a definition.

### CODE - generated C code file extension

Modes: *

Sets the file extension for code files generated by the compiler (by default .c).

### COMPILERTHRES - compiler's garbage collector threshold (obsolete)

Modes: *

This equation is left for compatibility; it is ignored by the compiler. In versions prior to 2.50, it was used to fine tune the compiler's garbage collector.

See also XDS memory usage.

### COMPILERHEAP - heap limit of the compiler

Modes: *

Sets the maximum amount of heap memory (in bytes), that can be used by the compiler. For systems with virtual memory, we recommend to use a value which is less than the amount of physical memory.

Setting this equation to zero forces adaptive compiler heap size adjustment according to system load.

### COPYRIGHT - copyright note

Modes: COMPILE

This copyright note line will be inserted as a comment into all generated C code/header files. See Layout of a generated code, Code presentation.

### DECOR - control of compiler messages

Modes: *

The equation controls output of the xm utility. The value of equation is a string that contains any combination of letters "h", "t", "r", "p" (capital letters are also allowed). Each character turns on output of

h
  header line, which contains the name and version of the compiler's front-end and back-end
p
  progress messages
r
  compiler report: number of errors, lines, etc.
t
  the summary of compilation of multiple files

By default, the equation value is "hrt".

### DEF - Modula-2 definition module extension

Modes: *

Sets the file extension for Modula-2 definition modules (by default .def).

### ENUMSIZE - default size of enumeration types

Modes: COMPILE(inline)

Sets the default size for enumeration types in bytes (1,2, or 4). If an enumeration type does not fit in the current default size, the smallest suitable size will be taken.

### ENV_HOST - host platform

Modes: *

A symbolic name of the host platform. See also Configuring XDS for seamless compilation.

### ENV_TARGET - target platform

Modes: *

Sets a symbolic name of a target platform. A platform is a combination of operating system, file system, C compiler, its options, etc. See a list of available platforms in `xm.cfg`. See also Configuring XDS for seamless compilation.

### ERRFMT - error message format

Modes: *

Sets the error message format. See Error message format specification for details.

### ERRLIM - maximum number of errors

Modes: *

Sets the maximum number of errors allowed for one compilation unit (by default 16).

### FILE - name of the file being compiled

Modes: COMPILE

The compiler sets this equation to the name of the currently compiled file. See also the MODULE equation.

### GCTHRESHOLD - garbage collector threshold (obsolete)

Modes: COMPILE,top-level module only

This equation is left for compatibility; it is ignored by the compiler. In versions prior to 2.50, it was used to fine tune the garbage collector.

See also Memory management.

### GENIDLEN - length of an identifier in the generated C text

Modes: COMPILE

The maximum length of an identifier in the generated C code (by default 30). Note: the identifier length limit cannot be less than 6 characters. Small values result in a more compact but less readable text. See also Identifiers.

### GENINDENT - indentation

Modes: COMPILE

Sets indentation in the generated code (by default 3 characters).

### GENWIDTH - line width in the generated C text

Modes: COMPILE

The maximum width of a line in generated C code/header files (by default 78).

Note: This equation is ignored and the maximun length of the line is not limited if at least one of the options LINENO and GENKRC is set ON.

### HEADER - generated C header file extension

Modes: *

Sets the file extension for ANSI C header files generated by compiler (by default .h).

### HEAPLIMIT - generated program heap limit

Modes: COMPILE,top-level module only

Sets the maximum amount of heap memory, that can be allocated by the generated program. The value is set in bytes.

Setting this equation to zero enables the run-time system to dynamically adjust heap size according to application's memory demands and system load.

The equation should be set when the top-level module of the program is compiled. We recommend to set it in a project file or the configuration file.

See also Memory management.

### LINK - linker command line

Modes: PROJECT

Defines a command line, which will be executed after a successful completion of a project. As a rule, the equation is used for calling a linker or make utility.

See Building a program for examples.

### LOOKUP - lookup directive

Modes: *

Syntax:

`-LOOKUP = pattern = directory {";" directory }`

The equation can be used for defining additional search paths that would complement those set in the redirection file. A configuration or project file may contain several LOOKUP equations; they are also permitted on the command line.

See also Redirection file and Project files.

### MKFEXT - makefile extension

Modes: GEN

Sets the file extension for generated makefiles (by default .mkf). See GEN mode.

### MKFNAME - makefile name

Modes: GEN

Sets the name for a generated makefile. See GEN mode.

### MOD - Modula-2 implementation or main module extension

Modes: *

Sets the file extension for Modula-2 implementation and program modules (by default .mod).

### MODULE - name of the module being compiled

Modes: COMPILE

The compiler sets this equation to the name of the currently compiled module. See also the FILE equation.

### OBERON - Oberon-2 module extension

Modes: *

Sets the file extension for Oberon-2 modules (by default .ob2).

### OBJEXT - object file extension

Modes: *

Sets the file extension for object files (by default .o).

### PRJ - project file name

Modes: COMPILE,MAKE,PROJECT

In the COMPILE and MAKE operation modes, the equation defines a project file to read settings from. In the PROJECT mode, the compiler sets this equation to a project file name from the command line. See PROJECT mode.

### PRJEXT - project file extension

Modes: COMPILE,MAKE,PROJECT

Sets the file extension for project files (by default .prj). See PROJECT mode.

### PROJECT - project name

Modes: COMPILE,MAKE,PROJECT

If a project file name is defined, the compiler sets the equation to a project name without a file path and extension. For example, if the project file name is `prj/Work.prj`, the value of the equation is set to `Work`. The equation may be used, for instance, in a template file to set the name of the executable file.

### SETSIZE - default size of small set types

Modes: COMPILE(inline)

Sets the default size for small (16 elements or less) set types in bytes (1,2, or 4). If a set type does not fit in the current default size, the smallest suitable size will be taken.

### STACKLIMIT - generated program stack limit

Modes: COMPILE,top-level module only

Sets the maximum size of the stack in a generated program. The value is set in bytes.

The equation should be set when a top-level module of a program is compiled. We recommend to set the option in the project or configuration file.

### SYM - symbol file extension

Modes: *

Sets the file extension for symbol files (by default .sym). See Files generated during compilation.

### TABSTOP - tabulation alignment

Modes: GEN

When reading text files, the compiler replaces the ASCII TAB character with the number of spaces required to align text (by default TABSTOP is equal to 8). A wrong value may cause misplaced comments in a generated pseudo-definition module, incorrect error location in an error message, etc. We recommend to set this equation to the number used in your text editor.

### TEMPLATE - template name (for makefile)

Modes: GEN

Sets a name of a template file. See Template files.

## Error message format specification

The format in which XDS reports errors is user configurable through the ERRFMT equation. Its syntax is as follows:

`{ string "," [ argument ] ";" }`

Any format specification allowed in the C procedure `printf` can be used in `string`.

Argument | Type | Meaning
line | integer | position in a source text
column | integer | position in a source text
file | string | name of a source file
module | string | module name
errmsg | string | message text
errno | integer | error code
language | string | Oberon-2 or Modula-2
mode | string | ERROR or WARNING or FAULT
utility | string | name of an utility

Argument names are not case sensitive. By default, the error message format includes the following clauses:

`"(%s",file;` | --- | a file name
`"%d",line;` | --- | a line number
`",%d",column;` | --- | a column number
`") [%.1s] ",mode;` | --- | the first letter of an error mode
`"%s\n",errmsg;` | --- | an error message

If a warning is reported for the file `test.mod` at line 5, column 6, the generated error message will look like this:

`(test.mod 5,6) [W] variable declared but never used`

## The system module COMPILER

The system module `COMPILER` provides two procedures which allow you to use compile-time values of options and equations in your Modula-2 or Oberon-2 program:

        PROCEDURE OPTION(<constant string>): BOOLEAN;
        PROCEDURE EQUATION(<constant string>): <constant string>;

Both this procedures are evaluated at compile-time and may be used in constant expressions.

Note: The `COMPILER` module is non-standard.

##### Examples

    Printf.printf("This program is optimized for the %s CPU\n",
                  COMPILER.EQUATION("CPU"));

    IF COMPILER.OPTION("__GEN_C__") THEN
      ...
    END;