Super Prev Next

Configuring the compiler

Super Prev Next

System search paths

In order for your operating system to know where to find the executable binary files which constitute the XDS package, you must set your operating system search paths appropriately. See the Read Me First file from your on-line documentation.

Super Prev Next

Working configuration

The core part of XDS is the xmutility, which combines the project subsystem with Modula-2 and Oberon-2 compilers, accompanied with a set of system files /A name of a system file is constructed from the name of the compiler utility and the correspondent filename extension. If you rename the xm utility, you should also rename all system files./ : Search path redirection file
xm.cfg Configuration file
xm.msg Texts of error messages
xm.kwd List of C/C++ keywords and reserved identifiers

Being invoked, xm tries to locate the file, first in the current directory and then in the directory where xm is placed (so called master redirection file).

Other system files are sought by paths defined in If is not found, or it does not contain paths for a particular system file, that file is sought in the current directory and then in the directory where the xm utility resides.

A configuration file contains settings that are relevant for all projects. Project specific settings are defined in project files (See Project files). A so-called template file is used to automate the program build process (See Template files).

A redirection file, a configuration file, and, optionally, a project file and a template file constitute a working environment for a single execution of the xm utility. The compiler preprocesses files of all these types as described in Control file preprocessing.

Portable software development is one of the main goals of XDS. To achieve that goal, not only the source texts should be portable between various platforms, but the environment also. XDS introduces a portable notation for file names that may be used in all system files and on the command line. The portable notation combines DOS-like and Unix-like notations (file names are case sensitive):

    [ drive_letter ":" ] unix_file_name

Super Prev Next



Along with the base directory macro (See Control file preprocessing) this portable notation allows to write all environment files in a platform independent and location independent manner.

Super Prev Next

XDS memory usage

XDS compilers are written in Oberon-2 /We use XDS in most of our developments./ . As any other Oberon-2 program, a compiler uses garbage collector to deallocate memory. These days, most operating systems, including Windows and Linux, provide virtual memory. If an Oberon-2 program exceeds the amount of avaiable physical memory, the garbage collector becomes inefficient. Thus, it is important to restrict the amount of memory that can be used by an Oberon-2 program. As a rule, such restriction is set in the configuration or project file (See the HEAPLIMIT equation). You may also let the run-time system determine the proper heap size at run time by setting HEAPLIMIT to zero.

Similarly, the equation COMPILERHEAP should be used to control the amount of memory used by a compiler itself. That equation is set in the configuration file (xm.cfg). We recommend to set it according to the amount of physical memory in your computer:

32-64 16000000
64-128 48000000
more than 128 96000000

It may be necessary to increase COMPILERHEAP if you get the "out of memory" message (???). It is very unlikely, if COMPILERHEAP is set to 16 megabytes or more. Your compilation unit should be very large to exceed this memory limit. Note: if you are using Win32 or X Window API definition modules, set COMPILERHEAP to at least 16 megabytes.

Vice versa, if you notice unusually intensive disk activity when compiling your program, it may indicate that the value of the COMPILERHEAP equation is too large for your system configuration.

Set COMPILERHEAP to zero if would prefer the compiler to dynamically adjust heap size in accordance with system load.

See Memory management for more information on XDS memory management.

Super Prev Next

Directory hierarchies

XDS compilers give you complete freedom over where you store both your source code files and any files which compilers create for you. It is advisable to work in a project oriented fashion — i.e. to have a separate directory hierarchy for each independent project.

Due to the re-usable nature of modules written in Modula-2 or Oberon-2, it is wise to keep a separate directory for those files which are to be made available to several projects. We will call such files the library files.

We recommend you to have a separate working directory for each project. You can also create subdirectories to store symbol files and generated code files. We recommend to use the supplied script or its customized version to create all subdirectories and, optionally, a local redirection file or a project file. Refer to the "Read Me First" file for more information about that script.

Super Prev Next

XDS search paths

Upon activation, xm looks for a file called — a redirection file. That file defines paths by which all other files are sought. If a redirection file was not found in the current directory, the master redirection file is loaded from the directory where xm executable is placed.

Super Prev Next

Redirection file

A redirection file consists of several lines of the form /See also Control file preprocessing/ :

    pattern = directory {";" directory}

pattern is a regular expression with which names of files xm has to open or create are compared. A pattern usually contains wildcard symbols ’*’ and ’?’, where

Symbol Matches
* any (possibly empty) string
? any single character.

