INTRO.TXT                        Copyright (c) 1991,96 xTech Ltd
----------------------------------------------------------------

                 Native XDS-x86 OS/2 Edition
                 ---------------------------
                     v2.17 (pre-release)

                        Introduction


XDS is a professional development system available for most popular
platforms, including  OS/2, Linux, Windows NT, Windows 95, PC/MS-DOS,
Unix workstations (Sun, HP, DEC, MIPS, etc), etc. via the C generation.
The native code compilers are available currently for OS/2, Linux,
Windows NT, and Windows 95. The previous version of XDS was known as
"Extacy".  The native code versions of the system were distributed 
as "Extacy.EXE" and "OM2".

XDS contains both Modula-2 and Oberon-2 compilers. The source
language of XDS Modula-2 compiler is fully compatible with ISO
Modula-2 standard. We are expecting that adaptation of the ISO
standard will cause the new wave of interest to Modula-2. The ISO
Modula-2 includes features important for industry programming such
as standard library set, exceptions, and support of concurrency.

Oberon-2 is an object-oriented programming (OOP) language based
on Modula-2. With introduction of object-oriented facilities,
extensible project design became much easier. Meanwhile Oberon-2
is quite simple and easy to learn and use, unlike other OOP
languages such as C++ or Smalltalk.

Moving to a new language usually means throwing away or rewriting
your existing library set which could have been the work of many
years. XDS allows programmer to mix Modula-2, Oberon-2, C and
Assembler modules and libraries in a single project.

XDS includes subsets of standard ISO and PIM Modula-2 libraries
complete with ANSI C standard interface which can be accessed
and used from both Modula-2 and Oberon-2.

                 About the pre_release Version
                 -----------------------------

This version is a pre-release distribution of XDS OS/2 package,
including:

        - "xds" - interactive programming environment
        - "xc" utility, which combines Modula-2 and Oberon-2
               to compilers and "make" facilities
        - ISO Modula-2 Library
        - A subset of the PIM Compliant Library
        - A subset of the ANSI C Library Interfaces

The "xc" utility  will  only  operate on computers that are IBM PS2
or IBM AT compatible and contain an 80386 processor (with numerical
coprocessor) or better.

                            Using XDS
                            ---------

The  XDS  Modula-2  and  Oberon-2 compilers are activated from a
single  utility  "xc".  When  invoked  without  parameters,  the
utility shows some "help" information. The working configuration
includes:

        xc.exe    Modula-2/Oberon-2 development system
        xc.msg    Contains texts of error messages
        xc.red    Search path redirection file (optional)
        xc.cfg    Configuration file (optional)

When  invoked  the  "xc"  tries  to locate the xc.red file in the
current directory or in the directory where "xc.exe" (C:\XDS\BIN)
is placed.

Other system files ("xc.msg" and "xc.cfg") are sought by paths
defined  by "xc.red". If "xc.red" is not found, or it does not
contain paths for a system file, the system file is sought in the
current  directory  or  in  the  directory where "xc.exe" is
placed.

                        Redirection File
                        ----------------

The file "xc.red" consists of several lines of the form:

        pattern = directory_path {";" directory_path}

Example of redirection file:

        *.def  = def
        *.mod  = mod
        *.sym  = sym; c:\xds\sym;
        xc.cfg = .; c:\xds\bin

XDS  will  search definition modules in the "def" sub-directory,
symbol files in the "sym" sub-directory and then in "c:\xds\sym"
and  files  "xc.cfg",  "xc.msg"  will  be  sought in the current
directory and then in "c:\xds\bin".


                       Configuration File
                       ------------------

The configuration file can be used to set the default values  of
options and equations.

When  invoked,  XDS  searches  for  configuration file "xc.cfg".
Every  line  in  the  configuration  file  can  contain only one
compiler  option  or equation setup directive. It is possible to
put  comment lines into configuration file. Comment lines should
start with a "%" symbol.

setup_directive = declare_option
                | declare_synonym
                | set_option_on
                | set_option_off
                | set_equation
declare_option  = '-' name ':' [ '+' | '-' ]
declare_synonym = '-' name ':=' name
set_option_on   = '-' name '+'
set_option_off  = '-' name '-'
set_equation    = '-' name ['='] value

