
        INTRO.TXT copyright (c) 1991-1993 xTech, RTA              page 1
        ----------------------------------------------------------------

                                Welcome to Extacy

        Extacy is a professional development system available  for  most
        popular platforms, including PC/MS-DOS, Unix workstations  (Sun,
        HP,  DEC,  MIPS,  etc),  Macintosh,  Amiga,  etc.   Both   large
        industrial projects containing millions  of  lines,  and  simple
        student projects had been developed using Extacy.

        Extacy contains both  Modula-2  and  Oberon-2  compilers.  These
        languages are often called "safe" and "modular".  The  principle
        innovation of  the  language  Modula-2  was  indeed  the  module
        concept,   incorporating   information   hiding   and   separate
        compilation.

        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.

        Extacy provides  an  outstanding  opportunity  to  design  truly
        portable software in comprehensible and safe  languages.  It  is
        currently  used  in  both  academic   institutions   and   large
        commercial companies. Extacy has been  ported  to  most  popular
        platforms, and the code it generates is as portable  as  Extacy,
        which is written in Extacy Modula-2 itself.

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

        Extacy  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,  and  are
        provided in source form.

        Current price for MS DOS version of EXTACY is GBP  #150  or  USD
        $230. See "EXTACY.TXT", or contact Real Time Associates Ltd  for
        other prices and details.

        Over the past 10 years Real Time Associates has  specialised  in
        the emerging 'safe typed' modular languages, such  as  Modula-2,
        Modula-3, and now Oberon-2. RTA was the first company to  launch
        a commercially supported Modula-2 compiler  back  in  1983,  and
        co-founders of the BSI/ISO Modula-2  standardisation  effort  in
        1985.  Similarly,  RTA  was  the  first  company  to  launch   a
        commercial Oberon-2 compiler package in June last year.  Through
        developing its own products and  culling  the  best  from  other
        authors throughout the world, Real Time Associates now have  the
        largest catalogue of supported products in this arena  available
        today. By coupling this with good  hotline  support,  Real  Time
        Associates created an International reputation as the people  to
        come to and now do business with some 43 countries of the world.

        ----------------------------------------------------------------
        INTRO.TXT copyright (c) 1991-1993 xTech, RTA              page 1

        INTRO.TXT copyright (c) 1991-1993 xTech, RTA              page 2
        ----------------------------------------------------------------

                                 Unique Features
                                 ---------------
        Extacy generates readable, maintainable, highly portable ANSI  C
        code. Because all C compilers have their own limitations, Extacy
        uses only really portable subset of  ANSI  C.  However  compiler
        options allow to generate code for K&R and C++ compilers.

        Extacy DOES NOT implement the Oberon  system  (as  per  the  ETH
        system). The generated C code can be compiled and  linked  using
        any ANSI C compiler to produce standalone executables.

        Extacy has been ported to dozens of platforms (and the  list  is
        continually  growing),  and  you  can   painlessly   move   your
        application under any of these platforms just  recompiling  your
        program by Extacy  on  a  target  platform,  or  moving  C  code
        generated by Extacy from one platform to  another  (beware  that
        Extacy  can  produce  slightly  different  code   for   Personal
        Computer, Personal Unix, and Workstation platforms).

        Multi-language programming with Extacy is not a problem:  Extacy
        projects can consist of an arbitrary mix of Modula-2,  Oberon-2,
        C, and Assembler, and, with some care, C++, Pascal, and Fortran.

        The C source code generated by  Extacy  is  perfectly  readable.
        Extacy will preserve the original identifiers and, moreover,  it
        can preserve even your comments.

        Extacy can insert "#line" statements into the generated C  code.
        It allows the use of the standard debuggers (like  Unix  dbx  or
        gdb, Microsoft  Code  View,  Borland  Turbo  Debugger,  Symantec
        Multiscope, etc) to trace your Modula-2/Oberon-2 (not  generated
        C code) sources to catch a bug.

        Extacy provides outstanding flexibility. Using compiler options,
        you  can  change  any  defaults  of  the  compiler  and  utility
        programs:  default  file  names/extensions,  style  of  C   code
        generation (K&R C, ANSI C, or C++),  error  message  format  (to
        allow your favourite  editor  the  use  of  compiler  messages),
        copyright notice to insert into generated code,

        Extacy language extensions  provides  a  unique  opportunity  to
        write truly portable, multi-language,  reliable  software  using
        modern   modular,   type-safe,    object-oriented    programming
        languages.

        Despite a long list of the language(s)  extensions,  in  default
        mode Extacy will allow  the  use  of  the  standard  language(s)
        facilities only. To utilize these extensions, the  explicit  use
        of   compiler   options   ":M2EXTENSION",   ":M2ADDTYPES",   and
        ":O2EXTENSIONS", placed either in configuration file, at command
        line, or inline, is strictly required, otherwise it  will  cause
        an error while compilation.




        ----------------------------------------------------------------
        INTRO.TXT copyright (c) 1991-1993 xTech, RTA              page 2

        INTRO.TXT copyright (c) 1991-1993 xTech, RTA              page 3
        ----------------------------------------------------------------

                      List of Modula-2/Oberon-2 Extensions
                      ------------------------------------

        - multi-language programming
        - conditional compilation
        - procedures with variable number of parameters
        - renaming of imported modules
        - read-only parameters
        - read-only export
        - fixed size types
        - inline options/pragmas
        - line comments
        - multi-dimensional open arrays
        - dynamic arrays
        - constant array constructors
        - constant string concatenation
        - set complement
        - standard procedure ASSERT
        - extended syntax for numeric constants
        - extended syntax for standard procedure HALT
        - extended type compatibility in expressions
        - extended type compatibility in assignments


                             About the DEMO Version
                             ----------------------

        This versions is a restricted  distribution  of  Extacy  package,
        including:

                - Modula-2 and Oberon-2 to C Compilers
                - A subset of the PIM Compliant Library
                - A subset of the ANSI C Library Interfaces
                - Hotline Support

        It does not include:

                - A subset of the ISO Modula-2 library
                - Utility library set
                - ANSI C Library Interfaces
                - Oberon-2 Object Browser Utility
                - Automatic "Makefile" Generator
                - And the Manual

        The demonstration version compiler can only translate relatively
        small modules (about 400 lines). You will get an  error  message
        "out of heap space" or "unexpected end of file" when this  limit
        is exceeded.








        ----------------------------------------------------------------
        INTRO.TXT copyright (c) 1991-1993 xTech, RTA              page 3

        INTRO.TXT copyright (c) 1991-1993 xTech, RTA              page 4
        ----------------------------------------------------------------

                           How to Install the DEMO Version
                           -------------------------------

        1) Create a directory C:\EXTACY
        2) Copy archive file to C:\EXTACY
        3) Extract archive file contents typing at MS DOS prompt
                pkunzip xc1305.zip
        4) Type at MS DOS prompt
                copy *.txt prn
        4) Type at MS DOS prompt
                xc =p xclib
           to compile supplied libraries

        Installation completed.


                             Using Extacy Compilers
                             ----------------------

        The Extacy 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
                x2c.msg   Contains texts of error messages
                X2C.h     C header file of a run-time support
                X2C.c     C code  of  a  run-time support
                x2c.red   Search path redirection file (optional)
                x2c.cfg   Configuration file (optional)

        The files "X2C.h" and "X2C.c" are C source files of the run-time
        support library. They contain a set of  typedefs  and  functions
        necessary for compilation and execution of translated code.


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

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

                pattern = directory_path {";" directory_path}

        Example of redirection file:

                *.def = def;
                *.sym = sym; c:\extacy\sym;
                x2c.* = .; c:\extacy\bin

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

        The file "x2c.red" is sought by standard OS paths.  Other  files
        are sought by paths defined  by  "x2c.red"  or  in  the  current
        directory if "x2c.red" is not found.
        ----------------------------------------------------------------
        INTRO.TXT copyright (c) 1991-1993 xTech, RTA              page 4

        INTRO.TXT copyright (c) 1991-1993 xTech, RTA              page 5
        ----------------------------------------------------------------

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

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

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

        To set a boolean compiler option to ON, use ":OPTION" directive.

        To  set  an  equation  compiler  option,  use  "#OPTION[=]VALUE"
        directive. It possible to omit "=" sign in configuration file.

        To set the compiler pragmas ON or OFF, use +LETTERS or  -LETTERS
        directive respectively.

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

        Example:

                % this is a comment
                % equation option - set Oberon-2 module extension
                # Oberon  .ob2
                % boolean option - allow Modula-2 extensions
                : M2extensions
                % pragmas ON
                +AGT
                % pragmas OFF
                - r n y
                % end of configuration file


                           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

        You will find a file called "hello.c" which contains the ANSI  C
        code of the program "hello.mod".


        ----------------------------------------------------------------
        INTRO.TXT copyright (c) 1991-1993 xTech, RTA              page 5

        INTRO.TXT copyright (c) 1991-1993 xTech, RTA              page 6
        ----------------------------------------------------------------

                           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

        It must be noted  that  during  the  translation,  the  Oberon-2
        compiler produces files "hello.c", "hello.h" and "hello.sym". As
        "hello.c" was  already  produced  in  the  previous  translation
        through Modula-2, the old version  will  be  found  through  the
        redirection file and overwritten by the new.


                               Building a Program
                               ------------------

        After translation you can invoke your C compiler, eg.

                copy C:\EXTACY\LIBC\*.* .
                cc hello.c InOut.c X2C.c

        to compile produced C code files.

        Please notice that most C compilers require all C  code  ("*.c")
        and header ("*.h")  files  be  placed  in  the  same  directory,
        therefore it is necessary to copy library code and header  files
        to your working directory.

        So, above line tells C compiler to compile "hello.c" (created by
        Extacy from  "hello"  module),  "InOut.c"  (compiled  by  Extacy
        library module,  imported  from  "hello"  module),  and  "X2C.c"
        (Extacy Modula-2/Oberon-2 runtime library).

        Extacy always includes file "X2C.h" into any  generated  source.
        This file contains basic types (such  as  INTEGER)  definitions,
        and Extacy runtime library functions/data types declarations.

        All  runtime   library   functions   (runtime   checks,   memory
        allocation, etc) are in "X2C.c" which should  be  combined  with
        any project created using Extacy.







        ----------------------------------------------------------------
        INTRO.TXT copyright (c) 1991-1993 xTech, RTA              page 6

        INTRO.TXT copyright (c) 1991-1993 xTech, RTA              page 7
        ----------------------------------------------------------------

                       Files Generated During Translation
                       ----------------------------------

        When  applied  to  a  file  which  contains  module  "abc",  the
        translators produce the following files.

        Modula-2 Compiler

                When  applied  to  a  definition  module,  the  Modula-2
                compiler produces a C header file "abc.h" and  a  symbol
                file "abc.sym". The  symbol  file  contains  information
                necessary for  the  translation  of  any  modules  which
                import module "abc".

                When applied to an implementation module  or  top  level
                module,  Modula-2  compiler  produces  a  C  code   body
                "abc.c".

        Oberon-2 Compiler

                For all translated modules, Oberon-2 compiler produces a
                C code body "abc.c", a symbol file  "abc.sym"  and  a  C
                header file "abc.h".

                The symbol file "abc.sym" contains information necessary
                for the translation of any modules which  import  module
                "abc". If, during translation,  the  compiler  needs  to
                overwrite an existing symbol file, it will only do so if
                the option "DEF" has been set.

        Example:

                xc :NOHEADER stdio.def      produces      stdio.sym
                xc Example.def              produces      Example.h
                                                          Example.sym
                xc Example.mod              produces      Example.c
                xc Windows.ob2 :DEF         produces      Windows.h
                                                          Windows.c
                                                          Windows.sym

















        ----------------------------------------------------------------
        INTRO.TXT copyright (c) 1991-1993 xTech, RTA              page 7

        INTRO.TXT copyright (c) 1991-1993 xTech, RTA              page 8
        ----------------------------------------------------------------

                               Options and Pragmas
                               -------------------

        This section describes some of the  more  important  options  and
        pragmas.


                                Compiler pragmas
                                ----------------

        Pragmas control run-time checks. Pragmas' values may be  set  by
        the configuration file "x2c.cfg" on the command line or  in  the
        source text The pragmas and their default values are  listed  in
        the table.

        PRAGMA   DEFAULT   MEANING

          A      ON        ASSERT generation
          D      ON        Dynamic array bounds check
          G      ON        Dynamic type guards generation
          N      OFF       NIL pointer dereference check
          P      OFF       NIL formal procedure call check
          R      OFF       Additional range checks for
                             ranges and enumerations
          T      ON        Static array bounds check
          Y      ON        Range check in set operations


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

        Boolean options control the overall method  of  the  compilation
        process. Options may be set in the configuration  file,  on  the
        command line or in the source text. To set corresponding  option
        value ON use :OPTION compiler directive:

                xc :def :verbose =p =a mypro.prj

        The following is the subset of compiler options:

        DEF
                Permission to change symbol file.

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

        FATFS
                Truncate names to MS-DOS 8.3 convention.
                When ON, Extacy  will  truncate  long  file  names  like
                WholeConv.mod to fit MS-DOS 8+3  convention  (8  symbols
                for file name, 3 symbols for file extension).
        ----------------------------------------------------------------
        INTRO.TXT copyright (c) 1991-1993 xTech, RTA              page 8

        INTRO.TXT copyright (c) 1991-1993 xTech, RTA              page 9
        ----------------------------------------------------------------

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

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

        M2EXTENSIONS    (Modula-2 only)
                Extacy Modula-2 extensions.

                When ON, the compiler  will  allow  the  use  of  Extacy
                Modula-2 language extensions such as line comment  "--",
                read-only parameters, and so on.

        MAIN            (Oberon-2 only)
                Oberon-2 main module.

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

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

        O2EXTENSIONS    (Oberon-2 only)
                Extacy Oberon-2 extensions.

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

        O2ISOPRAGMA     (Oberon-2 only)
                When ON, the compiler will allow the use of ISO M2 style
                pragmas <* *>.

        PROGRESS
                When  ON,  the  compiler  will   print   module   names,
                compilation pragmas, line numbers, and other information
                during compilation.

        VERBOSE
                When ON, the compiler will print module names and  final
                statistics.

        WOFF[number]
                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 "x2c.msg" file for warning texts and numbers.




        ----------------------------------------------------------------
        INTRO.TXT copyright (c) 1991-1993 xTech, RTA              page 9

        INTRO.TXT copyright (c) 1991-1993 xTech, RTA             page 10
        ----------------------------------------------------------------

                                 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

        These books are available from:

                Computer Manuals Ltd, 50 James Road
                Tyseley, Birmingham, England, B11 2BA.
                Tel: (+44) (0)21 706 6000
                Fax: (+44) (0)21 706 3301

        Information  is  available  on  Internet  and  from   the   RTA
        CompuServe forum ("PCVENH").

        You can find Modula-2 ISO standard  (1991,  latest  is  December
        1992) on ftp.mathematik.uni-ulm.de in /pub/soft/modula/standard.

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


                                [end of document]













        ----------------------------------------------------------------
        INTRO.TXT copyright (c) 1991-1993 xTech, RTA             page 10
