Copyright (C) 1992, Digital Equipment Corporation
All rights reserved.
See the file COPYRIGHT for a full description.


Welcome to Modula-3D!				Created:  22 January 1993
=====================			   Last updated:  1 February 1993

Modula-3D is Modula-3 extended to support programming distributed machines.


Essentials
----------

To use Modula-3D on the Mosaics, make sure the following directories are
on your path:

	/ufs/jan/rustan/m3/bin
	/usr/local/mosaic

Then, to compile a program, use M3.  For example, to compile a program
prog.m3, do:

	M3 prog.m3

(Among other files,) this produces a file called a.out.  To run this
program, login on 'mosaic' (other machines may be supported on request),
and use the monitor program m3mon, as follows:

	m3mon a.out


Sample program
--------------

Here follows a sample Hello World program:

	MODULE hello EXPORTS Main;
	IMPORT IO;
	BEGIN
	  IO.PutText( "Hello, world\n" )
	END hello.

Here's a program that prints a message from each of the processors:

	MODULE procids EXPORTS Main;
	IMPORT Processor, IO;
	TYPE
	  T = NETWORK OBJECT METHODS print() := Print END;
	PROCEDURE Print( <* UNUSED *> t: T ) =
	  BEGIN
	    IO.PutInt( Processor.ID());  IO.PutChar( '\n' )
	  END Print;
	BEGIN
	  FOR i := Processor.Min() TO Processor.Max() DO
	    NEW( T, i ).print()
	  END
	END procids.

The second parameter to NEW specifies the processor on which to
allocate the object.  These programs and a sieve program can be found
in /ufs/jan/rustan/m3/demo.


Command line options
--------------------

M3 has the same command line options as the DEC SRC Modula-3 compiler, m3.
By including /ufs/jan/modula3/mod-3/modula3/man in your MANPATH, you can
do:

	man m3

to find out more.


Make utility
------------

You can use the standard DEC SRC Modula-3 make utility, m3make, with
Modula-3D by including:

	/ufs/jan/modula3/mod-3/modula3/bin

on your path.  Check out:

	man m3make

for details of m3make.  (See section above for setting your MANPATH
variable.)  To select the Modula-3D compiler, as opposed to the SRC
Modula-3 compiler, add the following lines somewhere in your m3makefile:

	M3 = M3
	M3OPT =

The second line causes the -g switch not to be used, since the C compiler
for the Mosaic does not accept it.


Modula-3 mode for Epoch
-----------------------

There is a Modula-3 mode that can be used in Epoch.  For details, look
in /ufs/jan/modula3/mod-3/modula3/lib/util.


Mosaic Modula-3D standard library
---------------------------------

The standard library used with Modula-3D includes everything that is
required by the Modula-3D language, except that floating point numbers
are not supported.

The Processor interface provides procedures which return processor ID
related information.  For example, Processor.ID() is the ID of the current
processor.  Processor IDs in the inclusive range Processor.Min() to
Processor.Max() constitute the valid processor IDs.

In addition, the standard library contains an IO interface, which
provides support for printing to m3mon's standard output.

The standard library interface files are found in /ufs/jan/rustan/m3/include.


Other implementation specific limitations
-----------------------------------------

Return values from methods of network object types, and arguments of
exceptions raised by such methods may not be of "large" types.  More
precisely, they may not occupy more than one word of storage, and
may not be of type SET OF, ARRAY OF, or RECORD.  In addition, parameters
of network object type methods may not be of open array types.

The result of invoking a method or procedure value that is NIL is
undefined.  This ought to be a checked runtime error, but is not yet
implemented, so be program with care.


Sharing of success stories
--------------------------

Please share your success stories (and others) with me (rustan@vlsi).

Enjoy!
  Rustan
