3 @c Copyright (C) 2001-2023 Free Software Foundation, Inc.
4 @c This is part of the GM2 manual.
6 @c User level documentation for GNU Modula-2
11 @settitle The GNU Modula-2 Compiler
13 @set version-python 3.5
15 @include gcc-common.texi
17 @c Copyright years for this manual.
18 @set copyrights-gm2 1999-2023
21 @c man begin COPYRIGHT
22 Copyright @copyright{} @value{copyrights-gm2} Free Software Foundation, Inc.
24 Permission is granted to copy, distribute and/or modify this document
25 under the terms of the GNU Free Documentation License, Version 1.3 or
26 any later version published by the Free Software Foundation; with no
27 Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
28 A copy of the license is included in the
30 section entitled ``GNU Free Documentation License''.
32 @c man begin COPYRIGHT
40 @dircategory Software development
42 * gm2: (gm2). A GCC-based compiler for the Modula-2 language
50 @title The GNU Modula-2 Compiler
55 @vskip 0pt plus 1filll
56 Published by the Free Software Foundation @*
57 51 Franklin Street, Fifth Floor@*
58 Boston, MA 02110-1301, USA@*
65 @c `Top' Node and Master Menu
67 @node Top, Overview, (dir), (dir)
71 * Overview:: What is GNU Modula-2.
72 * Using:: Using GNU Modula-2.
73 * License:: License of GNU Modula-2
74 * Copying:: GNU Public License V3.
75 * Contributing:: Contributing to GNU Modula-2
76 @c * Internals:: GNU Modula-2 internals.
77 * EBNF:: EBNF of GNU Modula-2
78 * Libraries:: PIM and ISO library definitions.
79 * Indices:: Document and function indices.
82 @node Overview, Using, Top, Top
83 @chapter Overview of GNU Modula-2
86 * What is GNU Modula-2:: Brief description of GNU Modula-2.
87 * Why use GNU Modula-2:: Advantages of GNU Modula-2.
88 * Development:: How to get source code using git.
89 * Features:: GNU Modula-2 Features
92 @node What is GNU Modula-2, Why use GNU Modula-2, , Overview
93 @section What is GNU Modula-2
95 GNU Modula-2 is a @uref{http://gcc.gnu.org/frontends.html, front end}
96 for the GNU Compiler Collection (@uref{http://gcc.gnu.org/, GCC}).
97 The GNU Modula-2 compiler is compliant with the PIM2, PIM3, PIM4 and
98 ISO dialects. Also implemented are a complete set of free ISO
99 libraries and PIM libraries.
101 @footnote{The four Modula-2 dialects supported are defined in the following
104 PIM2: 'Programming in Modula-2', 2nd Edition, Springer Verlag, 1982,
105 1983 by Niklaus Wirth (PIM2).
107 PIM3: 'Programming in Modula-2', 3rd Corrected Edition, Springer Verlag,
110 PIM4: 'Programming in Modula-2', 4th Edition, Springer Verlag, 1988
111 (@uref{http://freepages.modula2.org/report4/modula-2.html, PIM4}).
113 ISO: the ISO Modula-2 language as defined in 'ISO/IEC Information
114 technology - programming languages - part 1: Modula-2 Language,
115 ISO/IEC 10514-1 (1996)'
118 @node Why use GNU Modula-2, Development, What is GNU Modula-2, Overview
119 @section Why use GNU Modula-2
121 There are a number of advantages of using GNU Modula-2 rather than
122 translate an existing project into another language.
124 The first advantage is of maintainability of the original sources
125 and the ability to debug the original project source code using a
126 combination of gm2 and gdb.
128 The second advantage is that gcc runs on many processors and
129 platforms. gm2 builds and runs on powerpc64le, amd64, i386, aarch64
130 to name but a few processors.
132 gm2 can produce swig interface headers to allow access from Python and
133 other scripting languages. It can also be used with C/C++ and
134 generate shared libraries.
136 The compiler provides semantic analysis and run time checking (full ISO
137 Modula-2 checking is implemented) and there is a plugin which can,
138 under certain conditions, detect run time errors at compile time.
140 The compiler supports PIM2, PIM3, PIM4 and ISO dialects of Modula-2,
141 work is underway to implement M2R10. Many of the GCC builtins are
142 available and access to assembly programming is achieved using the
143 same syntax as that used by GCC.
145 The gm2 driver allows third party libraries to be installed alongside
146 gm2 libraries. For example if the user specifies library @code{foo}
147 using @code{-flibs=foo} the driver will check the standard GCC install
148 directory for a sub directory @code{foo} containing the library
149 contents. The library module search path is altered accordingly
150 for compile and link.
152 @node Development, Features, Why use GNU Modula-2, Overview
153 @section How to get source code using git
155 GNU Modula-2 is now in the @url{https://gcc.gnu.org/git.html, GCC git
158 @node Features, , Development, Overview
159 @section GNU Modula-2 Features
164 the compiler currently complies with Programming in Modula-2 Edition
165 2, 3, 4 and ISO Modula-2. Users can switch on specific language
166 features by using: @samp{-fpim}, @samp{-fpim2}, @samp{-fpim3},
167 @samp{-fpim4} or @samp{-fiso}.
170 the option @samp{-fswig} will automatically create a swig interface
171 file which corresponds to the definition module of the file being
175 exception handling is compatible with C++ and swig. Modula-2 code can
176 be used with C or C++ code.
179 Python can call GNU Modula-2 modules via swig.
182 shared libraries can be built.
185 fixed sized types are now available from @samp{SYSTEM}.
188 @c support for dynamic @code{ARRAY}s has been added into @samp{gdb}.
191 variables can be declared at addresses.
194 much better dwarf-2 debugging support and when used with
195 @samp{gdb} the programmer can display @code{RECORD}s,
196 @code{ARRAY}s, @code{SET}s, subranges and constant char literals
200 supports sets of any ordinal size (memory permitting).
203 easy interface to C, and varargs can be passed to C routines.
206 many Logitech libraries have been implemented and can be accessed via:
207 @samp{-flibs=m2log,m2pim,m2iso}.
210 coroutines have been implemented in the PIM style and these are
211 accessible from SYSTEM. A number of supporting libraries (executive
212 and file descriptor mapping to interrupt vector libraries are
213 available through the @samp{-flibs=m2iso,m2pim} switch).
216 can be built as a cross compiler (for embedded microprocessors
217 such as the AVR and the ARM).
221 @node Using, License, Overview, Top
222 @chapter Using GNU Modula-2
225 * Example usage:: Example compile and link.
226 * Compiler options:: GNU Modula-2 compiler options.
227 * Linking:: Linking options in more detail.
228 * Elementary data types:: Data types supported by GNU Modula-2.
229 * Standard procedures:: Permanently accessible base procedures.
230 * Dialect:: GNU Modula-2 supported dialects.
231 * Exceptions:: Exception implementation
232 * Semantic checking:: How to detect run time problems at compile time.
233 * Extensions:: GNU Modula-2 language extensions.
234 * Type compatibility:: Data type compatibility.
235 * Unbounded by reference::Explanation of a language optimization.
236 * Building a shared library:: How to build a shared library.
237 * Interface for Python:: How to produce swig interface files.
238 * Producing a Python module:: How to produce a Python module.
239 * Interface to C:: Interfacing GNU Modula-2 to C.
240 * Assembly language:: Interface to assembly language.
241 * Alignment:: Data type alignment.
242 * Packed:: Packing data types.
243 * Built-ins:: Accessing GNU Modula-2 Built-ins.
244 * The PIM system module:: SYSTEM data types and procedures.
245 * The ISO system module:: SYSTEM data types, procedures and run time.
247 @c omit these nodes if generating gm2 webpage as these are hand written.
248 * Release map:: Release map.
249 * Documentation:: Placeholder for how to access the documentation online.
250 * Regression tests:: How to run the testsuite.
251 * Limitations:: Current limitations.
252 * Objectives:: Objectives of the implementation.
253 * FAQ:: Frequently asked questions.
254 * Community:: How to join the community.
255 * Other languages:: Other languages for GCC.
259 This document contains the user and design issues relevant to the
260 Modula-2 front end to gcc.
262 @node Example usage, Compiler options, Using, Using
263 @section Example compile and link
266 @c man begin SYNOPSIS gm2
267 gm2 [@option{-c}|@option{-S}] [@option{-g}] [@option{-pg}]
268 [@option{-O}@var{level}] [@option{-W}@var{warn}@dots{}]
269 [@option{-I}@var{dir}@dots{}] [@option{-L}@var{dir}@dots{}]
270 [@option{-f}@var{option}@dots{}] [@option{-m}@var{machine-option}@dots{}]
271 [@option{-o} @var{outfile}] [@@@var{file}] @var{infile}@dots{}
273 Only the most useful options are listed here; see below for the
277 gpl(7), gfdl(7), fsf-funding(7), gcc(1)
278 and the Info entries for @file{gm2} and @file{gcc}.
282 @c man begin DESCRIPTION gm2
284 The @command{gm2} command is the GNU compiler for the Modula-2 language and
285 supports many of the same options as @command{gcc}. @xref{Option Summary, ,
286 Option Summary, gcc, Using the GNU Compiler Collection (GCC)}.
287 This manual only documents the options specific to @command{gm2}.
291 This section describes how to compile and link a simple hello world
292 program. It provides a few examples of using the different options
293 mentioned in @pxref{Compiler options, , ,gm2}. Assuming that you have
294 a file called @file{hello.mod} in your current directory which
300 FROM StrIO IMPORT WriteString, WriteLn ;
303 WriteString ('hello world') ; WriteLn
307 You can compile and link it by: @samp{gm2 -g hello.mod}.
308 The result will be an @samp{a.out} file created in your directory.
310 You can split this command into two steps if you prefer. The compile
311 step can be achieved by: @samp{gm2 -g -c -fscaffold-main hello.mod}
312 and the link via: @samp{gm2 -g hello.o}.
314 @footnote{To see all the compile actions taken by @samp{gm2} users can also
315 add the @samp{-v} flag at the command line, for example:
317 @samp{gm2 -v -g -I. hello.mod}
319 This displays the sub processes initiated by @samp{gm2} which can be useful
320 when trouble shooting.}
322 @node Compiler options, Linking, Example usage, Using
323 @section Compiler options
325 This section describes the compiler options specific to GNU Modula-2
326 for generic flags details @xref{Invoking GCC, , ,gcc}.
330 For any given input file, the file name suffix determines what kind of
331 compilation is done. The following kinds of input file names are supported:
335 Modula-2 implementation or program source files. See the
336 @samp{-fmod=} option if you wish to compile a project which uses a
337 different source file extension.
339 Modula-2 definition module source files. Definition modules are not
340 compiled separately, in GNU Modula-2 definition modules are parsed as
341 required when program or implementation modules are compiled. See the
342 @samp{-fdef=} option if you wish to compile a project which uses a
343 different source file extension.
346 You can specify more than one input file on the @command{gm2} command line,
351 create debugging information so that debuggers such as @file{gdb}
352 can inspect and control executable.
355 used to specify the search path for definition and implementation
356 modules. An example is: @code{gm2 -g -c -I.:../../libs foo.mod}.
357 If this option is not specified then the default path is added
358 which consists of the current directory followed by the appropriate
359 language dialect library directories.
361 @c ordered list of options from here.
364 turns on auto initialization of pointers to NIL. Whenever a block is
365 created all pointers declared within this scope will have their
366 addresses assigned to NIL.
369 turns on run time subrange, array index and indirection via @code{NIL}
373 turns on compile time checking to check whether a @code{CASE}
374 statement requires an @code{ELSE} clause when on was not specified.
377 preprocess the source with @samp{cpp -lang-asm -traditional-cpp}
378 For further details about these options @xref{Invocation, , ,cpp}.
379 If @samp{-fcpp} is supplied then all definition modules and
380 implementation modules which are parsed will be prepossessed by
385 @c passed to the preprocessor if -fcpp is used (internal switch)
389 @c passed to the preprocessor if -fcpp is used (internal switch)
391 @item -fdebug-builtins
392 call a real function, rather than the builtin equivalent. This can
393 be useful for debugging parameter values to a builtin function as
394 it allows users to single step code into a real function.
398 @c turn on internal debugging of the compiler (internal switch)
402 @c turn on quadruple tracing (internal switch)
406 @c turn on the Modula-2 api tracing (internal switch)
408 @c fdebug-function-line-numbers
410 @c turn on the Modula-2 function line number generation (internal switch)
413 recognize the specified suffix as a definition module filename.
414 The default implementation and module filename suffix is @file{.def}.
415 If this option is used GNU Modula-2 will still fall back to this
416 default if a requested definition module is not found.
418 @item -fdump-system-exports
419 display all inbuilt system items.
420 This is an internal command line option.
423 turn on exception handling code. By default this option is on.
424 Exception handling can be disabled by @samp{-fno-exceptions}
425 and no references are made to the run time exception libraries.
427 @item -fextended-opaque
428 allows opaque types to be implemented as any type. This is a GNU
429 Modula-2 extension and it requires that the implementation module
430 defining the opaque type is available so that it can be resolved when
431 compiling the module which imports the opaque type.
434 turns on run time checking to check whether a floating point number is
435 about to exceed range.
437 @item -fgen-module-list=@file{filename}
438 attempt to find all modules when linking and generate a module list.
439 If the @file{filename} is @samp{-} then the contents are not written
440 and only used to force the linking of all module ctors.
441 This option cannot be used if @samp{-fuse-list=} is enabled.
444 generate code to check whether array index values are out of bounds.
445 Array index checking can be disabled via @samp{-fno-index}.
448 turn on ISO standard features. Currently this enables the ISO
449 @code{SYSTEM} module and alters the default library search path so
450 that the ISO libraries are searched before the PIM libraries. It also
451 effects the behavior of @code{DIV} and @code{MOD} operators.
452 @xref{Dialect, , ,gm2}.
455 modifies the default library search path. The libraries supplied are:
456 m2pim, m2iso, m2min, m2log and m2cor. These map onto the
457 Programming in Modula-2 base libraries, ISO standard libraries, minimal
458 library support, Logitech compatible library and Programming in
459 Modula-2 with coroutines.
460 Multiple libraries can be specified and are comma separated with precedence
461 going to the first in the list. It is not necessary to use -flibs=m2pim or
462 -flibs=m2iso if you also specify -fpim, -fpim2, -fpim3, -fpim4 or
463 -fiso. Unless you are using -flibs=m2min you should include m2pim as
464 the they provide the base modules which all other dialects utilize.
465 The option @samp{-fno-libs=-} disables the @samp{gm2} driver from
466 modifying the search and library paths.
469 On systems that provide the m2 runtimes as both shared and static libraries,
470 this option forces the use of the static version.
474 @c set all location values to a specific value (internal switch)
477 improve the debugging experience for new programmers at the expense
478 of generating @code{nop} instructions if necessary to ensure single
479 stepping precision over all code related keywords. An example
480 of this is in termination of a list of nested @code{IF} statements
481 where multiple @code{END} keywords are mapped onto a sequence of
482 @code{nop} instructions.
484 @item -fm2-lower-case
485 render keywords in error messages using lower case.
488 specify the module mangled prefix name for all modules in the
489 following include paths.
492 for internal use only: used by the driver to copy the user facing -I
496 insert plugin to identify run time errors at compile time (default on).
499 specify the module mangled prefix name. All exported symbols from a
500 definition module will have the prefix name.
502 @item -fm2-statistics
503 generates quadruple information: number of quadruples generated,
504 number of quadruples remaining after optimization and number of source
507 @item -fm2-strict-type
508 experimental flag to turn on the new strict type checker.
510 @item -fm2-whole-program
511 compile all implementation modules and program module at once. Notice
512 that you need to take care if you are compiling different dialect
513 modules (particularly with the negative operands to modulus). But
514 this option, when coupled together with @code{-O3}, can deliver huge
515 performance improvements.
518 recognize the specified suffix as implementation and module filenames.
519 The default implementation and module filename suffix is @file{.mod}.
520 If this option is used GNU Modula-2 will still fall back to this
521 default if it needs to read an implementation module and the specified
522 suffixed filename does not exist.
525 generate code to detect accessing data through a @code{NIL} value
526 pointer. Dereferencing checking through a @code{NIL} pointer can be
527 disabled by @samp{-fno-nil}.
530 turn on PIM standard features. Currently this enables the PIM
531 @code{SYSTEM} module and determines which identifiers are pervasive
532 (declared in the base module). If no other @samp{-fpim[234]} switch is
533 used then division and modulus operators behave as defined in PIM4.
534 @xref{Dialect, , ,gm2}.
537 turn on PIM-2 standard features. Currently this removes @code{SIZE}
538 from being a pervasive identifier (declared in the base module). It
539 places @code{SIZE} in the @code{SYSTEM} module. It also effects the
540 behavior of @code{DIV} and @code{MOD} operators.
541 @xref{Dialect, , ,gm2}.
544 turn on PIM-3 standard features. Currently this only effects the
545 behavior of @code{DIV} and @code{MOD} operators.
546 @xref{Dialect, , ,gm2}.
549 turn on PIM-4 standard features. Currently this only effects the
550 behavior of @code{DIV} and @code{MOD} operators.
551 @xref{Dialect, , ,gm2}.
553 @item -fpositive-mod-floor-div
554 forces the @code{DIV} and @code{MOD} operators to behave as defined by PIM4.
555 All modulus results are positive and the results from the division are
556 rounded to the floor.
557 @xref{Dialect, , ,gm2}.
560 link against the pthread library. By default this option is on. It
561 can be disabled by @samp{-fno-pthread}. GNU Modula-2 uses the GCC
562 pthread libraries to implement coroutines (see the SYSTEM
563 implementation module).
567 @c -internal compiler debugging information, dump the list of quadruples
570 generate code to check the assignment range, return value range
571 set range and constructor range. Range checking can be disabled
572 via @samp{-fno-range}.
575 generate code to check that functions always exit with a @code{RETURN}
576 and do not fall out at the end. Return checking can be disabled
577 via @samp{-fno-return}.
579 @item -fruntime-modules=
580 specify, using a comma separated list, the run time modules and their
581 order. These modules will initialized first before any other modules
582 in the application dependency. By default the run time modules list
583 is set to @code{m2iso:RTentity,m2iso:Storage,m2iso:SYSTEM,}
584 @code{m2iso:M2RTS,m2iso:RTExceptions,m2iso:IOLink}. Note that these
585 modules will only be linked into your executable if they are required.
586 Adding a long list of dependent modules will not effect the size of
587 the executable it merely states the initialization order should they
590 @item -fscaffold-dynamic
591 the option ensures that @samp{gm2} will generate a dynamic scaffold
592 infrastructure when compiling implementation and program modules.
593 By default this option is on. Use @samp{-fno-scaffold-dynamic}
594 to turn it off or select @samp{-fno-scaffold-static}.
597 generate a C source scaffold for the current module being compiled.
600 generate a C++ source scaffold for the current module being compiled.
602 @item -fscaffold-main
603 force the generation of the @samp{main} function. This is not
604 necessary if the @samp{-c} is omitted.
606 @item -fscaffold-static
607 the option ensures that @samp{gm2} will generate a static scaffold
608 within the program module. The static scaffold consists of sequences
609 of calls to all dependent module initialization and finalization
610 procedures. The static scaffold is useful for debugging and single
611 stepping the initialization blocks of implementation modules.
614 generate a shared library from the module.
616 @item -fsoft-check-all
617 turns on all run time checks. This is the same as invoking
618 GNU Modula-2 using the command options
619 @code{-fnil} @code{-frange} @code{-findex}
621 @code{-fwholediv} @code{-fcase} @code{-freturn}.
624 displays the path to the source of each module. This option
625 can be used at compile time to check the correct definition module
629 generate a swig interface file.
631 @item -funbounded-by-reference
632 enable optimization of unbounded parameters by attempting to pass non
633 @code{VAR} unbounded parameters by reference. This optimization
634 avoids the implicit copy inside the callee procedure. GNU Modula-2
635 will only allow unbounded parameters to be passed by reference if,
636 inside the callee procedure, they are not written to, no address is
637 calculated on the array and it is not passed as a @code{VAR}
638 parameter. Note that it is possible to write code to break this
639 optimization, therefore this option should be used carefully.
640 For example it would be possible to take the address of an array, pass
641 the address and the array to a procedure, read from the array in
642 the procedure and write to the location using the address parameter.
644 Due to the dangerous nature of this option it is not enabled
645 when the @samp{-O} option is specified.
647 @item -fuse-list=@file{filename}
648 if @samp{-fscaffold-static} is enabled then use the file
649 @file{filename} for the initialization order of modules. Whereas if
650 @samp{-fscaffold-dynamic} is enabled then use this file to force
651 linking of all module ctors.
652 This option cannot be used if @samp{-fgen-module-list=} is enabled.
655 generate code to detect whole number division by zero or modulus by
659 generate code to detect whole number overflow and underflow.
661 @c the following warning options are complete but need to be
662 @c regression tested against all other front ends
663 @c to ensure the options do not conflict.
666 @c turn on all Modula-2 warnings.
669 @c forces the compiler to reject nested @code{WITH} statements
670 @c referencing the same record type. Does not allow multiple imports of
671 @c the same item from a module. It also checks that: procedure variables
672 @c are written to before being read; variables are not only written to
673 @c but read from; variables are declared and used. If the compiler
674 @c encounters a variable being read before written it will terminate with
675 @c a message. It will check that @code{FOR} loop indices are not used
676 @c outside the end of this loop without being reset.
678 @c @item -Wpedantic-cast
679 @c warns if the ISO system function is used and if the size of
680 @c the variable is different from that of the type. This is legal
681 @c in ISO Modula-2, however it can be dangerous. Some users may prefer
682 @c to use @code{VAL} instead in these situations and use @code{CAST}
683 @c exclusively for changes in type on objects which have the same size.
685 @c @item -Wpedantic-param-names
686 @c procedure parameter names are checked in the definition module
687 @c against their implementation module counterpart. This is not
688 @c necessary in ISO or PIM versions of Modula-2.
691 @c checks for poor programming style. This option is aimed at new users of
692 @c Modula-2 in that it checks for situations which might cause confusion
693 @c and thus mistakes. It checks whether variables of the same name are
694 @c declared in different scopes and whether variables look like keywords.
695 @c Experienced users might find this option too aggressive.
697 @c @item -Wunused-variable
698 @c warns if a variable has been declared and it not used.
700 @c @item -Wunused-parameter
701 @c warns if a parameter has been declared and it not used.
703 @c @item -Wverbose-unbounded
704 @c inform the user which non @code{VAR} unbounded parameters will be
705 @c passed by reference. This only produces output if the option
706 @c @samp{-funbounded-by-reference} is also supplied on the command line.
712 @node Linking, Elementary data types, Compiler options, Using
714 This section describes the linking related options. There are three
715 linking strategies available which are dynamic scaffold, static
716 scaffold and user defined. The dynamic scaffold is enabled by default
717 and each module will register itself to the run time @samp{M2RTS} via
718 a constructor. The static scaffold mechanism will invoke each modules
719 @samp{_init} and @samp{_finish} function in turn via a sequence of
720 calls from within @samp{main}. Lastly the user defined strategy
721 can be implemented by turning off the dynamic and static options via
722 @samp{-fno-scaffold-dynamic} and @samp{-fno-scaffold-static}.
724 In the simple test below:
730 the driver will add the options @samp{-fscaffold-dynamic} and
731 @samp{-fgen-module-list=-} which generate a list of application
732 modules and also creates the @samp{main} function with calls to
733 @samp{M2RTS}. It can be useful to add the option @samp{-fsources}
734 which displays the source files as they are parsed and summarizes
735 whether the source file is required for compilation or linking.
737 If you wish to split the above command line into a compile and link
738 then you could use these steps:
741 $ gm2 -c -fscaffold-main hello.mod
745 The @samp{-fscaffold-main} informs the compiler to generate the
746 @samp{main} function and scaffold. You can enable the environment
747 variable @samp{GCC_M2LINK_RTFLAG} to trace the construction and
748 destruction of the application. The values for
749 @samp{GCC_M2LINK_RTFLAG} are shown in the table below:
754 all | turn on all flags below
755 module | trace modules as they register themselves
756 hex | display the hex address of the init/fini functions
757 warning | show any warnings
758 pre | generate module list prior to dependency resolution
759 dep | trace module dependency resolution
760 post | generate module list after dependency resolution
761 force | generate a module list after dependency and forced
762 | ordering is complete
765 The values can be combined using a comma separated list.
767 One of the advantages of the dynamic scaffold is that the driver
768 behaves in a similar way to the other front end drivers.
769 For example consider a small project consisting of 4 definition
770 implementation modules (@samp{a.def}, @samp{a.mod}, @samp{b.def},
771 @samp{b.mod}, @samp{c.def}, @samp{c.mod}, @samp{d.def}, @samp{d.mod})
772 and a program module @samp{program.mod}.
774 To link this project we could:
781 $ gm2 -g program.mod a.o b.o c.o d.o
784 The module initialization sequence is defined by the ISO standard to
785 follow the import graph traversal. The initialization order is the
786 order in which the corresponding separate modules finish the
787 processing of their import lists.
789 However, if required, you can override this using
790 @samp{-fruntime-modules=a,b,c,d} for example which forces the
791 initialization sequence to @samp{a}, @samp{b}, @samp{c} and @samp{d}.
793 @node Elementary data types, Standard procedures, Linking, Using
794 @section Elementary data types
796 This section describes the elementary data types supported by GNU
797 Modula-2. It also describes the relationship between these data types
798 and the equivalent C data types.
800 The following data types are supported: @code{INTEGER},
801 @code{LONGINT}, @code{SHORTINT}, @code{CARDINAL}, @code{LONGCARD},
802 @code{SHORTCARD}, @code{BOOLEAN}, @code{REAL}, @code{LONGREAL},
803 @code{SHORTREAL}, @code{COMPLEX}, @code{LONGCOMPLEX},
804 @code{SHORTCOMPLEX} and @code{CHAR}.
806 An equivalence table is given below:
810 ======================================
812 LONGINT long long int
814 CARDINAL unsigned int
815 LONGCARD long long unsigned int
816 SHORTCARD short unsigned int
822 SHORTCOMPLEX complex float
823 COMPLEX complex double
824 LONGCOMPLEX complex long double
827 Note that GNU Modula-2 also supports fixed sized data types which are
828 exported from the @code{SYSTEM} module.
829 @xref{The PIM system module, , ,gm2}.
830 @xref{The ISO system module, , ,gm2}.
832 @node Standard procedures, Dialect, Elementary data types, Using
833 @section Permanently accessible base procedures.
835 This section describes the procedures and functions which are
838 @subsection Standard procedures and functions common to PIM and ISO
840 The following procedures are implemented and conform with Programming
841 in Modula-2 and ISO Modula-2: @code{NEW}, @code{DISPOSE}, @code{INC},
842 @code{DEC}, @code{INCL}, @code{EXCL} and @code{HALT}. The standard
843 functions are: @code{ABS}, @code{CAP}, @code{CHR}, @code{FLOAT},
844 @code{HIGH}, @code{LFLOAT}, @code{LTRUNC}, @code{MIN}, @code{MAX},
845 @code{ODD}, @code{SFLOAT}, @code{STRUNC} @code{TRUNC} and
846 @code{VAL}. All these functions and procedures (except @code{HALT},
847 @code{NEW}, @code{DISPOSE} and, under non constant conditions,
848 @code{LENGTH}) generate in-line code for efficiency.
853 ABS - returns the positive value of i.
857 PROCEDURE ABS (i: <any signed type>) : <any signed type> ;
864 CAP - returns the capital of character ch providing
865 ch lies within the range 'a'..'z'. Otherwise ch
866 is returned unaltered.
870 PROCEDURE CAP (ch: CHAR) : CHAR ;
877 CHR - converts a value of a <whole number type> into a CHAR.
878 CHR(x) is shorthand for VAL(CHAR, x).
882 PROCEDURE CHR (x: <whole number type>) : CHAR ;
889 DISPOSE - the procedure DISPOSE is replaced by:
890 DEALLOCATE(p, TSIZE(p^)) ;
891 The user is expected to import the procedure DEALLOCATE
892 (normally found in the module, Storage.)
894 In: a variable p: of any pointer type which has been
895 initialized by a call to NEW.
896 Out: the area of memory
897 holding p^ is returned to the system.
898 Note that the underlying procedure DEALLOCATE
899 procedure in module Storage will assign p to NIL.
903 PROCEDURE DISPOSE (VAR p:<any pointer type>) ;
909 DEC - can either take one or two parameters. If supplied
910 with one parameter then on the completion of the call to
911 DEC, v will have its predecessor value. If two
912 parameters are supplied then the value v will have its
913 n'th predecessor. For these reasons the value of n
918 PROCEDURE DEC (VAR v: <any base type>; [n: <any base type> = 1]) ;
924 EXCL - excludes bit element e from a set type s.
928 PROCEDURE EXCL (VAR s: <any set type>; e: <element of set type s>) ;
934 FLOAT - will return a REAL number whose value is the same as o.
938 PROCEDURE FLOAT (o: <any whole number type>) : REAL ;
944 FLOATS - will return a SHORTREAL number whose value is the same as o.
948 PROCEDURE FLOATS (o: <any whole number type>) : REAL ;
954 FLOATL - will return a LONGREAL number whose value is the same as o.
958 PROCEDURE FLOATL (o: <any whole number type>) : REAL ;
964 HALT - will call the HALT procedure inside the module M2RTS.
965 Users can replace M2RTS.
975 HIGH - returns the last accessible index of an parameter declared as
978 PROCEDURE foo (a: ARRAY OF CHAR) ;
989 will cause the local variable c to contain the value 4
993 PROCEDURE HIGH (a: ARRAY OF CHAR) : CARDINAL ;
999 INC - can either take one or two parameters. If supplied
1000 with one parameter then on the completion of the call to
1001 INC, v will have its successor value. If two
1002 parameters are supplied then the value v will have its
1003 n'th successor. For these reasons the value of n
1008 PROCEDURE INC (VAR v: <any base type>; [n: <any base type> = 1]) ;
1014 INCL - includes bit element e to a set type s.
1018 PROCEDURE INCL (VAR s: <any set type>; e: <element of set type s>) ;
1024 LFLOAT - will return a LONGREAL number whose value is the same as o.
1028 PROCEDURE LFLOAT (o: <any whole number type>) : LONGREAL ;
1034 LTRUNC - will return a LONG<type> number whose value is the
1035 same as o. PIM2, PIM3 and ISO Modula-2 will return
1036 a LONGCARD whereas PIM4 returns LONGINT.
1040 PROCEDURE LTRUNC (o: <any floating point type>) : LONG<type> ;
1046 MIN - returns the lowest legal value of an ordinal type.
1050 PROCEDURE MIN (t: <ordinal type>) : <ordinal type> ;
1057 MAX - returns the largest legal value of an ordinal type.
1061 PROCEDURE MAX (t: <ordinal type>) : <ordinal type> ;
1068 NEW - the procedure NEW is replaced by:
1069 ALLOCATE(p, TSIZE(p^)) ;
1070 The user is expected to import the procedure ALLOCATE
1071 (normally found in the module, Storage.)
1073 In: a variable p: of any pointer type.
1074 Out: variable p is set to some allocated memory
1075 which is large enough to hold all the contents of p^.
1079 PROCEDURE NEW (VAR p:<any pointer type>) ;
1085 ODD - returns TRUE if the value is not divisible by 2.
1089 PROCEDURE ODD (x: <whole number type>) : BOOLEAN ;
1096 SFLOAT - will return a SHORTREAL number whose value is the same
1101 PROCEDURE SFLOAT (o: <any whole number type>) : SHORTREAL ;
1107 STRUNC - will return a SHORT<type> number whose value is the same
1108 as o. PIM2, PIM3 and ISO Modula-2 will return a
1109 SHORTCARD whereas PIM4 returns SHORTINT.
1113 PROCEDURE STRUNC (o: <any floating point type>) : SHORT<type> ;
1119 TRUNC - will return a <type> number whose value is the same as o.
1120 PIM2, PIM3 and ISO Modula-2 will return a CARDINAL
1121 whereas PIM4 returns INTEGER.
1125 PROCEDURE TRUNC (o: <any floating point type>) : <type> ;
1131 TRUNCS - will return a <type> number whose value is the same
1132 as o. PIM2, PIM3 and ISO Modula-2 will return a
1133 SHORTCARD whereas PIM4 returns SHORTINT.
1137 PROCEDURE TRUNCS (o: <any floating point type>) : <type> ;
1143 TRUNCL - will return a <type> number whose value is the same
1144 as o. PIM2, PIM3 and ISO Modula-2 will return a
1145 LONGCARD whereas PIM4 returns LONGINT.
1149 PROCEDURE TRUNCL (o: <any floating point type>) : <type> ;
1155 VAL - converts data i of <any simple data type 2> to
1156 <any simple data type 1> and returns this value.
1157 No range checking is performed during this conversion.
1161 PROCEDURE VAL (<any simple data type 1>,
1162 i: <any simple data type 2>) : <any simple data type 1> ;
1166 @subsection ISO specific standard procedures and functions
1168 The standard function @code{LENGTH} is specific to ISO Modula-2 and
1174 IM - returns the imaginary component of a complex type.
1175 The return value will the same type as the imaginary field
1176 within the complex type.
1180 PROCEDURE IM (c: <any complex type>) : <floating point type> ;
1186 INT - returns an INTEGER value which has the same value as v.
1187 This function is equivalent to: VAL(INTEGER, v).
1191 PROCEDURE INT (v: <any ordinal type>) : INTEGER ;
1197 LENGTH - returns the length of string a.
1201 PROCEDURE LENGTH (a: ARRAY OF CHAR) : CARDINAL ;
1204 This function is evaluated at compile time, providing that string
1205 @code{a} is a constant. If @code{a} cannot be evaluated then a call is
1206 made to @code{M2RTS.Length}.
1211 ODD - returns a BOOLEAN indicating whether the whole number
1216 PROCEDURE ODD (v: <any whole number type>) : BOOLEAN ;
1222 RE - returns the real component of a complex type.
1223 The return value will the same type as the real field
1224 within the complex type.
1228 PROCEDURE RE (c: <any complex type>) : <floating point type> ;
1231 @node Dialect, Exceptions, Standard procedures, Using
1232 @section GNU Modula-2 supported dialects
1234 This section describes the dialects understood by GNU Modula-2.
1235 It also describes the differences between the dialects and
1236 any command line switches which determine dialect behaviour.
1238 The GNU Modula-2 compiler is compliant with four dialects of Modula-2.
1239 The language as defined in 'Programming in Modula-2' 2nd Edition,
1240 Springer Verlag, 1982, 1983 by Niklaus Wirth (PIM2), 'Programming in
1241 Modula-2', 3rd Corrected Edition, Springer Verlag, 1985 (PIM3) and
1242 'Programming in Modula-2', 4th Edition, Springer Verlag, 1988 (PIM4)
1243 @uref{http://freepages.modula2.org/report4/modula-2.html} and the ISO
1244 Modula-2 language as defined in ISO/IEC Information technology -
1245 programming languages - part 1: Modula-2 Language, ISO/IEC 10514-1
1248 The command line switches @samp{-fpim2}, @samp{-fpim3}, @samp{-fpim4}
1249 and @samp{-fiso} can be used to force mutually exclusive
1250 features. However by default the compiler will not aggressively fail
1251 if a non mutually exclusive feature is used from another dialect. For
1252 example it is possible to specify @samp{-fpim2} and still utilize
1253 @samp{DEFINITION} @samp{MODULES} which have no export list.
1255 Some dialect differences will force a compile time error, for example
1256 in PIM2 the user must @code{IMPORT} @code{SIZE} from the module
1257 @code{SYSTEM}, whereas in PIM3 and PIM4 @code{SIZE} is a pervasive
1258 function. Thus compiling PIM4 source code with the @samp{-fpim2}
1259 switch will cause a compile time error. This can be fixed quickly
1260 with an additional @code{IMPORT} or alternatively by compiling with
1261 the @samp{-fpim4} switch.
1263 However there are some very important differences between the dialects
1264 which are mutually exclusive and therefore it is vital that users
1265 choose the dialects with care when these language features are used.
1267 @subsection Integer division, remainder and modulus
1269 The most dangerous set of mutually exclusive features found in the
1270 four dialects supported by GNU Modula-2 are the @code{INTEGER}
1271 division, remainder and modulus arithmetic operators. It is important
1272 to note that the same source code can be compiled to give different
1273 run time results depending upon these switches! The reference manual
1274 for the various dialects of Modula-2 are quite clear about this
1275 behavior and sadly there are three distinct definitions.
1277 The table below illustrates the problem when a negative operand is
1282 ----------- ----------- ----------------------
1283 lval rval DIV MOD DIV MOD DIV MOD / REM
1284 31 10 3 1 3 1 3 1 3 1
1285 -31 10 -3 -1 -4 9 -4 9 -3 -1
1286 31 -10 -3 1 -3 1 Exception -3 1
1287 -31 -10 3 -1 4 9 Exception 3 -1
1290 See also P24 of PIM2, P27 of PIM3, P29 of PIM4 and P201 of the ISO
1291 Standard. At present all dialect division, remainder and modulus are
1292 implemented as above, apart from the exception calling in the ISO
1293 dialect. Instead of exception handling the results are the same as the
1294 PIM4 dialect. This is a temporary implementation situation.
1296 @node Exceptions, Semantic checking, Dialect, Using
1297 @section Exception implementation
1299 This section describes how exceptions are implemented in GNU Modula-2
1300 and how command line switches affect their behavior. The option
1301 @samp{-fsoft-check-all} enables all software checking of nil
1302 dereferences, division by zero etc. Additional code is produced to
1303 check these conditions and exception handlers are invoked if the
1306 Without @samp{-fsoft-check-all} these exceptions will be caught by
1307 hardware (assuming the hardware support exists) and a signal handler
1308 is invoked. The signal handler will in turn @code{THROW} an exception
1309 which will be caught by the appropriate Modula-2 handler. However the
1310 action of throwing an exception from within a signal handler is
1311 implementation defined (according to the C++ documentation). For
1312 example on the x86_64 architecture this works whereas on the i686
1313 architecture it does not. Therefore to ensure portability it is
1314 recommended to use @samp{-fsoft-check-all}.
1316 @footnote{@samp{-fsoft-check-all} can be effectively combined with
1317 @samp{-O2} to semantically analyze source code for possible run time
1318 errors at compile time.}
1320 @node Semantic checking, Extensions, Exceptions, Using
1321 @section How to detect run time problems at compile time
1323 Consider the following program:
1326 MODULE assignvalue ; (*!m2iso+gm2*)
1328 PROCEDURE bad () : INTEGER ;
1339 (* The m2rte plugin will detect this as an error, post
1345 here we see that the programmer has overlooked that the return value
1346 from @samp{bad} will cause an overflow to @samp{foo}. If we compile
1347 the code with the following options:
1350 $ gm2 -g -fsoft-check-all -O2 -c assignvalue.mod
1351 assignvalue.mod:16:0:inevitable that this error will occur at run time,
1352 assignment will result in an overflow
1355 The gm2 semantic plugin is automatically run and will generate a
1356 warning message for every exception call which is known as reachable.
1357 It is highly advised to run the optimizer (@samp{-O2} or @samp{-O3})
1358 with @samp{-fsoft-check-all} so that the compiler is able to run the
1359 optimizer and perform variable and flow analysis before the semantic
1362 @node Extensions, Type compatibility, Semantic checking, Using
1363 @section GNU Modula-2 language extensions
1365 This section introduces the GNU Modula-2 language extensions.
1366 The GNU Modula-2 compiler allows abstract data types to be any type,
1367 not just restricted to a pointer type providing the
1368 @samp{-fextended-opaque} option is supplied
1369 @xref{Compiler options, , ,gm2}.
1371 Declarations can be made in any order, whether they are
1372 types, constants, procedures, nested modules or variables.
1373 @c (@xref{Passes, , ,}.)
1375 GNU Modula-2 also allows programmers to interface to @code{C} and
1378 GNU Modula-2 provides support for the special tokens @code{__LINE__},
1379 @code{__FILE__}, @code{__FUNCTION__} and @code{__DATE__}. Support for
1380 these tokens will occur even if the @samp{-fcpp} option is not
1381 supplied. A table of these identifiers and their data type and values
1385 Scope GNU Modula-2 token Data type and example value
1387 anywhere __LINE__ Constant Literal compatible
1388 with CARDINAL, INTEGER and WORD.
1391 anywhere __FILE__ Constant string compatible
1392 with parameter ARRAY OF CHAR or
1393 an ARRAY whose SIZE is >= string
1397 procedure __FUNCTION__ Constant string compatible
1398 with parameter ARRAY OF CHAR or
1399 an ARRAY whose SIZE is >= string
1403 module __FUNCTION__ Example
1404 "module hello initialization"
1406 anywhere __DATE__ Constant string compatible
1407 with parameter ARRAY OF CHAR or
1408 an ARRAY whose SIZE is >= string
1410 "Thu Apr 29 10:07:16 BST 2004"
1412 anywhere __COLUMN__ Gives a constant literal number
1413 determining the left hand column
1414 where the first _ appears in
1415 __COLUMN__. The left most column
1420 The preprocessor @samp{cpp} can be invoked via the @samp{-fcpp}
1421 command line option. This in turn invokes @samp{cpp} with the
1422 following arguments @samp{-traditional -lang-asm}. These options
1423 preserve comments and all quotations. @samp{gm2} treats a @samp{#}
1424 character in the first column as a preprocessor directive.
1426 For example here is a module which calls @code{FatalError}
1427 via the macro @code{ERROR}.
1432 FROM SYSTEM IMPORT ADR, SIZE ;
1433 FROM libc IMPORT exit, printf, malloc ;
1435 PROCEDURE FatalError (a, file: ARRAY OF CHAR;
1437 func: ARRAY OF CHAR) ;
1439 printf ("%s:%d:fatal error, %s, in %s\n",
1440 ADR (file), line, ADR (a), ADR (func)) ;
1444 #define ERROR(X) FatalError(X, __FILE__, __LINE__, __FUNCTION__)
1447 pc: POINTER TO CARDINAL;
1449 pc := malloc (SIZE (CARDINAL)) ;
1452 ERROR ('out of memory')
1457 Another use for the C preprocessor in Modula-2 might be to turn on
1458 debugging code. For example the library module
1459 @file{FormatStrings.mod} uses procedures from @file{DynamicStrings.mod}
1460 and to track down memory leaks it was useful to track the source file
1461 and line where each string was created. Here is a section of
1462 @file{FormatStrings.mod} which shows how the debugging code was
1463 enabled and disabled by adding @code{-fcpp} to the command line.
1466 FROM DynamicStrings IMPORT String, InitString, InitStringChar, Mark,
1467 ConCat, Slice, Index, char,
1468 Assign, Length, Mult, Dup, ConCatChar,
1469 PushAllocation, PopAllocationExemption,
1470 InitStringDB, InitStringCharStarDB,
1471 InitStringCharDB, MultDB, DupDB, SliceDB ;
1474 #define InitString(X) InitStringDB(X, __FILE__, __LINE__)
1475 #define InitStringCharStar(X) InitStringCharStarDB(X, __FILE__, \
1477 #define InitStringChar(X) InitStringCharDB(X, __FILE__, __LINE__)
1478 #define Mult(X,Y) MultDB(X, Y, __FILE__, __LINE__)
1479 #define Dup(X) DupDB(X, __FILE__, __LINE__)
1480 #define Slice(X,Y,Z) SliceDB(X, Y, Z, __FILE__, __LINE__)
1483 PROCEDURE doDSdbEnter ;
1488 PROCEDURE doDSdbExit (s: String) ;
1490 s := PopAllocationExemption (TRUE, s)
1493 PROCEDURE DSdbEnter ;
1497 PROCEDURE DSdbExit (s: String) ;
1502 #define DBsbEnter doDBsbEnter
1503 #define DBsbExit doDBsbExit
1506 PROCEDURE Sprintf1 (s: String; w: ARRAY OF BYTE) : String ;
1509 s := FormatString (HandleEscape (s), w) ;
1515 It is worth noting that the overhead of this code once @code{-fcpp} is
1516 not present and -O2 is used will be zero since the local empty
1517 procedures @code{DSdbEnter} and @code{DSdbExit} will be thrown away by
1518 the optimization passes of the GCC backend.
1520 @subsection Optional procedure parameter
1522 GNU Modula-2 allows the last parameter to a procedure or function
1523 parameter to be optional. For example in the ISO library
1524 @file{COROUTINES.def} the procedure @code{NEWCOROUTINE} is defined as
1525 having an optional fifth argument (@code{initProtection}) which, if
1526 absent, is automatically replaced by @code{NIL}.
1529 @findex NEWCOROUTINE
1530 PROCEDURE NEWCOROUTINE (procBody: PROC; workspace: SYSTEM.ADDRESS;
1531 size: CARDINAL; VAR cr: COROUTINE;
1532 [initProtection: PROTECTION = NIL]);
1534 (* Creates a new coroutine whose body is given by procBody,
1535 and returns the identity of the coroutine in cr.
1536 workspace is a pointer to the work space allocated to
1537 the coroutine; size specifies the size of this workspace
1538 in terms of SYSTEM.LOC.
1540 The optional fifth argument may contain a single parameter
1541 which specifies the initial protection level of the coroutine.
1545 The implementation module @file{COROUTINES.mod} implements this
1546 procedure using the following syntax:
1549 PROCEDURE NEWCOROUTINE (procBody: PROC; workspace: SYSTEM.ADDRESS;
1550 size: CARDINAL; VAR cr: COROUTINE;
1551 [initProtection: PROTECTION]);
1557 Note that it is illegal for this declaration to contain an initializer
1558 value for @code{initProtection}. However it is necessary to surround
1559 this parameter with the brackets @code{[} and @code{]}. This serves to
1560 remind the programmer that the last parameter was declared as optional
1561 in the definition module.
1563 Local procedures can be declared to have an optional final parameter
1564 in which case the initializer is mandatory in the implementation or
1567 GNU Modula-2 also provides additional fixed sized data types which
1568 are all exported from the @code{SYSTEM} module.
1569 @xref{The PIM system module, , ,gm2}.
1570 @xref{The ISO system module, , ,gm2}.
1572 @node Type compatibility, Unbounded by reference, Extensions, Using
1573 @section Type compatibility
1575 This section discuss the issues surrounding assignment, expression
1576 and parameter compatibility, their effect of the additional
1577 fixed sized datatypes and also their effect of run time checking.
1578 The data types supported by the compiler are:
1581 GNU Modula-2 scope switches
1582 =============================================
1595 SHORTCOMPLEX pervasive
1597 LONGCOMPLEX pervasive
1604 The following extensions are supported for
1605 most architectures (please check SYSTEM.def).
1606 =============================================
1631 The Modula-2 language categorizes compatibility between entities of
1632 possibly differing types into three sub components: expressions,
1633 assignments, and parameters. Parameter compatibility is further
1634 divided into two sections for pass by reference and pass by value
1637 For more detail on the Modula-2 type compatibility see the Modula-2
1638 ISO standard BS ISO/IEC 10514-1:1996 page 121-125. For detail on the
1639 PIM type compatibility see Programming in Modula-2 Edition 4 page 29,
1640 (Elementary Data Types).
1642 @subsection Expression compatibility
1644 Modula-2 restricts the types of expressions to the same type.
1645 Expression compatibility is a symmetric relation.
1647 For example two sub expressions of @code{INTEGER} and @code{CARDINAL}
1648 are not expression compatible
1649 (@uref{http://freepages.modula2.org/report4/modula-2.html} and ISO
1652 In GNU Modula-2 this rule is also extended across all fixed sized data
1653 types (imported from SYSTEM).
1655 @subsection Assignment compatibility
1657 This section discusses the assignment issues surrounding assignment
1658 compatibility of elementary types (@code{INTEGER}, @code{CARDINAL},
1659 @code{REAL} and @code{CHAR} for example). The information here is
1660 found in more detail in the Modula-2 ISO standard BS ISO/IEC
1661 10514-1:1996 page 122.
1663 Assignment compatibility exists between the same sized elementary
1666 Same type family of different sizes are
1667 also compatible as long as the @code{MAX(}type@code{)} and
1668 @code{MIN(}type@code{)} is known. So for example this includes the
1669 @code{INTEGER} family, @code{CARDINAL} family and the @code{REAL}
1672 The reason for this is that when the assignment is performed
1673 the compiler will check to see that the expression (on the right of
1674 the @code{:=}) lies within the range of the designator type (on the
1675 left hand side of the @code{:=}). Thus these ordinal types can be
1676 assignment compatible. However it does mean that @code{WORD32} is not
1677 compatible with @code{WORD16} as @code{WORD32} does not have a minimum
1678 or maximum value and therefore cannot be checked. The compiler does
1679 not know which of the two bytes from @code{WORD32} should be copied
1680 into @code{WORD16} and which two should be ignored. Currently the
1681 types @code{BITSET8}, @code{BITSET16} and @code{BITSET32} are
1682 assignment incompatible. However this restriction maybe lifted when
1683 further run time checking is achieved.
1685 Modula-2 does allow @code{INTEGER} to be assignment compatible with
1686 @code{WORD} as they are the same size. Likewise GNU Modula-2 allows
1687 @code{INTEGER16} to be compatible with @code{WORD16} and the same for
1688 the other fixed sized types and their sized equivalent in either
1689 @code{WORD}n, @code{BYTE} or @code{LOC} types. However it prohibits
1690 assignment between @code{WORD} and @code{WORD32} even though on many
1691 systems these sizes will be the same. The reasoning behind this rule
1692 is that the extended fixed sized types are meant to be used by
1693 applications requiring fixed sized data types and it is more portable
1694 to forbid the blurring of the boundaries between fixed sized and
1695 machine dependent sized types.
1697 Intermediate code run time checking is always generated by the front
1698 end. However this intermediate code is only translated into actual
1699 code if the appropriate command line switches are specified. This
1700 allows the compiler to perform limited range checking at compile time.
1701 In the future it will allow the extensive GCC optimizations to
1702 propagate constant values through to the range checks which if they
1703 are found to exceed the type range will result in a compile time
1706 @subsection Parameter compatibility
1708 Parameter compatibility is divided into two areas, pass by value and
1709 pass by reference (@code{VAR}). In the case of pass by value the
1710 rules are exactly the same as assignment. However in the second case,
1711 pass by reference, the actual parameter and formal parameter must be
1712 the same size and family. Furthermore @code{INTEGER} and
1713 @code{CARDINAL}s are not treated as compatible in the pass by
1716 The types @code{BYTE}, @code{LOC}, @code{WORD} and @code{WORD}n
1717 derivatives are assignment and parameter compatible with any data type
1720 @node Unbounded by reference, Building a shared library, Type compatibility, Using
1721 @section Unbounded by reference
1723 This section documents a GNU Modula-2 compiler switch which implements
1724 a language optimization surrounding the implementation of unbounded
1725 arrays. In GNU Modula-2 the unbounded array is implemented by
1726 utilizing an internal structure @code{struct @{dataType *address,
1727 unsigned int high@}}. So given the Modula-2 procedure declaration:
1730 PROCEDURE foo (VAR a: ARRAY OF dataType) ;
1736 it is translated into GCC @code{tree}s, which can be represented
1737 in their C form thus:
1740 void foo (struct @{dataType *address, unsigned int high@} a)
1742 if (a.address[2] == /* etc */
1746 Whereas if the procedure @code{foo} was declared as:
1749 PROCEDURE foo (a: ARRAY OF dataType) ;
1755 then it is implemented by being translated into the following
1756 GCC @code{tree}s, which can be represented in their C form thus:
1759 void foo (struct @{dataType *address, unsigned int high@} a)
1761 dataType *copyContents = (dataType *)alloca (a.high+1);
1762 memcpy(copyContents, a.address, a.high+1);
1763 a.address = copyContents;
1765 if (a.address[2] == /* etc */
1769 This implementation works, but it makes a copy of each non VAR
1770 unbounded array when a procedure is entered. If the unbounded array
1771 is not changed during procedure @code{foo} then this implementation
1772 will be very inefficient. In effect Modula-2 lacks the @code{REF}
1773 keyword of Ada. Consequently the programmer maybe tempted to
1774 sacrifice semantic clarity for greater efficiency by declaring the
1775 parameter using the @code{VAR} keyword in place of @code{REF}.
1777 The @code{-funbounded-by-reference} switch instructs the compiler to
1778 check and see if the programmer is modifying the content of any
1779 unbounded array. If it is modified then a copy will be made upon
1780 entry into the procedure. Conversely if the content is only read and
1781 never modified then this non @code{VAR} unbounded array is a candidate
1782 for being passed by reference. It is only a candidate as it is still
1783 possible that passing this parameter by reference could alter the
1784 meaning of the source code. For example consider the following case:
1787 PROCEDURE StrConCat (VAR a: ARRAY OF CHAR; b, c: ARRAY OF CHAR) ;
1789 (* code which performs string a := b + c *)
1794 a: ARRAY [0..3] OF CHAR ;
1801 In the code above we see that the same parameter, @code{a}, is being
1802 passed three times to @code{StrConCat}. Clearly even though parameters
1803 @code{b} and @code{c} are never modified it would be incorrect to
1804 implement them as pass by reference. Therefore the compiler checks to
1805 see if any non @code{VAR} parameter is type compatible with any
1806 @code{VAR} parameter and if so it generates run time procedure entry
1807 checks to determine whether the contents of parameters @code{b} or
1808 @code{c} matches the contents of @code{a}. If a match is detected
1809 then a copy is made and the @code{address} in the unbounded
1810 @code{struct}ure is modified.
1812 The compiler will check the address range of each candidate against
1813 the address range of any @code{VAR} parameter, providing they are type
1814 compatible. For example consider:
1817 PROCEDURE foo (a: ARRAY OF BYTE; VAR f: REAL) ;
1833 Here we see that although parameter, @code{a}, is a candidate for the
1834 passing by reference, it would be incorrect to use this
1835 transformation. Thus the compiler detects that parameters, @code{a}
1836 and @code{f} are type compatible and will produce run time checking
1837 code to test whether the address range of their respective contents
1840 @node Building a shared library, Interface for Python, Unbounded by reference, Using
1841 @section Building a shared library
1843 This section describes building a tiny shared library implemented in
1844 Modula-2 and built with @file{libtool}. Suppose a project consists of
1845 two definition modules and two implementation modules and a program
1846 module @file{a.def}, @file{a.mod}, @file{b.def}, @file{b.mod} and
1847 @file{c.mod}. The first step is to compile the modules using position
1848 independent code. This can be achieved by the following three
1852 libtool --tag=CC --mode=compile gm2 -g -c a.mod -o a.lo
1853 libtool --tag=CC --mode=compile gm2 -g -c b.mod -o b.lo
1854 libtool --tag=CC --mode=compile gm2 -g -c c.mod -o c.lo
1857 The second step is to generate the shared library initialization and
1858 finalization routines. We can do this by asking gm2 to generate a
1859 list of dependent modules and then use this to generate the scaffold.
1860 We also must compile the scaffold.
1863 gm2 -c -g -fmakelist c.mod
1864 gm2 -c -g -fmakeinit -fshared c.mod
1865 libtool --tag=CC --mode=compile g++ -g -c c_m2.cpp -o c_m2.lo
1868 The third step is to link all these @file{.lo} files.
1871 libtool --mode=link gcc -g c_m2.lo a.lo b.lo c.lo \
1873 -rpath `pwd` -lgm2 -lstdc++ -lm -o libabc.la
1876 At this point the shared library @file{libabc.so} will have been
1877 created inside the directory @file{.libs}.
1879 @node Interface for Python, Producing a Python module, Building a shared library, Using
1880 @section How to produce swig interface files
1882 This section describes how Modula-2 implementation modules can be
1883 called from Python (and other scripting languages such as TCL and
1884 Perl). GNU Modula-2 can be instructed to create a swig interface when
1885 it is compiling an implementation module. Swig then uses the
1886 interface file to generate all the necessary wrapping to that the
1887 desired scripting language may access the implementation module.
1889 Here is an example of how you might call upon the services of the
1890 Modula-2 library module @code{NumberIO} from Python3.
1892 The following commands can be used to generate the Python3 module:
1895 export src=@samp{directory to the sources}
1896 export prefix=@samp{directory to where the compiler is installed}
1897 gm2 -I$@{src@} -c -g -fswig $@{src@}/../../../gm2-libs/NumberIO.mod
1898 gm2 -I$@{src@} -c -g -fmakelist $@{src@}/../../../gm2-libs/NumberIO.mod
1900 gm2 -I$@{src@} -c -g -fmakeinit -fshared \
1901 $@{src@}/../../../gm2-libs/NumberIO.mod
1903 swig -c++ -python3 NumberIO.i
1905 libtool --mode=compile g++ -g -c -I$@{src@} NumberIO_m2.cpp \
1908 libtool --tag=CC --mode=compile gm2 -g -c \
1909 -I$@{src@}../../../gm2-libs \
1910 $@{src@}/../../../gm2-libs/NumberIO.mod -o NumberIO.lo
1912 libtool --tag=CC --mode=compile g++ -g -c NumberIO_wrap.cxx \
1913 -I/usr/include/python3 -o NumberIO_wrap.lo
1915 libtool --mode=link gcc -g NumberIO_m2.lo NumberIO_wrap.lo \
1916 -L$@{prefix@}/lib64 \
1917 -rpath `pwd` -lgm2 -lstdc++ -lm -o libNumberIO.la
1919 cp .libs/libNumberIO.so _NumberIO.so
1922 The first four commands, generate the swig interface file
1923 @file{NumberIO.i} and python wrap files @file{NumberIO_wrap.cxx} and
1924 @file{NumberIO.py}. The next three @file{libtool} commnads compile
1925 the C++ and Modula-2 source code into @file{.lo} objects. The last
1926 @file{libtool} command links all the @file{.lo} files into a
1927 @file{.la} file and includes all shared library dependencies.
1929 Now it is possible to run the following Python script
1930 (called @file{testnum.py}):
1935 print ("1234 x 2 =", NumberIO.NumberIO_StrToInt("1234")*2)
1941 $ python3 testnum.py
1945 @xref{Producing a Python module, , ,gm2} for another example which
1946 uses the @code{UNQUALIFIED} keyword to reduce the module name clutter
1947 from the viewport of Python3.
1949 @subsection Limitations of automatic generated of Swig files
1951 This section discusses the limitations of automatically generating
1952 swig files. From the previous example we see that the module
1953 @code{NumberIO} had a swig interface file @file{NumberIO.i}
1954 automatically generated by the compiler. If we consider three of the
1955 procedure definitions in @file{NumberIO.def} we can see the
1956 success and limitations of the automatic interface generation.
1959 PROCEDURE StrToHex (a: ARRAY OF CHAR; VAR x: CARDINAL) ;
1960 PROCEDURE StrToInt (a: ARRAY OF CHAR; VAR x: INTEGER) ;
1961 PROCEDURE ReadInt (VAR x: CARDINAL) ;
1964 Below are the swig interface prototypes:
1967 extern void NumberIO_StrToHex (char *_m2_address_a,
1968 int _m2_high_a, unsigned int *OUTPUT);
1969 /* parameters: x is known to be an OUTPUT */
1970 extern void NumberIO_StrToInt (char *_m2_address_a,
1971 int _m2_high_a, int *OUTPUT);
1972 /* parameters: x is guessed to be an OUTPUT */
1973 extern void NumberIO_ReadInt (int *x);
1974 /* parameters: x is unknown */
1977 In the case of @code{StrToHex} it can be seen that the compiler
1978 detects that the last parameter is an output. It explicitly tells
1979 swig this by using the parameter name @code{OUTPUT} and in the
1980 following comment it informs the user that it knows this to be an
1981 output parameter. In the second procedure @code{StrToInt} it marks
1982 the final parameter as an output, but it tells the user that this is
1983 only a guess. Finally in @code{ReadInt} it informs the user that
1984 it does not know whether the parameter, @code{x}, is an output, input
1985 or an inout parameter.
1987 The compiler decides whether to mark a parameter as either:
1988 @code{INPUT}, @code{OUTPUT} or @code{INOUT} if it is read before
1989 written or visa versa in the first basic block. At this point
1990 it will write output that the parameter is known. If it is not
1991 read or written in the first basic block then subsequent basic blocks
1992 are searched and the result is commented as a guess. Finally if
1993 no read or write occurs then the parameter is commented as unknown.
1994 However, clearly it is possible to fool this mechanism. Nevertheless
1995 automatic generation of implementation module into swig interface files
1996 was thought sufficiently useful despite these limitations.
1998 In conclusion it would be wise to check all parameters in any
1999 automatically generated swig interface file. Furthermore you can
2000 force the automatic mechanism to generate correct interface files by
2001 reading or writing to the @code{VAR} parameter in the first basic
2002 block of a procedure.
2004 @node Producing a Python module, Interface to C, Interface for Python, Using
2005 @section How to produce a Python module
2007 This section describes how it is possible to produce a Python module
2008 from Modula-2 code. There are a number of advantages to this
2009 approach, it ensures your code reaches a wider audience, maybe it is
2010 easier to initialize your application in Python.
2012 The example application here is a pedagogical two dimensional gravity
2013 next event simulation. The Python module needs to have a clear API
2014 which should be placed in a single definition module. Furthermore the
2015 API should only use fundamental pervasive data types and strings.
2016 Below the API is contained in the file @file{twoDsim.def}:
2019 DEFINITION MODULE twoDsim ;
2021 EXPORT UNQUALIFIED gravity, box, poly3, poly5, poly6, mass,
2022 fix, circle, pivot, velocity, accel, fps,
2023 replayRate, simulateFor ;
2025 gravity - turn on gravity at: g m^2
2028 PROCEDURE gravity (g: REAL) ;
2032 box - place a box in the world at (x0,y0),(x0+i,y0+j)
2035 PROCEDURE box (x0, y0, i, j: REAL) : CARDINAL ;
2039 poly3 - place a triangle in the world at:
2040 (x0,y0),(x1,y1),(x2,y2)
2043 PROCEDURE poly3 (x0, y0, x1, y1, x2, y2: REAL) : CARDINAL ;
2047 poly5 - place a pentagon in the world at:
2048 (x0,y0),(x1,y1),(x2,y2),(x3,y3),(x4,y4)
2051 PROCEDURE poly5 (x0, y0, x1, y1,
2052 x2, y2, x3, y3, x4, y4: REAL) : CARDINAL ;
2056 poly6 - place a hexagon in the world at:
2057 (x0,y0),(x1,y1),(x2,y2),(x3,y3),(x4,y4),(x5,y5)
2060 PROCEDURE poly6 (x0, y0, x1, y1,
2062 x4, y4, x5, y5: REAL) : CARDINAL ;
2066 mass - specify the mass of an object and return the, id.
2069 PROCEDURE mass (id: CARDINAL; m: REAL) : CARDINAL ;
2073 fix - fix the object to the world.
2076 PROCEDURE fix (id: CARDINAL) : CARDINAL ;
2080 circle - adds a circle to the world. Center
2081 defined by: x0, y0 radius, r.
2084 PROCEDURE circle (x0, y0, r: REAL) : CARDINAL ;
2088 velocity - give an object, id, a velocity, vx, vy.
2091 PROCEDURE velocity (id: CARDINAL; vx, vy: REAL) : CARDINAL ;
2095 accel - give an object, id, an acceleration, ax, ay.
2098 PROCEDURE accel (id: CARDINAL; ax, ay: REAL) : CARDINAL ;
2102 fps - set frames per second.
2105 PROCEDURE fps (f: REAL) ;
2109 replayRate - set frames per second during replay.
2112 PROCEDURE replayRate (f: REAL) ;
2116 simulateFor - render for, t, seconds.
2119 PROCEDURE simulateFor (t: REAL) ;
2125 The keyword @code{UNQUALIFIED} can be used to ensure that the
2126 compiler will provide externally accessible functions
2127 @code{gravity}, @code{box}, @code{poly3}, @code{poly5}, @code{poly6},
2128 @code{mass}, @code{fix}, @code{circle}, @code{pivot}, @code{velocity},
2129 @code{accel}, @code{fps}, @code{replayRate}, @code{simulateFor}
2130 rather than name mangled alternatives.
2131 Hence in our Python3 application we could write:
2134 #!/usr/bin/env python3
2136 from twoDsim import *
2138 b = box (0.0, 0.0, 1.0, 1.0)
2140 c1 = circle (0.7, 0.7, 0.05)
2141 c1 = mass (c1, 0.01)
2142 c2 = circle (0.7, 0.1, 0.05)
2143 c2 = mass (c2, 0.01)
2148 print ("creating frames")
2153 print ("exception raised")
2156 which accesses the various functions defined and implemented by the
2157 module @code{twoDsim}. The Modula-2 source code is compiled via:
2160 $ gm2 -g -fiso -c -fswig twoDsim.mod
2161 $ gm2 -g -fiso -c -fmakelist twoDsim.mod
2162 $ gm2 -g -fiso -c -fmakeinit twoDsim.mod
2165 The first command both compiles the source file creating
2166 @file{twoDsim.o} and produces a swig interface file @file{swig.i}. We
2167 now use @code{swig} and @code{g++} to produce and compile the
2171 $ libtool --mode=compile g++ -g -c twoDsim_m2.cpp -o twoDsim_m2.lo
2172 $ swig -c++ -python3 twoDsim.i
2173 $ libtool --mode=compile g++ -c -fPIC twoDsim_wrap.cxx \
2174 -I/usr/include/python3 -o twoDsim_wrap.lo
2175 $ libtool --mode=compile gm2 -g -fPIC -fiso -c deviceGnuPic.mod
2176 $ libtool --mode=compile gm2 -g -fPIC -fiso -c roots.mod
2177 $ libtool --mode=compile gm2 -g -fPIC -fiso -c -fswig \
2178 twoDsim.mod -o twoDsim.lo
2181 Finally the application is linked into a shared library:
2184 $ libtool --mode=link gcc -g twoDsim_m2.lo twoDsim_wrap.lo \
2185 roots.lo deviceGnuPic.lo \
2186 -L$@{prefix@}/lib64 \
2187 -rpath `pwd` -lgm2 -lstdc++ -lm -o libtwoDsim.la
2188 cp .libs/libtwoDsim.so _twoDsim.so
2191 The library name must start with @code{_} to comply with the Python3
2192 module naming scheme.
2194 @node Interface to C, Assembly language, Producing a Python module, Using
2195 @section Interfacing GNU Modula-2 to C
2197 The GNU Modula-2 compiler tries to use the C calling convention
2198 wherever possible however some parameters have no C equivalent and
2199 thus a language specific method is used. For example unbounded arrays
2200 are passed as a @code{struct @{void *address, unsigned int high@}} and
2201 the contents of these arrays are copied by callee functions when they
2202 are declared as non @code{VAR} parameters. The @code{VAR} equivalent
2203 unbounded array parameters need no copy, but still use the
2204 @code{struct} representation.
2206 The recommended method of interfacing GNU Modula-2 to C is by telling
2207 the definition module that the implementation is in the C language.
2208 This is achieved by using the tokens @code{DEFINITION MODULE FOR "C"}.
2209 Here is an example @file{libprintf.def}.
2212 DEFINITION MODULE FOR "C" libprintf ;
2214 EXPORT UNQUALIFIED printf ;
2216 PROCEDURE printf (a: ARRAY OF CHAR; ...) : [ INTEGER ] ;
2221 the @code{UNQUALIFIED} keyword in the definition module informs
2222 GNU Modula-2 not to prefix the module name to exported references
2225 The @code{printf} declaration states that the first parameter
2226 semantically matches @code{ARRAY OF CHAR} but since the module is for
2227 the C language it will be mapped onto @code{char *}. The token
2228 @code{...} indicates a variable number of arguments (varargs) and all
2229 parameters passed here are mapped onto their C equivalents. Arrays and
2230 constant strings are passed as pointers. Lastly @code{[ INTEGER ]}
2231 states that the caller can ignore the function return result if desired.
2233 The hello world program can be rewritten as:
2238 FROM libprintf IMPORT printf ;
2241 printf ("hello world\n")
2245 and it can be compiled by:
2247 @samp{gm2 -g hello.mod -lc}
2249 In reality the @samp{-lc} is redundant as libc is always included in the
2250 linking process. It is shown here to emphasize that the C library or
2251 object file containing @code{printf} must be present. The search path
2252 for modules can be changed by using @samp{-I}.
2254 If a procedure function is declared using varargs then some parameter
2255 values are converted. The table below summarizes the default conversions
2256 and default types used.
2259 Actual Parameter | Default conversion | Type of actual
2261 ===============================================================
2262 123 | none | long long int
2263 "hello world" | none | const char *
2264 a: ARRAY OF CHAR | ADR (a) | char *
2265 a: ARRAY [0..5] OF CHAR| ADR (a) | char *
2266 3.14 | none | long double
2269 If you wish to pass @code{int} values then you should explicitly
2270 convert the constants using one of the conversion mechanisms.
2271 For example: @code{INTEGER(10)} or @code{VAL(INTEGER, 10)} or
2272 @code{CAST(INTEGER, 10)}.
2274 @node Assembly language, Alignment, Interface to C, Using
2275 @section Interface to assembly language
2277 The interface for GNU Modula-2 to assembly language is almost
2278 identical to GNU C. The only alterations are that the keywords
2279 @code{asm} and @code{volatile} are in capitals, following the Modula-2
2282 A simple, but highly non optimal, example is given below. Here we want
2283 to add the two @code{CARDINAL}s @code{foo} and @code{bar} together and
2284 return the result. The target processor is assumed to be executing
2285 the x86_64 instruction set.
2288 PROCEDURE Example (foo, bar: CARDINAL) : CARDINAL ;
2292 ASM VOLATILE ("movq %1,%%rax; addq %2,%%rax; movq %%rax,%0"
2293 : "=rm" (myout) (* outputs *)
2294 : "rm" (foo), "rm" (bar) (* inputs *)
2295 : "rax") ; (* we trash *)
2300 For a full description of this interface we refer the reader to the GNU C manual.
2302 @xref{Extended Asm, ,Extensions to the C Language Family,gcc}.
2304 The same example can be written using the newer extensions of naming
2305 the operands rather than using numbered arguments.
2308 PROCEDURE Example (foo, bar: CARDINAL) : CARDINAL ;
2313 "movq %[left],%%rax; addq %[right],%%rax; movq %%rax,%[output]"
2314 : [output] "=rm" (myout) (* outputs *)
2315 : [left] "rm" (foo), [right] "rm" (bar) (* inputs *)
2316 : "rax") ; (* we trash *)
2321 Both examples generate exactly the same code. It is worth noting that
2322 the specifier ``rm'' indicates that the operand can be either a
2323 register or memory. Of course you must choose an instruction which
2324 can take either, but this allows the compiler to take make more
2325 efficient choices depending upon the optimization level given to the
2328 @node Alignment, Packed, Assembly language, Using
2329 @section Data type alignment
2331 GNU Modula-2 allows you to specify alignment for types and variables.
2332 The syntax for alignment is to use the ISO pragma directives @code{<*}
2333 @code{bytealignment (} expression @code{)} and @code{*>}. These directives
2334 can be used after type and variable declarations.
2336 The ebnf of the alignment production is:
2339 Alignment := [ ByteAlignment ] =:
2340 ByteAlignment := '<*' AttributeExpression '*>' =:
2341 AlignmentExpression := "(" ConstExpression ")" =:
2344 The @code{Alignment} ebnf statement may be used during construction of
2345 types, records, record fields, arrays, pointers and variables. Below
2346 is an example of aligning a type so that the variable @code{bar} is
2347 aligned on a 1024 address.
2353 foo = INTEGER <* bytealignment(1024) *> ;
2362 The next example aligns a variable on a 1024 byte boundary.
2369 z : ARRAY [0..255] OF INTEGER <* bytealignment(1024) *> ;
2374 Here the example aligns a pointer on a 1024 byte boundary.
2379 FROM SYSTEM IMPORT ADR ;
2380 FROM libc IMPORT exit ;
2384 z : POINTER TO INTEGER <* bytealignment(1024) *> ;
2386 IF ADR(z) MOD 1024=0
2395 In example @code{align5} record field @code{y} is aligned on a 1024
2401 FROM SYSTEM IMPORT ADR ;
2402 FROM libc IMPORT exit ;
2407 y: CHAR <* bytealignment(1024) *> ;
2412 IF ADR(r.y) MOD 1024=0
2421 In the example below module @code{align6} declares @code{foo} as an
2422 array of 256 @code{INTEGER}s. The array @code{foo} is aligned on a
2428 FROM SYSTEM IMPORT ADR ;
2429 FROM libc IMPORT exit ;
2432 foo = ARRAY [0..255] OF INTEGER <* bytealignment(1024) *> ;
2438 IF ADR(z) MOD 1024=0
2447 @node Packed, Built-ins, Alignment, Using
2448 @section Packing data types
2450 The pragma @code{<* bytealignment(0) *>} can be used to specify that
2451 the fields within a @code{RECORD} are to be packed. Currently this
2452 only applies to fields which are declared as subranges, ordinal types
2453 and enumerated types. Here is an example of how two subranges might
2454 be packed into a byte.
2462 <* bytealignment(0) *>
2469 Notice that the user has specified that in between fields @code{x} and
2470 @code{y} there are two bits unused.
2472 Now the user wishes to create a record with byte numbers zero and one
2473 occupied and then an @code{INTEGER32} field which is four byte
2474 aligned. In this case byte numbers two and three will be unused. The
2475 pragma @code{bytealignment} can be issued at the start of the record
2476 indicating the default alignment for the whole record and this can be
2477 overridden by individual fields if necessary.
2481 <* bytealignment (1) *> ;
2483 x: INTEGER32 <* bytealignment(4) *> ;
2487 In the following example the user has specified that a record has two
2488 fields @code{p} and @code{q} but that there are three bytes unused between
2493 <* bytealignment(1) *>
2495 <* bytesunused(3) *>
2500 The pragma @code{<* bytesunused(x) *>} can only be used if the current
2501 field is on a byte boundary. There is also a @code{SYSTEM} pseudo
2502 procedure function @code{TBITSIZE(T)} which returns the minimum number of
2503 bits necessary to represent type @code{T}.
2505 Another example of packing record bit fields is given below:
2510 FROM libc IMPORT exit ;
2513 colour = (red, blue, green, purple, white, black) ;
2515 soc = PACKEDSET OF colour ;
2518 <* bytealignment(0) *>
2532 r.x := soc@{blue@} ;
2540 Here we see that the total size of this record is one byte and consists
2541 of a six bit set type followed by a 2 bit integer subrange.
2543 @node Built-ins, The PIM system module, Packed, Using
2544 @section Accessing GNU Modula-2 Built-ins
2546 This section describes the built-in constants and functions defined in
2547 GNU Modula-2. The following compiler constants can be accessed using
2548 the @code{__ATTRIBUTE__} @code{__BUILTIN__} keywords. These are not
2549 part of the Modula-2 language and they may differ depending upon the
2550 target architecture but they provide a method whereby common
2551 libraries can interface to a different underlying architecture.
2553 The built-in constants are: @code{BITS_PER_UNIT}, @code{BITS_PER_WORD},
2554 @code{BITS_PER_CHAR} and @code{UNITS_PER_WORD}. They are integrated into
2555 GNU Modula-2 by an extension to the @code{ConstFactor} rule:
2558 ConstFactor := ConstQualidentOrSet | Number | ConstString |
2559 "(" ConstExpression ")" | "NOT" ConstFactor |
2562 ConstAttribute := "__ATTRIBUTE__" "__BUILTIN__" "(" "(" Ident ")" ")" =:
2565 Here is an example taken from the ISO library @code{SYSTEM.def}:
2569 BITSPERLOC = __ATTRIBUTE__ __BUILTIN__ ((BITS_PER_UNIT)) ;
2570 LOCSPERWORD = __ATTRIBUTE__ __BUILTIN__ ((UNITS_PER_WORD)) ;
2573 Built-in functions are transparent to the end user. All built-in
2574 functions are declared in @code{DEFINITION MODULE}s and are imported
2575 as and when required. Built-in functions are declared in definition
2576 modules by using the @code{__BUILTIN__} keyword. Here is a section of
2577 the ISO library @code{LongMath.def} which demonstrates this feature.
2580 PROCEDURE __BUILTIN__ sqrt (x: LONGREAL): LONGREAL;
2581 (* Returns the square root of x *)
2584 This indicates that the function @code{sqrt} will be implemented using
2585 the gcc built-in maths library. If gcc cannot utilize the built-in
2586 function (for example if the programmer requested the address of
2587 @code{sqrt}) then code is generated to call the alternative function
2588 implemented in the @code{IMPLEMENTATION} @code{MODULE}.
2590 Sometimes a function exported from the @code{DEFINITION} @code{MODULE}
2591 will have a different name from the built-in function within gcc. In
2592 such cases the mapping between the GNU Modula-2 function name and the
2593 gcc name is expressed using the keywords @code{__ATTRIBUTE__}
2594 @code{__BUILTIN__} @code{((Ident))}. For example the function
2595 @code{sqrt} in @code{LongMath.def} maps onto the gcc built-in function
2596 @code{sqrtl} and this is expressed as:
2599 PROCEDURE __ATTRIBUTE__ __BUILTIN__ ((sqrtl)) sqrt
2600 (x: LONGREAL) : LONGREAL;
2601 (* Returns the positive square root of x *)
2604 The following module @code{Builtins.def} enumerates the list of
2605 built-in functions which can be accessed in GNU Modula-2. It also
2606 serves to define the parameter and return value for each function:
2608 @include m2/Builtins.texi
2610 Although this module exists and will result in the generation of
2611 in-line code if optimization flags are passed to GNU Modula-2, users
2612 are advised to utilize the same functions from more generic libraries.
2613 The built-in mechanism will be applied to these generic
2614 libraries where appropriate. Note for the mathematical routines to
2615 be in-lined you need to specify the @samp{-ffast-math -O} options.
2617 @node The PIM system module, The ISO system module, Built-ins, Using
2618 @section The PIM system module
2620 @include m2/SYSTEM-pim.texi
2622 The different dialects of Modula-2 PIM-[234] and ISO Modula-2 declare
2623 the function @code{SIZE} in different places. PIM-[34] and ISO
2624 Modula-2 declare @code{SIZE} as a pervasive function (declared in the
2625 base module). PIM-2 defined @code{SIZE} in the @code{SYSTEM} module
2628 GNU Modula-2 allows users to specify the dialect of Modula-2 by using
2629 the @code{-fiso} and @code{-fpim2} command line switches.
2631 The data types @code{CSIZE_T} and @code{CSSIZE_T} are also exported from
2632 the @code{SYSTEM} module. The type @code{CSIZE_T} is unsigned and is
2633 mapped onto the target C data type @code{size_t} whereas the type
2634 @code{CSSIZE_T} is mapped onto the signed C data type @code{ssize_t}.
2636 It is anticipated that these should only be used to provide cross
2637 platform definition modules for C libraries.
2639 There are also a variety of fixed sized @code{INTEGER} and
2640 @code{CARDINAL} types. The variety of the fixed sized types will
2641 depend upon the target architecture.
2643 @node The ISO system module, Release map, The PIM system module, Using
2644 @section The ISO system module
2646 @include m2/SYSTEM-iso.texi
2648 The data types @code{CSIZE_T} and @code{CSSIZE_T} are also exported from
2649 the @code{SYSTEM} module. The type @code{CSIZE_T} is unsigned and is
2650 mapped onto the target C data type @code{size_t} whereas the type
2651 @code{CSSIZE_T} is mapped onto the signed C data type @code{ssize_t}.
2653 It is anticipated that these should only be used to provide cross
2654 platform definition modules for C libraries.
2656 There are also a variety of fixed sized @code{INTEGER} and
2657 @code{CARDINAL} types. The variety of the fixed sized types will
2658 depend upon the target architecture.
2660 @node Release map, Documentation, The ISO system module, Using
2661 @section Release map
2663 GNU Modula-2 is now part of GCC and therefore will adopt the GCC
2664 release schedule. It is intended that GNU Modula-2 implement more of
2665 the GCC builtins (vararg access) and GCC features.
2667 There is an intention to implement the ISO generics and the M2R10
2668 dialect of Modula-2. It will also implement all language changes. If
2669 you wish to see something different please email
2670 @email{gm2@@nongnu.org} with your ideas.
2672 @node Documentation, Regression tests, Release map, Using
2673 @section Documentation
2675 The GNU Modula-2 documentation is available on line
2676 @url{https://gcc.gnu.org/onlinedocs}
2677 or in the pdf, info, html file format.
2679 @node Regression tests, Limitations, Documentation, Using
2680 @section Regression tests for gm2 in the repository
2682 The regression testsuite can be run from the gcc build directory:
2689 which runs the complete testsuite for all compilers using 24 parallel
2690 invocations of the compiler. Individual language testsuites can be
2691 run by specifying the language, for example the Modula-2 testsuite can
2696 $ make check-m2 -j 24
2699 Finally the results of the testsuite can be emailed to the
2700 @url{https://gcc.gnu.org/lists.html, gcc-testresults} list using the
2701 @file{test_summary} script found in the gcc source tree:
2704 $ @samp{directory to the sources}/contrib/test_summary
2707 @node Limitations, Objectives, Regression tests, Using
2708 @section Limitations
2710 Logitech compatibility library is incomplete. The principle modules
2711 for this platform exist however for a comprehensive list of completed
2712 modules please check the documentation
2715 @node Objectives, FAQ, Limitations, Using
2721 The intention of GNU Modula-2 is to provide a production Modula-2
2725 It should support all Niklaus Wirth PIM Dialects [234] and also ISO
2726 Modula-2 including a re-implementation of all the ISO modules.
2729 There should be an easy interface to C.
2732 Exploit the features of GCC.
2735 Listen to the requests of the users.
2738 @node FAQ, Community, Objectives, Using
2741 @subsection Why use the C++ exception mechanism in GCC, rather than a bespoke Modula-2 mechanism?
2743 The C++ mechanism is tried and tested, it also provides GNU Modula-2
2744 with the ability to link with C++ modules and via swig it can raise
2747 @node Community, Other languages, FAQ, Using
2750 You can subscribe to the GNU Modula-2 mailing by sending an
2752 @email{gm2-subscribe@@nongnu.org}
2754 @url{http://lists.nongnu.org/mailman/listinfo/gm2}.
2755 The mailing list contents can be viewed
2756 @url{http://lists.gnu.org/archive/html/gm2}.
2758 @node Other languages, , Community, Using
2759 @section Other languages for GCC
2761 These exist and can be found on the frontends web page on the
2762 @uref{http://gcc.gnu.org/frontends.html, gcc web site}.
2764 @node License, Copying, Using, Top
2765 @section License of GNU Modula-2
2767 GNU Modula-2 is free software, the compiler is held under the GPL v3
2768 @uref{http://www.gnu.org/licenses/gpl.txt},
2769 its libraries (pim, iso and Logitech compatible) are under the
2770 GPL v3 with the GCC run time library exception clause.
2772 Under Section 7 of GPL version 3, you are granted additional
2773 permissions described in the GCC Runtime Library Exception, version
2774 3.1, as published by the Free Software Foundation.
2776 You should have received a copy of the GNU General Public License and
2777 a copy of the GCC Runtime Library Exception along with this program;
2778 see the files COPYING3 and COPYING.RUNTIME respectively. If not, see
2779 <http://www.gnu.org/licenses/>.
2781 More information on how these licenses work is available
2782 @uref{http://www.gnu.org/licenses/licenses.html} on the GNU web site.
2784 @node Copying, Contributing, License, Top
2785 @include gpl_v3_without_node.texi
2787 @node Contributing, EBNF, Copying, Top
2788 @section Contributing to GNU Modula-2
2790 Please do and please read the GNU Emacs info under
2793 * Standards: (standards). GNU coding standards.
2794 * Intellectual Property:: Keeping Free Software Free
2795 * Reading Non-Free Code:: Referring to Proprietary Programs
2796 * Contributions:: Accepting Contributions
2799 You might consider joining the GM2 Mailing list before you start
2800 coding. The mailing list may be subscribed via a web interface
2801 @uref{http://lists.nongnu.org/mailman/listinfo/gm2} or via email
2802 @email{gm2-subscribe@@nongnu.org}.
2804 Many thanks and enjoy your coding!
2806 @c @node Internals, , ,
2808 @c This section is still being written.
2809 @c @include gm2-internals.texi
2811 @node EBNF, Libraries, Contributing, Top
2812 @chapter EBNF of GNU Modula-2
2814 This chapter contains the EBNF of GNU Modula-2. This grammar currently
2815 supports both PIM and ISO dialects. The rules here are automatically
2816 extracted from the crammer files in GNU Modula-2 and serve to document
2817 the syntax of the extensions described earlier and how they fit in
2818 with the base language.
2820 Note that the first six productions are built into the lexical analysis
2823 @include m2/gm2-ebnf.texi
2825 @node Libraries, Indices, EBNF, Top
2826 @chapter PIM and ISO library definitions
2828 This chapter contains M2F, PIM and ISO libraries.
2830 @include m2/gm2-libs.texi
2832 @node Indices, , Libraries, Top
2837 * Contents:: Section and subsections.
2838 * Functions:: Function, constants, types, ebnf indices.
2842 @section Section and subsections
2845 @node Functions, , ,
2846 @section Function, constants, types, ebnf indices.