.\" Copyright (C) 1992, Digital Equipment Corporation
.\" All rights reserved.
.\" See the file COPYRIGHT for a full description.
.\"
.\" File: m3.1
.\" Last modified on Mon Mar  9 11:30:34 PST 1992 by kalsow
.\"      modified on Fri Feb  7 00:38:19 PST 1992 by muller
.nh
.TH M3 1
.SH Name
m3 \- Modula-3 compiler

.SH Syntax
.B m3
[options] [files] [libraries] 

.SH Description

The
.B m3
command invokes the SRC Modula-3 compiler.
It compiles and links Modula-3 compilation units
and objects to produce a program or library.

The order of arguments is generally not significant.
The order of the search path options (
.I -D
and
.I -L
) and
libraries (
.I -l
) are significant.

The derived files produced by
.B m3
(objects, libraries, and programs) are
placed in the directory where
.B m3
is invoked.
We call that directory the
.I derived
directory.

.B m3
parses the command line and invokes the compiler and linker as required.
.B m3
tells the compiler where to seek imported interfaces
and where to find the Modula-3 runtime and standard libraries.
The full path names of the compiler and runtime library are configured into
.BR m3 .
See the sections below on 
.B Finding Interfaces
and
.B Finding Objects And Libraries
for more details.

.SH Output options

.PP
The following options determine the final result:
.TP
.BI \-o  " name"
build the program
.I name.
.TP
.BI \-a " name"
build the library
.I name.
.TP
.B \-c
Stop after producing objects and keep
.IR .o ,
.IR .io
and 
.I .mo
files.
.TP
.B \-C
Stop after producing C code and keep 
.I .ic  
and 
.I .mc
files.
.TP
.B \-S
Stop after producing assembly code and keep 
.IR .s ,
.I .is
and
.I .ms
files.

.PP
At most one output option can be specified.
If none is present,
.BI \-o "  a.out"
is assumed.

.SH Tracing options

.PP
The following options determine how much
.B m3
reports on stdout.
.TP
.B \-silent
print only the error messages.
.TP
.B \-why
explain why each compilation is needed.
.TP
.B \-commands
print the compilation commands as they are started.
.TP
.B \-verbose
print what happens to each file.
.TP
.B \-debug
print everything, including internal debugging information.
.TP
.B \-times
print a breakdown of elapsed time.

.SH First pass options

.PP
The following options are passed to the first pass of the Modula-3
compiler:
.TP
.BR \-A
Do not generate code to check the <*ASSERT...*> pragmas.
.TP
.BI \-D defPath
Changes the search path to locate Modula-3 interfaces and generic sources.
.I defPath
is a list of directory names, separated by ":". If 
this list is empty, the search path is set to empty. Otherwise, the
given directories are prepended to the current search path.
.TP
.B \-v
very verbose: show compilation steps as they are performed
(implies
.B \-verbose
and
.B \-w3
).
.TP
.BI \-w [n]
Print messages from level n and above. The default is
.BR \-w3 .
The levels are:
(0) informational,
(1) "fussy" warnings,
(2) warnings,
and
(3) errors.

.SH Second pass options

.PP
The following options are passed to the second pass (the C compiler):
.TP
.B \-g 
generate debugging symbols.
.TP
.BI \-g x
Passed unchanged to pass 1.
.TP
.B \-O 
optimize.
.TP
.BI \-O x
Passed unchanged to pass 1.
The actual arguments passed to the C compiler for the
.B \-g
and
.B \-O
options are part of the site specific configuration described
below.

.SH Linking options

.PP
The following options are passed to the linker when producing
a program and are used in "make" mode.
.TP
.BI \-L libPath
Changes the search path to locate libraries.
.I libPath
is a list of directory names, separated by ":". If 
this list is empty, the search path is set to empty. Otherwise, the
given directories are prepended to the current search path.
This argument is not passed to the linker since
.B m3
does the name resolution for libraries.
.TP
.BI \-l name
Search for the library named
.I libname.a
along the library search path. If the library is found, the resolved
named is passed to the linker. Otherwise, the library should not
contain Modula-3 objects and this option is passed to the linker. 
.TP
.B \-nostd
omit the standard libraries
from final link step.
The standard libraries are part of the site specific
configuration described below.

.SH Miscellaneous options

.PP
The remaining options are:
.TP
.BI \-F file
Process each non-blank line of
.I file
as if it appeared as an argument on the command line.

.TP
.B \-keep
Keep intermediate files
.RI ( .ic , 
.IR .mc ,
.IR .o ,
.IR .io ,
.IR .mo
and the initialization code file
.IR _m3main.c )
created by the compiler. Normally, these files are deleted.

.TP
.B \-make
compile only those sources that are newer than their
corresponding objects or whose imports have changed
since they were last compiled.  The default mode is for
.B m3
to compile all given sources.
The default invocation by m3make(1) includes -make.

