
		Modula-3 for Energize

Introduction
------------

This is a modified version of the DEC SRC Modula-3 compiler, which adds the
ability to communicate with the Energize Programming System from Lucid,
Inc.  This enables the Energize browsing tools to be used on Modula-3 code.

			IMPORTANT NOTE

	This is experimental software which is being made available
	without charge on an as-is basis.  It is not supported by 
	Lucid, Inc.  There is no warranty of any kind, so use at your
	own risk.


Pre-requisites
--------------

This version is for release 3.3 of the Modula-3 compiler and release 3.0
(or later) of Energize, on a Sun SPARCstation running SunOS release 4.  (It
is possible to use it with Energize release 2, but that doesn't work well
enough to be very useful because release 2 doesn't understand modules.)

If you don't already have the DEC SRC compiler, either use the World Wide
Web to access:
	http://www.research.digital.com/SRC/modula-3/html/home.html
(this is also a good source of general information about the Modula-3
language) or get it by FTP:

	% ftp gatekeeper.dec.com
	Name: anonymous
	Password: <your e-mail address>
	ftp> cd pub/DEC/Modula-3/release-3.3
	ftp> get README

and then follow the directions there.

For information about purchasing Energize, send e-mail to "info@lucid.com"
or call Lucid sales at 1-800-223-9322.


Installation and use
--------------------

Assuming that you have already installed the standard releases of both the
SRC compiler and Energize, the following additional files are provided in
this package, to be added to the installation directory of the Modula-3
compiler:

   m3c-ez   	   An alternate version of "m3c", the compiler front-end.

   m3-ez           This is a script which is used like "m3" (the compiler
		   driver) except that it uses "m3c-ez" instead of "m3c" 
		   and if the optional argument "-Xez" is supplied, the 
		   compiler will connect to Energize.

   m3build-ez	   This script is like "m3build" except that it uses
		   "m3-ez" instead of "m3", passing the "-Xez" argument if
		   supplied, and it uses the Energize incremental linker
		   instead of "ld".  It also uses "energize_make_target"
		   to record a build command for the target program.

Once these are copied into your installation directory, you will need to
edit the pathnames in the two script files to match the location of your
installation. 

Also, you will want to be sure to take advantage of the Emacs mode support
for Modula-3.  Your ".emacs" file should contain something like this:

  (autoload 'modula-3-mode "/usr/local/modula3/lib/elisp/modula3" nil t)
  (setq auto-mode-alist
        (cons '("\\.[im][3g]$" . modula-3-mode) auto-mode-alist))
  (setq completion-ignored-extensions
        (append completion-ignored-extensions
	        '( ".mo" ".mx" ".mc" ".io" ".ix" ; Modula-3 internal files
		)))

The file "modula3.el" is included in the SRC distribution as part of file
"tools.tar.gz".  Alternatively, there is a slightly older version in the
Energize 3.0 directory as "$ENERGIZE_ROOTDIR/etc/unsupported/elisp/nm3.elc".


Thus, where you would normally do a build by:

	m3build

if you instead do:

	m3build-ez -Xez

then the compiler and linker will connect to Energize and report
information to it.


Limitations
-----------

This implementation is far from being complete, but it does provide for
using most of the capabilities of the Energize browsers with Modula-3 code:
Language Element Browser, call graphs, object inheritance graphs, error
messages annotated in the source code, edit definition or declaration,
visit uses of language element, etc.  The major features that are not
supported are "incremental compilation" and "smart compilation".  You do,
however, get incremental linking, which can save a lot of time.  Another
obvious limitation of the current Energize release is that the browsers
tend to display everything using C++ syntax and terminology.

Some additional details of the limitations of the current implementation:

  Since the current version of the SRC compiler only supports building
  programs or libraries, rather than compiling individual files, the
  Energize "Compile File" command doesn't work on Modula-3 files.  Because
  of this, the executable target is given the build option "do not build
  sub-targets".

  When "m3build-ez" is used, a use of `m3_option' in the "m3makefile" gets
  an error.  I just haven't figured out the right way to override the
  options in the "m3build" line (assuming that there is one).

  The compiler tells Energize that it is generating object files named
  "foo.mo", although the default SPARC configuration for this release is to
  use "foo_m.o"

  In many cases the browsers just show a language element's name without
  qualifying it with the module name.

  The browsers don't distinguish between a RECORD and an OBJECT; both are
  called a "class".

  The values of constants are not reported.

  Enumeration element names are not reported. 
 
  Energize doesn't understand set types and subrange types.

  Inherited members of objects are not reported to Energize, so are not
  available in the class grapher.

  The Language Element Browser for a method doesn't show the overriding or
  overridden methods from other objects.

  Exceptions and generic modules are not properly handled.

  The compiler shouldn't be writing error messages to `stdout' when it is
  invoked by Energize.

  Edit Definition doesn't find variables belonging to other modules unless
  the module is explicitly specified.

  Qualified names (i.e. module.member) are not supported by lookup from a
  browser panel.  (They are however understood by Edit Definition, Edit
  Declaration, and "Browse Selected Element".)

  Interface files edited during a build may not be detected as needing to
  be saved.

  The READONLY argument attribute is not shown in the browsers.

  Visit uses of language element sometimes claims to not be able to find a
  textual reference to the name within the procedure; there seems to be
  something wrong with its understanding of the Modula-3 lexical rules.  

  There are a number of bugs relating to proper scoping of names defined in
  unusual ways involving aliasing or "FROM ... IMPORT ..." or 
  "REVEAL ... = ... REF ...";

  There is some confusion if a module has more than one "FROM ... IMPORT ...". 

  Energize sometimes gives an invalid consistency warning for two type
  names that ought to be equivalent.  You may want to start Energize with
  the "-noinconsistencies" option to avoid this.

  After editing a Modula-3 function to remove some code and recompiling,
  the removed reference may still appear in the Language Element Browser.

  When connected to Energize, the compiler may give invalid errors on a
  forward referenced name used by a formal argument.

  The Energize Debugger has some trouble resolving names of Modula-3 source
  files when connected to Energize; it works OK using "gdb" not connected
  to Energize.  [ref 19904]

  Open array types are not reported to Energize.

  The return type of object methods is incorrectly shown as being the
  containing object.

There are probably many other bugs that have not yet been discovered.
The modified compiler has been successfully used in its own development, but
has had negligible testing beyond that.

If you find additional bugs, I would be interested in hearing about them,
but any bug fixing will be strictly on the basis of "if and when I feel
like it".  Once again, this is not a supported product of Lucid, so the
Lucid customer support folks won't be able to help you with this.
If you would like to volunteer to help with fixing or extending the
implementation, that would be most welcome.  The modified compiler sources
are available on request.


	David N. Gray			Internet:  gray@lucid.com
					Phone:	415 329-8400 x5529
	Lucid, Inc.
	707 Laurel Street
	Menlo Park, CA  94025-3414			June 30, 1994
