Document downloaded from:
http://www.doc.ic.ac.uk/~mac/manuals/sunos-manual-pages/sunos4/usr/local/man/man1/em2.1.html
dg, 09/12/99
NAME
em2 - EPC Modula-2 Compiler (Version 2.0.6)
SYNOPSIS
em2 [ options ] .. files ..
DESCRIPTION
em2 is a compiler for EPC Modula-2 implemented by Edinburgh
Portable Compilers Ltd. The language accepted by em2 is
based on the descriptions in editions 3 and 4 of the text-
book "Programming in Modula-2" by Professor Niklaus Wirth.
However, a control option -sun allows the compiler to accept
the dialect of Modula-2 available on Sun Workstations. The
only significant difference between this and the default
dialect selected by the option -epc is that under -sun the
types REAL and LONGREAL are compatible, whilst under -epc
they are not.
Both dialects contain a common set of extensions which pro-
vide a larger set of standard data types, logical bit opera-
tors, and support for mixed language programming. These
extensions are described in the EPC Modula-2 User's Refer-
ence Manual. Each dialect has an associated suite of
Modula-2 library modules. By default the -sun switch will
select the Sun library libSM2.a, whilst the -epc switch will
select the EPC library libEM2.a. The default choice may be
overridden and it is possible to use the Sun library with
the language dialect selected by -epc. See the ENVIRONMENT
section below.
em2 is the name of a driver program that controls the
overall compilation process. em2 analyses the set of
options provided and then passes them together with the name
of a file argument, to the compiler. If multiple file argu-
ments are specified, em2 invokes the compiler on each file
in turn. The nature of each input file is deduced from the
filename suffix. The suffixes recognized by em2 are
.mod Modula-2 source file
.def Modula-2 source file
.o Object file
If the suffix is .mod or .def, the file must contain the
source text of a single compilation unit. In the case of
.mod, the unit must be a program module or an implementation
module. In the case of .def, the unit must be a definition
module.
A file with a .o suffix, or with an unrecognized suffix, or
with no suffix at all, is passed straight to the linking
phase - no attempt is made to compile its contents.
In this implementation of Modula-2, it is possible, but not
necessary to submit .def files to the compiler. When the
compiler processes a .mod file containing an implementation
module, it automatically deduces the name of the .def file
containing the corresponding definition module from the
module identifier or from additional information supplied
via compilation options. The compiler then processes the
definition module before proceeding to compile the implemen-
tation module. When the compiler processes a definition
module, only syntax and semantic checks are performed. No
code or intermediate symbol file is produced. There are
three implications resulting from this approach:
(1) The compiler handles compilation ordering problems
automatically. An implementation module is always
compiled after the definition modules upon which it
depends.
(2) By default, the definition part of a module with
identifier M must be held in a source file M.def. A
compilation option is provided to override this map-
ping if required.
(3) When the compiler processes the module heading
IMPLEMENTATION MODULE M
or an import statement of the form
FROM M IMPORT ..idents ..
the compiler searches for the definition part of M
in a file called M.def. The search is conducted
along a search path consisting of one or more direc-
tories and archive libraries. By default, the
current directory is searched first.
For each directory on the search path, the compiler
attempts to locate M either in a file called M.def
in the directory or in a member file M.def of an
archive library in the directory. However, the only
archive libraries considered are those nominated by
the -i option.
For each library on the search path, the compiler
attempts to locate M within a member file M.def of
the library.
When the compiler processes a .mod file, it checks for syn-
tax and semantic errors errors and generates object code in
an equivalent object file. The name of the object file is
derived by replacing the .mod suffix of the source file name
with a .o suffix
It is normal for compiler options to precede file arguments
on the command line. However, it is possible to locate -E,
-I, -M, -Qoption, -Qinstall, -Qpath, -e, -i, -o, -f and -m
after file arguments. In some cases this may be necessary to
ensure order dependent information is propagated to the
linker correctly.
Files with the suffixes .def and .mod may be mixed on the
command line. If this is the case, the driver will call the
compiler for each of the .mod files first and then for each
of the .def files. The linker will not be called.
em2 supports the use of module libraries which are organised
as UNIX archive files containing definition modules and the
compiled object code. When a definition module is located as
a member of an archive file, the driver automatically passes
the name of the archive to the linker to ensure the
corresponding object code is linked at link time.
Detailed control of the compiler is provided by means of
control options that are submitted in the conventional UNIX
style. These options are summarised in the following para-
graphs.
-Ak On some implementations, some local data structures
are stored on an auxiliary stack. Set the size of
this stack to k Kbytes. The default size is 128
Kbytes. Ignored on implementations which do not use
an auxiliary stack.
-a This option generates a .d file for use with the
test coverage utility tcov. The .d file accummu-
lates execution data for the corresponding .mod
file. See the Unix documentation tcov(1) for further
information. This option is only available on SunOS
and Solaris versions of UNIX.
-align_block
Page align and pad the FORTRAN COMMON symbol _block.
This option is passed straight to the linker ld.
-Cstr Generate additional code to check for runtime
errors. str is a sequence of one or more digits in
the range 0 to 1 which control the class of errors
to be detected. In particular
-C0 enables the detection of range errors.
-C1 enables the detection of undefined value
errors.
Multiple classes of detections may be achieved by
including more than one digit in the string. Thus
-C01 enables both range and undefined value error
detection. The abbreviated form -C is equivalent to
-C01 and enables full error detection. When the -epc
option is used, most error checks are omitted. How-
ever some of the runtime libraries make checks
unconditionally for a small number of errors that
are potentially catastrophic. The EPC Modula-2
User's Reference Manual provides precise details of
the error checking capabilities of this implementa-
tion.
-c Suppress the linking phase of compilation. The
object program will be left in an equivalent .o
file. This option should be used when program
modules are to be compiled separately and then
linked at a later stage.
-cg87 Ignored.
-cg89 Ignored.
-Dn Control the level of post mortem diagnostic informa-
tion that is provided following the detection of a
runtime error. n is a single digit number in the
range 0 to 4. In particular
-D0 suppresses the production of all post mortem
diagnostics. When used with -g (see below)
it prevents the runtime system from setting
up signal handlers. The main reason for
this is to allow the generation of a core
file when an exception occurs. A side effect
of this is to prevent the runtime system
from setting up its own signal handlers
which might possibly interfere with signal
handlers set up by the programmer.
-D1 limits diagnostic information to a minimal
execution trace back giving the set of
active blocks at the time the error
occurred.
-D2 enables the production of a full execution
trace back including source line numbers for
the statement causing the error and the
points of call for each of the active
blocks.
-D3 supplements the trace back with a partial
dump of scalar variables.
-D4 supplements the trace back with a full vari-
able dump which includes a treatment of
structured variables.
The default setting for n is 1. The abbreviated form
-D is equivalent to -D4.
-df filename
Perform a syntax and semantic check on the defini-
tion module specified by "filename".
-dm modulename
Search for and perform a syntax and semantic check
on the definition module specified by "modulename".
-dryrun Cause the driver to do a 'dry run', ie. it will pro-
cess its arguments but will not call the compiler or
any other underlying utility. This is useful with -v
allowing the user to see what commands would be exe-
cuted by the driver.
-E root Ignored.
-e root Ignored.
-epc Select the EPC Modula-2 dialect and library suite.
-F Cause the compiler to fully evaluate BOOLEAN expres-
sions. By default, if an operand of AND evaluates to
FALSE, or an operand of OR evaluates to TRUE, the
remaining operands are ignored.
-f Specify a file of -m style options. Each line in the
file must have one of the forms
OldName:NewName
or
Module=FileName
Leading blanks and lines whose first non-blank char-
acter is hash (#) are ignored.
-f1167 Generate code for the Weitek 1167 floating point
accelerator. Files compiled with this option should
not be linked with files compiled with the -f387
option. Ignored on systems not based on Intel
80386/80486 processors.
-f68881 Generate code for the Motorola M68881 coprocessor.
Ignored on systems not based on Motorola processors.
-fast Reserved for future use.
-ffpa Generate code for the Sun Floating Point Accelera-
tor. Ignored on systems not based on this hardware.
-ffpaplus
Generate code for the Sun FPA+ Accelerator. Ignored
on systems not based on this hardware.
-fpa A synonym for the -f1167 option. Ignored on systems
not based on Intel 80386/80486 processors.
-f387 Generate code for the Intel 80387 floating point
processor. This option is selected by default by the
compiler. Ignored on systems not based on Intel
80386/80486 processors.
-fnonstd
Ignored.
-fsoft Ignored.
-fswitch
Ignored.
-G Produce a numbered compilation listing of all lines
in the source files supplied as arguments. If the
source file holds an implementation module, the
corresponding definition module will be listed as
well.
-g On some platforms this option generates additional
information for use with an interactive debugger.
On SunOS platforms information is generated for dbx.
See supporting Unix documentation for additional
information on dbx.
On Solaris 2.x, SPARC SVR4 and Intel SVR4 systems,
information is generated for the EPC interactive
debugger, edb. See edb documentation for more
detail.
On other platforms the option is ignored.
Where this option is enabled, it also affects the
behaviour of programs produced by the compiler. It
ensures that a SIGTRAP signal is generated should a
runtime check or library error occur. This in turn
generates a diagnostic traceback as would any other
signal. If however diagnostics have been disabled
(see -D above) then the runtime system sets up no
signal handlers of its own. Unless the programmer
has requested non-default signal behaviour then this
usually means that a core file is generated when a
signal occurs. The generation of a core file allows
a debugger to perform a postmortem on a program and
the generation of a signal when an exception occurs
allows a debugger to interactively trap exceptions.
-help Ignored.
-Ifile Takes file to be a full pathname. If file does not
exist it is ignored. If file is a directory, it is
added to the search path for definition modules and
the option -Lfile is passed to the linker. Otherwise
file is assumed to be an archive library which is
added to the search path and file is passed to the
linker.
On systems running AIX some extra processing is per-
formed. If file ends with .a then a test is made for
the existence of file_x.a otherwise a test is made
for the existence of file_x. If the file exists, a
corresponding -I argument is also passed to the com-
piler. See the -i option for an explanantion.
-iX Specify that archive libX.a is to be added to the
library set. The compiler will search in any file
libX.a occurring in directories on the search path.
The option -lX is passed to the linker.
On systems running AIX the archive libX_x.a is also
added to the library set. No equivalent -lX_x is
passed to the linker however.
The reason for this extra _x processing for -i and
-I is because of the AIX linker. On other UNIX sys-
tems it is possible to mix .def files and their
corresponding .o files in the same archive. The AIX
linker will not accept such files. em2 therefore
adopts the convention that .def files are put into
archives distinguished by _x. For example, the Sun
compatibility library provided with the compiler
comes in two parts: libSM2.a for .o files and
libSM2_x.a for .def files. User libraries can be
constructed similarly.
-J Ignored.
-j Specify that fields of a record are not to be
aligned for efficient access but should be jammed
together with no padding bytes. Ignored on systems
not based on Intel 80x86 processors.
-k Reserved for future use.
-keys Ignored.
-Ldir Add dir to the list of directories searched while
processing the -l option. This option is passed
straight to the linker.
-libmil Ignored.
-list This option is an alternative for -G.
-lx Similar to -i However, the option is just passed to
the linker. If the library contains definition
modules, then -i must be used.
-Mdir An alternative to -Idir.
-m Override the default association of a module iden-
tifier M with a corresponding file M.def. When the
form
-mOldName:NewName
is used, an import statement
FROM OldName IMPORT .. idents ..
causes the compiler to search for a definition
module in the file NewName.def. When the form
-mModule=FileName
is used, an import statement
FROM Module IMPORT .. idents ..
causes the compiler to read the definition module
from the file FileName. In either form a space may
be inserted between the m and the module identifier.
-map file
Ignored.
-n An alternative for -dryrun.
-native Ignored.
-nobounds
This option is used to disable range checking for
array indices and case selectors. The same effect
may be obtained by the compiler directive T-. This
option should only be used in conjunction with -sun.
-nolibmil
Ignored.
-norange
This option is used to disable range checking for
assignments to subrange types. The same effect may
be obtained by the compiler directive R-. This
option should only be used in conjunction with -sun.
-On Optimize for code for execution speed. n is a single
digit expressing the level of optimization.
Currently, the only value permitted is zero which
enables instruction scheduling on SPARC and Motorola
M88K platforms. The form -O may be used to switch on
all available optimisations. This option is only
available on SunOS and Solaris versions of UNIX.
-o file Place the run file generated by the linker in the
named file rather than a.out. The file will be
created with the appropriate access permissions if
it does not already exist. When used in conjunction
with -c the object code will be generated in file.o
-P Reserved for use by EPC.
-p Generates additional information for use with the
profiling program prof. See the Unix documentation
prof(1) for further information. This option is
only available on SunOS, Solaris and SPARC SVR4 ver-
sions of UNIX.
-pg Generates additional information for use with the
profiling program gprof. See the Unix documentation
gprof(1) for further information. This option is
only available on SunOS versions of UNIX.
-pic Produce position independent code. Each reference to
a global datum is generated as a dereference of a
pointer to a global offset table. Each function call
is generated in pc-relative addressing mode through
a procedure linkage table. The size of the global
offset table is limited to 8K for SPARC processors.
This option is only available on SunOS, Solaris and
SPARC SVR4 versions of UNIX.
-PIC Produce position independent code, but allow the
global offset table to span the range of 32-bit
addresses. This option should be used in preference
to pic when there are too many global data objects
for the smaller 8K table to accommodate. This
option is only available on SunOS, Solaris and SPARC
SVR4 versions of UNIX.
-pipe Ignored.
-Qoption program option
Pass option to program. The option must be appropri-
ate to program. program may be either em2compiler or
ld.
-Qpath directory
Insert directory into the search path used by the
compiler to locate source files. This path is also
use to locate files such as the startups *crt*.o
that are linked to the compiled program.
-Qproduce
Ignored.
-R Ignored.
-S Generate a pseudo assembler listing to the standard
output file. Ignored on some systems.
-sb Ignored.
-sun Select the Sun Modula-2 dialect and library suite.
This option also has the effect of turning on all
possible range checks. These checks may be
suppressed by using the -norange and -nobounds
options.
-sun4 Ignored.
-T Reserved for future use.
-t Cause the compiler to output the name of the file
containing each imported module definition.
-temp=dir
Set the directory for temporary file creation to
dir. The default is /tmp.
-time Ignored.
-trace Ignored.
-U Update object files for make(1). For each .mod file
on the command line, the compiler will attempt to
remove the object file if it is older than the
source file or any of its imports. Implies -w, -y,
-c and disables any -G or -t options. Any .def files
given will be ignored. The EPC Modula-2 User's
Reference Manual gives examples of how to use this
option in make(1) scripts.
-V Ignored.
-v Cause the compiler driver to enter verbose mode and
print the commands and arguments which it issues.
-w Allows the compiler to suppress warnings regarding
unused variables or redundant or potentially
insecure language constructs.
-y Suppress the generation of object code and run the
compiler as a syntax and semantic checker.
ENVIRONMENT
Control over the choice of dialect or libraries may also be
exercised through the use of environment variables.
Currently, EPC Modula-2 supports three variables called
EM2_DEFAULTS, EM2_OPTIONS and EM2_FPAOPTIONS.
The language dialect accepted by the compiler is decided on
the basis of the options -sun and -epc, the contents of the
environment variable EM2_DEFAULTS and the host computer sys-
tem.
If -sun or -epc is specified on the command line then the
corresponding dialect and library are selected. If neither
option is specified, the driver will consult the environment
variable EM2_DEFAULTS. If this is set to "-sun" or "-epc"
then the appropriate dialect and library is selected. If the
environment variable is not found or not set, then then the
choice depends upon the host system. For platforms running
the SunOS or Solaris version of UNIX, the default choice is
-sun. For all other platforms, the default choice is -epc.
By default, the compiler driver em2 will append an implemen-
tation dependent set of additional options to the command
line. This set may be overridden by setting the environment
variable EM2_OPTIONS to an alternative set. EM2_OPTIONS is
interpreted by em2 as though its value had been placed on
the command line as in
em2 [ options ] .. files .. $EM2_OPTIONS
The default setting for EM2_OPTIONS is usually
"-I. -I/usr/local/lib -I/usr/lib -I/lib -i?M2 -iCEM2
-lm -lc"
However on SunOS and other platforms there is also a
-ltermcap option required
"-I. -I/usr/local/lib -I/usr/lib -I/lib -i?M2 -iCEM2
-ltermcap -lm -lc"
When the Sun dialect is specified, the ? in -i?M2 is
replaced by S with the effect that the Sun library suite is
selected. When the EPC dialect is specified, ? is replaced
with E with the effect that the EPC library is selected.
It is possible to select the Sun dialect but use the EPC
libraries instead. This may be done with a command line of
the form
em2 -sun p.mod -iEM2
Similarily the Sun libraries may be selected in preference
with
em2 -epc p.mod -iSM2
Alternatively, the choice may be set permanently by setting
EM2_OPTIONS appropriately. For example the EPC libraries are
selected with
"-I. -I/usr/local/lib -I/usr/lib -I/lib -iEM2 -iCEM2 -lc
-lm"
On Intel 80x86 based systems where -fpa or -f1167 has been
selected then EM2_FPAOPTIONS is used in place of
EM2_OPTIONS. Its default setting is of the form
"-I. -I/usr/local/lib -I/usr/lib -I/lib -i?M21167 -iCEM21167
-lm1167 -lc1167"
NOTE: Environment variable names beginning with the charac-
ters `EM2_' are reserved for possible future enhancements.
FILES
file.def definition module
file.mod implementation module
file.o object file
file.a module library
a.out executable run file
em2 compiler driver
em2compiler compiler binary
em2list compilation listing utility
em2make Modula-2 make utility
em2errors error messages
libEM2.a EPC Modula-2 library
libSM2.a Sun Modula-2 library
libCEM2.a Runtime support library
SEE ALSO
em2 Make(1) A Modula-2 Program Make Utility
EPC Modula-2 User's Reference Manual, Edinburgh Portable
Compilers Limited, 1991.
DIAGNOSTICS
The diagnostics produced by em2 are intended to be self
explanatory.
Last Change: EPCL