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.
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 filesA 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
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 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 (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 |
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.
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.
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.
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 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;/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.
xc.msg = /xds/bin *.mod = mod *.def = def *.ob2 = oberon *.sym = sym; /xds/sym/x86
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.
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
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 |
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
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 |
-def = def -mod = mod -oberon = ob2 -sym = sym
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.
XDS allows C object modules and libraries to be used in your projects. Different C compilers use different alignment, naming and calling conventions. ATTENTION! Since XDS libraries on linux are built through GCC compiler it is absolutely neccesary to configure XDS for GCC. See Configuring XDS for a C Compiler for more details.