.TP
.BI \-X "n @ arg1[ @ arg2...] @"
Add
.I arg1 arg2 ...
to the arguments to pass 
.I n
of the compiler.  You can replace 
.B @
by any character of your choice.
Pass 0 is the Modula-3 to C compiler,
pass 1 is the C compiler,
pass 2 is the C compiler used as a linker,
pass 3 constructs library archives (ar),
pass 4 builds the table of contents for a library (ranlib)
and pass 5 invokes the linker to build overlays.
For example, normally the compiler generates Modula-3 line information in
the intermediate C program; -X0@-C@ prevents that.  If you want debugging
or optimization, you can pass the proper options to the C compiler,
for example -X1@-O@, -X1@-O2@ or -X1@-g@. 

.TP
.BI \-Y "n @ Program[ @ arg1 @ arg2...] @"
Substitute
.I Program arg1 arg2 ...
for pass
.I n
of the compiler. You can replace 
.B @
by any character of your choice.
The passes are numbered as above.
The default values for each of the passes
is part of the site specific configuration described
below.

.TP
.B \-Z
Compile object files for line-based coverage analysis by
.BR analyze_coverage (1). 
Coverage data will be available only for those modules that have been
compiled with this option.  To produce the coverage data, you must also
link your program with this option. 

.TP
.B \-?
Print the executable used for the various passes as well as the value
of the search paths.


.SH Files

.PP
The
.B m3 
command recognizes files with the following suffixes:

.TP
.B .i3 (.m3)
Modula-3 interface (module) sources.

.TP
.B .ic (.mc)
C files produced by 
.B m3 
from Modula-3 interfaces (modules).

.TP
.B .c
C source files.

.TP
.B .is (.ms)
assembly files produced by
.B m3
from Modula-3 interfaces (modules).

.TP
.B .s
assembly source files.

.TP
.B .io ( .mo )
object files produced by
.B m3
from Modula-3 interfaces (modules).

.TP
.B .o
object files created by other language processors.

.TP
.B .a
libraries archives. A library can contain
object files produced by
.B m3
or other language processors.

.TP
.B .b
"base" programs.  An executable program that
needs an overlay.

.PP
Arguments that name directories are searched recursively.
Any files with recognized suffixes
.RI ( .i3 ,
.IR .m3 ,
.IR .ic ,
.IR .mc ,
.IR .c ,
.IR .is ,
.IR .ms
.IR .s ,
.IR .io ,
.IR .mo
.IR .o ,
.IR .a )
found in those directories are effectively added to the command line.
Any directories containing
.I .i3
files are prepended to the
.I \-D
search path.

When a file is compiled into another form, the resulting file has the
same base name as the input file and its extension reflects the
new form of the file.

.PP
The first pass of the compiler produces two files,
a C file that is compiled by the second pass, and a
.I link info
file that is used by the Modula-3 linker.
Link info files have suffixes .ix, .mx, .ax, and .bx.
They cannot be named on the command line and must
be present along side the corresponding .io, .mo, and .a
files.
If a library (.a file) doesn't have a link info file (.ax),
it is assumed to be library that contains no Modula-3
code.

.PP
The source for a module named 
.I M
is normally in a file named 
.IR M.m3 .
The source for an interface named 
.I I 
must be in a file named
.IR I.i3 .

.PP
The source for a generic module named
.I M
must be in a file named 
.IR M.mg .
The source for a generic interface named 
.I I 
must be in a file named
.IR I.ig .

.SH "Finding Definition Modules"

.PP
The compiler locates the interface 
.I Mumble
as follows: it
looks for a file named
.I Mumble.i3
in the first directory on the search path.  If this file exists, the
compiler expects to find the interface within.  If the file does not
exist in the directory, the next one on the search path is examined,
and so on.  An error is given if the search path is exhausted before
the interface is found.

.PP
The compiler uses the same mechanism and search path to locate
generic interfaces and modules as it does to locate interfaces.

.PP
.B m3
has a built-in default
search path.  
The directories on this path contain the standard SRC Modula-3 interfaces.
The default search path is part of the site specific configuration
described below.

.SH "Finding Objects And Libraries"

.PP
Objects and libraries are linked together by the driver to
produce an executable program.  These modules may be divided into
three classes: (1) objects that are produced by the compiler as
a result of a compilation; (2) objects that are specified on
the compiler command line by the user; (3) libraries.

.PP
The driver needs to know where to get these files to create a
command line for the linker.  It knows where type (1) objects are
(since it created them). Type (2) objects must be fully specified
either as absolute or relative paths.  Libraries can be specified 
either by their full names or using the 
.BR -L / -l
combination.

.PP
.B m3
has a built-in default
search path for libraries.
The directories on this path contain the
standard SRC Modula-3 libraries.
The search path is part of the site specific configuration
described below.

.PP
When linking a program,
.B m3
adds a built-in list of standard libraries (e.g. the C math library).
This list of libraries is part of the site specific configuration
described below.
The
.B -nostd
option stops the automatic addition of these libraries.

.PP
If the 
.B -Z 
option has been specified,
an object that collects and dumps
the coverage tables
is added to the list of files to be linked.
The name of this object is part of the site specific
configuration described below.

