# Configuring the compiler

- System search paths
- Working configuration
- XDS memory usage
- Directory hierarchies
- XDS search paths
- Options
- Configuration file
- Filename extensions
- Customizing compiler messages
- XDS and your C compiler

## 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.

## Working configuration

The core part of XDS is the `xm`utility, which combines the project subsystem with Modula-2 and Oberon-2 compilers, accompanied with a set of system filesA 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.:

xm.red | 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 `xm.red` 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 `xm.red`. If `xm.red` 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`

##### Examples

        c:/xds/bin
        /mnt/users/alex/cur_pro
        cur_pro/sources

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.

## XDS memory usage

XDS compilers are written in Oberon-2We 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:

RAM in megabytes | COMPILERHEAP
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.

## 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.

## XDS search paths

Upon activation, xm looks for a file called `xm.red` --- 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.

- Redirection file
- Regular expression

### Redirection file

A redirection file consists of several lines of the formSee 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

`/usr/myproj/def`

or of names relative to the current directory, such as

`src/common`

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 `xm.red` 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 `xm.red` would be appropriate for searching for the symbol files (provided that symbol files have the extension .sym).

`*.sym=sym;/usr/xds/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.

##### 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

### 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`.

##### Examples

`*.def`
  all files which extension is `.def`

`project.*`
  files which name is `project` with an arbitrary extension

`*.def|*.mod`
  files which extension is either `.def` or `.mod`

`{a-z}*X.def`
  files starting with any sequence of letters, ending in one final "X" and having the extension `.def`.

## Options

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`

##### Examples

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

## 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:
       -iPentium:+
       -i80486:-
       -i80386:         % is equal to -i80386:-
      % Declare synonym:
       -N :: checknil
       -N               % disallow NIL checks
      % end of configuration file

## 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.

##### Example (file extension entries in xm.cfg):

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

## 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.

## 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.

- Building the run-time library
- Configuring XDS for seamless compilation

### 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.

### 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.