README-FILE for the GMD Modula-2 Compiler MOCKA
===============================================

CONTENTS:

1. LICENCE
2. INSTALLATION GUIDE
3. EXAMPLE SESSION
4. FEATURES OF MOCKA
5. THE SOURCECODE
6. BUG REPORTS
7. REGISTRATION
8. MOCKA ON OTHER TARGET MACHINES

======================================================================

1. LICENCE
----------

 * Copyright (c) 1993 by GMD Karlruhe, Germany
 * Gesellschaft fuer Mathematik und Datenverarbeitung
 * (German National Research Center for Computer Science)
 * Forschungsstelle fuer Programmstrukturen an Universitaet Karlsruhe
 * All rights reserved.
 * 
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are
 * met: 1. Redistributions of source code must retain the above copyright
 * notice, this list of conditions and the following disclaimer. 2.
 * Redistributions in binary form must reproduce the above copyright notice,
 * this list of conditions and the following disclaimer in the documentation
 * and/or other materials provided with the distribution. 3. All advertising
 * materials mentioning features or use of this software must display the
 * following acknowledgement: This product includes software developed by the
 * GMD Karsruhe and its contributors. 4. Neither the name of the institution
 * nor the names of its contributors may be used to endorse or promote
 * products derived from this software without specific prior written
 * permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND ANY
 * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 * DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE FOR
 * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
 * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 * SUCH DAMAGE.
 *

======================================================================

2. Installation of the GMD Modula-2 Compiler MOCKA for Linux/386BSD
-------------------------------------------------------------------

2.1. Files:

mocka9502main-linuxaout.tar.gz	Compiler, documentation, and lib-library
mocka9605main-linuxelf.tar.gz	Compiler, documentation, and lib-library
mocka9605main-386bsd.tar.gz	Compiler, documentation, and lib-library
mocka9605src.tar.gz		sourcecode for the compiler (Modula-2)
beg1.75-linux.tar.gz		Backend Generator BEG
beg1.75-386bsd.tar.gz		Backend Generator BEG

The compiler sources and the Backend Generator BEG are in extra packages.
You need BEG if you want to change the Backend. The main and the BEG package
include binaries, these are different in Linux and 386BSD.


2.2. Installation:

Change to a directory where you want to install the MOCKA Modula-2
compiler. For example

>  cd /usr

Then unpack the mocka9605main.tar.gz package. This creates a subdirectory 
'mocka' with some subdirectories. After this you have to do more
installations, e.g. compiling the lib library. For this installation you find
a Makefile in the mocka9605main.tar.gz package.

> cd mocka

You can change the directories where to install the mocka script mc, the
manual page, etc. in the Makefile. The default is /usr/bin for the mc script
and /usr/man/man1 for the manualpage. If you don't have write access to these
directories, you must change them in the Makefile before the installation.
You can change the way error messages are printed. In the default mode, the
'vi' editor is called, with merged error messages, where you can step to the
next error with 'v'. If you want error messages only printed, then change
the LISTSCRIPT entry in the Makefile. If you don't like both, then change
the script mocka/sys/list.
Then call

> make install

This will make a script mc, which calls the compiler with your prefered
options, especially the directories where MOCKA will find the library etc.
Also it will compile the library and install the manual page.

Note: You need GNU make for this installation. BSD make does not work.


======================================================================

3. EXAMPLE SESSION
------------------

First call MOCKA with the session mode

> mc

'mc' without any options enters the MOCKA session mode. In this session mode
the recompilations of modules are done automatically. You need no 'make' to
translate Modula-2 programs. You can edit sourcefiles in the session mode with

>> i hello

This will call the 'vi' editor (if you don't like 'vi', change the script
mocka/sys/edit). Write 
	MODULE hello;
	FROM InOut IMPORT WriteString, WriteLn;
	BEGIN
	  WriteNl; (* here is an error *)
	  WriteString ("Hello World"); WriteLn;
	END hello.
and quit the editor. Then compile:

>> p hello
.. Compiling Program Module hello

If errors occured, the mocka/sys/list script is called. If you have the
default 'merge', then 'vi' is called with merged error messages:
	@ LISTING
        MODULE hello;
        FROM InOut IMPORT WriteString, WriteLn;
        BEGIN
          WriteNl; (* here is an error *)
	@ ^
	@ Col 3: 'WriteNl' not declared
          WriteString ("Hello World"); WriteLn;
        END hello.