.SH "Overlays"

.PP
The compiler and runtime system support (on some machines) a limited
form of dynamic loading.  This feature allows you to compile and link
the usually large, fixed piece of your program, the
.IR iceberg ,
once.  And then, recompile
and link a much smaller piece, the
.IR tip ,
in each cycle of editing and debugging.

To produce an iceberg for a program
.IR foo ,
invoke
.B m3 
with
.B \-o 
.I foo.b 
and a list of the modules and libraries that are to be in the iceberg.
The presence of the
.B .b 
suffix tells the compiler to build an iceberg.
The compiler will generate two additional files,
.I foo.bx
which contains the linker information for the iceberg and
.I foo.by
which contains the global symbol table for the iceberg.

To produce the corresponding tip,
invoke
.B m3
as you would if there was no iceberg,
replacing the modules and libraries included
in the iceberg by the iceberg's name.
The compiler will produce a short shell script
under the name of your program,
.IR foo ,
and the actual bits of the overlay in another file,
.IR foo.ov .


For example, if you would normally build your program
with the following command:
.TP
.na
         m3 -o foo A.m3 B.i3 B.m3 C.i3 C.m3 -lmylib
.fi
.PP
Then, the following builds an iceberg that contains
C and mylib:
.TP
.na
         m3 -o foo.b C.i3 C.m3 -lmylib
.fi
.PP
And finally,
.TP
.na
         m3 -o foo A.m3 B.i3 B.m3 foo.b
.fi
.PP
builds the tip.


.SH "Version Stamps"

.PP
For each interface or module, the compiler generates an object file
and a link info file that contains information for the linker.
The link info file names the versions stamps imported and exported by the
compilation unit.

.PP
A version stamp encodes the type and value of a symbol at the time
it was compiled.  The Modula-3 linker ensures that the version stamps from
separately compiled units are equal before linking a program.

.PP
Consider the following interface:
.TP
.na
       INTERFACE Foo;
       IMPORT Bar;
       CONST A = 4;
       CONST B = Bar.N + 1;
       END Foo.
.fi

.PP
It exports two version stamps: one for the constant Foo.A, with type
INTEGER and value 4, and one for the constant Foo.B, with type INTEGER
and value 1 plus the value of Bar.N at the time of the complation.  It
also imports the version stamp of the constant Bar.N.

.PP
In general, the value of a version stamp is independent of the particular
expression used to specify the symbol.  For example, CONST A=2+2 yields
the same version stamp as CONST A=4 or CONST X=3; A=X+1.

.PP
Version stamps are produced for each exported symbol in an interface
(ie. each type, exception, variable, and procedure).  Modules import
the version stamps of the symbols that they import.

.PP
In
.B \-make
mode, the compiler only recompiles a source module if
its object is missing or if any of its imported version
stamps is no longer exported.

.SH Site specific configuration

The default options and paths used by the compiler are
determined at the time it is installed.  To examine them,
run
.B m3
with the
.B \-config
option.

.SH "Differences And Extensions"

.PP
As is always the case, this compiler does not implement exactly
the language defined in the Modula-3 report.
See the user manual, "SRC Modula-3 Version 2.0" for the complete story
on incompatibilities.

.SH Files
.TS
tab(*);
l l.
file.i3 (.m3)	* Interface (Module) source
file.ig (.mg)	* Generic interface (module) source
file.ic (.mc)   * Intermediate C file for an interface (module)
file.is (.ms)   * Intermediate assembly file for an interface (module)
file.ix (.mx)   * Linker information for interface (module)
file.io (.mo)   * Compiled interface (module)
file.a          * Library archive
file.ax         * Library linker information
file.b		* Iceberg or "base program"
file.bx		* Linker information for iceberg
file.by		* Global symbol table for iceberg
file.ov		* Object code for a tip
_m3main.c       * Main program generated by the Modula-3 linker
_m3lib.c	* Debugging symbols for a library
.TE

.SH "See Also"
.PP
.IR "Systems Programming with Modula-3"
edited by Greg Nelson.  Prentice Hall, Inc.  1991.
.PP
.IR "Modula-3"
by Sam Harbison.  Prentice Hall, Inc.  1992.
.PP
.IR "SRC Modula-3 Version 2.0"
by Bill Kalsow and Eric Muller.
.PP
.BR m3make (1),
.BR cc (1),
.BR ld (1),
.BR analyze_coverage (1),
.BR m3pp (1).

.SH Diagnostics

Generally, errors suppress subsequent compilation phases.
Error messages ending with a question mark are internal errors, and
probably represent compiler bugs.

.SH Bugs And Limitations

The compiler's error recovery is poor; it is often the case that errors
following the first one are bogus or redundant, or cause the compiler to
dump core.

Please send bug reports to
.BR m3-request@src.dec.com .

.SH Author Of Object
Bill Kalsow and Eric Muller

.SH Author Of Documentation
Bill Kalsow and Eric Muller