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

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

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

2.1. Files:

mocka9304main.tar.gz	Compiler, documentation, and lib-library
mocka9304src.tar.gz	sourcecode for the compiler
beg1.72.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.


2.2. Installation:

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

>  cd /usr

Then unpack the archive mockamain9304.tar.gz . 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 mockamain9304.tar.gz .

> 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 makes a script mc, which calls the compiler with your prefered
options, especially the directories where MOCKA found the library etc.
Also it will compile the library and install the manual page.


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

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 of index checks
- debugging option

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

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

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

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

Or use 'make':

> cd mocka
> make Mc

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

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

Please report bugs to modula@ira.uka.de . Thank you

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

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

The GMD Karlsruhe would like to know the number of MOCKA users for
Linux. Please send a short mail with 'subject: LINUX-MOCKA-USER' to 
modula@ira.uka.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$ 300).
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. 
