     [file gcc-common.texi not included]

Copyright © 1999-2023 Free Software Foundation, Inc.

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 section entitled ``GNU Free Documentation License''.

Introduction
************

Overview of GNU Modula-2
************************

What is GNU Modula-2
====================

GNU Modula-2 is a front end (http://gcc.gnu.org/frontends.html) for the GNU Compiler Collection (GCC (http://gcc.gnu.org/)). The GNU Modula-2 compiler is compliant with the PIM2, PIM3, PIM4 and ISO dialects.  Also implemented are a complete set of free ISO libraries and PIM libraries.

 (The four Modula-2 dialects supported are defined in the following references:

PIM2: 'Programming in Modula-2', 2nd Edition, Springer Verlag, 1982, 1983 by Niklaus Wirth (PIM2).

PIM3: 'Programming in Modula-2', 3rd Corrected Edition, Springer Verlag, 1985 (PIM3).

PIM4: 'Programming in Modula-2', 4th Edition, Springer Verlag, 1988 (PIM4 (http://freepages.modula2.org/report4/modula-2.html)).

ISO: the ISO Modula-2 language as defined in 'ISO/IEC Information technology - programming languages - part 1: Modula-2 Language, ISO/IEC 10514-1 (1996)')

Why use GNU Modula-2
====================

There are a number of advantages of using GNU Modula-2 rather than translate an existing project into another language.

The first advantage is of maintainability of the original sources and the ability to debug the original project source code using a combination of gm2 and gdb.

The second advantage is that gcc runs on many processors and platforms.  gm2 builds and runs on powerpc64le, amd64, i386, aarch64 to name but a few processors.

gm2 can produce swig interface headers to allow access from Python and other scripting languages.  It can also be used with C/C++ and generate shared libraries.

The compiler provides semantic analysis and run time checking (full ISO Modula-2 checking is implemented) and there is a plugin which can, under certain conditions, detect run time errors at compile time.

The compiler supports PIM2, PIM3, PIM4 and ISO dialects of Modula-2, work is underway to implement M2R10.  Many of the GCC builtins are available and access to assembly programming is achieved using the same syntax as that used by GCC.

The gm2 driver allows third party libraries to be installed alongside gm2 libraries.  For example if the user specifies library foo using -flibs=foo the driver will check the standard GCC install directory for a sub directory foo containing the library contents.  The library module search path is altered accordingly for compile and link.

How to get source code using git
================================

GNU Modula-2 is now in the GCC git tree (https://gcc.gnu.org/git.html).

GNU Modula-2 Features
=====================

  * the compiler currently complies with Programming in Modula-2 Edition 2, 3, 4 and ISO Modula-2.  Users can switch on specific language features by using: -fpim, -fpim2, -fpim3, -fpim4 or -fiso.

  * the option -fswig will automatically create a swig interface file which corresponds to the definition module of the file being compiled.

  * exception handling is compatible with C++ and swig.  Modula-2 code can be used with C or C++ code.

  * Python can call GNU Modula-2 modules via swig.

  * shared libraries can be built.

  * fixed sized types are now available from SYSTEM.

  * variables can be declared at addresses.

  * much better dwarf-2 debugging support and when used with gdb the programmer can display RECORDs, ARRAYs, SETs, subranges and constant char literals in Modula-2 syntax.

  * supports sets of any ordinal size (memory permitting).

  * easy interface to C, and varargs can be passed to C routines.

  * many Logitech libraries have been implemented and can be accessed via: -flibs=m2log,m2pim,m2iso.

  * coroutines have been implemented in the PIM style and these are accessible from SYSTEM.  A number of supporting libraries (executive and file descriptor mapping to interrupt vector libraries are available through the -flibs=m2iso,m2pim switch).

  * can be built as a cross compiler (for embedded microprocessors such as the AVR and the ARM).

Using GNU Modula-2
******************

This document contains the user and design issues relevant to the Modula-2 front end to gcc.

Example compile and link
========================

The gm2 command is the GNU compiler for the Modula-2 language and supports many of the same options as gcc.  See Option Summary (Using the GNU Compiler Collection (GCC)). This manual only documents the options specific to gm2.

This section describes how to compile and link a simple hello world program.  It provides a few examples of using the different options mentioned in see Compiler options (gm2).  Assuming that you have a file called hello.mod in your current directory which contains:

     MODULE hello ;

     FROM StrIO IMPORT WriteString, WriteLn ;

     BEGIN
        WriteString ('hello world') ; WriteLn
     END hello.

You can compile and link it by: gm2 -g hello.mod. The result will be an a.out file created in your directory.

You can split this command into two steps if you prefer.  The compile step can be achieved by: gm2 -g -c -fscaffold-main hello.mod and the link via: gm2 -g hello.o.

 (To see all the compile actions taken by gm2 users can also add the -v flag at the command line, for example:

gm2 -v -g -I. hello.mod

This displays the sub processes initiated by gm2 which can be useful when trouble shooting.)

Compiler options
================

This section describes the compiler options specific to GNU Modula-2 for generic flags details see Invoking GCC (gcc).

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:

FILE.mod
     Modula-2 implementation or program source files.  See the -fmod= option if you wish to compile a project which uses a different source file extension.

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 -fdef= option if you wish to compile a project which uses a different source file extension.

You can specify more than one input file on the gm2 command line,

-g
     create debugging information so that debuggers such as gdb can inspect and control executable.

-I
     used to specify the search path for definition and implementation modules.  An example is:  gm2 -g -c -I.:../../libs foo.mod. 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.

-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.

-fbounds
     turns on run time subrange, array index and indirection via NIL pointer checking.

-fcase
     turns on compile time checking to check whether a CASE statement requires an ELSE clause when on was not specified.

-fcpp
     preprocess the source with cpp -lang-asm -traditional-cpp For further details about these options see Invocation (cpp). If -fcpp is supplied then all definition modules and implementation modules which are parsed will be prepossessed by cpp.

-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 a real function.

-fdef=
     recognize the specified suffix as a definition module filename. The default implementation and module filename suffix is .def. If this option is used GNU Modula-2 will still fall back to this default if a requested definition module is not found.

-fdump-system-exports
     display all inbuilt system items. This is an internal command line option.

-fexceptions
     turn on exception handling code.  By default this option is on. Exception handling can be disabled by -fno-exceptions and no references are made to the run time exception libraries.

-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.

-ffloatvalue
     turns on run time checking to check whether a floating point number is about to exceed range.

-fgen-module-list=filename
     attempt to find all modules when linking and generate a module list. If the filename is - then the contents are not written and only used to force the linking of all module ctors. This option cannot be used if -fuse-list= is enabled.

-findex
     generate code to check whether array index values are out of bounds. Array index checking can be disabled via -fno-index.

-fiso
     turn on ISO standard features.  Currently this enables the ISO SYSTEM 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 DIV and MOD operators. See Dialect (gm2).

-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 -fno-libs=- disables the gm2 driver from modifying the search and library paths.

-static-libgm2
     On systems that provide the m2 runtimes as both shared and static libraries, this option forces the use of the static version.

-fm2-g
     improve the debugging experience for new programmers at the expense of generating nop 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 IF statements where multiple END keywords are mapped onto a sequence of nop instructions.

-fm2-lower-case
     render keywords in error messages using lower case.

-fm2-pathname=
     specify the module mangled prefix name for all modules in the following include paths.

-fm2-pathnameI
     for internal use only: used by the driver to copy the user facing -I option.

-fm2-plugin
     insert plugin to identify run time errors at compile time (default on).

-fm2-prefix=
     specify the module mangled prefix name.  All exported symbols from a definition module will have the prefix name.

-fm2-statistics
     generates quadruple information: number of quadruples generated, number of quadruples remaining after optimization and number of source lines compiled.

-fm2-strict-type
     experimental flag to turn on the new strict type checker.

-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 -O3, can deliver huge performance improvements.

-fmod=
     recognize the specified suffix as implementation and module filenames. The default implementation and module filename suffix is .mod. 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.

-fnil
     generate code to detect accessing data through a NIL value pointer.  Dereferencing checking through a NIL pointer can be disabled by -fno-nil.

-fpim
     turn on PIM standard features.  Currently this enables the PIM SYSTEM module and determines which identifiers are pervasive (declared in the base module).  If no other -fpim[234] switch is used then division and modulus operators behave as defined in PIM4. See Dialect (gm2).

-fpim2
     turn on PIM-2 standard features.  Currently this removes SIZE from being a pervasive identifier (declared in the base module).  It places SIZE in the SYSTEM module.  It also effects the behavior of DIV and MOD operators. See Dialect (gm2).

-fpim3
     turn on PIM-3 standard features.  Currently this only effects the behavior of DIV and MOD operators. See Dialect (gm2).

-fpim4
     turn on PIM-4 standard features.  Currently this only effects the behavior of DIV and MOD operators. See Dialect (gm2).

-fpositive-mod-floor-div
     forces the DIV and MOD operators to behave as defined by PIM4. All modulus results are positive and the results from the division are rounded to the floor. See Dialect (gm2).

-fpthread
     link against the pthread library.  By default this option is on.  It can be disabled by -fno-pthread.  GNU Modula-2 uses the GCC pthread libraries to implement coroutines (see the SYSTEM implementation module).

-frange
     generate code to check the assignment range, return value range set range and constructor range.  Range checking can be disabled via -fno-range.

-freturn
     generate code to check that functions always exit with a RETURN and do not fall out at the end.  Return checking can be disabled via -fno-return.

-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 m2iso:RTentity,m2iso:Storage,m2iso:SYSTEM, m2iso:M2RTS,m2iso:RTExceptions,m2iso:IOLink.  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.

-fscaffold-dynamic
     the option ensures that gm2 will generate a dynamic scaffold infrastructure when compiling implementation and program modules. By default this option is on.  Use -fno-scaffold-dynamic to turn it off or select -fno-scaffold-static.

-fscaffold-c
     generate a C source scaffold for the current module being compiled.

-fscaffold-c++
     generate a C++ source scaffold for the current module being compiled.

-fscaffold-main
     force the generation of the main function.  This is not necessary if the -c is omitted.

-fscaffold-static
     the option ensures that gm2 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.

-fshared
     generate a shared library from the module.

-fsoft-check-all
     turns on all run time checks.  This is the same as invoking GNU Modula-2 using the command options -fnil -frange -findex -fwholevalue -fwholediv -fcase -freturn.

-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.

-fswig
     generate a swig interface file.

-funbounded-by-reference
     enable optimization of unbounded parameters by attempting to pass non VAR 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 VAR 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.

     Due to the dangerous nature of this option it is not enabled when the -O option is specified.

-fuse-list=filename
     if -fscaffold-static is enabled then use the file filename for the initialization order of modules.  Whereas if -fscaffold-dynamic is enabled then use this file to force linking of all module ctors. This option cannot be used if -fgen-module-list= is enabled.

-fwholediv
     generate code to detect whole number division by zero or modulus by zero.

-fwholevalue
     generate code to detect whole number overflow and underflow.

-Wcase-enum
     generate a warning if a CASE statement selects on an enumerated type expression and the statement is missing one or more CASE labels.  No warning is issued if the CASE statement has a default ELSE clause. The option -Wall will turn on this flag.

-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.

-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 known is specified.  If cond or all 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 -Wall will turn on this flag with -Wuninit-variable-checking=known. The -Wuninit-variable-checking=all will increase compile time.

This section describes the linking related options.  There are three linking strategies available which are dynamic scaffold, static scaffold and user defined.  The dynamic scaffold is enabled by default and each module will register itself to the run time M2RTS via a constructor.  The static scaffold mechanism will invoke each modules _init and _finish function in turn via a sequence of calls from within main.  Lastly the user defined strategy can be implemented by turning off the dynamic and static options via -fno-scaffold-dynamic and -fno-scaffold-static.

In the simple test below:

     $ gm2 hello.mod

the driver will add the options -fscaffold-dynamic and -fgen-module-list=- which generate a list of application modules and also creates the main function with calls to M2RTS.  It can be useful to add the option -fsources which displays the source files as they are parsed and summarizes whether the source file is required for compilation or linking.

If you wish to split the above command line into a compile and link then you could use these steps:

     $ gm2 -c -fscaffold-main hello.mod
     $ gm2 hello.o

The -fscaffold-main informs the compiler to generate the main function and scaffold.  You can enable the environment variable GCC_M2LINK_RTFLAG to trace the construction and destruction of the application.  The values for GCC_M2LINK_RTFLAG are shown in the table below:

     value   | meaning
     =================
     all     | turn on all flags below
     module  | trace modules as they register themselves
     hex     | display the hex address of the init/fini functions
     warning | show any warnings
     pre     | generate module list prior to dependency resolution
     dep     | trace module dependency resolution
     post    | generate module list after dependency resolution
     force   | generate a module list after dependency and forced
             | ordering is complete

The values can be combined using a comma separated list.

One of the advantages of the dynamic scaffold is that the driver behaves in a similar way to the other front end drivers. For example consider a small project consisting of 4 definition implementation modules (a.def, a.mod, b.def, b.mod, c.def, c.mod, d.def, d.mod) and a program module program.mod.

To link this project we could:

     $ gm2 -g -c a.mod
     $ gm2 -g -c b.mod
     $ gm2 -g -c c.mod
     $ gm2 -g -c d.mod
     $ gm2 -g program.mod a.o b.o c.o d.o

The module initialization sequence is defined by the ISO standard to follow the import graph traversal.  The initialization order is the order in which the corresponding separate modules finish the processing of their import lists.

However, if required, you can override this using -fruntime-modules=a,b,c,d for example which forces the initialization sequence to a, b, c and d.

Elementary data types
=====================

This section describes the elementary data types supported by GNU Modula-2.  It also describes the relationship between these data types and the equivalent C data types.

The following data types are supported: INTEGER, LONGINT, SHORTINT, CARDINAL, LONGCARD, SHORTCARD, BOOLEAN, REAL, LONGREAL, SHORTREAL, COMPLEX, LONGCOMPLEX, SHORTCOMPLEX and CHAR.

An equivalence table is given below:

     GNU Modula-2              GNU C
     ======================================
     INTEGER                   int
     LONGINT                   long long int
     SHORTINT                  short int
     CARDINAL                  unsigned int
     LONGCARD                  long long unsigned int
     SHORTCARD                 short unsigned int
     BOOLEAN                   bool
     REAL                      double
     LONGREAL                  long double
     SHORTREAL                 float
     CHAR                      char
     SHORTCOMPLEX              complex float
     COMPLEX                   complex double
     LONGCOMPLEX               complex long double

Note that GNU Modula-2 also supports fixed sized data types which are exported from the SYSTEM module. See The PIM system module (gm2). See The ISO system module (gm2).

Permanently accessible base procedures.
=======================================

This section describes the procedures and functions which are always visible.

Standard procedures and functions common to PIM and ISO
-------------------------------------------------------

The following procedures are implemented and conform with Programming in Modula-2 and ISO Modula-2: NEW, DISPOSE, INC, DEC, INCL, EXCL and HALT.  The standard functions are: ABS, CAP, CHR, FLOAT, HIGH, LFLOAT, LTRUNC, MIN, MAX, ODD, SFLOAT, STRUNC TRUNC and VAL.  All these functions and procedures (except HALT, NEW, DISPOSE and, under non constant conditions, LENGTH) generate in-line code for efficiency.

     (*
        ABS - returns the positive value of i.
     *)

     PROCEDURE ABS (i: <any signed type>) : <any signed type> ;

     (*
        CAP - returns the capital of character ch providing
              ch lies within the range 'a'..'z'.  Otherwise ch
              is returned unaltered.
     *)

     PROCEDURE CAP (ch: CHAR) : CHAR ;

     (*
        CHR - converts a value of a <whole number type> into a CHAR.
              CHR(x) is shorthand for VAL(CHAR, x).
     *)

     PROCEDURE CHR (x: <whole number type>) : CHAR ;

     (*
        DISPOSE - the procedure DISPOSE is replaced by:
                  DEALLOCATE(p, TSIZE(p^)) ;
                  The user is expected to import the procedure DEALLOCATE
                  (normally found in the module, Storage.)

                  In:  a variable p: of any pointer type which has been
                       initialized by a call to NEW.
                  Out: the area of memory
                       holding p^ is returned to the system.
                       Note that the underlying procedure DEALLOCATE
                       procedure in module Storage will assign p to NIL.
     *)

     PROCEDURE DISPOSE (VAR p:<any pointer type>) ;

     (*
        DEC - can either take one or two parameters.  If supplied
              with one parameter then on the completion of the call to
              DEC, v will have its predecessor value.  If two
              parameters are supplied then the value v will have its
              n'th predecessor.  For these reasons the value of n
              must be >=0.
     *)

     PROCEDURE DEC (VAR v: <any base type>; [n: <any base type> = 1]) ;

     (*
        EXCL - excludes bit element e from a set type s.
     *)

     PROCEDURE EXCL (VAR s: <any set type>; e: <element of set type s>) ;

     (*
        FLOAT - will return a REAL number whose value is the same as o.
     *)

     PROCEDURE FLOAT (o: <any whole number type>) : REAL ;

     (*
        FLOATS - will return a SHORTREAL number whose value is the same as o.
     *)

     PROCEDURE FLOATS (o: <any whole number type>) : REAL ;

     (*
        FLOATL - will return a LONGREAL number whose value is the same as o.
     *)

     PROCEDURE FLOATL (o: <any whole number type>) : REAL ;

     (*
        HALT - will call the HALT procedure inside the module M2RTS.
               Users can replace M2RTS.
     *)

     PROCEDURE HALT ;

     (*
        HIGH - returns the last accessible index of an parameter declared as
               ARRAY OF CHAR.  Thus

               PROCEDURE foo (a: ARRAY OF CHAR) ;
               VAR
                  c: CARDINAL ;
               BEGIN
                  c := HIGH(a)
               END foo ;

               BEGIN
                  foo('hello')
               END

               will cause the local variable c to contain the value 5
     *)

     PROCEDURE HIGH (a: ARRAY OF CHAR) : CARDINAL ;

     (*
        INC - can either take one or two parameters.  If supplied
              with one parameter then on the completion of the call to
              INC, v will have its successor value.  If two
              parameters are supplied then the value v will have its
              n'th successor.  For these reasons the value of n
              must be >=0.
     *)

     PROCEDURE INC (VAR v: <any base type>; [n: <any base type> = 1]) ;

     (*
        INCL - includes bit element e to a set type s.
     *)

     PROCEDURE INCL (VAR s: <any set type>; e: <element of set type s>) ;

     (*
        LFLOAT - will return a LONGREAL number whose value is the same as o.
     *)

     PROCEDURE LFLOAT (o: <any whole number type>) : LONGREAL ;

     (*
        LTRUNC - will return a LONG<type> number whose value is the
                 same as o.  PIM2, PIM3 and ISO Modula-2 will return
                 a LONGCARD whereas PIM4 returns LONGINT.
     *)

     PROCEDURE LTRUNC (o: <any floating point type>) : LONG<type> ;

     (*
        MIN - returns the lowest legal value of an ordinal type.
     *)

     PROCEDURE MIN (t: <ordinal type>) : <ordinal type> ;

     (*
        MAX - returns the largest legal value of an ordinal type.
     *)

     PROCEDURE MAX (t: <ordinal type>) : <ordinal type> ;

     (*
        NEW - the procedure NEW is replaced by:
              ALLOCATE(p, TSIZE(p^)) ;
              The user is expected to import the procedure ALLOCATE
              (normally found in the module, Storage.)

              In:  a variable p: of any pointer type.
              Out: variable p is set to some allocated memory
                   which is large enough to hold all the contents of p^.
     *)

     PROCEDURE NEW (VAR p:<any pointer type>) ;

     (*
        ODD - returns TRUE if the value is not divisible by 2.
     *)

     PROCEDURE ODD (x: <whole number type>) : BOOLEAN ;

     (*
        SFLOAT - will return a SHORTREAL number whose value is the same
                 as o.
     *)

     PROCEDURE SFLOAT (o: <any whole number type>) : SHORTREAL ;

     (*
        STRUNC - will return a SHORT<type> number whose value is the same
                 as o.  PIM2, PIM3 and ISO Modula-2 will return a
                 SHORTCARD whereas PIM4 returns SHORTINT.
     *)

     PROCEDURE STRUNC (o: <any floating point type>) : SHORT<type> ;

     (*
        TRUNC - will return a <type> number whose value is the same as o.
                PIM2, PIM3 and ISO Modula-2 will return a CARDINAL
                whereas PIM4 returns INTEGER.
     *)

     PROCEDURE TRUNC (o: <any floating point type>) : <type> ;

     (*
        TRUNCS - will return a <type> number whose value is the same
                 as o.  PIM2, PIM3 and ISO Modula-2 will return a
                 SHORTCARD whereas PIM4 returns SHORTINT.
     *)

     PROCEDURE TRUNCS (o: <any floating point type>) : <type> ;

     (*
        TRUNCL - will return a <type> number whose value is the same
                 as o.  PIM2, PIM3 and ISO Modula-2 will return a
                 LONGCARD whereas PIM4 returns LONGINT.
     *)

     PROCEDURE TRUNCL (o: <any floating point type>) : <type> ;

     (*
        VAL - converts data i of <any simple data type 2> to
              <any simple data type 1> and returns this value.
              No range checking is performed during this conversion.
     *)

     PROCEDURE VAL (<any simple data type 1>,
                    i: <any simple data type 2>) : <any simple data type 1> ;

ISO specific standard procedures and functions
----------------------------------------------

The standard function LENGTH is specific to ISO Modula-2 and is defined as:

     (*
        IM - returns the imaginary component of a complex type.
             The return value will the same type as the imaginary field
             within the complex type.
     *)

     PROCEDURE IM (c: <any complex type>) : <floating point type> ;

     (*
        INT - returns an INTEGER value which has the same value as v.
              This function is equivalent to: VAL(INTEGER, v).
     *)

     PROCEDURE INT (v: <any ordinal type>) : INTEGER ;

     (*
        LENGTH - returns the length of string a.
     *)

     PROCEDURE LENGTH (a: ARRAY OF CHAR) : CARDINAL ;

This function is evaluated at compile time, providing that string a is a constant.  If a cannot be evaluated then a call is made to M2RTS.Length.

     (*
        ODD - returns a BOOLEAN indicating whether the whole number
              value, v, is odd.
     *)

     PROCEDURE ODD (v: <any whole number type>) : BOOLEAN ;

     (*
        RE - returns the real component of a complex type.
             The return value will the same type as the real field
             within the complex type.
     *)

     PROCEDURE RE (c: <any complex type>) : <floating point type> ;

Behavior of the high procedure function
=======================================

This section describes the behavior of the standard procedure function HIGH and it includes a table of parameters with the expected return result.  The standard procedure function will return the last accessible indice of an ARRAY.  If the parameter to HIGH is a static array then the result will be a CARDINAL value matching the upper bound in the ARRAY declaration.

The section also describes the behavior of a string literal actual parameter and how it relates to HIGH. The PIM2, PIM3, PIM4 and ISO standard is silent on the issue of whether a nul is present in an ARRAY OF CHAR actual parameter.

If the first parameter to HIGH is an unbounded ARRAY the return value from HIGH will be the last accessible element in the array.  If a constant string literal is passed as an actual parameter then it will be nul terminated.  The table and example code below describe the effect of passing an actual parameter and the expected HIGH value.

     MODULE example1 ;

     PROCEDURE test (a: ARRAY OF CHAR) ;
     VAR
        x: CARDINAL ;
     BEGIN
        x := HIGH (a) ;
        ...
     END test ;

     BEGIN
        test ('') ;
        test ('1') ;
        test ('12') ;
        test ('123') ;
     END example1.

     Actual parameter | HIGH (a) | a[HIGH (a)] = nul
     ===============================================
      ''              | 0        | TRUE
      '1'             | 1        | TRUE
      '12'            | 2        | TRUE
      '123'           | 3        | TRUE

A constant string literal will be passed to an ARRAY OF CHAR with an appended nul CHAR.  Thus if the constant string literal '' is passed as an actual parameter (in example1) then the result from HIGH(a) will be 0.

     MODULE example2 ;

     PROCEDURE test (a: ARRAY OF CHAR) ;
     VAR
        x: CARDINAL ;
     BEGIN
        x := HIGH (a) ;
        ...
     END test ;

     VAR
        str0: ARRAY [0..0] OF CHAR ;
        str1: ARRAY [0..1] OF CHAR ;
        str2: ARRAY [0..2] OF CHAR ;
        str3: ARRAY [0..3] OF CHAR ;
     BEGIN
        str0 := 'a' ;   (* No room for the nul terminator.  *)
        test (str0) ;
        str1 := 'ab' ;  (* No room for the nul terminator.  *)
        test (str1) ;
        str2 := 'ab' ;  (* Terminated with a nul.  *)
        test (str2) ;
        str2 := 'abc' ; (* Terminated with a nul.  *)
        test (str3) ;
     END example2.

     Actual parameter | HIGH (a) | a[HIGH (a)] = nul
     ===============================================
      str0            | 0        | FALSE
      str1            | 1        | FALSE
      atr2            | 2        | TRUE
      str3            | 3        | TRUE

GNU Modula-2 supported dialects
===============================

This section describes the dialects understood by GNU Modula-2. It also describes the differences between the dialects and any command line switches which determine dialect behaviour.

The GNU Modula-2 compiler is compliant with four dialects of Modula-2. The language as defined in 'Programming in Modula-2' 2nd Edition, Springer Verlag, 1982, 1983 by Niklaus Wirth (PIM2), 'Programming in Modula-2', 3rd Corrected Edition, Springer Verlag, 1985 (PIM3) and 'Programming in Modula-2', 4th Edition, Springer Verlag, 1988 (PIM4) http://freepages.modula2.org/report4/modula-2.html and the ISO Modula-2 language as defined in ISO/IEC Information technology - programming languages - part 1: Modula-2 Language, ISO/IEC 10514-1 (1996) (ISO).

The command line switches -fpim2, -fpim3, -fpim4 and -fiso can be used to force mutually exclusive features.  However by default the compiler will not aggressively fail if a non mutually exclusive feature is used from another dialect.  For example it is possible to specify -fpim2 and still utilize DEFINITION MODULES which have no export list.

Some dialect differences will force a compile time error, for example in PIM2 the user must IMPORT SIZE from the module SYSTEM, whereas in PIM3 and PIM4 SIZE is a pervasive function.  Thus compiling PIM4 source code with the -fpim2 switch will cause a compile time error.  This can be fixed quickly with an additional IMPORT or alternatively by compiling with the -fpim4 switch.

However there are some very important differences between the dialects which are mutually exclusive and therefore it is vital that users choose the dialects with care when these language features are used.

Integer division, remainder and modulus
---------------------------------------

The most dangerous set of mutually exclusive features found in the four dialects supported by GNU Modula-2 are the INTEGER division, remainder and modulus arithmetic operators.  It is important to note that the same source code can be compiled to give different run time results depending upon these switches!  The reference manual for the various dialects of Modula-2 are quite clear about this behavior and sadly there are three distinct definitions.

The table below illustrates the problem when a negative operand is used.

                       Pim2/3          Pim4                ISO
                    -----------    -----------    ----------------------
     lval    rval   DIV     MOD    DIV     MOD    DIV    MOD    /    REM
      31      10      3       1      3       1      3      1     3     1
     -31      10     -3      -1     -4       9     -4      9    -3    -1
      31     -10     -3       1     -3       1     Exception    -3     1
     -31     -10      3      -1      4       9     Exception     3    -1

See also P24 of PIM2, P27 of PIM3, P29 of PIM4 and P201 of the ISO Standard.  At present all dialect division, remainder and modulus are implemented as above, apart from the exception calling in the ISO dialect.  Instead of exception handling the results are the same as the PIM4 dialect.  This is a temporary implementation situation.

Exception implementation
========================

This section describes how exceptions are implemented in GNU Modula-2 and how command line switches affect their behavior.  The option -fsoft-check-all enables all software checking of nil dereferences, division by zero etc.  Additional code is produced to check these conditions and exception handlers are invoked if the conditions prevail.

Without -fsoft-check-all these exceptions will be caught by hardware (assuming the hardware support exists) and a signal handler is invoked.  The signal handler will in turn THROW an exception which will be caught by the appropriate Modula-2 handler.  However the action of throwing an exception from within a signal handler is implementation defined (according to the C++ documentation).  For example on the x86_64 architecture this works whereas on the i686 architecture it does not.  Therefore to ensure portability it is recommended to use -fsoft-check-all.

 (-fsoft-check-all can be effectively combined with -O2 to semantically analyze source code for possible run time errors at compile time.)

How to detect run time problems at compile time
===============================================

Consider the following program:

     MODULE assignvalue ;  (*!m2iso+gm2*)

     PROCEDURE bad () : INTEGER ;
     VAR
        i: INTEGER ;
     BEGIN
        i := -1 ;
        RETURN i
     END bad ;

     VAR
        foo: CARDINAL ;
     BEGIN
        (* The m2rte plugin will detect this as an error, post
           optimization.  *)
        foo := bad ()
     END assignvalue.

here we see that the programmer has overlooked that the return value from bad will cause an overflow to foo.  If we compile the code with the following options:

     $ gm2 -g -fsoft-check-all -O2 -c assignvalue.mod
     assignvalue.mod:16:0:inevitable that this error will occur at run time,
     assignment will result in an overflow

The gm2 semantic plugin is automatically run and will generate a warning message for every exception call which is known as reachable. It is highly advised to run the optimizer (-O2 or -O3) with -fsoft-check-all so that the compiler is able to run the optimizer and perform variable and flow analysis before the semantic plugin is invoked.

The -Wuninit-variable-checking can be used to identify uninitialized variables within the first basic block in a procedure. The checking is limited to variables so long as they are not an array or set or a variant record or var parameter.

The following example detects whether a sub component within a record is uninitialized.

     MODULE testlarge2 ;

     TYPE
        color = RECORD
                   r, g, b: CARDINAL ;
                END ;

        pixel = RECORD
                   fg, bg: color ;
                END ;

     PROCEDURE test ;
     VAR
        p: pixel ;
     BEGIN
        p.fg.r := 1 ;
        p.fg.g := 2 ;
        p.fg.g := 3 ;   (* Deliberate typo should be p.fg.b.  *)
        p.bg := p.fg ;  (* Accessing an uninitialized field.  *)
     END test ;

     BEGIN
        test
     END testlarge2.

     $ gm2 -c -Wuninit-variable-checking testlarge2.mod
     testlarge2.mod:19:13: warning: In procedure ‘test’: attempting to
     access expression before it has been initialized
        19 |    p.bg := p.fg ;  (* Accessing an uninitialized field.  *)
           |            ~^~~

The following example detects if an individual field is uninitialized.

     MODULE testwithnoptr ;

     TYPE
        Vec =  RECORD
                  x, y: CARDINAL ;
               END ;

     PROCEDURE test ;
     VAR
        p: Vec ;
     BEGIN
        WITH p DO
           x := 1 ;
           x := 2   (* Deliberate typo, user meant y.  *)
        END ;
        IF p.y = 2
        THEN
        END
     END test ;

     BEGIN
        test
     END testwithnoptr.

The following example detects a record is uninitialized via a pointer variable in a WITH block.

     $ gm2 -g -c -Wuninit-variable-checking testwithnoptr.mod
     testwithnoptr.mod:21:8: warning: In procedure ‘test’: attempting to
     access expression before it has been initialized
        21 |    IF p.y = 2
           |       ~^~

     MODULE testnew6 ;

     FROM Storage IMPORT ALLOCATE ;

     TYPE
        PtrToVec = POINTER TO RECORD
                                 x, y: INTEGER ;
                              END ;

     PROCEDURE test ;
     VAR
        p: PtrToVec ;
     BEGIN
        NEW (p) ;
        WITH p^ DO
           x := 1 ;
           x := 2   (* Deliberate typo, user meant y.  *)
        END ;
        IF p^.y = 2
        THEN
        END
     END test ;

     BEGIN
        test
     END testnew6.

     $ gm2 -g -c -Wuninit-variable-checking testnew6.mod
     testnew6.mod:19:9: warning: In procedure ‘test’: attempting to
     access expression before it has been initialized
        19 |    IF p^.y = 2
           |       ~~^~

GNU Modula-2 language extensions
================================

This section introduces the GNU Modula-2 language extensions. The GNU Modula-2 compiler allows abstract data types to be any type, not just restricted to a pointer type providing the -fextended-opaque option is supplied see Compiler options (gm2).

Declarations can be made in any order, whether they are types, constants, procedures, nested modules or variables.

GNU Modula-2 also allows programmers to interface to C and assembly language.

GNU Modula-2 provides support for the special tokens __LINE__, __FILE__, __FUNCTION__ and __DATE__.  Support for these tokens will occur even if the -fcpp option is not supplied.  A table of these identifiers and their data type and values is given below:

     Scope       GNU Modula-2 token      Data type and example value

     anywhere    __LINE__                Constant Literal compatible
                                         with CARDINAL, INTEGER and WORD.
                                         Example 1234

     anywhere    __FILE__                Constant string compatible
                                         with parameter ARRAY OF CHAR or
                                         an ARRAY whose SIZE is >= string
                                         length.  Example
                                         "hello.mod"

     procedure   __FUNCTION__            Constant string compatible
                                         with parameter ARRAY OF CHAR or
                                         an ARRAY whose SIZE is >= string
                                         length.  Example
                                         "calc"

     module      __FUNCTION__            Example
                                         "module hello initialization"

     anywhere    __DATE__                Constant string compatible
                                         with parameter ARRAY OF CHAR or
                                         an ARRAY whose SIZE is >= string
                                         length.  Example
                                         "Thu Apr 29 10:07:16 BST 2004"

     anywhere   __COLUMN__               Gives a constant literal number
                                         determining the left hand column
                                         where the first _ appears in
                                         __COLUMN__.  The left most column
                                         is 1.

The preprocessor cpp can be invoked via the -fcpp command line option.  This in turn invokes cpp with the following arguments -traditional -lang-asm.  These options preserve comments and all quotations.  gm2 treats a # character in the first column as a preprocessor directive.

For example here is a module which calls FatalError via the macro ERROR.

     MODULE cpp ;

     FROM SYSTEM IMPORT ADR, SIZE ;
     FROM libc IMPORT exit, printf, malloc ;

     PROCEDURE FatalError (a, file: ARRAY OF CHAR;
                              line: CARDINAL;
                              func: ARRAY OF CHAR) ;
     BEGIN
        printf ("%s:%d:fatal error, %s, in %s\n",
                 ADR (file), line, ADR (a), ADR (func)) ;
        exit (1)
     END FatalError ;

     #define ERROR(X)  FatalError(X, __FILE__, __LINE__, __FUNCTION__)

     VAR
        pc: POINTER TO CARDINAL;
     BEGIN
        pc := malloc (SIZE (CARDINAL)) ;
        IF pc = NIL
        THEN
           ERROR ('out of memory')
        END
     END cpp.

Another use for the C preprocessor in Modula-2 might be to turn on debugging code.  For example the library module FormatStrings.mod uses procedures from DynamicStrings.mod and to track down memory leaks it was useful to track the source file and line where each string was created.  Here is a section of FormatStrings.mod which shows how the debugging code was enabled and disabled by adding -fcpp to the command line.

     FROM DynamicStrings IMPORT String, InitString, InitStringChar, Mark,
                                ConCat, Slice, Index, char,
                                Assign, Length, Mult, Dup, ConCatChar,
                                PushAllocation, PopAllocationExemption,
                                InitStringDB, InitStringCharStarDB,
                                InitStringCharDB, MultDB, DupDB, SliceDB ;

     (*
     #define InitString(X) InitStringDB(X, __FILE__, __LINE__)
     #define InitStringCharStar(X) InitStringCharStarDB(X, __FILE__, \
                                                        __LINE__)
     #define InitStringChar(X) InitStringCharDB(X, __FILE__, __LINE__)
     #define Mult(X,Y) MultDB(X, Y, __FILE__, __LINE__)
     #define Dup(X) DupDB(X, __FILE__, __LINE__)
     #define Slice(X,Y,Z) SliceDB(X, Y, Z, __FILE__, __LINE__)
     *)

     PROCEDURE doDSdbEnter ;
     BEGIN
        PushAllocation
     END doDSdbEnter ;

     PROCEDURE doDSdbExit (s: String) ;
     BEGIN
        s := PopAllocationExemption (TRUE, s)
     END doDSdbExit ;

     PROCEDURE DSdbEnter ;
     BEGIN
     END DSdbEnter ;

     PROCEDURE DSdbExit (s: String) ;
     BEGIN
     END DSdbExit ;

     (*
     #define DBsbEnter doDBsbEnter
     #define DBsbExit  doDBsbExit
     *)

     PROCEDURE Sprintf1 (s: String; w: ARRAY OF BYTE) : String ;
     BEGIN
        DSdbEnter ;
        s := FormatString (HandleEscape (s), w) ;
        DSdbExit (s) ;
        RETURN s
     END Sprintf1 ;

It is worth noting that the overhead of this code once -fcpp is not present and -O2 is used will be zero since the local empty procedures DSdbEnter and DSdbExit will be thrown away by the optimization passes of the GCC backend.

Optional procedure parameter
----------------------------

GNU Modula-2 allows the last parameter to a procedure or function parameter to be optional.  For example in the ISO library COROUTINES.def the procedure NEWCOROUTINE is defined as having an optional fifth argument (initProtection) which, if absent, is automatically replaced by NIL.

     PROCEDURE NEWCOROUTINE (procBody: PROC; workspace: SYSTEM.ADDRESS;
                             size: CARDINAL; VAR cr: COROUTINE;
                             [initProtection: PROTECTION = NIL]);

       (* Creates a new coroutine whose body is given by procBody,
          and returns the identity of the coroutine in cr.
          workspace is a pointer to the work space allocated to
          the coroutine; size specifies the size of this workspace
          in terms of SYSTEM.LOC.

          The optional fifth argument may contain a single parameter
          which specifies the initial protection level of the coroutine.
       *)

The implementation module COROUTINES.mod implements this procedure using the following syntax:

     PROCEDURE NEWCOROUTINE (procBody: PROC; workspace: SYSTEM.ADDRESS;
                             size: CARDINAL; VAR cr: COROUTINE;
                             [initProtection: PROTECTION]);
     BEGIN

     END NEWCOROUTINE ;

Note that it is illegal for this declaration to contain an initializer value for initProtection.  However it is necessary to surround this parameter with the brackets [ and ].  This serves to remind the programmer that the last parameter was declared as optional in the definition module.

Local procedures can be declared to have an optional final parameter in which case the initializer is mandatory in the implementation or program module.

GNU Modula-2 also provides additional fixed sized data types which are all exported from the SYSTEM module. See The PIM system module (gm2). See The ISO system module (gm2).

Type compatibility
==================

This section discuss the issues surrounding assignment, expression and parameter compatibility, their effect of the additional fixed sized datatypes and also their effect of run time checking. The data types supported by the compiler are:

     GNU Modula-2              scope      switches
     =============================================
     INTEGER                   pervasive
     LONGINT                   pervasive
     SHORTINT                  pervasive
     CARDINAL                  pervasive
     LONGCARD                  pervasive
     SHORTCARD                 pervasive
     BOOLEAN                   pervasive
     BITSET                    pervasive
     REAL                      pervasive
     LONGREAL                  pervasive
     SHORTREAL                 pervasive
     CHAR                      pervasive
     SHORTCOMPLEX              pervasive
     COMPLEX                   pervasive
     LONGCOMPLEX               pervasive

     LOC                       SYSTEM     -fiso
     BYTE                      SYSTEM
     WORD                      SYSTEM
     ADDRESS                   SYSTEM

     The following extensions are supported for
     most architectures (please check SYSTEM.def).
     =============================================
     INTEGER8                  SYSTEM
     INTEGER16                 SYSTEM
     INTEGER32                 SYSTEM
     INTEGER64                 SYSTEM
     CARDINAL8                 SYSTEM
     CARDINAL16                SYSTEM
     CARDINAL32                SYSTEM
     CARDINAL64                SYSTEM
     BITSET8                   SYSTEM
     BITSET16                  SYSTEM
     BITSET32                  SYSTEM
     WORD16                    SYSTEM
     WORD32                    SYSTEM
     WORD64                    SYSTEM
     REAL32                    SYSTEM
     REAL64                    SYSTEM
     REAL96                    SYSTEM
     REAL128                   SYSTEM
     COMPLEX32                 SYSTEM
     COMPLEX64                 SYSTEM
     COMPLEX96                 SYSTEM
     COMPLEX128                SYSTEM

The Modula-2 language categorizes compatibility between entities of possibly differing types into three sub components: expressions, assignments, and parameters.  Parameter compatibility is further divided into two sections for pass by reference and pass by value compatibility.

For more detail on the Modula-2 type compatibility see the Modula-2 ISO standard BS ISO/IEC 10514-1:1996 page 121-125.  For detail on the PIM type compatibility see Programming in Modula-2 Edition 4 page 29, (Elementary Data Types).

Expression compatibility
------------------------

Modula-2 restricts the types of expressions to the same type. Expression compatibility is a symmetric relation.

For example two sub expressions of INTEGER and CARDINAL are not expression compatible (http://freepages.modula2.org/report4/modula-2.html and ISO Modula-2).

In GNU Modula-2 this rule is also extended across all fixed sized data types (imported from SYSTEM).

Assignment compatibility
------------------------

This section discusses the assignment issues surrounding assignment compatibility of elementary types (INTEGER, CARDINAL, REAL and CHAR for example).  The information here is found in more detail in the Modula-2 ISO standard BS ISO/IEC 10514-1:1996 page 122.

Assignment compatibility exists between the same sized elementary types.

Same type family of different sizes are also compatible as long as the MAX(type) and MIN(type) is known.  So for example this includes the INTEGER family, CARDINAL family and the REAL family.

The reason for this is that when the assignment is performed the compiler will check to see that the expression (on the right of the :=) lies within the range of the designator type (on the left hand side of the :=).  Thus these ordinal types can be assignment compatible.  However it does mean that WORD32 is not compatible with WORD16 as WORD32 does not have a minimum or maximum value and therefore cannot be checked.  The compiler does not know which of the two bytes from WORD32 should be copied into WORD16 and which two should be ignored.  Currently the types BITSET8, BITSET16 and BITSET32 are assignment incompatible.  However this restriction maybe lifted when further run time checking is achieved.

Modula-2 does allow INTEGER to be assignment compatible with WORD as they are the same size.  Likewise GNU Modula-2 allows INTEGER16 to be compatible with WORD16 and the same for the other fixed sized types and their sized equivalent in either WORDn, BYTE or LOC types.  However it prohibits assignment between WORD and WORD32 even though on many systems these sizes will be the same.  The reasoning behind this rule is that the extended fixed sized types are meant to be used by applications requiring fixed sized data types and it is more portable to forbid the blurring of the boundaries between fixed sized and machine dependent sized types.

Intermediate code run time checking is always generated by the front end.  However this intermediate code is only translated into actual code if the appropriate command line switches are specified.  This allows the compiler to perform limited range checking at compile time. In the future it will allow the extensive GCC optimizations to propagate constant values through to the range checks which if they are found to exceed the type range will result in a compile time error message.

Parameter compatibility
-----------------------

Parameter compatibility is divided into two areas, pass by value and pass by reference (VAR).  In the case of pass by value the rules are exactly the same as assignment.  However in the second case, pass by reference, the actual parameter and formal parameter must be the same size and family.  Furthermore INTEGER and CARDINALs are not treated as compatible in the pass by reference case.

The types BYTE, LOC, WORD and WORDn derivatives are assignment and parameter compatible with any data type of the same size.

Unbounded by reference
======================

This section documents a GNU Modula-2 compiler switch which implements a language optimization surrounding the implementation of unbounded arrays.  In GNU Modula-2 the unbounded array is implemented by utilizing an internal structure struct {dataType *address, unsigned int high}.  So given the Modula-2 procedure declaration:

     PROCEDURE foo (VAR a: ARRAY OF dataType) ;
     BEGIN
        IF a[2]= (* etc *)
     END foo ;

it is translated into GCC trees, which can be represented in their C form thus:

     void foo (struct {dataType *address, unsigned int high} a)
     {
        if (a.address[2] == /* etc */
     }

Whereas if the procedure foo was declared as:

     PROCEDURE foo (a: ARRAY OF dataType) ;
     BEGIN
        IF a[2]= (* etc *)
     END foo ;

then it is implemented by being translated into the following GCC trees, which can be represented in their C form thus:

     void foo (struct {dataType *address, unsigned int high} a)
     {
        dataType *copyContents = (dataType *)alloca (a.high+1);
        memcpy(copyContents, a.address, a.high+1);
        a.address = copyContents;

        if (a.address[2] == /* etc */
     }

This implementation works, but it makes a copy of each non VAR unbounded array when a procedure is entered.  If the unbounded array is not changed during procedure foo then this implementation will be very inefficient.  In effect Modula-2 lacks the REF keyword of Ada.  Consequently the programmer maybe tempted to sacrifice semantic clarity for greater efficiency by declaring the parameter using the VAR keyword in place of REF.

The -funbounded-by-reference switch instructs the compiler to check and see if the programmer is modifying the content of any unbounded array.  If it is modified then a copy will be made upon entry into the procedure.  Conversely if the content is only read and never modified then this non VAR unbounded array is a candidate for being passed by reference.  It is only a candidate as it is still possible that passing this parameter by reference could alter the meaning of the source code.  For example consider the following case:

     PROCEDURE StrConCat (VAR a: ARRAY OF CHAR; b, c: ARRAY OF CHAR) ;
     BEGIN
        (* code which performs string a := b + c *)
     END StrConCat ;

     PROCEDURE foo ;
     VAR
        a: ARRAY [0..3] OF CHAR ;
     BEGIN
        a := 'q' ;
        StrConCat(a, a, a)
     END foo ;

In the code above we see that the same parameter, a, is being passed three times to StrConCat.  Clearly even though parameters b and c are never modified it would be incorrect to implement them as pass by reference.  Therefore the compiler checks to see if any non VAR parameter is type compatible with any VAR parameter and if so it generates run time procedure entry checks to determine whether the contents of parameters b or c matches the contents of a.  If a match is detected then a copy is made and the address in the unbounded structure is modified.

The compiler will check the address range of each candidate against the address range of any VAR parameter, providing they are type compatible.  For example consider:

     PROCEDURE foo (a: ARRAY OF BYTE; VAR f: REAL) ;
     BEGIN
        f := 3.14 ;
        IF a[0]=BYTE(0)
        THEN
           (* etc *)
        END
     END foo ;

     PROCEDURE bar ;
     BEGIN
        r := 2.0 ;
        foo(r, r)
     END bar ;

Here we see that although parameter, a, is a candidate for the passing by reference, it would be incorrect to use this transformation.  Thus the compiler detects that parameters, a and f are type compatible and will produce run time checking code to test whether the address range of their respective contents intersect.

Building a shared library
=========================

This section describes building a tiny shared library implemented in Modula-2 and built with libtool.  Suppose a project consists of two definition modules and two implementation modules and a program module a.def, a.mod, b.def, b.mod and c.mod.  The first step is to compile the modules using position independent code.  This can be achieved by the following three commands:

     libtool --tag=CC --mode=compile gm2 -g -c a.mod -o a.lo
     libtool --tag=CC --mode=compile gm2 -g -c b.mod -o b.lo
     libtool --tag=CC --mode=compile gm2 -g -c c.mod -o c.lo

The second step is to generate the shared library initialization and finalization routines.  We can do this by asking gm2 to generate a list of dependent modules and then use this to generate the scaffold. We also must compile the scaffold.

     gm2 -c -g -fmakelist c.mod
     gm2 -c -g -fmakeinit -fshared c.mod
     libtool --tag=CC --mode=compile g++ -g -c c_m2.cpp -o c_m2.lo

The third step is to link all these .lo files.

     libtool --mode=link gcc -g c_m2.lo a.lo b.lo c.lo \
             -L$(prefix)/lib64 \
             -rpath `pwd` -lgm2 -lstdc++ -lm -o libabc.la

At this point the shared library libabc.so will have been created inside the directory .libs.

How to produce swig interface files
===================================

This section describes how Modula-2 implementation modules can be called from Python (and other scripting languages such as TCL and Perl).  GNU Modula-2 can be instructed to create a swig interface when it is compiling an implementation module.  Swig then uses the interface file to generate all the necessary wrapping to that the desired scripting language may access the implementation module.

Here is an example of how you might call upon the services of the Modula-2 library module NumberIO from Python3.

The following commands can be used to generate the Python3 module:

     export src=directory to the sources
     export prefix=directory to where the compiler is installed
     gm2 -I${src} -c -g -fswig ${src}/../../../gm2-libs/NumberIO.mod
     gm2 -I${src} -c -g -fmakelist ${src}/../../../gm2-libs/NumberIO.mod

     gm2 -I${src} -c -g -fmakeinit -fshared \
        ${src}/../../../gm2-libs/NumberIO.mod

     swig -c++ -python3 NumberIO.i

     libtool --mode=compile g++ -g -c -I${src} NumberIO_m2.cpp \
       -o NumberIO_m2.lo

     libtool --tag=CC --mode=compile gm2 -g -c \
       -I${src}../../../gm2-libs \
       ${src}/../../../gm2-libs/NumberIO.mod -o NumberIO.lo

     libtool --tag=CC --mode=compile g++ -g -c NumberIO_wrap.cxx \
       -I/usr/include/python3 -o NumberIO_wrap.lo

     libtool --mode=link gcc -g NumberIO_m2.lo NumberIO_wrap.lo \
        -L${prefix}/lib64 \
        -rpath `pwd` -lgm2 -lstdc++ -lm -o libNumberIO.la

     cp .libs/libNumberIO.so _NumberIO.so

The first four commands, generate the swig interface file NumberIO.i and python wrap files NumberIO_wrap.cxx and NumberIO.py.  The next three libtool commnads compile the C++ and Modula-2 source code into .lo objects.  The last libtool command links all the .lo files into a .la file and includes all shared library dependencies.

Now it is possible to run the following Python script (called testnum.py):

     import NumberIO

     print ("1234 x 2 =", NumberIO.NumberIO_StrToInt("1234")*2)

like this:

     $ python3 testnum.py
     1234 x 2 = 2468

See Producing a Python module (gm2) for another example which uses the UNQUALIFIED keyword to reduce the module name clutter from the viewport of Python3.

Limitations of automatic generated of Swig files
------------------------------------------------

This section discusses the limitations of automatically generating swig files.  From the previous example we see that the module NumberIO had a swig interface file NumberIO.i automatically generated by the compiler.  If we consider three of the procedure definitions in NumberIO.def we can see the success and limitations of the automatic interface generation.

     PROCEDURE StrToHex (a: ARRAY OF CHAR; VAR x: CARDINAL) ;
     PROCEDURE StrToInt (a: ARRAY OF CHAR; VAR x: INTEGER) ;
     PROCEDURE ReadInt (VAR x: CARDINAL) ;

Below are the swig interface prototypes:

     extern void NumberIO_StrToHex (char *_m2_address_a,
                                    int _m2_high_a, unsigned int *OUTPUT);
     /*  parameters: x is known to be an OUTPUT */
     extern void NumberIO_StrToInt (char *_m2_address_a,
                                    int _m2_high_a, int *OUTPUT);
     /*  parameters: x is guessed to be an OUTPUT */
     extern void NumberIO_ReadInt (int *x);
     /*  parameters: x is unknown */

In the case of StrToHex it can be seen that the compiler detects that the last parameter is an output.  It explicitly tells swig this by using the parameter name OUTPUT and in the following comment it informs the user that it knows this to be an output parameter.  In the second procedure StrToInt it marks the final parameter as an output, but it tells the user that this is only a guess.  Finally in ReadInt it informs the user that it does not know whether the parameter, x, is an output, input or an inout parameter.

The compiler decides whether to mark a parameter as either: INPUT, OUTPUT or INOUT if it is read before written or visa versa in the first basic block.  At this point it will write output that the parameter is known.  If it is not read or written in the first basic block then subsequent basic blocks are searched and the result is commented as a guess.  Finally if no read or write occurs then the parameter is commented as unknown. However, clearly it is possible to fool this mechanism.  Nevertheless automatic generation of implementation module into swig interface files was thought sufficiently useful despite these limitations.

In conclusion it would be wise to check all parameters in any automatically generated swig interface file.  Furthermore you can force the automatic mechanism to generate correct interface files by reading or writing to the VAR parameter in the first basic block of a procedure.

How to produce a Python module
==============================

This section describes how it is possible to produce a Python module from Modula-2 code.  There are a number of advantages to this approach, it ensures your code reaches a wider audience, maybe it is easier to initialize your application in Python.

The example application here is a pedagogical two dimensional gravity next event simulation.  The Python module needs to have a clear API which should be placed in a single definition module.  Furthermore the API should only use fundamental pervasive data types and strings. Below the API is contained in the file twoDsim.def:

     DEFINITION MODULE twoDsim ;

     EXPORT UNQUALIFIED gravity, box, poly3, poly5, poly6, mass,
                        fix, circle, pivot, velocity, accel, fps,
                        replayRate, simulateFor ;
     (*
        gravity - turn on gravity at: g m^2
     *)

     PROCEDURE gravity (g: REAL) ;

     (*
        box - place a box in the world at (x0,y0),(x0+i,y0+j)
     *)

     PROCEDURE box (x0, y0, i, j: REAL) : CARDINAL ;

     (*
        poly3 - place a triangle in the world at:
                (x0,y0),(x1,y1),(x2,y2)
     *)

     PROCEDURE poly3 (x0, y0, x1, y1, x2, y2: REAL) : CARDINAL ;

     (*
        poly5 - place a pentagon in the world at:
                (x0,y0),(x1,y1),(x2,y2),(x3,y3),(x4,y4)
     *)

     PROCEDURE poly5 (x0, y0, x1, y1,
                      x2, y2, x3, y3, x4, y4: REAL) : CARDINAL ;

     (*
        poly6 - place a hexagon in the world at:
                (x0,y0),(x1,y1),(x2,y2),(x3,y3),(x4,y4),(x5,y5)
     *)

     PROCEDURE poly6 (x0, y0, x1, y1,
                      x2, y2, x3, y3,
                      x4, y4, x5, y5: REAL) : CARDINAL ;

     (*
        mass - specify the mass of an object and return the, id.
     *)

     PROCEDURE mass (id: CARDINAL; m: REAL) : CARDINAL ;

     (*
        fix - fix the object to the world.
     *)

     PROCEDURE fix (id: CARDINAL) : CARDINAL ;

     (*
        circle - adds a circle to the world.  Center
                 defined by: x0, y0 radius, r.
     *)

     PROCEDURE circle (x0, y0, r: REAL) : CARDINAL ;

     (*
        velocity - give an object, id, a velocity, vx, vy.
     *)

     PROCEDURE velocity (id: CARDINAL; vx, vy: REAL) : CARDINAL ;

     (*
        accel - give an object, id, an acceleration, ax, ay.
     *)

     PROCEDURE accel (id: CARDINAL; ax, ay: REAL) : CARDINAL ;

     (*
        fps - set frames per second.
     *)

     PROCEDURE fps (f: REAL) ;

     (*
        replayRate - set frames per second during replay.
     *)

     PROCEDURE replayRate (f: REAL) ;

     (*
        simulateFor - render for, t, seconds.
     *)

     PROCEDURE simulateFor (t: REAL) ;

     END twoDsim.

The keyword UNQUALIFIED can be used to ensure that the compiler will provide externally accessible functions gravity, box, poly3, poly5, poly6, mass, fix, circle, pivot, velocity, accel, fps, replayRate, simulateFor rather than name mangled alternatives. Hence in our Python3 application we could write:

     #!/usr/bin/env python3

     from twoDsim import *

     b = box (0.0, 0.0, 1.0, 1.0)
     b = fix (b)
     c1 = circle (0.7, 0.7, 0.05)
     c1 = mass (c1, 0.01)
     c2 = circle (0.7, 0.1, 0.05)
     c2 = mass (c2, 0.01)
     c2 = fix (c2)
     gravity (-9.81)
     fps (24.0*4.0)
     replayRate (24.0)
     print ("creating frames")
     try:
         simulateFor (1.0)
         print ("all done")
     except:
         print ("exception raised")

which accesses the various functions defined and implemented by the module twoDsim.  The Modula-2 source code is compiled via:

     $ gm2 -g -fiso -c -fswig twoDsim.mod
     $ gm2 -g -fiso -c -fmakelist twoDsim.mod
     $ gm2 -g -fiso -c -fmakeinit twoDsim.mod

The first command both compiles the source file creating twoDsim.o and produces a swig interface file swig.i.  We now use swig and g++ to produce and compile the interface wrappers:

     $ libtool --mode=compile g++ -g -c twoDsim_m2.cpp -o twoDsim_m2.lo
     $ swig -c++ -python3 twoDsim.i
     $ libtool --mode=compile g++ -c -fPIC twoDsim_wrap.cxx \
        -I/usr/include/python3 -o twoDsim_wrap.lo
     $ libtool --mode=compile gm2 -g -fPIC -fiso -c deviceGnuPic.mod
     $ libtool --mode=compile gm2 -g -fPIC -fiso -c roots.mod
     $ libtool --mode=compile gm2 -g -fPIC -fiso -c -fswig \
        twoDsim.mod -o twoDsim.lo

Finally the application is linked into a shared library:

     $ libtool --mode=link gcc -g twoDsim_m2.lo twoDsim_wrap.lo \
       roots.lo deviceGnuPic.lo \
        -L${prefix}/lib64 \
        -rpath `pwd` -lgm2 -lstdc++ -lm -o libtwoDsim.la
     cp .libs/libtwoDsim.so _twoDsim.so

The library name must start with _ to comply with the Python3 module naming scheme.

Interfacing GNU Modula-2 to C
=============================

The GNU Modula-2 compiler tries to use the C calling convention wherever possible however some parameters have no C equivalent and thus a language specific method is used.  For example unbounded arrays are passed as a struct {void *address, unsigned int high} and the contents of these arrays are copied by callee functions when they are declared as non VAR parameters.  The VAR equivalent unbounded array parameters need no copy, but still use the struct representation.

The recommended method of interfacing GNU Modula-2 to C is by telling the definition module that the implementation is in the C language. This is achieved by using the tokens DEFINITION MODULE FOR "C". Here is an example libprintf.def.

     DEFINITION MODULE FOR "C" libprintf ;

     EXPORT UNQUALIFIED printf ;

     PROCEDURE printf (a: ARRAY OF CHAR; ...) : [ INTEGER ] ;

     END libprintf.

the UNQUALIFIED keyword in the definition module informs GNU Modula-2 not to prefix the module name to exported references in the object file.

The printf declaration states that the first parameter semantically matches ARRAY OF CHAR but since the module is for the C language it will be mapped onto char *.  The token ... indicates a variable number of arguments (varargs) and all parameters passed here are mapped onto their C equivalents.  Arrays and constant strings are passed as pointers.  Lastly [ INTEGER ] states that the caller can ignore the function return result if desired.

The hello world program can be rewritten as:

     MODULE hello ;

     FROM libprintf IMPORT printf ;

     BEGIN
        printf ("hello world\n")
     END hello.

and it can be compiled by:

gm2 -g hello.mod -lc

In reality the -lc is redundant as libc is always included in the linking process.  It is shown here to emphasize that the C library or object file containing printf must be present.  The search path for modules can be changed by using -I.

If a procedure function is declared using varargs then some parameter values are converted.  The table below summarizes the default conversions and default types used.

     Actual Parameter       |  Default conversion  |   Type of actual
                            |                      |   value passed
     ===============================================================
     123                    |  none                |   long long int
     "hello world"          |  none                |   const char *
     a: ARRAY OF CHAR       |  ADR (a)             |   char *
     a: ARRAY [0..5] OF CHAR|  ADR (a)             |   char *
     3.14                   |  none                |   long double

If you wish to pass int values then you should explicitly convert the constants using one of the conversion mechanisms. For example:  INTEGER(10) or VAL(INTEGER, 10) or CAST(INTEGER, 10).

Interface to assembly language
==============================

The interface for GNU Modula-2 to assembly language is almost identical to GNU C.  The only alterations are that the keywords asm and volatile are in capitals, following the Modula-2 convention.

A simple, but highly non optimal, example is given below.  Here we want to add the two CARDINALs foo and bar together and return the result.  The target processor is assumed to be executing the x86_64 instruction set.

     PROCEDURE Example (foo, bar: CARDINAL) : CARDINAL ;
     VAR
        myout: CARDINAL ;
     BEGIN
        ASM VOLATILE ("movq %1,%%rax; addq %2,%%rax; movq %%rax,%0"
           : "=rm" (myout)            (* outputs *)
           : "rm" (foo), "rm" (bar)   (* inputs  *)
           : "rax") ;                 (* we trash *)
        RETURN( myout )
     END Example ;

For a full description of this interface we refer the reader to the GNU C manual.

See Extensions to the C Language Family (gcc).

The same example can be written using the newer extensions of naming the operands rather than using numbered arguments.

     PROCEDURE Example (foo, bar: CARDINAL) : CARDINAL ;
     VAR
        myout: CARDINAL ;
     BEGIN
        ASM VOLATILE (
         "movq %[left],%%rax; addq %[right],%%rax; movq %%rax,%[output]"
           : [output] "=rm" (myout)                  (* outputs *)
           : [left] "rm" (foo), [right] "rm" (bar)   (* inputs  *)
           : "rax") ;                                (* we trash *)
        RETURN( myout )
     END Example ;

Both examples generate exactly the same code.  It is worth noting that the specifier ``rm'' indicates that the operand can be either a register or memory.  Of course you must choose an instruction which can take either, but this allows the compiler to take make more efficient choices depending upon the optimization level given to the compiler.

Data type alignment
===================

GNU Modula-2 allows you to specify alignment for types and variables. The syntax for alignment is to use the ISO pragma directives <* bytealignment ( expression ) and *>.  These directives can be used after type and variable declarations.

The ebnf of the alignment production is:

     Alignment := [ ByteAlignment ] =:
     ByteAlignment := '<*' AttributeExpression '*>' =:
     AlignmentExpression := "(" ConstExpression ")" =:

The Alignment ebnf statement may be used during construction of types, records, record fields, arrays, pointers and variables.  Below is an example of aligning a type so that the variable bar is aligned on a 1024 address.

     MODULE align ;

     TYPE
        foo = INTEGER <* bytealignment(1024) *> ;

     VAR
        z  : INTEGER ;
        bar: foo ;
     BEGIN
     END align.

The next example aligns a variable on a 1024 byte boundary.

     MODULE align2 ;

     VAR
        x  : CHAR ;
        z  : ARRAY [0..255] OF INTEGER <* bytealignment(1024) *> ;
     BEGIN
     END align2.

Here the example aligns a pointer on a 1024 byte boundary.

     MODULE align4 ;

     FROM SYSTEM IMPORT ADR ;
     FROM libc IMPORT exit ;

     VAR
        x  : CHAR ;
        z  : POINTER TO INTEGER <* bytealignment(1024) *> ;
     BEGIN
        IF ADR(z) MOD 1024=0
        THEN
           exit(0)
        ELSE
           exit(1)
        END
     END align4.

In example align5 record field y is aligned on a 1024 byte boundary.

     MODULE align5 ;

     FROM SYSTEM IMPORT ADR ;
     FROM libc IMPORT exit ;

     TYPE
        rec = RECORD
                 x: CHAR ;
                 y: CHAR <* bytealignment(1024) *> ;
              END ;
     VAR
        r: rec ;
     BEGIN
        IF ADR(r.y) MOD 1024=0
        THEN
           exit(0)
        ELSE
           exit(1)
        END
     END align5.

In the example below module align6 declares foo as an array of 256 INTEGERs.  The array foo is aligned on a 1024 byte boundary.

     MODULE align6 ;

     FROM SYSTEM IMPORT ADR ;
     FROM libc IMPORT exit ;

     TYPE
        foo = ARRAY [0..255] OF INTEGER <* bytealignment(1024) *> ;

     VAR
        x  : CHAR ;
        z  : foo ;
     BEGIN
        IF ADR(z) MOD 1024=0
        THEN
           exit(0)
        ELSE
           exit(1)
        END
     END align6.

Packing data types
==================

The pragma <* bytealignment(0) *> can be used to specify that the fields within a RECORD are to be packed.  Currently this only applies to fields which are declared as subranges, ordinal types and enumerated types.  Here is an example of how two subranges might be packed into a byte.

     TYPE
        bits3c =  [0..7] ;
        bits3i = [-4..3] ;

        byte = RECORD
                   <* bytealignment(0) *>
                   x: bits3c ;
                   <* bitsunused(2) *>
                   y: bits3i ;
               END ;

Notice that the user has specified that in between fields x and y there are two bits unused.

Now the user wishes to create a record with byte numbers zero and one occupied and then an INTEGER32 field which is four byte aligned.  In this case byte numbers two and three will be unused.  The pragma bytealignment can be issued at the start of the record indicating the default alignment for the whole record and this can be overridden by individual fields if necessary.

        rec = RECORD
                 <* bytealignment (1) *> ;
                 a, b: byte ;
                 x: INTEGER32 <* bytealignment(4) *> ;
              END ;

In the following example the user has specified that a record has two fields p and q but that there are three bytes unused between these fields.

        header = RECORD
                    <* bytealignment(1) *>
                    p: byte ;
                    <* bytesunused(3) *>
                    q: byte ;
                 END ;

The pragma <* bytesunused(x) *> can only be used if the current field is on a byte boundary.  There is also a SYSTEM pseudo procedure function TBITSIZE(T) which returns the minimum number of bits necessary to represent type T.

Another example of packing record bit fields is given below:

     MODULE align21 ;

     FROM libc IMPORT exit ;

     TYPE
        colour = (red, blue, green, purple, white, black) ;

        soc = PACKEDSET OF colour ;

        rec = RECORD
                 <* bytealignment(0) *>
                 x: soc ;
                 y: [-1..1] ;
              END ;

     VAR
        r: rec ;
        v: CARDINAL ;
     BEGIN
        v := SIZE(r) ;
        IF SIZE(r)#1
        THEN
           exit(1)
        END ;
        r.x := soc{blue} ;
        IF r.x#soc{blue}
        THEN
           exit(2)
        END
     END align21.

Here we see that the total size of this record is one byte and consists of a six bit set type followed by a 2 bit integer subrange.

Accessing GNU Modula-2 Built-ins
================================

This section describes the built-in constants and functions defined in GNU Modula-2.  The following compiler constants can be accessed using the __ATTRIBUTE__ __BUILTIN__ keywords.  These are not part of the Modula-2 language and they may differ depending upon the target architecture but they provide a method whereby common libraries can interface to a different underlying architecture.

The built-in constants are: BITS_PER_UNIT, BITS_PER_WORD, BITS_PER_CHAR and UNITS_PER_WORD.  They are integrated into GNU Modula-2 by an extension to the ConstFactor rule:

     ConstFactor := ConstQualidentOrSet | Number | ConstString |
                    "(" ConstExpression ")" | "NOT" ConstFactor |
                    ConstAttribute =:

     ConstAttribute := "__ATTRIBUTE__" "__BUILTIN__" "(" "(" Ident ")" ")" =:

Here is an example taken from the ISO library SYSTEM.def:

     CONST
        BITSPERLOC    = __ATTRIBUTE__ __BUILTIN__ ((BITS_PER_UNIT)) ;
        LOCSPERWORD   = __ATTRIBUTE__ __BUILTIN__ ((UNITS_PER_WORD)) ;

Built-in functions are transparent to the end user.  All built-in functions are declared in DEFINITION MODULEs and are imported as and when required.  Built-in functions are declared in definition modules by using the __BUILTIN__ keyword.  Here is a section of the ISO library LongMath.def which demonstrates this feature.

     PROCEDURE __BUILTIN__ sqrt (x: LONGREAL): LONGREAL;
       (* Returns the square root of x *)

This indicates that the function sqrt will be implemented using the gcc built-in maths library.  If gcc cannot utilize the built-in function (for example if the programmer requested the address of sqrt) then code is generated to call the alternative function implemented in the IMPLEMENTATION MODULE.

Sometimes a function exported from the DEFINITION MODULE will have a different name from the built-in function within gcc.  In such cases the mapping between the GNU Modula-2 function name and the gcc name is expressed using the keywords __ATTRIBUTE__ __BUILTIN__ ((Ident)).  For example the function sqrt in LongMath.def maps onto the gcc built-in function sqrtl and this is expressed as:

     PROCEDURE __ATTRIBUTE__ __BUILTIN__ ((sqrtl)) sqrt
                                         (x: LONGREAL) : LONGREAL;
       (* Returns the positive square root of x *)

The following module Builtins.def enumerates the list of built-in functions which can be accessed in GNU Modula-2.  It also serves to define the parameter and return value for each function:

     [file Builtins.texi not included]

Although this module exists and will result in the generation of in-line code if optimization flags are passed to GNU Modula-2, users are advised to utilize the same functions from more generic libraries. The built-in mechanism will be applied to these generic libraries where appropriate.  Note for the mathematical routines to be in-lined you need to specify the -ffast-math -O options.

The PIM system module
=====================

     [file SYSTEM-pim.texi not included]

The different dialects of Modula-2 PIM-[234] and ISO Modula-2 declare the function SIZE in different places.  PIM-[34] and ISO Modula-2 declare SIZE as a pervasive function (declared in the base module).  PIM-2 defined SIZE in the SYSTEM module (as shown above).

GNU Modula-2 allows users to specify the dialect of Modula-2 by using the -fiso and -fpim2 command line switches.

The data types CSIZE_T and CSSIZE_T are also exported from the SYSTEM module.  The type CSIZE_T is unsigned and is mapped onto the target C data type size_t whereas the type CSSIZE_T is mapped onto the signed C data type ssize_t.

It is anticipated that these should only be used to provide cross platform definition modules for C libraries.

There are also a variety of fixed sized INTEGER and CARDINAL types.  The variety of the fixed sized types will depend upon the target architecture.

The ISO system module
=====================

     [file SYSTEM-iso.texi not included]

The data types CSIZE_T and CSSIZE_T are also exported from the SYSTEM module.  The type CSIZE_T is unsigned and is mapped onto the target C data type size_t whereas the type CSSIZE_T is mapped onto the signed C data type ssize_t.

It is anticipated that these should only be used to provide cross platform definition modules for C libraries.

There are also a variety of fixed sized INTEGER and CARDINAL types.  The variety of the fixed sized types will depend upon the target architecture.

Release map
===========

GNU Modula-2 is now part of GCC and therefore will adopt the GCC release schedule.  It is intended that GNU Modula-2 implement more of the GCC builtins (vararg access) and GCC features.

There is an intention to implement the ISO generics and the M2R10 dialect of Modula-2.  It will also implement all language changes.  If you wish to see something different please email gm2@nongnu.org with your ideas.

Documentation
=============

The GNU Modula-2 documentation is available on line https://gcc.gnu.org/onlinedocs or in the pdf, info, html file format.

Regression tests for gm2 in the repository
==========================================

The regression testsuite can be run from the gcc build directory:

     $ cd build-gcc
     $ make check -j 24

which runs the complete testsuite for all compilers using 24 parallel invocations of the compiler.  Individual language testsuites can be run by specifying the language, for example the Modula-2 testsuite can be run using:

     $ cd build-gcc
     $ make check-m2 -j 24

Finally the results of the testsuite can be emailed to the gcc-testresults (https://gcc.gnu.org/lists.html) list using the test_summary script found in the gcc source tree:

     $ directory to the sources/contrib/test_summary

Limitations
===========

Logitech compatibility library is incomplete.  The principle modules for this platform exist however for a comprehensive list of completed modules please check the documentation gm2.html.

Objectives
==========

  * The intention of GNU Modula-2 is to provide a production Modula-2 front end to GCC.

  * It should support all Niklaus Wirth PIM Dialects [234] and also ISO Modula-2 including a re-implementation of all the ISO modules.

  * There should be an easy interface to C.

  * Exploit the features of GCC.

  * Listen to the requests of the users.

FAQ
===

Why use the C++ exception mechanism in GCC, rather than a bespoke Modula-2 mechanism?
-------------------------------------------------------------------------------------

The C++ mechanism is tried and tested, it also provides GNU Modula-2 with the ability to link with C++ modules and via swig it can raise Python exceptions.

Community
=========

You can subscribe to the GNU Modula-2 mailing by sending an email to: gm2-subscribe@nongnu.org or by http://lists.nongnu.org/mailman/listinfo/gm2. The mailing list contents can be viewed http://lists.gnu.org/archive/html/gm2.

Other languages for GCC
=======================

These exist and can be found on the frontends web page on the gcc web site (http://gcc.gnu.org/frontends.html).

License of GNU Modula-2
=======================

GNU Modula-2 is free software, the compiler is held under the GPL v3 http://www.gnu.org/licenses/gpl.txt, its libraries (pim, iso and Logitech compatible) are under the GPL v3 with the GCC run time library exception clause.

Under Section 7 of GPL version 3, you are granted additional permissions described in the GCC Runtime Library Exception, version 3.1, as published by the Free Software Foundation.

You should have received a copy of the GNU General Public License and a copy of the GCC Runtime Library Exception along with this program; see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see <http://www.gnu.org/licenses/>.

More information on how these licenses work is available http://www.gnu.org/licenses/licenses.html on the GNU web site.

     [file gpl_v3_without_node.texi not included]

Contributing to GNU Modula-2
============================

Please do and please read the GNU Emacs info under

     * Standards: (standards).       GNU coding standards.
     * Intellectual Property::       Keeping Free Software Free
     * Reading Non-Free Code::       Referring to Proprietary Programs
     * Contributions::               Accepting Contributions

You might consider joining the GM2 Mailing list before you start coding.  The mailing list may be subscribed via a web interface http://lists.nongnu.org/mailman/listinfo/gm2 or via email gm2-subscribe@nongnu.org.

Many thanks and enjoy your coding!

EBNF of GNU Modula-2
********************

This chapter contains the EBNF of GNU Modula-2.  This grammar currently supports both PIM and ISO dialects.  The rules here are automatically extracted from the crammer files in GNU Modula-2 and serve to document the syntax of the extensions described earlier and how they fit in with the base language.

Note that the first six productions are built into the lexical analysis phase.

     [file gm2-ebnf.texi not included]

PIM and ISO library definitions
*******************************

This chapter contains M2F, PIM and ISO libraries.

     [file gm2-libs.texi not included]