For a full description of regular expressions see Regular expression.

It is also possible to have comment lines in a redirection file. A comment line should start with the "%" symbol.

A portable notation is used for directory names or paths. A path may be absolute or relative, i.e. may consist of full names such as


or of names relative to the current directory, such as


denoting the directory src/common which is a subdirectory of the current directory. A single dot as a pathname represents the current directory, a double dot represents the parent, i.e. the directory which has the current directory as a subdirectory.

The base directory macro $! can be used in a directory name. It denotes the path to the redirection file. If the redirection file is placed in the /usr/alex directory then $!/sym denotes the /usr/alex/sym directory, whereas $!/.. denotes the /usr directory.

For any file, its name is sequentially matched with a pattern of each line. If a match was found, the file is sought in the first of the directories listed on that line, then in the second directory, and so on until either the file is found, or there are no more directories to search or there are no more patterns to match.

If xm could not locate a file which is needed for correct operation, e.g. a necessary symbol file, it terminates with an appropriate error message.

When creating a file, xm also uses redirection, and its behavior is determined by the OVERWRITE option. If the option was set ON, xm first searches for the file it is about to create using redirection. Then, if the file was found, xm overwrites it. If no file of the same name as the one which xm needs to create was found or the OVERWRITE option was set OFF, then the file is be created in the directory which appears first in the search path list which pattern matched the filename.

If no pattern matching a given filename can be found in the file, then the file will be read from (or written to) the current working directory.

Note: If a pattern matching a given filename is found then xm will not look into the current directory, unless it is explicitly specified in the search path.

The following entry in would be appropriate for searching for the symbol files (provided that symbol files have the extension .sym).


Given the above redirection, the compiler will first search for symbol files in the directory sym which is a subdirectory of the current working directory; then in the directory storing the XDS library symbol files and then in the current directory.

Super Prev Next

Example of a redirection file:

    xm.msg = /xds/bin
    *.mod = mod
    *.def = def
    *.ob2 = oberon
    *.c   = c
    *.h   = include;/xds/include
    *.sym = sym; /xds/sym/C

Super Prev Next

Regular expression

A regular expression is a string containing certain special symbols:

Sequence Denotes
* an arbitrary sequence of any characters, possibly empty
  (equivalent to {\000-\377} expression)
? any single character
  (equivalent to [\000-\377] expression)
[...] one of the listed characters
{...} an arbitrary sequence of the listed characters, possibly empty
\nnn the ASCII character with octal code nnn, where n is [0-7]
& the logical operation AND
| the logical operation OR
^ the logical operation NOT
(...) the priority of operations

A sequence of the form a-b used within either [] or {} brackets denotes all characters from a to b.

Super Prev Next


all files which extension is .def

files which name is project with an arbitrary extension

files which extension is either .def or .mod

files starting with any sequence of letters, ending in one final "X" and having the extension .def.

Super Prev Next


A rich set of xm options allows one to control the source language, code generation and 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. In this chapter we describe only the syntax of setup directive. The full list of xm options and equations is provided in the Chapter Compiler options and equations.

Options and equations may be set in a configuration file, on the command line, in a project file), and in the source text (see Source code directives).

The same syntax of a setup directive is used in configuration and project files and on the command line. The only difference is that arbitrary spaces are permitted in files, but not on the command line. Option and equation names are case independent.

SetupDirective   = SetOption
                 | SetEquation
                 | DeclareOption
                 | DeclareEquation
                 | DeclareSynonym
SetOption        = '-' name ('+'| '-')
SetEquation      = '-' name '=' [ value ]
DeclareOption    = '-' name ':' [ '+' | '-' ]
DeclareEquation  = '-' name ':=' [ value ]
DeclareSynonym   = '-' name '::' name

All options and equations used by xm are predeclared.

The DeclareSynonym directive allows one to use a different name (e.g. shorter name) for an option or equation.

The old version of SetOption is also supported for convenience:

OldSetOption   = '+' name | '-' name

Super Prev Next


Directive Meaning
-M2Extensions+ M2EXTENSION is set ON
-Oberon=o2 OBERON is set to "o2"
-debug: DEBUG is declared and set OFF
-Demo:+ DEMO is declared and set ON
-Vers:=1.0 VERS is declared and set to "1.0"
-A::genasm A is declared as a synonym for GENASM
+m2extensions M2EXTENSIONS is set OFF

Super Prev Next

Configuration file