To set an option ON, use "-OPTION+" directive.
To set an equation,  use  "-OPTION = VALUE" directive.

Option and equation names are case independent. Arbitrary spaces
are permitted in the configuration file.

Example:

        % this is a comment
        % equation option - set Oberon-2 file extension
        - Oberon = ob2
        % boolean option - allow Modula-2 extensions
        - M2extensions +
        % end of configuration file

                          Invoking XDS
                          ------------

"xc" is invoked from the command line of the following form

        xc { OPERATION MODE | OPTION | NAME }

where  NAME for different operation modes is a module name, file
name or a project name.

XDS has the following modes of operation:

    Mode    |  Meaning
------------+---------------------------------------------------
    COMPILE | Compile all modules given in the command line
    PROJECT | Make all projects given in the command line
    MAKE    | Check dependencies and recompile
    GEN     | Generate makefile for all projects
    BROWSE  | Extract definitions from symbol files
    HELP    | Print help and abort the program
------------+---------------------------------------------------

Both the PROJECT and MAKE modes have two optional submodes of
operation: BATCH and ALL. Two auxiliary operation submodes -
OPTIONS and EQUATIONS can be used to inspect the set of compiler
options and equations and their values.

From the command line, the compiler mode is set using '=',
followed by the required mode. Only the unique portion of a name
need be specified. Operation mode names are not case sensitive,
thus
        =PROJECT   is equivalent to   =p
        =BROWSE    is equivalent to   =Bro

Operation modes and options can be placed everywhere in the
command line. Thus the following two invocation are equal:
    xc =make hello.mod =all -checknil+
    xc -checknil+ =a =make hello.mod

COMPILE mode
------------

    xc [=compile] { FILENAME | OPTION  }

COMPILE is the default mode, and can be invoked simply by
supplying "xc" with a source module(s) to compile. If xc is
invoked without a given mode, COMPILE mode is assumed. In order
to determine which compiler to use, xc looks at the extensions of
given source files. The default mapping of extensions is given
below :
    .mod  - Modula-2 implementation module
    .def  - Modula-2 definition module
    .ob2  - Oberon-2 module

For example:
        xc hello.mod
will invoke Modula-2 compiler, whilst:
        xc hello.ob2
will invoke Oberon-2 compiler.

The user is able to reconfigure the extension mapping. It is
also possible to override this extension mapping from the
command line, using options M2 and O2:
     xc hello.mod +o2  (* invokes O2 compiler *)
     xc hello.ob2 +m2  (* invokes M2 compiler *)

MAKE mode
---------

    xc =make [=batch] [=all] { FILENAME | OPTION }

In the MAKE mode the compiler calculates module dependencies
(using IMPORT clauses) and then recompiles all modules that
necessary.

Starting from the files in the command line it tries to find an
Oberon module or a definition and implementation module for each
imported module. It then tries to do the same for each of the
imported modules until all modules are located. Note that search
is made for source files only, if a source file is not found, the
imported modules will not be appended to the project. Usually,
only a Modula-2 program module or Oberon-2 top-level module
should be given in the command line.

When all modules are gathered, XDS looks to an operation submode.
If the BATCH submode is specified, the XDS creates a batch file
of all necessary compilations, rather than actually calling the
compilers and compiling the source code.

If  the ALL submode is specified, all gathered files are
recompiled, otherwise XDS calculates conditions for recompilation
and recompiles only those files that necessary.

PROJECT mode
------------

   xc =project [=batch] [=all] { PROJECTFILE | OPTION }

