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 xcutility, 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 xc utility, you should also rename all system files./ :

xc.red Search path redirection file
xc.cfg Configuration file
xc.msg Texts of error messages

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

Other system files are sought by paths defined in xc.red. If xc.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 xc 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 xc 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

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.


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 (xc.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 (F950). 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, xc looks for a file called xc.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 xc 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 xc 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 xc 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, xc also uses redirection, and its behavior is determined by the OVERWRITE option. If the option was set ON, xc first searches for the file it is about to create using redirection. Then, if the file was found, xc overwrites it. If no file of the same name as the one which xc 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 xc.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 xc will not look into the current directory, unless it is explicitly specified in the search path.

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

    *.sym=sym;c:/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.

Super Prev Next

Example of a redirection file:

    xc.msg = /xds/bin
    *.mod = mod
    *.def = def
    *.ob2 = oberon
    *.sym = sym; /xds/sym/x86


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

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.


Super Prev Next

Options

A rich set of xc 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 xc 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 xc 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

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


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


Super Prev Next

Filename extensions

xc 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
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 xc.cfg):

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


Super Prev Next

Customizing compiler messages

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

    number text

The following is an extract from xc.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 xc.msg, preserving error numbers and the order of format specifiers.


Super Prev Next

XDS and your C compiler

XDS allows C object modules and libraries to be used in your projects. Different C compilers use different alignment, naming and calling conventions. Thus it is necessary to configure XDS for your C compiler in order to use C libraries and modules in your program. See Configuring XDS for a C Compiler for more details.