.TH M3CHECK 1 "Aug 12 1992"
.UC 4
.SH NAME
m3check \- Modula-3 checkout tool

.SH SYNOPSIS
.B m3check
.so ../../m3tk-toolframe.2.2/src/m3help_a.1
[
.B \-InitialCommands 
.I commands
]
.br
.so ../../m3tk-toolframe.2.2/src/m3dpath_a.1
.br
.so ../../m3tk-fe.2.2/src/m3cfe_a.1
.br
.so ../../m3tk-toolframe.2.2/src/m3astc_a.1
.br
.so ../../m3tk-target.2/src/m3cbe_a.1
.br
.so ../../m3tk-dep.2.1/src/m3dep_a.1
.br
.so ../../m3tk-warn.2.1/src/m3cwarn_a.1
.br
.so ../../m3tk-chartool.2.2/src/m3char_a.1
.br
[
.B \-ARchive 
.I name
]
[ 
.B \-M3MakeFile
.I m3MakefileName
]

.SH DESCRIPTION
\fIm3check\fP is a tool to aid in the development
and maintenance of Modula-3 packages and programs.
It contains several
integrated components, including a compiler (syntax and semantic analysis), 
a scanner that checks the file system for changes to source files, 
a pre-linker, and some simple browsing operations. 
\fIm3check\fP expects to interact via the 
standard input
and output, but it is possible to drive it in batch mode.
.PP
\fIm3check\fP aims to provide fast turnround for syntax and semantic
errors, by eliminating the compiler startup overhead and by
avoiding the repeated compilation of imported interfaces.
The pre-linker can verify that all procedures have been implemented
and that all opaque types have been revealed. With the browser,
one can ask questions like "Who imports Foo", or show
object type hierarchies.
.PP
For simple use, invoke \fIm3check\fP in a directory containing
some Modula-3 source files and type "Scan" to the "m3check>" prompt.
You might want to set the "PrintUnits" flag to be notified
as the units are compiled.
.SH "FINDING FILES"
\fIm3check\fP locates files
through a search path specified as an ordered list of directories.
There is no distinction between those directories
containing sources and those containing objects.
Note that, in general,
\fIm3check\fP deals only with sources.
The search path can be specified in one of
two ways; via an explicit command line option (similar to the 
standard Modula-3 compiler), or in a file named \fIm3path\fP
in the current working directory. In the latter case, the file
should contain a list
of directories, one per line. In \fIm3path\fP files,
the directory names may contain
environment variables in the style of \fImake\fP, e.g. \fB$(M3LIB)\fP.
A line introduced by a `#' character is treated
as a comment. Typically each directory listed in the \fIm3path\fP file
will also contain such a file, and
\fIm3check\fP forms the transitive closure 
(breadth-first) of all such files reachable from the current directory.
One virtue of this is that a package may have private sub-directories
and these need not be listed in a client's \fIm3path\fP file.
.PP
\fIm3check\fP checks the search path and warns about missing directories,
often the result of unset or incorrectly set environment variables.
Subsequent messages about being unable to find interfaces are indicative 
of an incomplete search path.
.PP
Whichever way the search path is specified, the current directory
is always prepended to the specified path, and the (site-specific) directory
containing the standard interfaces is always appended to the specified
path. So, for simple use, no explicit search path is necessary.
.SH "READ-ONLY DIRECTORIES"
Initially, \fIm3check\fP designates all directories on the search path,
other than the current working directory and those specified with the
\fBCompileInDir\fP list, as read-only. After the initial scan of the
file system, a read-only directory is not re-scanned. That is,
the information last gathered is assumed still to be accurate.
This strategy helps to minimise the duration of subsequent scans.
However, it is possible to toggle the read-only
status of a directory via the interactive command \fBChangeDirStatus\fP
(see below). So, for example, if a library directory is updated
during the execution of \fIm3check\fP, you can change its status
to writable, scan for the updated files, and then set the status
back to read-only.
Note that the current working directory cannot be made read-only.
.SH "ERROR REPORTING"
Compilation errors and warnings are reported with the name of the file
containing the source code and the line and character position of the
error. Only syntax errors are reported for generic definitions,
as semantic checking is restricted to the instantiated generic.
There are two kinds of errors associated with generic instantiations.
First an error in the source defining the generic instantiation, e.g.
a mismatch between the number of formal and actual parameters.
Second an error in the actual instantation, either because the
generic definition was intrinsically erroneous, or because of an
error introduced by a particular actual parameter. The two kinds
of error are distinguished by appending the characters " (I)" to
the filename to indicate the instantiated generic. One way to
"see" the actual instantiation that the compiler checks is to
use the \fIm3seegen\fP tool.
.SH OPTIONS
The behaviour of the component tools of \fIm3check\fP is controlled
by options, boolean flags and string values, which are associated
with keywords. These options can be set initially on the command line
and many of them can be set explicitly during an interactive session. 
Capitalisation indicates the alternate short form of an option keyword.
Options are grouped by the component sub-tools of \fIm3check\fP.
.so ../../m3tk-toolframe.2.2/src/m3help.1
.so ../../m3tk-fe.2.2/src/m3cfe.1
.so ../../m3tk-toolframe.2.2/src/m3dpath.1
.so ../../m3tk-toolframe.2.2/src/m3astc.1
.so ../../m3tk-warn.2.1/src/m3cwarn.1
.so ../../m3tk-dep.2.1/src/m3dep.1
.so ../../m3tk-chartool.2.2/src/m3char.1
.SH "INTERACTIVE MODE"
By default, \fIm3check\fP assumes interactive mode, although it
can be driven in batch mode via the \fBInitialCommands\fP command
line argument. On startup it outputs the "m3check>" prompt to the
standard output and then waits for one of the following commands.
Most of the control flags that can be set on the command line can
also be set interactively, and the usual first command is "Scan",
which scans the directories defined by the search path and compiles
a subset of the Modula-3 files that it finds, based on the setting
of other options.
After the scan and compilations complete, any
of the following commands can be given.
As with the command line options,
capitalisation indicates an acceptable short form. The commands are
separated into individual tools as for the command line options.
Commands are terminated either by a newline or a semi-colon but
will not be actioned until a newline is entered.
.SH "MASTER TOOL COMMANDS"
.TP
.B ArgValues
Show the current values of the tool arguments.
.TP
.B Help, ?
Output help information on the available commands.
.TP
.B Last
Repeat the last command.
.TP
.B StartLog name
After this command start logging commands to the file \fIname\fP.
.TP 
.B EndLog
Stop logging commands and close the log file.
.TP
.B Quit
Quit the program.
.TP
.B @ file
Execute commands stored in \fIfile\fP.
.SH "SEARCH PATH TOOL"
.TP
.B Dir dir
If \fIm3check\fP is reading \fIm3path\fP files to generate a
search path, then this command sets it into explicit path mode
exactly as if it had been started up with an \fB-Defpath dir\fP 
command argument. Otherwise, if it is in explicit mode already, it
prepends the directory \fIdir\fP to the search path.
The initial status of the directory is read-only.
With no argument, the search path is reset to empty (modulo the
current directory and the default interface directory).
.TP
.B DirC dir
This is defined to be equivalent to \fBDir dir; CompileInDir dir\fP.
.TP
.B ChangeDirStatus directory X
Change the status of \fIdirectory\fP to readonly, \fBX=R\fP, or
to read-write, \fBX=W\fP. The directory must exist on the 
current search path,
.TP
.B FreezeM3Path
This command converts a search path generated by reading \fIm3path\fP
files into an explicit list, as if it had been given with the 
\fBDefpath\fP option. Subsequent scans of the file system will not
read the \fIm3path\fP files, and thus will be faster.
There is no way back from this command to reading \fIm3path\fP files.
option.
.SH "COMPILATION COMMANDS"
.TP
.B ScanDirs
Effect a (re)scan of the (writeable) directories on the search path.
.TP
.B Compile
Generate
a list of units that have changed since the last invocation of this
command. 
Then compile these, after possible filtering.
.TP
.B Scan
Equivalent to \fBScanDirs; Compile\fP.
.TP
.B CompileInDir [dir]
Add the given directory to the list of directories in which to compile,
(other than the current). This also invokes a \fBChangeDirStatus W\fP
command, that is, removes the readonly status. The directory must exist on the 
current search path.
If no argument is given, reset the list to empty.
.TP
.B CompileInterface name
Compile the given interface, and any interfaces or modules that
use (transitively import) the interface.
.TP
.B CompileModule name
Compile the given module.
.TP
.B Verbose, PrintUnits, TTimings
Toggle the respective compiler front-end tool flag.
.TP
.B CompileAll
This command recompiles all units (and dependent units) that 
had errors when they were last compiled. 
.TP
.B NOFilterUnits, FilterUnitsExact, HeadersOnly
Toggle the respective flag.
.TP
.B M3Make [dir]
Execute \fIm3make\fP in a subshell in the directory "dir/target",
where "dir" defaults to "..", and "target" defaults to the value
of the CPU_TYPE environment variable.. 
This assumes that you invoked \fIm3check\fP from the
"src" subdirectory of a package or program, which is a
sensible idea else the default filtering will result in
nothing being compiled!
.TP
.B SHell command
Execute "command" in a subshell.
.SH "WARNING TOOL COMMANDS"
.TP 
.B WarnAll, WarnExceptions, WarnIgnoreFor, WarnReturns, WarnUses, WarnNarrows
Toggle the respective warning tool flag. N.B. Only those units that
are explicitly compiled as the result of a \fBScan\fP or
a \fBCompileAll\fP, \fBCompileInterfaces\fP, \fBCompileModules\fP or \fBCompileAll\fP command
are analysed for warnings.
.SH "GARBAGE COLLECTION COMMANDS"
.TP
.B \-NotifyGC
Toggle the \fBNotifyGC\fP flag.
.TP
.B \-GarbageCollect
Force a garbage collection now. If you are going to be editing for
a while, it might save time later.
.SH "BROWSING COMMANDS"
.TP
.B ListInterfaces [dir]
List the interfaces that are known to the system. An interface is
followed by a `-' character if it has not been compiled at all
and a `*' character if it has been compiled but had errors.
If the optional \fBdir\fP is given, the listing is restricted to
those interfaces in directory \fBdir\fP.
.TP
.B ListModules [dir]
As \fBListInterfaces\fP but for modules.
.TP
.B ListUnits [dir]
Equivalent to \fBListInterfaces [dir]; ListModules [dir]\fP.
.TP
.B ListPath
List the search path, with environment variables
expanded.
.TP 
.B TypeHierarchy typename
Show the type hierarchy for object type \fBtypename\fP,
which must be a qualified identifier. If the object type 
or any of its supertypes is opaque, the parts of the hierarchy that
correspond to the concrete revelations are not shown.
.TP
.B ConcreteTypeHierarchy typename
As \fBTypeHierarchy\fP, except that concrete revelations 
are included. N.B. If the concrete revelation occurs in an interface
or module that has not been compiled, that part of the hierarchy
will not be visible.
.TP
.B ShowUsesInterface interface
Show the \fIuses\fP relation for an \fBinterface\fP. The \fIuses\fP relation is 
defined as the transitive closure of the IMPORT statements starting
from \fBinterface\fP.
.TP
.B ShowUsesModule module
Show the \fIuses\fP relation for \fBmodule\fP. The \fIuses\fP relation  is
defined as: A module M \fIuses\fP an interface I if M imports or
exports I or uses an interface that imports I.
.TP
.B ShowDependsOn module
Show the \fIdepends on\fP relation for \fBmodule\fP.
The depends on relation is defined as: module M \fIdepends on\fP
a module N if M uses an  interface that N exports or if M depends
on a module that depends on N. N.B. This command will only
show any information after a pre-link has been performed
(See the PreLink command).
.TP
.B ShowLocationInterface interface
Show the location in the file system of \fBinterface\fP and its
time of last modification.
.TP
.B ShowLocationModule module
Show the location in the file system of \fBmodule\fP and its
time of last modification.
.TP
.B WhoDependsOn module
This lists those modules which depend on \fBmodule\fP. It has the
same precondition as \fBShowDependsOn\fP. 
.TP
.B WhoImports interface
Show those interfaces and modules which import \fBinterface\fP.
Those which only import the interface by the transitive closure
of direct imports are marked with an `asterisk'.
.TP
.B WhoeXports interface
Show those modules which export \fBinterface\fP.
.SH "PRE-LINKER TOOL COMMANDS"
.TP
.B PreLink [name]
Analyse the program 
for link-time completeness, reporting on unimplemented procedures
or unrevealed opaque types. \fBname\fP must be the name of a main
program module, that is, one which exports the interface `Main'.
\fBname\fP defaults to `Main'. The set of units that make up the
program is computed from the \fIdepends on\fP relation of the
main program module. This command can be slow for large programs.
.PP
Note that, unless all the units comprising the program have been compiled,
there will be lots of messages about unimplemented procedures and
unrevealed opaque types.
.SH "M3MAKEFILE GENERATOR TOOL OPTIONS"
This tool generates an \fIm3makefile\fP using the source files in the
current directory and information from the search path. 
Each interface "I" in the current directory generates an "Interface(I)"
entry. Each module "M" generates an "implementation(M)" entry.
Generic units generate similar entries.
Each directory on the search path that contains sources, other than
the current working directory and the standard repository, generates
a component of an "M3DEFPATH" definition. A directory that
contains a library "libA" generates an "import_lib(A)" entry and
a component of an M3LIBPATH definition.  If the \fB-archive name\fP
option is set, a "Library(name)" is generated. If there is a main
program "M" (i.e a module that exports "Main") in the current working directory,
a "Program(M)" entry is generated. 
.TP
.B \-ARchive name
Generate a `Library(name)' command in the generated \fIm3makefile\fP.
.TP
.B \-M3Makefile \fIM3MakefileName\fP 
The m3makefile generated is given the name \fIM3MakefileName\fP.  Defaults to
\fIm3makefile\fP.  If the argument is \fBstdout\fP, the file is written to the 
standard output.
.SH EXAMPLES
.SH "SEE ALSO"
m3(1), m3make(1)

.SH FILES
.PD 0
.TP 1.25i
.I m3makefile
built by \fIm3check\fP
.TP 
.I m3path
list of directories in which to look for Modula-3 files.  The
transitive closure of directories on reachable \fIm3path\fPs is used.
.TP
.I *.m3 *.i3 *.mg *.ig
Modula-3 source files.
.PD
.SH BUGS
.SH AUTHORS
Mick Jordan, Marion Sturtevant and Trevor Morris
.SH COPYRIGHT
.nf
.na
                     Copyright (C) Olivetti 1989 
                       
                         All Rights reserved                            
                                                                        
Use and copy of this software and preparation of derivative works based
upon this software are permitted to any person, provided this same
copyright notice and the following Olivetti warranty disclaimer are
included in any copy of the software or any modification thereof or
derivative work therefrom made by any person.
                                                                        
This software is made available AS IS and Olivetti disclaims all        
warranties with respect to this software, whether expressed or implied  
under any law, including all implied warranties of merchantibility and  
fitness for any purpose. In no event shall Olivetti be liable for any   
damages whatsoever resulting from loss of use, data or profits or       
otherwise arising out of or in connection with the use or performance   
of this software.    
 
             Copyright (C) 1992 Digital Equipment Corporation 
                        All Rights reserved      
                  See the file COPYRIGHT for details