Correct the error. Then

>> (return)
.. Compiling Program Module hello
.. Linking hello

Test your wonderful Modula-2 Programm:

>> hello
Hello World

>> q

Quit session.


======================================================================

4. FEATURES OF MOCKA
--------------------

4.1. Compiled Language

- N.Wirth, Programming in Modula-2, 3.corrected Edition, 1984
- no FORWARD declaration needed for procedures
- short/long types for REAL,INTEGER,CARDINAL
- Standard Libraries: InOut, MathLib, Storage, etc.
- procedures declared in FOREIGN MODULES may be implemented in other languages
- full acces to operating system using FOREIGN MODULES
- Coroutines (NEWPROCESS, TRANSFER)

4.2. Features of interactive (session) mode
- editor of your choice
- automatic determination of the compilation order
- automatic recomplation, if necessary
- textual error messages are shown together with the source program in
  the editor

4.3. Other Features
- enable/disable of range and index checks
- debugging option

======================================================================

5. THE SOURCECODE
-----------------

It's very easy to compile the sourcecode you got in mocka9605src.tar.gz :

> cd mocka/src
> mc
>> p Mc
>> q

Or use 'make':

> cd mocka
> make Mc

======================================================================

6. BUG REPORTS
--------------

Please report bugs to modula@ipd.info.uni-karlsruhe.de . A bug report must
contain at least the MOCKA Version number and the operating system you use.
Please make a precise report about the bug you found. It is useful, if you
send a small example program with this bug. And make sure that you use the
newest MOCKA version and that the bug is really a compiler bug!
Thank you

======================================================================

7. REGISTRATION
---------------

The GMD Karlsruhe would like to know the number of MOCKA users for
Linux/386BSD. Please send a short mail with Subject: 'LINUX-MOCKA-USER' or
'386BSD-MOCKA-USER' to modula@ipd.info.uni-karlsruhe.de, if you use MOCKA,
so we can count the users.

Universities and others, who heavily use MOCKA and want to support its
development can donate 500 DM (~US$ 330).
The money is used to pay students, who work at MOCKA.
If you are interested, please send an email to us, and you get an 
invoice about 500 DM. 

======================================================================

8. MOCKA ON OTHER TARGET MACHINES
---------------------------------

The MOCKA compiler is now available for

    system       | operating system    |   processor         |
    -------------+---------------------+---------------------+
    SUN 4        | SUN OS              | SPARC               |
    SUN 4        | Solaris2.x/SunOS 5.0| SPARC               |
    DEC Station  | ULTRIX              | R3000, R2000 (MIPS) |
    Silicon      | IRIX                | R3000, R2000 (MIPS) | *
      Graphics   |                     |                     |
    Sony NEWS    | News                | MC 68020 with 68881 | *
    SUN 3        | SUN OS              | MC 68020 with 68881 |
    PCS Cadmus   | UNIX                | MC 68020 with 68881 | *
    NeXT         | Mach/UNIX           | MC 68020 with 68881 | *
    HP 9000/300  | HPUX                | MC 68020 with 68881 | *
    HP 9000/700  | HPUX                | C back end          |
    RS6000       | AIX                 | C back end          | *
    VAX          | UNIX (BSD) / ULTRIX | VAX                 | *
    PC           | Linux               | 80386               | +
    PC           | 386BSD              | 80386               | +
    C-back end   | UNIX                | different           |
    translates   |                     |                     |
    M-2 To C     |                     |                     |

Please note, that we [no longer] have access to the maschines marked
with a * , it is therefor not possible for us to update the version of
Mocka for these architectures.  If you are interested in one of these
compilers and allow us to make use of your maschine we will try to
make a updated version of Mocka for this architecture.

Only the versions marked with a + are free, i.e. no orderform must be
send to us, no lincence fee to be paid.

If you are interested in one of the other MOCKA systems, please sign the
MOCKA orderform and return it to us. The MOCKA orderform you will get on
i44ftp.info.uni-karlsruhe.de:/pub/mocka/orderform. The licence is DM 500
(~US$ 330) for Universities and DM 4000 (~US$ 2600) for commercial use.
Look to this orderform for more information.