A configuration file can be used to set the default values of options and equations (see Chapter Compiler options and equations) for all projects (or a set of projects). A non-empty line of a configuration file may contain a single compiler option or equation setup directive (see Options) or a comment. Arbitrary spaces are permitted. The "%" character indicates a comment; it causes the rest of a line to be discarded. Note: the comment character can not be used when setting an equation.

The master configuration file, placed along with the xm utility, usually contains default settings for the target platform and declarations of platform-specific options and equations, which may be used in project and template files.

Figure 1. A sample configuration file

  % this is a comment line
  % Set equation:
   - BSDef = df
  % Set predeclared options:
   - RangeCheck -   % turn range checks off
   - M2EXTENSIONS + % allow Modula-2 extensions
  % Declare new options:
   -i80386:         % is equal to -i80386:-
  % Declare synonym:
   -N :: checknil
   -N               % disallow NIL checks
  % end of configuration file

Super Prev Next

Filename extensions

xm allows you to define what you want to be the standard extensions for each particular type of file. For instance, you may prefer your Oberon-2 source code texts to end in .o2 instead of .ob2.

We recommend to either use the traditional extensions or at least the extensions which describe the kind of file they refer to, and keep same extensions across all your projects. For example, use .def and .mod for Modula-2 modules, .ob2 for Oberon-2 modules, etc.

Certain other factors must also influence your decisions. Traditionally, Oberon-2 pseudo-definition modules (as created by a browser) are extended with a .def. With XDS, this may conflict with the extension used for Modula-2 definition modules. Therefore, the XDS browser uses the extension .odf by default.

The following filename extensions are usually defined in the configuration file:

DEF extension for Modula-2 definition modules
MOD extension for Modula-2 implementation modules
OBERON extension for Oberon-2 modules
BSDEF extension for Oberon-2 pseudo definition modules
HEADER extension for C header files
CODE extension for generated code files
SYM extension for symbol files

See Table 5. File extensions for the full list of file extensions.

Super Prev Next

Example (file extension entries in xm.cfg):

   -def     = def
   -mod     = mod
   -oberon  = ob2
   -sym     = sym

Super Prev Next

Customizing compiler messages

The file xm.msg contains texts of error messages in the form

    number text

The following is an extract from xm.msg:

001 illegal character
002 comment not closed; started at line %d
042 incompatible assignment

Some messages contain format specifiers for additional arguments. In the above example, the message 002 contains a %d specifier used to print a line number.

To use a language other than English for compiler messages it is sufficient to translate xm.msg, preserving error numbers and the order of format specifiers.

Super Prev Next

XDS and your C compiler

XDS-C can be used as a translator or compiler. In the first case, the C code generated by xm will be used for further development or will be ported to another platform. In the second case, xm is used as first pass of compilation process; to get an executable program a C compiler must be used. A C compiler, linker, or make utility may be invoked seamlessly

Usually, you have to configure xm for your C compiler only once and then xm will do everything to get your program ready for execution.

Super Prev Next

Building the run-time library

The XDS run-time library is included in an XDS package in C source form, i.e. for each library module its header file and C source file are provided. For Unix platforms, a pre-built library file containing object files may be included. This is not the case for the Windows platform, because different C compilers support different calling and naming conventions. We recommend to build the library file for your C compiler or several library files for various C compilers or memory models. The LIB/C subdirectory or your XDS installation contains makefiles which can be used for that purpose. It may be necessary to change a C compiler name or compiler options in this file.

Super Prev Next

Configuring XDS for seamless compilation

We will use the term seamless compilation if xm is configured to call a C compiler, linker or make implicitly to prepare an executable for your program. A makefile can be produced after successful completion of a project and a make utility can be implicitly called then to compile and link your program.

The compiler uses a template file (See Template files) to generate a makefile. The XDS distribution contains the xds.tem template file, which can be used for various C compilers. The equation ENV_TARGET determines a target platform, i.e. a file system, including a representation of a file name, C compiler to use, its options, etc. By default, the value of this equation is equal to the value of the ENV_HOST equation. The configuration file xm.cfg contains a list of supported platform, i.e. list of names, that can be used as a value of ENV_TARGET equation. We recommend to set the value of the equation in the beginning of the configuration file. It may be necessary to change some settings for your platform or append a new platform. All changes should be done in xm.cfg and xds.tem files.

Note, in the current version it is not possible to append a new platform with DOS-like file system. We recommend to change settings for platform "MSDOS", "OS2" and "WinNT" if necessary.

See Building a program for more information.