.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Required to disable full justification in groff 1.23.0.
.if n .ds AD l
.\" ========================================================================
.\"
.IX Title "GM2 1"
.TH GM2 1 2026-06-19 gcc-14.3.1 GNU
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
gm2 \- The GNU Modula\-2 Compiler
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.SH DESCRIPTION
.IX Header "DESCRIPTION"
.SH OPTIONS
.IX Header "OPTIONS"
For any given input file, the file name suffix determines what kind of
compilation is done.  The following kinds of input file names are supported:
.IP \fIfile\fR\fB.mod\fR 4
.IX Item "file.mod"
Modula\-2 implementation or program source files.  See the
\&\fB\-fmod=\fR option if you wish to compile a project which uses a
different source file extension.
.IP \fIfile\fR\fB.def\fR 4
.IX Item "file.def"
Modula\-2 definition module source files.  Definition modules are not
compiled separately, in GNU Modula\-2 definition modules are parsed as
required when program or implementation modules are compiled.  See the
\&\fB\-fdef=\fR option if you wish to compile a project which uses a
different source file extension.
.PP
You can specify more than one input file on the \fBgm2\fR command line,
.ie n .IP """\-g""" 4
.el .IP \f(CW\-g\fR 4
.IX Item "-g"
create debugging information so that debuggers such as \fIgdb\fR
can inspect and control executable.
.ie n .IP """\-I""" 4
.el .IP \f(CW\-I\fR 4
.IX Item "-I"
used to specify the search path for definition and implementation
modules.  An example is:  \f(CW\*(C`gm2 \-g \-c \-I.:../../libs foo.mod\*(C'\fR.
If this option is not specified then the default path is added
which consists of the current directory followed by the appropriate
language dialect library directories.
.ie n .IP """\-fauto\-init""" 4
.el .IP \f(CW\-fauto\-init\fR 4
.IX Item "-fauto-init"
turns on auto initialization of pointers to NIL.  Whenever a block is
created all pointers declared within this scope will have their
addresses assigned to NIL.
.ie n .IP """\-fbounds""" 4
.el .IP \f(CW\-fbounds\fR 4
.IX Item "-fbounds"
turns on run time subrange, array index and indirection via \f(CW\*(C`NIL\*(C'\fR
pointer checking.
.ie n .IP """\-fcase""" 4
.el .IP \f(CW\-fcase\fR 4
.IX Item "-fcase"
turns on compile time checking to check whether a \f(CW\*(C`CASE\*(C'\fR
statement requires an \f(CW\*(C`ELSE\*(C'\fR clause when on was not specified.
.ie n .IP """\-fcpp""" 4
.el .IP \f(CW\-fcpp\fR 4
.IX Item "-fcpp"
preprocess the source with \fBcpp \-lang\-asm \-traditional\-cpp\fR
For further details about these options 
If \fB\-fcpp\fR is supplied then all definition modules and
implementation modules which are parsed will be prepossessed by
\&\fBcpp\fR.
.ie n .IP """\-fdebug\-builtins""" 4
.el .IP \f(CW\-fdebug\-builtins\fR 4
.IX Item "-fdebug-builtins"
call a real function, rather than the builtin equivalent.  This can
be useful for debugging parameter values to a builtin function as
it allows users to single step code into an intrinsic function.
.ie n .IP """\-fdef=""" 4
.el .IP \f(CW\-fdef=\fR 4
.IX Item "-fdef="
recognize the specified suffix as a definition module filename.
The default implementation and module filename suffix is \fI.def\fR.
If this option is used GNU Modula\-2 will still fall back to this
default if a requested definition module is not found.
.ie n .IP """\-fdump\-system\-exports""" 4
.el .IP \f(CW\-fdump\-system\-exports\fR 4
.IX Item "-fdump-system-exports"
display all inbuilt system items.
This is an internal command line option.
.ie n .IP """\-fexceptions""" 4
.el .IP \f(CW\-fexceptions\fR 4
.IX Item "-fexceptions"
turn on exception handling code.  By default this option is on.
Exception handling can be disabled by \fB\-fno\-exceptions\fR
and no references are made to the run time exception libraries.
.ie n .IP """\-fextended\-opaque""" 4
.el .IP \f(CW\-fextended\-opaque\fR 4
.IX Item "-fextended-opaque"
allows opaque types to be implemented as any type.  This is a GNU
Modula\-2 extension and it requires that the implementation module
defining the opaque type is available so that it can be resolved when
compiling the module which imports the opaque type.
.ie n .IP """\-ffloatvalue""" 4
.el .IP \f(CW\-ffloatvalue\fR 4
.IX Item "-ffloatvalue"
turns on run time checking to check whether a floating point number is
about to exceed range.
.ie n .IP """\-fgen\-module\-list=\fIfilename\fR""" 4
.el .IP \f(CW\-fgen\-module\-list=\fR\f(CIfilename\fR\f(CW\fR 4
.IX Item "-fgen-module-list=filename"
attempt to find all modules when linking and generate a module list.
If the \fIfilename\fR is \fB\-\fR then the contents are not written
and only used to force the linking of all module ctors.
This option cannot be used if \fB\-fuse\-list=\fR is enabled.
.ie n .IP """\-findex""" 4
.el .IP \f(CW\-findex\fR 4
.IX Item "-findex"
generate code to check whether array index values are out of bounds.
Array index checking can be disabled via \fB\-fno\-index\fR.
.ie n .IP """\-fiso""" 4
.el .IP \f(CW\-fiso\fR 4
.IX Item "-fiso"
turn on ISO standard features.  Currently this enables the ISO
\&\f(CW\*(C`SYSTEM\*(C'\fR module and alters the default library search path so
that the ISO libraries are searched before the PIM libraries.  It also
effects the behavior of \f(CW\*(C`DIV\*(C'\fR and \f(CW\*(C`MOD\*(C'\fR operators.
.ie n .IP """\-flibs=""" 4
.el .IP \f(CW\-flibs=\fR 4
.IX Item "-flibs="
modifies the default library search path.  The libraries supplied are:
m2pim, m2iso, m2min, m2log and m2cor.  These map onto the
Programming in Modula\-2 base libraries, ISO standard libraries, minimal
library support, Logitech compatible library and Programming in
Modula\-2 with coroutines.
Multiple libraries can be specified and are comma separated with precedence
going to the first in the list.  It is not necessary to use \-flibs=m2pim or
\&\-flibs=m2iso if you also specify \-fpim, \-fpim2, \-fpim3, \-fpim4 or
\&\-fiso.  Unless you are using \-flibs=m2min you should include m2pim as
the they provide the base modules which all other dialects utilize.
The option \fB\-fno\-libs=\-\fR disables the \fBgm2\fR driver from
modifying the search and library paths.
.ie n .IP """\-static\-libgm2""" 4
.el .IP \f(CW\-static\-libgm2\fR 4
.IX Item "-static-libgm2"
On systems that provide the m2 runtimes as both shared and static libraries,
this option forces the use of the static version.
.ie n .IP """\-fm2\-g""" 4
.el .IP \f(CW\-fm2\-g\fR 4
.IX Item "-fm2-g"
improve the debugging experience for new programmers at the expense
of generating \f(CW\*(C`nop\*(C'\fR instructions if necessary to ensure single
stepping precision over all code related keywords.  An example
of this is in termination of a list of nested \f(CW\*(C`IF\*(C'\fR statements
where multiple \f(CW\*(C`END\*(C'\fR keywords are mapped onto a sequence of
\&\f(CW\*(C`nop\*(C'\fR instructions.
.ie n .IP """\-fm2\-lower\-case""" 4
.el .IP \f(CW\-fm2\-lower\-case\fR 4
.IX Item "-fm2-lower-case"
render keywords in error messages using lower case.
.ie n .IP """\-fm2\-pathname=""" 4
.el .IP \f(CW\-fm2\-pathname=\fR 4
.IX Item "-fm2-pathname="
specify the module mangled prefix name for all modules in the
following include paths.
.ie n .IP """\-fm2\-pathnameI""" 4
.el .IP \f(CW\-fm2\-pathnameI\fR 4
.IX Item "-fm2-pathnameI"
for internal use only: used by the driver to copy the user facing \-I
option.
.ie n .IP """\-fm2\-plugin""" 4
.el .IP \f(CW\-fm2\-plugin\fR 4
.IX Item "-fm2-plugin"
insert plugin to identify run time errors at compile time (default on).
.ie n .IP """\-fm2\-prefix=""" 4
.el .IP \f(CW\-fm2\-prefix=\fR 4
.IX Item "-fm2-prefix="
specify the module mangled prefix name.  All exported symbols from a
definition module will have the prefix name.
.ie n .IP """\-fm2\-statistics""" 4
.el .IP \f(CW\-fm2\-statistics\fR 4
.IX Item "-fm2-statistics"
generates quadruple information: number of quadruples generated,
number of quadruples remaining after optimization and number of source
lines compiled.
.ie n .IP """\-fm2\-strict\-type""" 4
.el .IP \f(CW\-fm2\-strict\-type\fR 4
.IX Item "-fm2-strict-type"
experimental flag to turn on the new strict type checker.
.ie n .IP """\-fm2\-whole\-program""" 4
.el .IP \f(CW\-fm2\-whole\-program\fR 4
.IX Item "-fm2-whole-program"
compile all implementation modules and program module at once.  Notice
that you need to take care if you are compiling different dialect
modules (particularly with the negative operands to modulus).  But
this option, when coupled together with \f(CW\*(C`\-O3\*(C'\fR, can deliver huge
performance improvements.
.ie n .IP """\-fmod=""" 4
.el .IP \f(CW\-fmod=\fR 4
.IX Item "-fmod="
recognize the specified suffix as implementation and module filenames.
The default implementation and module filename suffix is \fI.mod\fR.
If this option is used GNU Modula\-2 will still fall back to this
default if it needs to read an implementation module and the specified
suffixed filename does not exist.
.ie n .IP """\-fnil""" 4
.el .IP \f(CW\-fnil\fR 4
.IX Item "-fnil"
generate code to detect accessing data through a \f(CW\*(C`NIL\*(C'\fR value
pointer.  Dereferencing checking through a \f(CW\*(C`NIL\*(C'\fR pointer can be
disabled by \fB\-fno\-nil\fR.
.ie n .IP """\-fpim""" 4
.el .IP \f(CW\-fpim\fR 4
.IX Item "-fpim"
turn on PIM standard features.  Currently this enables the PIM
\&\f(CW\*(C`SYSTEM\*(C'\fR module and determines which identifiers are pervasive
(declared in the base module).  If no other \fB\-fpim[234]\fR switch is
used then division and modulus operators behave as defined in PIM4.
.ie n .IP """\-fpim2""" 4
.el .IP \f(CW\-fpim2\fR 4
.IX Item "-fpim2"
turn on PIM\-2 standard features.  Currently this removes \f(CW\*(C`SIZE\*(C'\fR
from being a pervasive identifier (declared in the base module).  It
places \f(CW\*(C`SIZE\*(C'\fR in the \f(CW\*(C`SYSTEM\*(C'\fR module.  It also effects the
behavior of \f(CW\*(C`DIV\*(C'\fR and \f(CW\*(C`MOD\*(C'\fR operators.
.ie n .IP """\-fpim3""" 4
.el .IP \f(CW\-fpim3\fR 4
.IX Item "-fpim3"
turn on PIM\-3 standard features.  Currently this only effects the
behavior of \f(CW\*(C`DIV\*(C'\fR and \f(CW\*(C`MOD\*(C'\fR operators.
.ie n .IP """\-fpim4""" 4
.el .IP \f(CW\-fpim4\fR 4
.IX Item "-fpim4"
turn on PIM\-4 standard features.  Currently this only effects the
behavior of \f(CW\*(C`DIV\*(C'\fR and \f(CW\*(C`MOD\*(C'\fR operators.
.ie n .IP """\-fpositive\-mod\-floor\-div""" 4
.el .IP \f(CW\-fpositive\-mod\-floor\-div\fR 4
.IX Item "-fpositive-mod-floor-div"
forces the \f(CW\*(C`DIV\*(C'\fR and \f(CW\*(C`MOD\*(C'\fR operators to behave as defined by PIM4.
All modulus results are positive and the results from the division are
rounded to the floor.
.ie n .IP """\-fpthread""" 4
.el .IP \f(CW\-fpthread\fR 4
.IX Item "-fpthread"
link against the pthread library.  By default this option is on.  It
can be disabled by \fB\-fno\-pthread\fR.  GNU Modula\-2 uses the GCC
pthread libraries to implement coroutines (see the SYSTEM
implementation module).
.ie n .IP """\-frange""" 4
.el .IP \f(CW\-frange\fR 4
.IX Item "-frange"
generate code to check the assignment range, return value range
set range and constructor range.  Range checking can be disabled
via \fB\-fno\-range\fR.
.ie n .IP """\-freturn""" 4
.el .IP \f(CW\-freturn\fR 4
.IX Item "-freturn"
generate code to check that functions always exit with a \f(CW\*(C`RETURN\*(C'\fR
and do not fall out at the end.  Return checking can be disabled
via \fB\-fno\-return\fR.
.ie n .IP """\-fruntime\-modules=""" 4
.el .IP \f(CW\-fruntime\-modules=\fR 4
.IX Item "-fruntime-modules="
specify, using a comma separated list, the run time modules and their
order.  These modules will initialized first before any other modules
in the application dependency.  By default the run time modules list
is set to \f(CW\*(C`m2iso:RTentity,m2iso:Storage,m2iso:SYSTEM,\*(C'\fR
\&\f(CW\*(C`m2iso:M2RTS,m2iso:RTExceptions,m2iso:IOLink\*(C'\fR.  Note that these
modules will only be linked into your executable if they are required.
Adding a long list of dependent modules will not effect the size of
the executable it merely states the initialization order should they
be required.
.ie n .IP """\-fscaffold\-dynamic""" 4
.el .IP \f(CW\-fscaffold\-dynamic\fR 4
.IX Item "-fscaffold-dynamic"
the option ensures that \fBgm2\fR will generate a dynamic scaffold
infrastructure when compiling implementation and program modules.
By default this option is on.  Use \fB\-fno\-scaffold\-dynamic\fR
to turn it off or select \fB\-fno\-scaffold\-static\fR.
.ie n .IP """\-fscaffold\-c""" 4
.el .IP \f(CW\-fscaffold\-c\fR 4
.IX Item "-fscaffold-c"
generate a C source scaffold for the current module being compiled.
.ie n .IP """\-fscaffold\-c++""" 4
.el .IP \f(CW\-fscaffold\-c++\fR 4
.IX Item "-fscaffold-c++"
generate a C++ source scaffold for the current module being compiled.
.ie n .IP """\-fscaffold\-main""" 4
.el .IP \f(CW\-fscaffold\-main\fR 4
.IX Item "-fscaffold-main"
force the generation of the \fBmain\fR function.  This is not
necessary if the \fB\-c\fR is omitted.
.ie n .IP """\-fscaffold\-static""" 4
.el .IP \f(CW\-fscaffold\-static\fR 4
.IX Item "-fscaffold-static"
the option ensures that \fBgm2\fR will generate a static scaffold
within the program module.  The static scaffold consists of sequences
of calls to all dependent module initialization and finalization
procedures.  The static scaffold is useful for debugging and single
stepping the initialization blocks of implementation modules.
.ie n .IP """\-fshared""" 4
.el .IP \f(CW\-fshared\fR 4
.IX Item "-fshared"
generate a shared library from the module.
.ie n .IP """\-fsoft\-check\-all""" 4
.el .IP \f(CW\-fsoft\-check\-all\fR 4
.IX Item "-fsoft-check-all"
turns on all run time checks.  This is the same as invoking
GNU Modula\-2 using the command options
\&\f(CW\*(C`\-fnil\*(C'\fR \f(CW\*(C`\-frange\*(C'\fR \f(CW\*(C`\-findex\*(C'\fR
\&\f(CW\*(C`\-fwholevalue\*(C'\fR
\&\f(CW\*(C`\-fwholediv\*(C'\fR \f(CW\*(C`\-fcase\*(C'\fR \f(CW\*(C`\-freturn\*(C'\fR.
.ie n .IP """\-fsources""" 4
.el .IP \f(CW\-fsources\fR 4
.IX Item "-fsources"
displays the path to the source of each module.  This option
can be used at compile time to check the correct definition module
is being used.
.ie n .IP """\-fswig""" 4
.el .IP \f(CW\-fswig\fR 4
.IX Item "-fswig"
generate a swig interface file.
.ie n .IP """\-funbounded\-by\-reference""" 4
.el .IP \f(CW\-funbounded\-by\-reference\fR 4
.IX Item "-funbounded-by-reference"
enable optimization of unbounded parameters by attempting to pass non
\&\f(CW\*(C`VAR\*(C'\fR unbounded parameters by reference.  This optimization
avoids the implicit copy inside the callee procedure.  GNU Modula\-2
will only allow unbounded parameters to be passed by reference if,
inside the callee procedure, they are not written to, no address is
calculated on the array and it is not passed as a \f(CW\*(C`VAR\*(C'\fR
parameter.  Note that it is possible to write code to break this
optimization, therefore this option should be used carefully.
For example it would be possible to take the address of an array, pass
the address and the array to a procedure, read from the array in
the procedure and write to the location using the address parameter.
.Sp
Due to the dangerous nature of this option it is not enabled
when the \fB\-O\fR option is specified.
.ie n .IP """\-fuse\-list=\fIfilename\fR""" 4
.el .IP \f(CW\-fuse\-list=\fR\f(CIfilename\fR\f(CW\fR 4
.IX Item "-fuse-list=filename"
if \fB\-fscaffold\-static\fR is enabled then use the file
\&\fIfilename\fR for the initialization order of modules.  Whereas if
\&\fB\-fscaffold\-dynamic\fR is enabled then use this file to force
linking of all module ctors.
This option cannot be used if \fB\-fgen\-module\-list=\fR is enabled.
.ie n .IP """\-fwholediv""" 4
.el .IP \f(CW\-fwholediv\fR 4
.IX Item "-fwholediv"
generate code to detect whole number division by zero or modulus by
zero.
.ie n .IP """\-fwholevalue""" 4
.el .IP \f(CW\-fwholevalue\fR 4
.IX Item "-fwholevalue"
generate code to detect whole number overflow and underflow.
.ie n .IP """\-Wcase\-enum""" 4
.el .IP \f(CW\-Wcase\-enum\fR 4
.IX Item "-Wcase-enum"
generate a warning if a \f(CW\*(C`CASE\*(C'\fR statement selects on an enumerated
type expression and the statement is missing one or more \f(CW\*(C`CASE\*(C'\fR
labels.  No warning is issued if the \f(CW\*(C`CASE\*(C'\fR statement has a default
\&\f(CW\*(C`ELSE\*(C'\fR clause.
The option \fB\-Wall\fR will turn on this flag.
.ie n .IP """\-Wuninit\-variable\-checking""" 4
.el .IP \f(CW\-Wuninit\-variable\-checking\fR 4
.IX Item "-Wuninit-variable-checking"
issue a warning if a variable is used before it is initialized.
The checking only occurs in the first basic block in each procedure.
It does not check parameters, array types or set types.
.ie n .IP """\-Wuninit\-variable\-checking=all,known,cond""" 4
.el .IP \f(CW\-Wuninit\-variable\-checking=all,known,cond\fR 4
.IX Item "-Wuninit-variable-checking=all,known,cond"
issue a warning if a variable is used before it is initialized.
The checking will only occur in the first basic block in each
procedure if \fBknown\fR is specified.  If \fBcond\fR or \fBall\fR
is specified then checking continues into conditional branches of the
flow graph.  All checking will stop when a procedure call is invoked
or the top of a loop is encountered.
The option \fB\-Wall\fR will turn on this flag with
\&\fB\-Wuninit\-variable\-checking=known\fR.
The \fB\-Wuninit\-variable\-checking=all\fR will increase compile time.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBgpl\fR\|(7), \fBgfdl\fR\|(7), \fBfsf\-funding\fR\|(7), \fBgcc\fR\|(1)
and the Info entries for \fIgm2\fR and \fIgcc\fR.
.SH COPYRIGHT
.IX Header "COPYRIGHT"
Copyright (c) 1999\-2024 Free Software Foundation, Inc.
.PP
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, no Front\-Cover Texts, and no Back\-Cover Texts.
A copy of the license is included in the
man page \fBgfdl\fR\|(7).