PROJECT mode is essentially the same as MAKE mode except that the
modules to be `made' are provided in a project file. A project
file consists of options settings and a list of modules:

     { OPTION }
     { !module { FILENAME } }

where OPTIONs are the compiler options that all modules should be
compiled  with,  and  FILENAMEs  are  modules in the project. XDS
recursively  looks  at  all  the  given  files  for  any imported
modules.  Thus,  usually,  a  project  file  would consist of one
single  module, the main program module. As in MAKE mode, ALL and
BATCH submodes can be used.

GEN mode
--------

    xc =gen { PROJECTFILE | OPTION }

The GEN operation mode allows you to generate a file, containing
information about your project. The most important usage is to
generate a makefile or task file for linker. This DEMO
documentation does not contain the description of template files.

The DEMO package contains the "xds.tem" template file (See on
C:\XDS\BIN) which can be used to create task file for link386.

XDS also process a template if the option MAKEFILE is set
on, when invoking the xc utility in the PROJECT mode.

BROWSE mode
-----------

    xc =browse { MODULENAME | OPTION }

The BROWSE operation mode allows you to generate a pseudo
definition module for an Oberon-2 module. In this mode "xc" scans
the corresponding symbol file and outputs definitions of all
client-visible symbols in a Modula-2-like definition module in
Oberon-2  syntax.  This  pseudo definition module will not
necessarily contain legal Modula-2 or Oberon-2 and thus any
output should not be treated as such.

The MAKEDEF option provides an alternative method of producing
pseudo definition modules, preserving so-called exported
comments if necessary. If the option is set the compiler will
create a definition for the each Oberon module compiled.

ALL submode
----------

In both PROJECT and MAKE modes, XDS checks the time stamps of the
files concerned and only recompiles when necessary. If ALL submode
is set, the time stamps are ignored, and all files are compiled.

BATCH submode
-------------

The BATCH submode, creates a batch file of all necessary
compilations when specified from either PROJECT or MAKE modes,
rather than actually calling the compilers and compiling the source
code.

OPTIONS submode
---------------

The OPTIONS submode allows you to inspect the values of options set
in the configuration file, project file and on the command line. It
can be used along with COMPILE, MAKE and PROJECT modes.

The following invocation will print (to the standard output) the
list of all defined options, including all pre-declared options,
all options declared in the configuration file, in the project file
"my.prj" and on the command line (XYZ option):
         xc =options  -prj=my.prj -xyz:+

In the PROJECT mode options are listed for each project file
given on the command line.

EQUATIONS submode
-----------------

The EQUATIONS submode allows you to inspect the values of
options set in the configuration file, project file and on the
command line. It can be used along with COMPILE, MAKE and
PROJECT modes.


                   Using the Modula-2 Compiler
                   ---------------------------

Create a file called "hello.mod", containing the following text:

        MODULE hello;
        IMPORT InOut;
        BEGIN
          InOut.WriteString("Hello World");
          InOut.WriteLn;
        END hello.

Now type:
        xc hello.mod

It will generate hello.obj.


                   Using the Oberon-2 Compiler
                   ---------------------------

The Modula-2 source code just  shown  is  also  perfectly  valid
Oberon-2. Rename the source file to "hello.ob2".

As in Modula-2, this  source  code  in  Oberon-2  constitutes  a
top-level module or program module. Unlike Modula-2, there is no
syntactic distinction between a top-level module and  any  other
service module. The Oberon-2 compiler must be specifically  told
that this is a program module by using option "MAIN".

Type:
        xc hello.ob2 +MAIN +DEF

During the compilation, the Oberon-2 compiler produces files
"hello.obj" and "hello.sym".

                       Running a Program
                       -----------------

After compilation of all modules composing your project you have to
link the program.
        link386 hello.obj, ,\xds\lib\libxds.lib+\xds\lib\os2min;

After that, one can invoke the program:
        hello

It may be necessary to specify additional options to put debug
information into hello.exe file, or to specify stack size.
Check "link386" documentation to get help.

To simplify linking, XDS allows to specify a linker command line in
the XDS environment, using the LINK equation.  A command line,
specified by the equation will be executed after successful
compilation of the whole project. Usually, the equation is
specified in the project file.

Example of project file hello.prj:

-link="link386 hello.obj, ,\\xds\\lib\\libxds.lib;"
!module hello.mod

The project file contains the LINK equation and a name of
program module.

The following invokation
        xc hello.prj =project
will compile modules constituting the project (if required) and
then execute the linker command line specified.

If your project contains more than one module, it'd be better
to use universal scheme. The XDS distibution contains the template
file "xds.tem" (C:\XDS\BIN\xds.tem). To use it, write a project
file hello.prj:

-template = xds.tem
-mkfname = tmp
-mkfext  = lnk
-makefile+
-link = "link386 @%s",mkfname
!module hello.ob2

Then call
        xc hello =p
After the successful compilation xc will call linker.

See also SAMPLES.TXT for more information.

                Configuring XDS for a C Compiler
                --------------------------------

XDS allows to use C functions and libraries in your projects.
Different C compilers have different naming and calling
conventions.  Your have to specify your C compiler in XDS
environment, using the CC equation.  The equation forces XDS to
call all C functions in a way compatible with the specified C
compiler. Also the compiler sets default values of additional
configuration options according to the value of the equation.

Currently, XDS supports Watcom compiler and SysCall calling
conventions. The corresponding values of the CC equations are
WATCOM and OS2SYSCALL (written in any case). To configure XDS
append the line

-cc=Watcom

or

-cc=OS2SYS_CALL

in your configuration file.

                     Options and Equations
                     ---------------------

A  rich  set  of XDS options and equations allows one to control
source   language,   code  generated  and  internal  limits  and
settings.  Note:  All options in the command line are applied to
all operands.

Precedence of Compiler Options
------------------------------

The "xc" utility can receive its options from
     - configuration file "xc.cfg"
     - command line
     - project file (if present)
     - inline in source text (not all options may be used there)

At  any  point  during  operation,  the  most recent option value
setting will be in effect. Thus, if the compiler equation OBERON
was  set to ".ob2" in the configuration file, but then set on the
command line as "OBERON=.o", then XDS will recognize ".o" as the
Oberon-2 module extension.

Compiler Options
----------------

The following is the subset of compiler options (default values are
pointed out as [ON] or [OFF]:

CHECKDINDEX [ON]
        Dynamic array bounds check

CHECKINDEX [ON]
        Static array bounds check

CHECKNIL [ON]
        NIL pointer dereference check

CHECKPROC [ON]
        NIL formal procedure call check

CHECKRANGE [ON]
        Range checks for ranges and enumerations

CHECKSET [ON]
        Range check in set operations

CHECKTYPE [ON]  (Oberon-2 only)
        Dynamic type guards generation

DEF [OFF]
        Permission to change symbol file.

        XDS  creates  a  temporary  symbol  file  every  time  an
        Oberon-2 module is compiled and compares this symbol file
        with  the  existing one, overriding the file with the new
        one  if  necessary.  If  option DEF is OFF (default), the
        compiler  will  give an error if the symbol file (and the
        module  interface respectively) had been changed and will
        not replace the old symbol file.

M2ADDTYPES [OFF] (Modula-2 only)
        Add SHORT and LONG types.

        When  ON,  the  compiler  will  recognize  as  pervasive
        identifiers the types SHORTINT, LONGINT,  SHORTCARD  and
        LONGCARD.

M2BASE16 [OFF]  (Modula-2 only)

        When  ON,  basic types (INTEGER, CARDINAL and BITSET) are
        16-bits wide in Modula-2.

M2EXTENSIONS [OFF] (Modula-2 only)
        XDS Modula-2 extensions.

        When ON, the compiler  will  allow  the  use  of  XDS
        Modula-2 language extensions.

MAIN [OFF]      (Oberon-2 only)
        Oberon-2 main module.

        When ON, the compiler  will  generate  a  program  entry
        point ("main"  function)  for  this  Oberon-2  module.
        Inline usage recommended, ie:

                <*+ MAIN *>
                MODULE Example;
                  ...
                END Example.

O2EXTENSIONS [OFF] (Oberon-2 only)
        XDS Oberon-2 extensions.

        When ON, the compiler  will  allow  the  use  of  XDS
        Oberon-2 language extensions.

O2ISOPRAGMA [OFF] (Oberon-2 only)

        When  ON, the compiler will allow the use of ISO M2 style
        pragmas <* *>.

        The  option  is  set  ON  in  "C:\XDS\BIN\xc.cfg".  It is
        required  to compile Oberon samples, containing ISO style
        pragmas, such as <*+ MAIN *>.

O2NUMEXT [OFF]  (Oberon-2 only)

        Enables Oberon-2 numeric extensions (complex types
        and in-line exponentiation operator "**").

WOFF[number] [OFF]
        WOFF without parameter turn all warnings OFF.

        When WOFF<number> (i.e. WOFF301)  is  ON,  the  compiler
        will not report warning <number> (i.e. 301).

        See "xc.msg" file for warning texts and numbers.


                            Libraries
                            ---------

The pre-release package contains libraries from the following library
sets:
        - Interface to ANSI C libraries
        - PIM compliant libraries
        - ISO standard Modula-2 libraries
        - Interface to Oberon run-time support

All  these  libraries  can  be used in both Modula-2 and Oberon-2
programs. We recommend to use ISO libraries to improve portability
of your software.

This documentation does not contain the description of libraries,
use corresponding definition modules instead (C:\XDS\DEF).

Interface to ANSI C libraries
-----------------------------

The following libraries provides an interface to ANSI C libraries:

    stdlib       interface to <stdlib.h>
    stdio        interface to <stdio.h>
    math         interface to <math.h>
    time         interface to <time.h>

PIM compliant libraries
-----------------------

The   following   libraries   defined  in  PIM  ("Programming  in
Modula-2") are provided:

    InOut        general purpose IO operations
    MathLib0     mathematical functions
    RealInOut    REAL numbers IO operations
    LongInOut    LONGREAL numbers IO operations
    Terminal     computer's terminal IO operations

Since   PIM   "Storage" library   is   not  compatible  with  the
corresponding ISO library, it is omitted.

ISO standard Modula-2 libraries
-------------------------------

The following ISO libraries are included in the package:

    ProgramArgs   Access to program arguments
    StreamFile    Sequentional data streams
    IOConsts      Types and constants for IO modules
    TextIO        Character and strings type IO operations
    STextIO       TextIO over default channels
    WholeIO       Whole numbers IO operations
    SWholeIO      WholeIO over default channels
    RealIO        Real number IO operations
    SRealIO       RealIO over default channels
    IOResult      Read results for specified channels
    SResultIO     Read results for the default input channel
    ConvTypes     Common types used in the string conversion
                  modules
    RealStr       REAL/string conversions
    WholeStr      Whole-number/string conversions
    CharClass     provides predicates to test a given value
                  of the character type
    RealMath      Mathematical functions for the type REAL
    LongMath      Mathematical functions for the type LONGREAL
    Storage       Facilities for dynamically allocating
                  and deallocating storage
    Strings       Facilities for manipulating strings
    SysClock      Facilities for accessing a system clock

The following system libraries are available in the package:

    TERMINATION   Facilities for enquiries concerning the
                  occurrence of termination events.
    EXCEPTIONS    Facilities for raising user exceptions
                  and for making enquiries concerning
                  the current execution state.
    M2EXCEPTION   Facilities for identifying language exceptions.

Note:  all  these  system  libraries  are  not  embedded  in  the
compiler,  ie.  the corresponding symbol files shall be available
to  use  them. The system module "COROUTINES" is not available in
the DEMO version.

Interface to Oberon run-time support
------------------------------------

The  "oberonRTS" library provides an interface to Oberon-2 run-time
support functions, including garbage collection and meta-language
facilities. See also SAMPLES.TXT.

                         Further Reading
                         ---------------

[1]     H. Mossenbock, N. Wirth
        The Programming Language Oberon-2
        Structured Programming, 1991, 12, 179-195

[2]     N. Wirth
        Programming in Modula-2 (4th edition)
        Springer-Verlag, 1988. ISBN 0-387-50150-9

[3]     N. Wirth
        From Modula-2 to Oberon
        Software, Practice and Experience 18:7 (1988), 661-670

[4]     M. Reiser, N. Wirth
        Programming in Oberon-2 - Steps Beyond Pascal and Modula
        ACM Press, Addison Wessley, 1992. ISBN 0-201-56543-9

[5]     H. Mossenbock
        Object-Oriented Programming in Oberon-2
        Springer-Verlag, 1993.
        ISBN 0-387-56411-X, 0-387-56411-X

Internet newsgroups comp.lang.modula2 and  comp.lang.oberon  are
useful  not  only  for  beginners  but  for experienced Modula-2
programmers as well.


                        [end of document]
