Debian Codegraph @

gcc/doc/gm2.texi

raw
1 \input texinfo
2 @c -*-texinfo-*-
3 @c Copyright (C) 2001-2025 Free Software Foundation, Inc.
4 @c This is part of the GM2 manual.
5
6 @c User level documentation for GNU Modula-2
7 @c
8 @c header
9
10 @setfilename gm2.info
11 @settitle The GNU Modula-2 Compiler
12
13 @set version-python 3.5
14
15 @include gcc-common.texi
16
17 @c Copyright years for this manual.
18 @set copyrights-gm2 1999-2025
19
20 @copying
21 @c man begin COPYRIGHT
22 Copyright @copyright{} @value{copyrights-gm2} Free Software Foundation, Inc.
23
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
29 @c man end
30 section entitled ``GNU Free Documentation License''.
31 @ignore
32 @c man begin COPYRIGHT
33 man page gfdl(7).
34 @c man end
35 @end ignore
36 @end copying
37
38 @ifinfo
39 @format
40 @dircategory Software development
41 @direntry
42 * gm2: (gm2). A GCC-based compiler for the Modula-2 language
43 @end direntry
44 @end format
45
46 @insertcopying
47 @end ifinfo
48
49 @titlepage
50 @title The GNU Modula-2 Compiler
51 @versionsubtitle
52 @author Gaius Mulley
53
54 @page
55 @vskip 0pt plus 1filll
56 Published by the Free Software Foundation @*
57 51 Franklin Street, Fifth Floor@*
58 Boston, MA 02110-1301, USA@*
59 @sp 1
60 @insertcopying
61 @end titlepage
62 @contents
63 @page
64
65 @c `Top' Node and Master Menu
66
67 @node Top, Overview, (dir), (dir)
68 @top Introduction
69
70 @menu
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.
80 @end menu
81
82 @node Overview, Using, Top, Top
83 @chapter Overview of GNU Modula-2
84
85 @menu
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
90 @end menu
91
92 @node What is GNU Modula-2, Why use GNU Modula-2, , Overview
93 @section What is GNU Modula-2
94
95 GNU Modula-2 is a @uref{https://gcc.gnu.org/frontends.html, front end}
96 for the GNU Compiler Collection (@uref{https://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.
100
101 @footnote{The four Modula-2 dialects supported are defined in the following
102 references:
103
104 PIM2: 'Programming in Modula-2', 2nd Edition, Springer Verlag, 1982,
105 1983 by Niklaus Wirth (PIM2).
106
107 PIM3: 'Programming in Modula-2', 3rd Corrected Edition, Springer Verlag,
108 1985 (PIM3).
109
110 PIM4: 'Programming in Modula-2', 4th Edition, Springer Verlag, 1988
111 (@uref{https://freepages.modula2.org/report4/modula-2.html, PIM4}).
112
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)'
116 }
117
118 @node Why use GNU Modula-2, Development, What is GNU Modula-2, Overview
119 @section Why use GNU Modula-2
120
121 There are a number of advantages of using GNU Modula-2 rather than
122 translate an existing project into another language.
123
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.
127
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.
131
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.
135
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.
139
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.
144
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.
151
152 @node Development, Features, Why use GNU Modula-2, Overview
153 @section How to get source code using git
154
155 GNU Modula-2 is now in the @url{https://gcc.gnu.org/git.html, GCC git
156 tree}.
157
158 @node Features, , Development, Overview
159 @section GNU Modula-2 Features
160
161 @itemize @bullet
162
163 @item
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}.
168
169 @item
170 the option @samp{-fswig} will automatically create a swig interface
171 file which corresponds to the definition module of the file being
172 compiled.
173
174 @item
175 exception handling is compatible with C++ and swig. Modula-2 code can
176 be used with C or C++ code.
177
178 @item
179 Python can call GNU Modula-2 modules via swig.
180
181 @item
182 shared libraries can be built.
183
184 @item
185 fixed sized types are now available from @samp{SYSTEM}.
186
187 @c @item
188 @c support for dynamic @code{ARRAY}s has been added into @samp{gdb}.
189
190 @item
191 variables can be declared at addresses.
192
193 @item
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
197 in Modula-2 syntax.
198
199 @item
200 supports sets of any ordinal size (memory permitting).
201
202 @item
203 easy interface to C, and varargs can be passed to C routines.
204
205 @item
206 many Logitech libraries have been implemented and can be accessed via:
207 @samp{-flibs=m2log,m2pim,m2iso}.
208
209 @item
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).
214
215 @item
216 can be built as a cross compiler (for embedded microprocessors
217 such as the AVR and the ARM).
218
219 @end itemize
220
221 @node Using, License, Overview, Top
222 @chapter Using GNU Modula-2
223
224 @menu
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 * High procedure function:: Behavior of the high procedure function.
231 * Dialect:: GNU Modula-2 supported dialects.
232 * Exceptions:: Exception implementation
233 * Semantic checking:: How to detect run time problems at compile time.
234 * Extensions:: GNU Modula-2 language extensions.
235 * Type compatibility:: Data type compatibility.
236 * Unbounded by reference::Explanation of a language optimization.
237 * Exception handling:: Example of exception handling.
238 * Building a shared library:: How to build a shared library.
239 * Interface for Python:: How to produce swig interface files.
240 * Producing a Python module:: How to produce a Python module.
241 * Interface to C:: Interfacing GNU Modula-2 to C.
242 * Assembly language:: Interface to assembly language.
243 * Alignment:: Data type alignment.
244 * Packed:: Packing data types.
245 * Built-ins:: Accessing GNU Modula-2 Built-ins.
246 * The PIM system module:: SYSTEM data types and procedures.
247 * The ISO system module:: SYSTEM data types, procedures and run time.
248 @c @ifnothtml
249 @c omit these nodes if generating gm2 webpage as these are hand written.
250 * Release map:: Release map.
251 * Documentation:: Placeholder for how to access the documentation online.
252 * Regression tests:: How to run the testsuite.
253 * Limitations:: Current limitations.
254 * Objectives:: Objectives of the implementation.
255 * FAQ:: Frequently asked questions.
256 * Community:: How to join the community.
257 * Other languages:: Other languages for GCC.
258 @c @end ifnothtml
259 @end menu
260
261 This document contains the user and design issues relevant to the
262 Modula-2 front end to gcc.
263
264 @node Example usage, Compiler options, Using, Using
265 @section Example compile and link
266
267 @ignore
268 @c man begin SYNOPSIS gm2
269 gm2 [@option{-c}|@option{-S}] [@option{-g}] [@option{-pg}]
270 [@option{-O}@var{level}] [@option{-W}@var{warn}@dots{}]
271 [@option{-I}@var{dir}@dots{}] [@option{-L}@var{dir}@dots{}]
272 [@option{-f}@var{option}@dots{}] [@option{-m}@var{machine-option}@dots{}]
273 [@option{-o} @var{outfile}] [@@@var{file}] @var{infile}@dots{}
274
275 Only the most useful options are listed here; see below for the
276 remainder.
277 @c man end
278 @c man begin SEEALSO
279 gpl(7), gfdl(7), fsf-funding(7), gcc(1)
280 and the Info entries for @file{gm2} and @file{gcc}.
281 @c man end
282 @end ignore
283
284 @c man begin DESCRIPTION gm2
285
286 The @command{gm2} command is the GNU compiler for the Modula-2 language and
287 supports many of the same options as @command{gcc}. @xref{Option Summary, ,
288 Option Summary, gcc, Using the GNU Compiler Collection (GCC)}.
289 This manual only documents the options specific to @command{gm2}.
290
291 @c man end
292
293 This section describes how to compile and link a simple hello world
294 program. It provides a few examples of using the different options
295 mentioned in @pxref{Compiler options}. Assuming that you have
296 a file called @file{hello.mod} in your current directory which
297 contains:
298
299 @example
300 MODULE hello ;
301
302 FROM StrIO IMPORT WriteString, WriteLn ;
303
304 BEGIN
305 WriteString ('hello world') ; WriteLn
306 END hello.
307 @end example
308
309 You can compile and link it by: @samp{gm2 -g hello.mod}.
310 The result will be an @samp{a.out} file created in your directory.
311
312 You can split this command into two steps if you prefer. The compile
313 step can be achieved by: @samp{gm2 -g -c -fscaffold-main hello.mod}
314 and the link via: @samp{gm2 -g hello.o}.
315
316 @footnote{To see all the compile actions taken by @samp{gm2} users can also
317 add the @samp{-v} flag at the command line, for example:
318
319 @samp{gm2 -v -g -I. hello.mod}
320
321 This displays the sub processes initiated by @samp{gm2} which can be useful
322 when trouble shooting.}
323
324 @node Compiler options, Linking, Example usage, Using
325 @section Compiler options
326
327 This section describes the compiler options specific to GNU Modula-2
328 for generic flags details @xref{Invoking GCC, , ,gcc}.
329
330 @c man begin OPTIONS
331
332 For any given input file, the file name suffix determines what kind of
333 compilation is done. The following kinds of input file names are supported:
334
335 @table @gcctabopt
336 @item @var{file}.mod
337 Modula-2 implementation or program source files. See the
338 @samp{-fmod=} option if you wish to compile a project which uses a
339 different source file extension.
340 @item @var{file}.def
341 Modula-2 definition module source files. Definition modules are not
342 compiled separately, in GNU Modula-2 definition modules are parsed as
343 required when program or implementation modules are compiled. See the
344 @samp{-fdef=} option if you wish to compile a project which uses a
345 different source file extension.
346 @end table
347
348 You can specify more than one input file on the @command{gm2} command line,
349
350 @table @code
351
352 @item -g
353 create debugging information so that debuggers such as @file{gdb}
354 can inspect and control executable.
355
356 @item -I
357 used to specify the search path for definition and implementation
358 modules. An example is: @code{gm2 -g -c -I.:../../libs foo.mod}.
359 If this option is not specified then the default path is added
360 which consists of the current directory followed by the appropriate
361 language dialect library directories.
362
363 @c ordered list of options from here.
364
365 @item -fauto-init
366 turns on auto initialization of pointers to NIL. Whenever a block is
367 created all pointers declared within this scope will have their
368 addresses assigned to NIL.
369
370 @item -fbounds
371 turns on run time subrange, array index and indirection via @code{NIL}
372 pointer checking.
373
374 @item -fcase
375 turns on compile time checking to check whether a @code{CASE}
376 statement requires an @code{ELSE} clause when on was not specified.
377
378 @item -fcpp
379 preprocess the source with @samp{cpp -lang-asm -traditional-cpp}
380 For further details about these options @xref{Invocation, , ,cpp}.
381 If @samp{-fcpp} is supplied then all definition modules and
382 implementation modules which are parsed will be prepossessed by
383 @samp{cpp}.
384
385 @c fcpp-end
386 @c Modula-2
387 @c passed to the preprocessor if -fcpp is used (internal switch)
388
389 @c fcpp-begin
390 @c Modula-2
391 @c passed to the preprocessor if -fcpp is used (internal switch)
392
393 @item -fdebug-builtins
394 call a real function, rather than the builtin equivalent. This can
395 be useful for debugging parameter values to a builtin function as
396 it allows users to single step code into an intrinsic function.
397
398 @c fd
399 @c Modula-2
400 @c turn on internal debugging of the compiler (internal switch)
401
402 @c fdebug-function-line-numbers
403 @c Modula-2
404 @c turn on the Modula-2 function line number generation (internal switch)
405
406 @item -fdef=
407 recognize the specified suffix as a definition module filename.
408 The default implementation and module filename suffix is @file{.def}.
409 If this option is used GNU Modula-2 will still fall back to this
410 default if a requested definition module is not found.
411
412 @item -fdump-system-exports
413 display all inbuilt system items.
414 This is an internal command line option.
415
416 @item -fexceptions
417 turn on exception handling code. By default this option is on.
418 Exception handling can be disabled by @samp{-fno-exceptions}
419 and no references are made to the run time exception libraries.
420
421 @item -fextended-opaque
422 allows opaque types to be implemented as any type. This is a GNU
423 Modula-2 extension and it requires that the implementation module
424 defining the opaque type is available so that it can be resolved when
425 compiling the module which imports the opaque type.
426
427 @item -ffloatvalue
428 turns on run time checking to check whether a floating point number is
429 about to exceed range.
430
431 @item -fgen-module-list=@file{filename}
432 attempt to find all modules when linking and generate a module list.
433 If the @file{filename} is @samp{-} then the contents are not written
434 and only used to force the linking of all module ctors.
435 This option cannot be used if @samp{-fuse-list=} is enabled.
436
437 @item -findex
438 generate code to check whether array index values are out of bounds.
439 Array index checking can be disabled via @samp{-fno-index}.
440
441 @item -fiso
442 turn on ISO standard features. Currently this enables the ISO
443 @code{SYSTEM} module and alters the default library search path so
444 that the ISO libraries are searched before the PIM libraries. It also
445 effects the behavior of @code{DIV} and @code{MOD} operators.
446 @xref{Dialect}.
447
448 @item -flibs=
449 modifies the default library search path. The libraries supplied are:
450 m2pim, m2iso, m2min, m2log and m2cor. These map onto the
451 Programming in Modula-2 base libraries, ISO standard libraries, minimal
452 library support, Logitech compatible library and Programming in
453 Modula-2 with coroutines.
454 Multiple libraries can be specified and are comma separated with precedence
455 going to the first in the list. It is not necessary to use -flibs=m2pim or
456 -flibs=m2iso if you also specify -fpim, -fpim2, -fpim3, -fpim4 or
457 -fiso. Unless you are using -flibs=m2min you should include m2pim as
458 the they provide the base modules which all other dialects utilize.
459 The option @samp{-fno-libs=-} disables the @samp{gm2} driver from
460 modifying the search and library paths.
461
462 @item -static-libgm2
463 On systems that provide the m2 runtimes as both shared and static libraries,
464 this option forces the use of the static version.
465
466 @c flocation=
467 @c Modula-2 Joined
468 @c set all location values to a specific value (internal switch)
469
470 @item -fm2-debug-trace=
471 turn on trace debugging using a comma separated list:
472 @samp{line,token,quad,all}. This is an internal command line option.
473
474 @item -fm2-dump=
475 enable dumping of modula-2 internal representation of data structures
476 using a comma separated list. The list can contain:
477 @samp{quad,gimple,decl,all}.
478
479 @item -fm2-dump-decl=@file{filestem}
480 dump the modula-2 representation of a symbol to the @file{filestem}
481 specified. This option only takes effect if the
482 @samp{-fm2-dump-filter} is specified.
483
484 @item -fm2-dump-gimple=@file{filestem}
485 dump modula-2 gimple representation to the @file{filestem} specified.
486
487 @item -fm2-dump-quad=@file{filestem}
488 dump quadruple representation to the @file{filestem} specified.
489
490 @item -fm2-dump-filter=@samp{rules}
491 filter the language dumps @samp{-fdump-lang-decl},
492 @samp{-fdump-lang-gimple} and@samp{-fdump-lang-quad}
493 on @samp{rules}. @samp{rules} must be a comma
494 separated list which can take three forms: the full decl textual name
495 of a procedure, @samp{[libname.]module.ident} or
496 @samp{[filename:]module.ident}. This is an internal command line
497 option. Currently it only filters on procedure names and regexp
498 matching is not implemented. Three examples of its use following
499 the previous forms could be:
500 @code{-fm2-dump-filter=_M2_hello_init},
501 @code{-fm2-dump-filter=m2pim.StrIO.WriteString} and
502 @code{-fm2-dump-filter=StrLib.mod:StrIO.WriteString}.
503
504 @item -fm2-file-offset-bits=
505 force the type @code{SYSTEM.COFF_T} to be built using the specified
506 number of bits. If this option is not used then default is
507 @code{CSSIZE_T} bits.
508
509 @item -fm2-g
510 improve the debugging experience for new programmers at the expense
511 of generating @code{nop} instructions if necessary to ensure single
512 stepping precision over all code related keywords. An example
513 of this is in termination of a list of nested @code{IF} statements
514 where multiple @code{END} keywords are mapped onto a sequence of
515 @code{nop} instructions.
516
517 @item -fm2-lower-case
518 render keywords in error messages using lower case.
519
520 @item -fm2-pathname=
521 specify the module mangled prefix name for all modules in the
522 following include paths.
523
524 @item -fm2-pathnameI
525 for internal use only: used by the driver to copy the user facing @samp{-I}
526 option.
527
528 @item -fm2-plugin
529 insert plugin to identify run time errors at compile time (default on).
530
531 @item -fm2-prefix=
532 specify the module mangled prefix name. All exported symbols from a
533 definition module will have the prefix name.
534
535 @item -fm2-statistics
536 generates quadruple information: number of quadruples generated,
537 number of quadruples remaining after optimization and number of source
538 lines compiled.
539
540 @item -fm2-strict-type
541 experimental flag to turn on the new strict type checker.
542
543 @item -fm2-whole-program
544 compile all implementation modules and program module at once. Notice
545 that you need to take care if you are compiling different dialect
546 modules (particularly with the negative operands to modulus). But
547 this option, when coupled together with @code{-O3}, can deliver huge
548 performance improvements.
549
550 @item -fmod=
551 recognize the specified suffix as implementation and module filenames.
552 The default implementation and module filename suffix is @file{.mod}.
553 If this option is used GNU Modula-2 will still fall back to this
554 default if it needs to read an implementation module and the specified
555 suffixed filename does not exist.
556
557 @item -fnil
558 generate code to detect accessing data through a @code{NIL} value
559 pointer. Dereferencing checking through a @code{NIL} pointer can be
560 disabled by @samp{-fno-nil}.
561
562 @item -fpim
563 turn on PIM standard features. Currently this enables the PIM
564 @code{SYSTEM} module and determines which identifiers are pervasive
565 (declared in the base module). If no other @samp{-fpim[234]} switch is
566 used then division and modulus operators behave as defined in PIM4.
567 @xref{Dialect}.
568
569 @item -fpim2
570 turn on PIM-2 standard features. Currently this removes @code{SIZE}
571 from being a pervasive identifier (declared in the base module). It
572 places @code{SIZE} in the @code{SYSTEM} module. It also effects the
573 behavior of @code{DIV} and @code{MOD} operators.
574 @xref{Dialect}.
575
576 @item -fpim3
577 turn on PIM-3 standard features. Currently this only effects the
578 behavior of @code{DIV} and @code{MOD} operators.
579 @xref{Dialect}.
580
581 @item -fpim4
582 turn on PIM-4 standard features. Currently this only effects the
583 behavior of @code{DIV} and @code{MOD} operators.
584 @xref{Dialect}.
585
586 @item -fpositive-mod-floor-div
587 forces the @code{DIV} and @code{MOD} operators to behave as defined by PIM4.
588 All modulus results are positive and the results from the division are
589 rounded to the floor.
590 @xref{Dialect}.
591
592 @item -fpthread
593 link against the pthread library. By default this option is on. It
594 can be disabled by @samp{-fno-pthread}. GNU Modula-2 uses the GCC
595 pthread libraries to implement coroutines (see the SYSTEM
596 implementation module).
597
598 @c -fq
599 @c -Modula-2
600 @c -internal compiler debugging information, dump the list of quadruples
601
602 @item -frange
603 generate code to check the assignment range, return value range
604 set range and constructor range. Range checking can be disabled
605 via @samp{-fno-range}.
606
607 @item -freturn
608 generate code to check that functions always exit with a @code{RETURN}
609 and do not fall out at the end. Return checking can be disabled
610 via @samp{-fno-return}.
611
612 @item -fruntime-modules=
613 specify, using a comma separated list, the run time modules and their
614 order. These modules will initialized first before any other modules
615 in the application dependency. By default the run time modules list
616 is set to @code{m2iso:RTentity,m2iso:Storage,m2iso:SYSTEM,}
617 @code{m2iso:M2RTS,m2iso:RTExceptions,m2iso:IOLink}. Note that these
618 modules will only be linked into your executable if they are required.
619 Adding a long list of dependent modules will not effect the size of
620 the executable it merely states the initialization order should they
621 be required.
622
623 @item -fscaffold-dynamic
624 the option ensures that @samp{gm2} will generate a dynamic scaffold
625 infrastructure when compiling implementation and program modules.
626 By default this option is on. Use @samp{-fno-scaffold-dynamic}
627 to turn it off or select @samp{-fno-scaffold-static}.
628
629 @item -fscaffold-c
630 generate a C source scaffold for the current module being compiled.
631
632 @item -fscaffold-c++
633 generate a C++ source scaffold for the current module being compiled.
634
635 @item -fscaffold-main
636 force the generation of the @samp{main} function. This is not
637 necessary if the @samp{-c} is omitted.
638
639 @item -fscaffold-static
640 the option ensures that @samp{gm2} will generate a static scaffold
641 within the program module. The static scaffold consists of sequences
642 of calls to all dependent module initialization and finalization
643 procedures. The static scaffold is useful for debugging and single
644 stepping the initialization blocks of implementation modules.
645
646 @item -fshared
647 generate a shared library from the module.
648
649 @item -fsoft-check-all
650 turns on all run time checks. This is the same as invoking
651 GNU Modula-2 using the command options
652 @code{-fnil} @code{-frange} @code{-findex}
653 @code{-fwholevalue}
654 @code{-fwholediv} @code{-fcase} @code{-freturn}.
655
656 @item -fsources
657 displays the path to the source of each module. This option
658 can be used at compile time to check the correct definition module
659 is being used.
660
661 @item -fswig
662 generate a swig interface file.
663
664 @item -funbounded-by-reference
665 enable optimization of unbounded parameters by attempting to pass non
666 @code{VAR} unbounded parameters by reference. This optimization
667 avoids the implicit copy inside the callee procedure. GNU Modula-2
668 will only allow unbounded parameters to be passed by reference if,
669 inside the callee procedure, they are not written to, no address is
670 calculated on the array and it is not passed as a @code{VAR}
671 parameter. Note that it is possible to write code to break this
672 optimization, therefore this option should be used carefully.
673 For example it would be possible to take the address of an array, pass
674 the address and the array to a procedure, read from the array in
675 the procedure and write to the location using the address parameter.
676
677 Due to the dangerous nature of this option it is not enabled
678 when the @samp{-O} option is specified.
679
680 @item -fuse-list=@file{filename}
681 if @samp{-fscaffold-static} is enabled then use the file
682 @file{filename} for the initialization order of modules. Whereas if
683 @samp{-fscaffold-dynamic} is enabled then use this file to force
684 linking of all module ctors.
685 This option cannot be used if @samp{-fgen-module-list=} is enabled.
686
687 @item -fwholediv
688 generate code to detect whole number division by zero or modulus by
689 zero.
690
691 @item -fwholevalue
692 generate code to detect whole number overflow and underflow.
693
694 @item -Wcase-enum
695 generate a warning if a @code{CASE} statement selects on an enumerated
696 type expression and the statement is missing one or more @code{CASE}
697 labels. No warning is issued if the @code{CASE} statement has a default
698 @code{ELSE} clause.
699 The option @samp{-Wall} will turn on this flag.
700
701 @item -Wuninit-variable-checking
702 issue a warning if a variable is used before it is initialized.
703 The checking only occurs in the first basic block in each procedure.
704 It does not check parameters, array types or set types.
705
706 @item -Wuninit-variable-checking=all,known,cond
707 issue a warning if a variable is used before it is initialized.
708 The checking will only occur in the first basic block in each
709 procedure if @samp{known} is specified. If @samp{cond} or @samp{all}
710 is specified then checking continues into conditional branches of the
711 flow graph. All checking will stop when a procedure call is invoked
712 or the top of a loop is encountered.
713 The option @samp{-Wall} will turn on this flag with
714 @samp{-Wuninit-variable-checking=known}.
715 The @samp{-Wuninit-variable-checking=all} will increase compile time.
716
717 @c the following warning options are complete but need to be
718 @c regression tested against all other front ends
719 @c to ensure the options do not conflict.
720
721 @c @item -Wall
722 @c turn on all Modula-2 warnings.
723
724 @c @item -Wpedantic
725 @c forces the compiler to reject nested @code{WITH} statements
726 @c referencing the same record type. Does not allow multiple imports of
727 @c the same item from a module. It also checks that: procedure variables
728 @c are written to before being read; variables are not only written to
729 @c but read from; variables are declared and used. If the compiler
730 @c encounters a variable being read before written it will terminate with
731 @c a message. It will check that @code{FOR} loop indices are not used
732 @c outside the end of this loop without being reset.
733
734 @c @item -Wpedantic-cast
735 @c warns if the ISO system function is used and if the size of
736 @c the variable is different from that of the type. This is legal
737 @c in ISO Modula-2, however it can be dangerous. Some users may prefer
738 @c to use @code{VAL} instead in these situations and use @code{CAST}
739 @c exclusively for changes in type on objects which have the same size.
740
741 @c @item -Wpedantic-param-names
742 @c procedure parameter names are checked in the definition module
743 @c against their implementation module counterpart. This is not
744 @c necessary in ISO or PIM versions of Modula-2.
745
746 @c @item -Wstyle
747 @c checks for poor programming style. This option is aimed at new users of
748 @c Modula-2 in that it checks for situations which might cause confusion
749 @c and thus mistakes. It checks whether variables of the same name are
750 @c declared in different scopes and whether variables look like keywords.
751 @c Experienced users might find this option too aggressive.
752
753 @c @item -Wunused-variable
754 @c warns if a variable has been declared and it not used.
755
756 @c @item -Wunused-parameter
757 @c warns if a parameter has been declared and it not used.
758
759 @c @item -Wverbose-unbounded
760 @c inform the user which non @code{VAR} unbounded parameters will be
761 @c passed by reference. This only produces output if the option
762 @c @samp{-funbounded-by-reference} is also supplied on the command line.
763
764 @end table
765
766 @c man end
767
768 @node Linking, Elementary data types, Compiler options, Using
769
770 This section describes the linking related options. There are three
771 linking strategies available which are dynamic scaffold, static
772 scaffold and user defined. The dynamic scaffold is enabled by default
773 and each module will register itself to the run time @samp{M2RTS} via
774 a constructor. The static scaffold mechanism will invoke each modules
775 @samp{_init} and @samp{_finish} function in turn via a sequence of
776 calls from within @samp{main}. Lastly the user defined strategy
777 can be implemented by turning off the dynamic and static options via
778 @samp{-fno-scaffold-dynamic} and @samp{-fno-scaffold-static}.
779
780 In the simple test below:
781
782 @example
783 $ gm2 hello.mod
784 @end example
785
786 the driver will add the options @samp{-fscaffold-dynamic} and
787 @samp{-fgen-module-list=-} which generate a list of application
788 modules and also creates the @samp{main} function with calls to
789 @samp{M2RTS}. It can be useful to add the option @samp{-fsources}
790 which displays the source files as they are parsed and summarizes
791 whether the source file is required for compilation or linking.
792
793 If you wish to split the above command line into a compile and link
794 then you could use these steps:
795
796 @example
797 $ gm2 -c -fscaffold-main hello.mod
798 $ gm2 hello.o
799 @end example
800
801 The @samp{-fscaffold-main} informs the compiler to generate the
802 @samp{main} function and scaffold. You can enable the environment
803 variable @samp{GCC_M2LINK_RTFLAG} to trace the construction and
804 destruction of the application. The values for
805 @samp{GCC_M2LINK_RTFLAG} are shown in the table below:
806
807 @example
808 value | meaning
809 =================
810 all | turn on all flags below
811 module | trace modules as they register themselves
812 hex | display the hex address of the init/fini functions
813 warning | show any warnings
814 pre | generate module list prior to dependency resolution
815 dep | trace module dependency resolution
816 post | generate module list after dependency resolution
817 force | generate a module list after dependency and forced
818 | ordering is complete
819 @end example
820
821 The values can be combined using a comma separated list.
822
823 One of the advantages of the dynamic scaffold is that the driver
824 behaves in a similar way to the other front end drivers.
825 For example consider a small project consisting of 4 definition
826 implementation modules (@samp{a.def}, @samp{a.mod}, @samp{b.def},
827 @samp{b.mod}, @samp{c.def}, @samp{c.mod}, @samp{d.def}, @samp{d.mod})
828 and a program module @samp{program.mod}.
829
830 To link this project we could:
831
832 @example
833 $ gm2 -g -c a.mod
834 $ gm2 -g -c b.mod
835 $ gm2 -g -c c.mod
836 $ gm2 -g -c d.mod
837 $ gm2 -g program.mod a.o b.o c.o d.o
838 @end example
839
840 The module initialization sequence is defined by the ISO standard to
841 follow the import graph traversal. The initialization order is the
842 order in which the corresponding separate modules finish the
843 processing of their import lists.
844
845 However, if required, you can override this using
846 @samp{-fruntime-modules=a,b,c,d} for example which forces the
847 initialization sequence to @samp{a}, @samp{b}, @samp{c} and @samp{d}.
848
849 @node Elementary data types, Standard procedures, Linking, Using
850 @section Elementary data types
851
852 This section describes the elementary data types supported by GNU
853 Modula-2. It also describes the relationship between these data types
854 and the equivalent C data types.
855
856 The following data types are supported: @code{INTEGER},
857 @code{LONGINT}, @code{SHORTINT}, @code{CARDINAL}, @code{LONGCARD},
858 @code{SHORTCARD}, @code{BOOLEAN}, @code{REAL}, @code{LONGREAL},
859 @code{SHORTREAL}, @code{COMPLEX}, @code{LONGCOMPLEX},
860 @code{SHORTCOMPLEX} and @code{CHAR}.
861
862 An equivalence table is given below:
863
864 @example
865 GNU Modula-2 GNU C
866 ======================================
867 INTEGER int
868 LONGINT long long int
869 SHORTINT short int
870 CARDINAL unsigned int
871 LONGCARD long long unsigned int
872 SHORTCARD short unsigned int
873 BOOLEAN bool
874 REAL double
875 LONGREAL long double
876 SHORTREAL float
877 CHAR char
878 SHORTCOMPLEX complex float
879 COMPLEX complex double
880 LONGCOMPLEX complex long double
881 @end example
882
883 Note that GNU Modula-2 also supports fixed sized data types which are
884 exported from the @code{SYSTEM} module.
885 @xref{The PIM system module}.
886 @xref{The ISO system module}.
887
888 @node Standard procedures, High procedure function, Elementary data types, Using
889 @section Permanently accessible base procedures.
890
891 This section describes the procedures and functions which are
892 always visible.
893
894 @subsection Standard procedures and functions common to PIM and ISO
895
896 The following procedures are implemented and conform with Programming
897 in Modula-2 and ISO Modula-2: @code{NEW}, @code{DISPOSE}, @code{INC},
898 @code{DEC}, @code{INCL}, @code{EXCL} and @code{HALT}. The standard
899 functions are: @code{ABS}, @code{CAP}, @code{CHR}, @code{FLOAT},
900 @code{HIGH}, @code{LFLOAT}, @code{LTRUNC}, @code{MIN}, @code{MAX},
901 @code{ODD}, @code{SFLOAT}, @code{STRUNC} @code{TRUNC} and
902 @code{VAL}. All these functions and procedures (except @code{HALT},
903 @code{NEW}, @code{DISPOSE} and, under non constant conditions,
904 @code{LENGTH}) generate in-line code for efficiency.
905
906 @example
907
908 (*
909 ABS - returns the positive value of i.
910 *)
911
912 @findex ABS
913 PROCEDURE ABS (i: <any signed type>) : <any signed type> ;
914
915 @end example
916
917 @example
918
919 (*
920 CAP - returns the capital of character ch providing
921 ch lies within the range 'a'..'z'. Otherwise ch
922 is returned unaltered.
923 *)
924
925 @findex CAP
926 PROCEDURE CAP (ch: CHAR) : CHAR ;
927
928 @end example
929
930 @example
931
932 (*
933 CHR - converts a value of a <whole number type> into a CHAR.
934 CHR(x) is shorthand for VAL(CHAR, x).
935 *)
936
937 @findex CHR
938 PROCEDURE CHR (x: <whole number type>) : CHAR ;
939
940 @end example
941
942 @example
943
944 (*
945 DISPOSE - the procedure DISPOSE is replaced by:
946 DEALLOCATE(p, TSIZE(p^)) ;
947 The user is expected to import the procedure DEALLOCATE
948 (normally found in the module, Storage.)
949
950 In: a variable p: of any pointer type which has been
951 initialized by a call to NEW.
952 Out: the area of memory
953 holding p^ is returned to the system.
954 Note that the underlying procedure DEALLOCATE
955 procedure in module Storage will assign p to NIL.
956 *)
957
958 @findex DISPOSE
959 PROCEDURE DISPOSE (VAR p:<any pointer type>) ;
960 @end example
961
962 @example
963
964 (*
965 DEC - can either take one or two parameters. If supplied
966 with one parameter then on the completion of the call to
967 DEC, v will have its predecessor value. If two
968 parameters are supplied then the value v will have its
969 n'th predecessor. For these reasons the value of n
970 must be >=0.
971 *)
972
973 @findex DEC
974 PROCEDURE DEC (VAR v: <any base type>; [n: <any base type> = 1]) ;
975 @end example
976
977 @example
978
979 (*
980 EXCL - excludes bit element e from a set type s.
981 *)
982
983 @findex EXCL
984 PROCEDURE EXCL (VAR s: <any set type>; e: <element of set type s>) ;
985 @end example
986
987 @example
988
989 (*
990 FLOAT - will return a REAL number whose value is the same as o.
991 *)
992
993 @findex FLOAT
994 PROCEDURE FLOAT (o: <any whole number type>) : REAL ;
995 @end example
996
997 @example
998
999 (*
1000 FLOATS - will return a SHORTREAL number whose value is the same as o.
1001 *)
1002
1003 @findex FLOATS
1004 PROCEDURE FLOATS (o: <any whole number type>) : REAL ;
1005 @end example
1006
1007 @example
1008
1009 (*
1010 FLOATL - will return a LONGREAL number whose value is the same as o.
1011 *)
1012
1013 @findex FLOATL
1014 PROCEDURE FLOATL (o: <any whole number type>) : REAL ;
1015 @end example
1016
1017 @example
1018
1019 (*
1020 HALT - will call the HALT procedure inside the module M2RTS.
1021 Users can replace M2RTS.
1022 *)
1023
1024 @findex HALT
1025 PROCEDURE HALT ;
1026 @end example
1027
1028 @example
1029
1030 (*
1031 HIGH - returns the last accessible index of an parameter declared as
1032 ARRAY OF CHAR. Thus
1033
1034 PROCEDURE foo (a: ARRAY OF CHAR) ;
1035 VAR
1036 c: CARDINAL ;
1037 BEGIN
1038 c := HIGH(a)
1039 END foo ;
1040
1041 BEGIN
1042 foo('hello')
1043 END
1044
1045 will cause the local variable c to contain the value 5
1046 *)
1047
1048 @findex HIGH
1049 PROCEDURE HIGH (a: ARRAY OF CHAR) : CARDINAL ;
1050 @end example
1051
1052 @example
1053
1054 (*
1055 INC - can either take one or two parameters. If supplied
1056 with one parameter then on the completion of the call to
1057 INC, v will have its successor value. If two
1058 parameters are supplied then the value v will have its
1059 n'th successor. For these reasons the value of n
1060 must be >=0.
1061 *)
1062
1063 @findex INC
1064 PROCEDURE INC (VAR v: <any base type>; [n: <any base type> = 1]) ;
1065 @end example
1066
1067 @example
1068
1069 (*
1070 INCL - includes bit element e to a set type s.
1071 *)
1072
1073 @findex INCL
1074 PROCEDURE INCL (VAR s: <any set type>; e: <element of set type s>) ;
1075 @end example
1076
1077 @example
1078
1079 (*
1080 LFLOAT - will return a LONGREAL number whose value is the same as o.
1081 *)
1082
1083 @findex LFLOAT
1084 PROCEDURE LFLOAT (o: <any whole number type>) : LONGREAL ;
1085 @end example
1086
1087 @example
1088
1089 (*
1090 LTRUNC - will return a LONG<type> number whose value is the
1091 same as o. PIM2, PIM3 and ISO Modula-2 will return
1092 a LONGCARD whereas PIM4 returns LONGINT.
1093 *)
1094
1095 @findex LTRUNC
1096 PROCEDURE LTRUNC (o: <any floating point type>) : LONG<type> ;
1097 @end example
1098
1099 @example
1100
1101 (*
1102 MIN - returns the lowest legal value of an ordinal type.
1103 *)
1104
1105 @findex MIN
1106 PROCEDURE MIN (t: <ordinal type>) : <ordinal type> ;
1107
1108 @end example
1109
1110 @example
1111
1112 (*
1113 MAX - returns the largest legal value of an ordinal type.
1114 *)
1115
1116 @findex MAX
1117 PROCEDURE MAX (t: <ordinal type>) : <ordinal type> ;
1118
1119 @end example
1120
1121 @example
1122
1123 (*
1124 NEW - the procedure NEW is replaced by:
1125 ALLOCATE(p, TSIZE(p^)) ;
1126 The user is expected to import the procedure ALLOCATE
1127 (normally found in the module, Storage.)
1128
1129 In: a variable p: of any pointer type.
1130 Out: variable p is set to some allocated memory
1131 which is large enough to hold all the contents of p^.
1132 *)
1133
1134 @findex NEW
1135 PROCEDURE NEW (VAR p:<any pointer type>) ;
1136 @end example
1137
1138 @example
1139
1140 (*
1141 ODD - returns TRUE if the value is not divisible by 2.
1142 *)
1143
1144 @findex ODD
1145 PROCEDURE ODD (x: <whole number type>) : BOOLEAN ;
1146
1147 @end example
1148
1149 @example
1150
1151 (*
1152 SFLOAT - will return a SHORTREAL number whose value is the same
1153 as o.
1154 *)
1155
1156 @findex SFLOAT
1157 PROCEDURE SFLOAT (o: <any whole number type>) : SHORTREAL ;
1158 @end example
1159
1160 @example
1161
1162 (*
1163 STRUNC - will return a SHORT<type> number whose value is the same
1164 as o. PIM2, PIM3 and ISO Modula-2 will return a
1165 SHORTCARD whereas PIM4 returns SHORTINT.
1166 *)
1167
1168 @findex STRUNC
1169 PROCEDURE STRUNC (o: <any floating point type>) : SHORT<type> ;
1170 @end example
1171
1172 @example
1173
1174 (*
1175 TRUNC - will return a <type> number whose value is the same as o.
1176 PIM2, PIM3 and ISO Modula-2 will return a CARDINAL
1177 whereas PIM4 returns INTEGER.
1178 *)
1179
1180 @findex TRUNC
1181 PROCEDURE TRUNC (o: <any floating point type>) : <type> ;
1182 @end example
1183
1184 @example
1185
1186 (*
1187 TRUNCS - will return a <type> number whose value is the same
1188 as o. PIM2, PIM3 and ISO Modula-2 will return a
1189 SHORTCARD whereas PIM4 returns SHORTINT.
1190 *)
1191
1192 @findex TRUNCS
1193 PROCEDURE TRUNCS (o: <any floating point type>) : <type> ;
1194 @end example
1195
1196 @example
1197
1198 (*
1199 TRUNCL - will return a <type> number whose value is the same
1200 as o. PIM2, PIM3 and ISO Modula-2 will return a
1201 LONGCARD whereas PIM4 returns LONGINT.
1202 *)
1203
1204 @findex TRUNCL
1205 PROCEDURE TRUNCL (o: <any floating point type>) : <type> ;
1206 @end example
1207
1208 @example
1209
1210 (*
1211 VAL - converts data i of <any simple data type 2> to
1212 <any simple data type 1> and returns this value.
1213 No range checking is performed during this conversion.
1214 *)
1215
1216 @findex VAL
1217 PROCEDURE VAL (<any simple data type 1>,
1218 i: <any simple data type 2>) : <any simple data type 1> ;
1219
1220 @end example
1221
1222 @subsection ISO specific standard procedures and functions
1223
1224 The standard function @code{LENGTH} is specific to ISO Modula-2 and
1225 is defined as:
1226
1227 @example
1228
1229 (*
1230 IM - returns the imaginary component of a complex type.
1231 The return value will the same type as the imaginary field
1232 within the complex type.
1233 *)
1234
1235 @findex IM
1236 PROCEDURE IM (c: <any complex type>) : <floating point type> ;
1237 @end example
1238
1239 @example
1240
1241 (*
1242 INT - returns an INTEGER value which has the same value as v.
1243 This function is equivalent to: VAL(INTEGER, v).
1244 *)
1245
1246 @findex INT
1247 PROCEDURE INT (v: <any ordinal type>) : INTEGER ;
1248 @end example
1249
1250 @example
1251
1252 (*
1253 LENGTH - returns the length of string a.
1254 *)
1255
1256 @findex LENGTH
1257 PROCEDURE LENGTH (a: ARRAY OF CHAR) : CARDINAL ;
1258 @end example
1259
1260 This function is evaluated at compile time, providing that string
1261 @code{a} is a constant. If @code{a} cannot be evaluated then a call is
1262 made to @code{M2RTS.Length}.
1263
1264 @example
1265
1266 (*
1267 ODD - returns a BOOLEAN indicating whether the whole number
1268 value, v, is odd.
1269 *)
1270
1271 @findex ODD
1272 PROCEDURE ODD (v: <any whole number type>) : BOOLEAN ;
1273 @end example
1274
1275 @example
1276
1277 (*
1278 RE - returns the real component of a complex type.
1279 The return value will the same type as the real field
1280 within the complex type.
1281 *)
1282
1283 @findex RE
1284 PROCEDURE RE (c: <any complex type>) : <floating point type> ;
1285 @end example
1286
1287 @node High procedure function, Dialect, Standard procedures, Using
1288
1289 @section Behavior of the high procedure function
1290
1291 This section describes the behavior of the standard procedure function
1292 @code{HIGH} and it includes a table of parameters with the expected
1293 return result. The standard procedure function will return the last
1294 accessible indice of an @code{ARRAY}. If the parameter to @code{HIGH}
1295 is a static array then the result will be a @code{CARDINAL} value
1296 matching the upper bound in the @code{ARRAY} declaration.
1297
1298 The section also describes the behavior of a string literal actual
1299 parameter and how it relates to @code{HIGH}.
1300 The PIM2, PIM3, PIM4 and ISO standard is silent on the issue of
1301 whether a @code{nul} is present in an @code{ARRAY} @code{OF}
1302 @code{CHAR} actual parameter.
1303
1304 If the first parameter to @code{HIGH} is an unbounded @code{ARRAY} the
1305 return value from @code{HIGH} will be the last accessible element in
1306 the array. If a constant string literal is passed as an actual
1307 parameter then it will be @code{nul} terminated. The table and
1308 example code below describe the effect of passing an actual parameter
1309 and the expected @code{HIGH} value.
1310
1311 @example
1312 MODULE example1 ;
1313
1314 PROCEDURE test (a: ARRAY OF CHAR) ;
1315 VAR
1316 x: CARDINAL ;
1317 BEGIN
1318 x := HIGH (a) ;
1319 ...
1320 END test ;
1321
1322
1323 BEGIN
1324 test ('') ;
1325 test ('1') ;
1326 test ('12') ;
1327 test ('123') ;
1328 END example1.
1329
1330
1331 Actual parameter | HIGH (a) | a[HIGH (a)] = nul
1332 ===============================================
1333 '' | 0 | TRUE
1334 '1' | 1 | TRUE
1335 '12' | 2 | TRUE
1336 '123' | 3 | TRUE
1337 @end example
1338
1339 A constant string literal will be passed to an @code{ARRAY} @code{OF}
1340 @code{CHAR} with an appended @code{nul} @code{CHAR}. Thus if the
1341 constant string literal @code{''} is passed as an actual parameter (in
1342 example1) then the result from @code{HIGH(a)} will be @code{0}.
1343
1344 @example
1345 MODULE example2 ;
1346
1347 PROCEDURE test (a: ARRAY OF CHAR) ;
1348 VAR
1349 x: CARDINAL ;
1350 BEGIN
1351 x := HIGH (a) ;
1352 ...
1353 END test ;
1354
1355 VAR
1356 str0: ARRAY [0..0] OF CHAR ;
1357 str1: ARRAY [0..1] OF CHAR ;
1358 str2: ARRAY [0..2] OF CHAR ;
1359 str3: ARRAY [0..3] OF CHAR ;
1360 BEGIN
1361 str0 := 'a' ; (* No room for the nul terminator. *)
1362 test (str0) ;
1363 str1 := 'ab' ; (* No room for the nul terminator. *)
1364 test (str1) ;
1365 str2 := 'ab' ; (* Terminated with a nul. *)
1366 test (str2) ;
1367 str2 := 'abc' ; (* Terminated with a nul. *)
1368 test (str3) ;
1369 END example2.
1370
1371 Actual parameter | HIGH (a) | a[HIGH (a)] = nul
1372 ===============================================
1373 str0 | 0 | FALSE
1374 str1 | 1 | FALSE
1375 atr2 | 2 | TRUE
1376 str3 | 3 | TRUE
1377 @end example
1378
1379 @node Dialect, Exceptions, High procedure function, Using
1380 @section GNU Modula-2 supported dialects
1381
1382 This section describes the dialects understood by GNU Modula-2.
1383 It also describes the differences between the dialects and
1384 any command line switches which determine dialect behaviour.
1385
1386 The GNU Modula-2 compiler is compliant with four dialects of Modula-2.
1387 The language as defined in 'Programming in Modula-2' 2nd Edition,
1388 Springer Verlag, 1982, 1983 by Niklaus Wirth (PIM2), 'Programming in
1389 Modula-2', 3rd Corrected Edition, Springer Verlag, 1985 (PIM3) and
1390 'Programming in Modula-2', 4th Edition, Springer Verlag, 1988 (PIM4)
1391 @uref{https://freepages.modula2.org/report4/modula-2.html} and the ISO
1392 Modula-2 language as defined in ISO/IEC Information technology -
1393 programming languages - part 1: Modula-2 Language, ISO/IEC 10514-1
1394 (1996) (ISO).
1395
1396 The command line switches @samp{-fpim2}, @samp{-fpim3}, @samp{-fpim4}
1397 and @samp{-fiso} can be used to force mutually exclusive
1398 features. However by default the compiler will not aggressively fail
1399 if a non mutually exclusive feature is used from another dialect. For
1400 example it is possible to specify @samp{-fpim2} and still utilize
1401 @samp{DEFINITION} @samp{MODULES} which have no export list.
1402
1403 Some dialect differences will force a compile time error, for example
1404 in PIM2 the user must @code{IMPORT} @code{SIZE} from the module
1405 @code{SYSTEM}, whereas in PIM3 and PIM4 @code{SIZE} is a pervasive
1406 function. Thus compiling PIM4 source code with the @samp{-fpim2}
1407 switch will cause a compile time error. This can be fixed quickly
1408 with an additional @code{IMPORT} or alternatively by compiling with
1409 the @samp{-fpim4} switch.
1410
1411 However there are some very important differences between the dialects
1412 which are mutually exclusive and therefore it is vital that users
1413 choose the dialects with care when these language features are used.
1414
1415 @subsection Integer division, remainder and modulus
1416
1417 The most dangerous set of mutually exclusive features found in the
1418 four dialects supported by GNU Modula-2 are the @code{INTEGER}
1419 division, remainder and modulus arithmetic operators. It is important
1420 to note that the same source code can be compiled to give different
1421 run time results depending upon these switches! The reference manual
1422 for the various dialects of Modula-2 are quite clear about this
1423 behavior and sadly there are three distinct definitions.
1424
1425 The table below illustrates the problem when a negative operand is
1426 used.
1427
1428 @example
1429 Pim2/3 Pim4 ISO
1430 ----------- ----------- ----------------------
1431 lval rval DIV MOD DIV MOD DIV MOD / REM
1432 31 10 3 1 3 1 3 1 3 1
1433 -31 10 -3 -1 -4 9 -4 9 -3 -1
1434 31 -10 -3 1 -3 1 Exception -3 1
1435 -31 -10 3 -1 4 9 Exception 3 -1
1436 @end example
1437
1438 See also P24 of PIM2, P27 of PIM3, P29 of PIM4 and P201 of the ISO
1439 Standard. At present all dialect division, remainder and modulus are
1440 implemented as above, apart from the exception calling in the ISO
1441 dialect. Instead of exception handling the results are the same as the
1442 PIM4 dialect. This is a temporary implementation situation.
1443
1444 @node Exceptions, Semantic checking, Dialect, Using
1445 @section Exception implementation
1446
1447 This section describes how exceptions are implemented in GNU Modula-2
1448 and how command line switches affect their behavior. The option
1449 @samp{-fsoft-check-all} enables all software checking of nil
1450 dereferences, division by zero etc. Additional code is produced to
1451 check these conditions and exception handlers are invoked if the
1452 conditions prevail.
1453
1454 Without @samp{-fsoft-check-all} these exceptions will be caught by
1455 hardware (assuming the hardware support exists) and a signal handler
1456 is invoked. The signal handler will in turn @code{THROW} an exception
1457 which will be caught by the appropriate Modula-2 handler. However the
1458 action of throwing an exception from within a signal handler is
1459 implementation defined (according to the C++ documentation). For
1460 example on the x86_64 architecture this works whereas on the i686
1461 architecture it does not. Therefore to ensure portability it is
1462 recommended to use @samp{-fsoft-check-all}.
1463
1464 @footnote{@samp{-fsoft-check-all} can be effectively combined with
1465 @samp{-O2} to semantically analyze source code for possible run time
1466 errors at compile time.}
1467
1468 @node Semantic checking, Extensions, Exceptions, Using
1469 @section How to detect run time problems at compile time
1470
1471 Consider the following program:
1472
1473 @example
1474 MODULE assignvalue ; (*!m2iso+gm2*)
1475
1476 PROCEDURE bad () : INTEGER ;
1477 VAR
1478 i: INTEGER ;
1479 BEGIN
1480 i := -1 ;
1481 RETURN i
1482 END bad ;
1483
1484 VAR
1485 foo: CARDINAL ;
1486 BEGIN
1487 (* The m2rte plugin will detect this as an error, post
1488 optimization. *)
1489 foo := bad ()
1490 END assignvalue.
1491 @end example
1492
1493 here we see that the programmer has overlooked that the return value
1494 from @samp{bad} will cause an overflow to @samp{foo}. If we compile
1495 the code with the following options:
1496
1497 @example
1498 $ gm2 -g -fsoft-check-all -O2 -fm2-plugin -c assignvalue.mod
1499 assignvalue.mod:16:0:inevitable that this error will occur at run time,
1500 assignment will result in an overflow
1501 @end example
1502
1503 The gm2 semantic plugin is automatically run and will generate a
1504 warning message for every exception call which is known as reachable.
1505 It is highly advised to run the optimizer (@samp{-O2} or @samp{-O3})
1506 with @samp{-fsoft-check-all} so that the compiler is able to run the
1507 optimizer and perform variable and flow analysis before the semantic
1508 plugin is invoked.
1509
1510 The @samp{-Wuninit-variable-checking} can be used to identify
1511 uninitialized variables within the first basic block in a procedure.
1512 The checking is limited to variables so long as they are
1513 not an array or set or a variant record or var parameter.
1514
1515 The following example detects whether a sub component within a record
1516 is uninitialized.
1517
1518 @example
1519 MODULE testlarge2 ;
1520
1521 TYPE
1522 color = RECORD
1523 r, g, b: CARDINAL ;
1524 END ;
1525
1526 pixel = RECORD
1527 fg, bg: color ;
1528 END ;
1529
1530 PROCEDURE test ;
1531 VAR
1532 p: pixel ;
1533 BEGIN
1534 p.fg.r := 1 ;
1535 p.fg.g := 2 ;
1536 p.fg.g := 3 ; (* Deliberate typo should be p.fg.b. *)
1537 p.bg := p.fg ; (* Accessing an uninitialized field. *)
1538 END test ;
1539
1540 BEGIN
1541 test
1542 END testlarge2.
1543 @end example
1544
1545 @example
1546 $ gm2 -c -Wuninit-variable-checking testlarge2.mod
1547 testlarge2.mod:19:13: warning: In procedure ‘test’: attempting to
1548 access expression before it has been initialized
1549 19 | p.bg := p.fg ; (* Accessing an uninitialized field. *)
1550 | ~^~~
1551 @end example
1552
1553 The following example detects if an individual field is uninitialized.
1554
1555 @example
1556 MODULE testwithnoptr ;
1557
1558 TYPE
1559 Vec = RECORD
1560 x, y: CARDINAL ;
1561 END ;
1562
1563 PROCEDURE test ;
1564 VAR
1565 p: Vec ;
1566 BEGIN
1567 WITH p DO
1568 x := 1 ;
1569 x := 2 (* Deliberate typo, user meant y. *)
1570 END ;
1571 IF p.y = 2
1572 THEN
1573 END
1574 END test ;
1575
1576 BEGIN
1577 test
1578 END testwithnoptr.
1579 @end example
1580
1581 The following example detects a record is uninitialized via a
1582 pointer variable in a @samp{WITH} block.
1583
1584 @example
1585 $ gm2 -g -c -Wuninit-variable-checking testwithnoptr.mod
1586 testwithnoptr.mod:21:8: warning: In procedure ‘test’: attempting to
1587 access expression before it has been initialized
1588 21 | IF p.y = 2
1589 | ~^~
1590 @end example
1591
1592 @example
1593 MODULE testnew6 ;
1594
1595 FROM Storage IMPORT ALLOCATE ;
1596
1597 TYPE
1598 PtrToVec = POINTER TO RECORD
1599 x, y: INTEGER ;
1600 END ;
1601
1602 PROCEDURE test ;
1603 VAR
1604 p: PtrToVec ;
1605 BEGIN
1606 NEW (p) ;
1607 WITH p^ DO
1608 x := 1 ;
1609 x := 2 (* Deliberate typo, user meant y. *)
1610 END ;
1611 IF p^.y = 2
1612 THEN
1613 END
1614 END test ;
1615
1616
1617 BEGIN
1618 test
1619 END testnew6.
1620 @end example
1621
1622 @example
1623 $ gm2 -g -c -Wuninit-variable-checking testnew6.mod
1624 testnew6.mod:19:9: warning: In procedure ‘test’: attempting to
1625 access expression before it has been initialized
1626 19 | IF p^.y = 2
1627 | ~~^~
1628 @end example
1629
1630 @node Extensions, Type compatibility, Semantic checking, Using
1631 @section GNU Modula-2 language extensions
1632
1633 This section introduces the GNU Modula-2 language extensions.
1634 The GNU Modula-2 compiler allows abstract data types to be any type,
1635 not just restricted to a pointer type providing the
1636 @samp{-fextended-opaque} option is supplied
1637 @xref{Compiler options}.
1638
1639 Declarations can be made in any order, whether they are
1640 types, constants, procedures, nested modules or variables.
1641 @c (@xref{Passes, , ,}.)
1642
1643 GNU Modula-2 also allows programmers to interface to @code{C} and
1644 assembly language.
1645
1646 GNU Modula-2 provides support for the special tokens @code{__LINE__},
1647 @code{__FILE__}, @code{__FUNCTION__} and @code{__DATE__}. Support for
1648 these tokens will occur even if the @samp{-fcpp} option is not
1649 supplied. A table of these identifiers and their data type and values
1650 is given below:
1651
1652 @example
1653 Scope GNU Modula-2 token Data type and example value
1654
1655 anywhere __LINE__ Constant Literal compatible
1656 with CARDINAL, INTEGER and WORD.
1657 Example 1234
1658
1659 anywhere __FILE__ Constant string compatible
1660 with parameter ARRAY OF CHAR or
1661 an ARRAY whose SIZE is >= string
1662 length. Example
1663 "hello.mod"
1664
1665 procedure __FUNCTION__ Constant string compatible
1666 with parameter ARRAY OF CHAR or
1667 an ARRAY whose SIZE is >= string
1668 length. Example
1669 "calc"
1670
1671 module __FUNCTION__ Example
1672 "module hello initialization"
1673
1674 anywhere __DATE__ Constant string compatible
1675 with parameter ARRAY OF CHAR or
1676 an ARRAY whose SIZE is >= string
1677 length. Example
1678 "Thu Apr 29 10:07:16 BST 2004"
1679
1680 anywhere __COLUMN__ Gives a constant literal number
1681 determining the left hand column
1682 where the first _ appears in
1683 __COLUMN__. The left most column
1684 is 1.
1685
1686 @end example
1687
1688 The preprocessor @samp{cpp} can be invoked via the @samp{-fcpp}
1689 command line option. This in turn invokes @samp{cpp} with the
1690 following arguments @samp{-traditional -lang-asm}. These options
1691 preserve comments and all quotations. @samp{gm2} treats a @samp{#}
1692 character in the first column as a preprocessor directive unless
1693 @samp{-fno-cpp} is supplied.
1694
1695 For example here is a module which calls @code{FatalError}
1696 via the macro @code{ERROR}.
1697
1698 @example
1699 MODULE cpp ;
1700
1701 FROM SYSTEM IMPORT ADR, SIZE ;
1702 FROM libc IMPORT exit, printf, malloc ;
1703
1704 PROCEDURE FatalError (a, file: ARRAY OF CHAR;
1705 line: CARDINAL;
1706 func: ARRAY OF CHAR) ;
1707 BEGIN
1708 printf ("%s:%d:fatal error, %s, in %s\n",
1709 ADR (file), line, ADR (a), ADR (func)) ;
1710 exit (1)
1711 END FatalError ;
1712
1713 #define ERROR(X) FatalError(X, __FILE__, __LINE__, __FUNCTION__)
1714
1715 VAR
1716 pc: POINTER TO CARDINAL;
1717 BEGIN
1718 pc := malloc (SIZE (CARDINAL)) ;
1719 IF pc = NIL
1720 THEN
1721 ERROR ('out of memory')
1722 END
1723 END cpp.
1724 @end example
1725
1726 Another use for the C preprocessor in Modula-2 might be to turn on
1727 debugging code. For example the library module
1728 @file{FormatStrings.mod} uses procedures from @file{DynamicStrings.mod}
1729 and to track down memory leaks it was useful to track the source file
1730 and line where each string was created. Here is a section of
1731 @file{FormatStrings.mod} which shows how the debugging code was
1732 enabled and disabled by adding @code{-fcpp} to the command line.
1733
1734 @example
1735 FROM DynamicStrings IMPORT String, InitString, InitStringChar, Mark,
1736 ConCat, Slice, Index, char,
1737 Assign, Length, Mult, Dup, ConCatChar,
1738 PushAllocation, PopAllocationExemption,
1739 InitStringDB, InitStringCharStarDB,
1740 InitStringCharDB, MultDB, DupDB, SliceDB ;
1741
1742 (*
1743 #define InitString(X) InitStringDB(X, __FILE__, __LINE__)
1744 #define InitStringCharStar(X) InitStringCharStarDB(X, __FILE__, \
1745 __LINE__)
1746 #define InitStringChar(X) InitStringCharDB(X, __FILE__, __LINE__)
1747 #define Mult(X,Y) MultDB(X, Y, __FILE__, __LINE__)
1748 #define Dup(X) DupDB(X, __FILE__, __LINE__)
1749 #define Slice(X,Y,Z) SliceDB(X, Y, Z, __FILE__, __LINE__)
1750 *)
1751
1752 PROCEDURE doDSdbEnter ;
1753 BEGIN
1754 PushAllocation
1755 END doDSdbEnter ;
1756
1757 PROCEDURE doDSdbExit (s: String) ;
1758 BEGIN
1759 s := PopAllocationExemption (TRUE, s)
1760 END doDSdbExit ;
1761
1762 PROCEDURE DSdbEnter ;
1763 BEGIN
1764 END DSdbEnter ;
1765
1766 PROCEDURE DSdbExit (s: String) ;
1767 BEGIN
1768 END DSdbExit ;
1769
1770 (*
1771 #define DBsbEnter doDBsbEnter
1772 #define DBsbExit doDBsbExit
1773 *)
1774
1775 PROCEDURE Sprintf1 (s: String; w: ARRAY OF BYTE) : String ;
1776 BEGIN
1777 DSdbEnter ;
1778 s := FormatString (HandleEscape (s), w) ;
1779 DSdbExit (s) ;
1780 RETURN s
1781 END Sprintf1 ;
1782 @end example
1783
1784 It is worth noting that the overhead of this code once @code{-fcpp} is
1785 not present and -O2 is used will be zero since the local empty
1786 procedures @code{DSdbEnter} and @code{DSdbExit} will be thrown away by
1787 the optimization passes of the GCC backend.
1788
1789 @subsection Optional procedure parameter
1790
1791 GNU Modula-2 allows the last parameter to a procedure or function
1792 parameter to be optional. For example in the ISO library
1793 @file{COROUTINES.def} the procedure @code{NEWCOROUTINE} is defined as
1794 having an optional fifth argument (@code{initProtection}) which, if
1795 absent, is automatically replaced by @code{NIL}.
1796
1797 @example
1798 @findex NEWCOROUTINE
1799 PROCEDURE NEWCOROUTINE (procBody: PROC; workspace: SYSTEM.ADDRESS;
1800 size: CARDINAL; VAR cr: COROUTINE;
1801 [initProtection: PROTECTION = NIL]);
1802
1803 (* Creates a new coroutine whose body is given by procBody,
1804 and returns the identity of the coroutine in cr.
1805 workspace is a pointer to the work space allocated to
1806 the coroutine; size specifies the size of this workspace
1807 in terms of SYSTEM.LOC.
1808
1809 The optional fifth argument may contain a single parameter
1810 which specifies the initial protection level of the coroutine.
1811 *)
1812 @end example
1813
1814 The implementation module @file{COROUTINES.mod} implements this
1815 procedure using the following syntax:
1816
1817 @example
1818 PROCEDURE NEWCOROUTINE (procBody: PROC; workspace: SYSTEM.ADDRESS;
1819 size: CARDINAL; VAR cr: COROUTINE;
1820 [initProtection: PROTECTION]);
1821 BEGIN
1822
1823 END NEWCOROUTINE ;
1824 @end example
1825
1826 Note that it is illegal for this declaration to contain an initializer
1827 value for @code{initProtection}. However it is necessary to surround
1828 this parameter with the brackets @code{[} and @code{]}. This serves to
1829 remind the programmer that the last parameter was declared as optional
1830 in the definition module.
1831
1832 Local procedures can be declared to have an optional final parameter
1833 in which case the initializer is mandatory in the implementation or
1834 program module.
1835
1836 GNU Modula-2 also provides additional fixed sized data types which
1837 are all exported from the @code{SYSTEM} module.
1838 @xref{The PIM system module}.
1839 @xref{The ISO system module}.
1840
1841 @node Type compatibility, Exception handling, Extensions, Using
1842 @section Type compatibility
1843
1844 This section discuss the issues surrounding assignment, expression
1845 and parameter compatibility, their effect of the additional
1846 fixed sized datatypes and also their effect of run time checking.
1847 The data types supported by the compiler are:
1848
1849 @example
1850 GNU Modula-2 scope switches
1851 =============================================
1852 INTEGER pervasive
1853 LONGINT pervasive
1854 SHORTINT pervasive
1855 CARDINAL pervasive
1856 LONGCARD pervasive
1857 SHORTCARD pervasive
1858 BOOLEAN pervasive
1859 BITSET pervasive
1860 REAL pervasive
1861 LONGREAL pervasive
1862 SHORTREAL pervasive
1863 CHAR pervasive
1864 SHORTCOMPLEX pervasive
1865 COMPLEX pervasive
1866 LONGCOMPLEX pervasive
1867
1868 LOC SYSTEM -fiso
1869 BYTE SYSTEM
1870 WORD SYSTEM
1871 ADDRESS SYSTEM
1872
1873 The following extensions are supported for
1874 most architectures (please check SYSTEM.def).
1875 =============================================
1876 INTEGER8 SYSTEM
1877 INTEGER16 SYSTEM
1878 INTEGER32 SYSTEM
1879 INTEGER64 SYSTEM
1880 CARDINAL8 SYSTEM
1881 CARDINAL16 SYSTEM
1882 CARDINAL32 SYSTEM
1883 CARDINAL64 SYSTEM
1884 BITSET8 SYSTEM
1885 BITSET16 SYSTEM
1886 BITSET32 SYSTEM
1887 WORD16 SYSTEM
1888 WORD32 SYSTEM
1889 WORD64 SYSTEM
1890 REAL32 SYSTEM
1891 REAL64 SYSTEM
1892 REAL96 SYSTEM
1893 REAL128 SYSTEM
1894 COMPLEX32 SYSTEM
1895 COMPLEX64 SYSTEM
1896 COMPLEX96 SYSTEM
1897 COMPLEX128 SYSTEM
1898 @end example
1899
1900 The Modula-2 language categorizes compatibility between entities of
1901 possibly differing types into three sub components: expressions,
1902 assignments, and parameters. Parameter compatibility is further
1903 divided into two sections for pass by reference and pass by value
1904 compatibility.
1905
1906 For more detail on the Modula-2 type compatibility see the Modula-2
1907 ISO standard BS ISO/IEC 10514-1:1996 page 121-125. For detail on the
1908 PIM type compatibility see Programming in Modula-2 Edition 4 page 29,
1909 (Elementary Data Types).
1910
1911 @subsection Expression compatibility
1912
1913 Modula-2 restricts the types of expressions to the same type.
1914 Expression compatibility is a symmetric relation.
1915
1916 For example two sub expressions of @code{INTEGER} and @code{CARDINAL}
1917 are not expression compatible
1918 (@uref{https://freepages.modula2.org/report4/modula-2.html} and ISO
1919 Modula-2).
1920
1921 In GNU Modula-2 this rule is also extended across all fixed sized data
1922 types (imported from SYSTEM).
1923
1924 @subsection Assignment compatibility
1925
1926 This section discusses the assignment issues surrounding assignment
1927 compatibility of elementary types (@code{INTEGER}, @code{CARDINAL},
1928 @code{REAL} and @code{CHAR} for example). The information here is
1929 found in more detail in the Modula-2 ISO standard BS ISO/IEC
1930 10514-1:1996 page 122.
1931
1932 Assignment compatibility exists between the same sized elementary
1933 types.
1934
1935 Same type family of different sizes are
1936 also compatible as long as the @code{MAX(}type@code{)} and
1937 @code{MIN(}type@code{)} is known. So for example this includes the
1938 @code{INTEGER} family, @code{CARDINAL} family and the @code{REAL}
1939 family.
1940
1941 The reason for this is that when the assignment is performed
1942 the compiler will check to see that the expression (on the right of
1943 the @code{:=}) lies within the range of the designator type (on the
1944 left hand side of the @code{:=}). Thus these ordinal types can be
1945 assignment compatible. However it does mean that @code{WORD32} is not
1946 compatible with @code{WORD16} as @code{WORD32} does not have a minimum
1947 or maximum value and therefore cannot be checked. The compiler does
1948 not know which of the two bytes from @code{WORD32} should be copied
1949 into @code{WORD16} and which two should be ignored. Currently the
1950 types @code{BITSET8}, @code{BITSET16} and @code{BITSET32} are
1951 assignment incompatible. However this restriction maybe lifted when
1952 further run time checking is achieved.
1953
1954 Modula-2 does allow @code{INTEGER} to be assignment compatible with
1955 @code{WORD} as they are the same size. Likewise GNU Modula-2 allows
1956 @code{INTEGER16} to be compatible with @code{WORD16} and the same for
1957 the other fixed sized types and their sized equivalent in either
1958 @code{WORD}n, @code{BYTE} or @code{LOC} types. However it prohibits
1959 assignment between @code{WORD} and @code{WORD32} even though on many
1960 systems these sizes will be the same. The reasoning behind this rule
1961 is that the extended fixed sized types are meant to be used by
1962 applications requiring fixed sized data types and it is more portable
1963 to forbid the blurring of the boundaries between fixed sized and
1964 machine dependent sized types.
1965
1966 Intermediate code run time checking is always generated by the front
1967 end. However this intermediate code is only translated into actual
1968 code if the appropriate command line switches are specified. This
1969 allows the compiler to perform limited range checking at compile time.
1970 In the future it will allow the extensive GCC optimizations to
1971 propagate constant values through to the range checks which if they
1972 are found to exceed the type range will result in a compile time
1973 error message.
1974
1975 @subsection Parameter compatibility
1976
1977 Parameter compatibility is divided into two areas, pass by value and
1978 pass by reference (@code{VAR}). In the case of pass by value the
1979 rules are exactly the same as assignment. However in the second case,
1980 pass by reference, the actual parameter and formal parameter must be
1981 the same size and family. Furthermore @code{INTEGER} and
1982 @code{CARDINAL}s are not treated as compatible in the pass by
1983 reference case.
1984
1985 The types @code{BYTE}, @code{LOC}, @code{WORD} and @code{WORD}n
1986 derivatives are assignment and parameter compatible with any data type
1987 of the same size.
1988
1989 @node Exception handling, Unbounded by reference, Type compatibility, Using
1990 @section Exception handling
1991
1992 This section gives an example of exception handling and briefly
1993 describes its runtime behavior. The module below is written in the
1994 ISO dialect of Modula-2 and can be compiled with the command line:
1995
1996 @example
1997 $ gm2 -g -fiso -fsoft-check-all lazyunique.mod
1998 @end example
1999
2000 The option @samp{-fsoft-check-all} generates checks for @code{NIL}
2001 pointer access violation. In turn this will call the exception handler.
2002
2003 @example
2004 @group
2005 MODULE lazyunique ; (*!m2iso+gm2*)
2006
2007 FROM Storage IMPORT ALLOCATE ;
2008 FROM libc IMPORT printf, exit ;
2009
2010 TYPE
2011 List = POINTER TO RECORD
2012 next : List ;
2013 value: INTEGER ;
2014 END ;
2015
2016 Array = ARRAY [0..3] OF INTEGER ;
2017
2018 CONST
2019 Unsorted = Array @{0, 2, 1, 1@} ;
2020
2021 VAR
2022 head: List ;
2023 @end group
2024 @end example
2025
2026 @example
2027 @group
2028 PROCEDURE Display ;
2029 VAR
2030 p: List ;
2031 BEGIN
2032 p := head^.next ;
2033 printf ("\nunique data\n");
2034 printf ("===========\n");
2035 WHILE p # NIL DO
2036 printf ("%d\n", p^.value);
2037 p := p^.next
2038 END
2039 END Display ;
2040 @end group
2041 @end example
2042
2043 @example
2044 @group
2045 PROCEDURE Add (VAR p: List; val: INTEGER) ;
2046 BEGIN
2047 NEW (p) ;
2048 WITH p^ DO
2049 value := val ;
2050 next := NIL
2051 END
2052 END Add ;
2053 @end group
2054 @end example
2055
2056 @example
2057 @group
2058 PROCEDURE Unique (val: INTEGER) ;
2059 VAR
2060 p: List ;
2061 BEGIN
2062 printf ("new value %d\n", val);
2063 p := head ;
2064 (* The following line may cause an exception accessing next or
2065 value. *)
2066 WHILE p^.next^.value # val DO
2067 p := p^.next
2068 END
2069 EXCEPT
2070 (* Now fixup. Determine the source of the exception and retry. *)
2071 IF head = NIL
2072 THEN
2073 printf ("list was empty, add sentinal\n");
2074 Add (head, -1) ;
2075 RETRY (* Jump back to the begin statement. *)
2076 ELSIF p^.next = NIL
2077 THEN
2078 printf ("growing the list\n");
2079 Add (p^.next, val) ;
2080 RETRY (* Jump back to the begin statement. *)
2081 ELSE
2082 printf ("should never reach here!\n");
2083 END
2084 END Unique ;
2085 @end group
2086 @end example
2087
2088 @example
2089 @group
2090 PROCEDURE unique ;
2091 VAR
2092 i: CARDINAL ;
2093 BEGIN
2094 FOR i := 0 TO HIGH (Unsorted) DO
2095 Unique (Unsorted[i])
2096 END ;
2097 Display
2098 END unique ;
2099
2100 BEGIN
2101 head := NIL ;
2102 unique
2103 END lazyunique.
2104 @end group
2105 @end example
2106
2107 @example
2108 @group
2109 new value 0
2110 list was empty, add sentinal
2111 new value 0
2112 growing the list
2113 new value 0
2114 new value 2
2115 growing the list
2116 new value 2
2117 new value 1
2118 growing the list
2119 new value 1
2120 new value 1
2121
2122 unique data
2123 ===========
2124 0
2125 2
2126 1
2127 @end group
2128 @end example
2129
2130 @node Unbounded by reference, Building a shared library, Exception handling, Using
2131 @section Unbounded by reference
2132
2133 This section documents a GNU Modula-2 compiler switch which implements
2134 a language optimization surrounding the implementation of unbounded
2135 arrays. In GNU Modula-2 the unbounded array is implemented by
2136 utilizing an internal structure @code{struct @{dataType *address,
2137 unsigned int high@}}. So given the Modula-2 procedure declaration:
2138
2139 @example
2140 PROCEDURE foo (VAR a: ARRAY OF dataType) ;
2141 BEGIN
2142 IF a[2]= (* etc *)
2143 END foo ;
2144 @end example
2145
2146 it is translated into GCC @code{tree}s, which can be represented
2147 in their C form thus:
2148
2149 @example
2150 void foo (struct @{dataType *address, unsigned int high@} a)
2151 @{
2152 if (a.address[2] == /* etc */
2153 @}
2154 @end example
2155
2156 Whereas if the procedure @code{foo} was declared as:
2157
2158 @example
2159 PROCEDURE foo (a: ARRAY OF dataType) ;
2160 BEGIN
2161 IF a[2]= (* etc *)
2162 END foo ;
2163 @end example
2164
2165 then it is implemented by being translated into the following
2166 GCC @code{tree}s, which can be represented in their C form thus:
2167
2168 @example
2169 void foo (struct @{dataType *address, unsigned int high@} a)
2170 @{
2171 dataType *copyContents = (dataType *)alloca (a.high+1);
2172 memcpy(copyContents, a.address, a.high+1);
2173 a.address = copyContents;
2174
2175 if (a.address[2] == /* etc */
2176 @}
2177 @end example
2178
2179 This implementation works, but it makes a copy of each non VAR
2180 unbounded array when a procedure is entered. If the unbounded array
2181 is not changed during procedure @code{foo} then this implementation
2182 will be very inefficient. In effect Modula-2 lacks the @code{REF}
2183 keyword of Ada. Consequently the programmer maybe tempted to
2184 sacrifice semantic clarity for greater efficiency by declaring the
2185 parameter using the @code{VAR} keyword in place of @code{REF}.
2186
2187 The @code{-funbounded-by-reference} switch instructs the compiler to
2188 check and see if the programmer is modifying the content of any
2189 unbounded array. If it is modified then a copy will be made upon
2190 entry into the procedure. Conversely if the content is only read and
2191 never modified then this non @code{VAR} unbounded array is a candidate
2192 for being passed by reference. It is only a candidate as it is still
2193 possible that passing this parameter by reference could alter the
2194 meaning of the source code. For example consider the following case:
2195
2196 @example
2197 PROCEDURE StrConCat (VAR a: ARRAY OF CHAR; b, c: ARRAY OF CHAR) ;
2198 BEGIN
2199 (* code which performs string a := b + c *)
2200 END StrConCat ;
2201
2202 PROCEDURE foo ;
2203 VAR
2204 a: ARRAY [0..3] OF CHAR ;
2205 BEGIN
2206 a := 'q' ;
2207 StrConCat(a, a, a)
2208 END foo ;
2209 @end example
2210
2211 In the code above we see that the same parameter, @code{a}, is being
2212 passed three times to @code{StrConCat}. Clearly even though parameters
2213 @code{b} and @code{c} are never modified it would be incorrect to
2214 implement them as pass by reference. Therefore the compiler checks to
2215 see if any non @code{VAR} parameter is type compatible with any
2216 @code{VAR} parameter and if so it generates run time procedure entry
2217 checks to determine whether the contents of parameters @code{b} or
2218 @code{c} matches the contents of @code{a}. If a match is detected
2219 then a copy is made and the @code{address} in the unbounded
2220 @code{struct}ure is modified.
2221
2222 The compiler will check the address range of each candidate against
2223 the address range of any @code{VAR} parameter, providing they are type
2224 compatible. For example consider:
2225
2226 @example
2227 PROCEDURE foo (a: ARRAY OF BYTE; VAR f: REAL) ;
2228 BEGIN
2229 f := 3.14 ;
2230 IF a[0]=BYTE(0)
2231 THEN
2232 (* etc *)
2233 END
2234 END foo ;
2235
2236 PROCEDURE bar ;
2237 BEGIN
2238 r := 2.0 ;
2239 foo(r, r)
2240 END bar ;
2241 @end example
2242
2243 Here we see that although parameter, @code{a}, is a candidate for the
2244 passing by reference, it would be incorrect to use this
2245 transformation. Thus the compiler detects that parameters, @code{a}
2246 and @code{f} are type compatible and will produce run time checking
2247 code to test whether the address range of their respective contents
2248 intersect.
2249
2250 @node Building a shared library, Interface for Python, Unbounded by reference, Using
2251 @section Building a shared library
2252
2253 This section describes building a tiny shared library implemented in
2254 Modula-2 and built with @file{libtool}. Suppose a project consists of
2255 two definition modules and two implementation modules and a program
2256 module @file{a.def}, @file{a.mod}, @file{b.def}, @file{b.mod} and
2257 @file{c.mod}. The first step is to compile the modules using position
2258 independent code. This can be achieved by the following three
2259 commands:
2260
2261 @example
2262 libtool --tag=CC --mode=compile gm2 -g -c a.mod -o a.lo
2263 libtool --tag=CC --mode=compile gm2 -g -c b.mod -o b.lo
2264 libtool --tag=CC --mode=compile gm2 -g -c c.mod -o c.lo
2265 @end example
2266
2267 The second step is to generate the shared library initialization and
2268 finalization routines. We can do this by asking gm2 to generate a
2269 list of dependent modules and then use this to generate the scaffold.
2270 We also must compile the scaffold.
2271
2272 @example
2273 gm2 -c -g -fmakelist c.mod
2274 gm2 -c -g -fmakeinit -fshared c.mod
2275 libtool --tag=CC --mode=compile g++ -g -c c_m2.cpp -o c_m2.lo
2276 @end example
2277
2278 The third step is to link all these @file{.lo} files.
2279
2280 @example
2281 libtool --mode=link gcc -g c_m2.lo a.lo b.lo c.lo \
2282 -L$(prefix)/lib64 \
2283 -rpath `pwd` -lgm2 -lstdc++ -lm -o libabc.la
2284 @end example
2285
2286 At this point the shared library @file{libabc.so} will have been
2287 created inside the directory @file{.libs}.
2288
2289 @node Interface for Python, Producing a Python module, Building a shared library, Using
2290 @section How to produce swig interface files
2291
2292 This section describes how Modula-2 implementation modules can be
2293 called from Python (and other scripting languages such as TCL and
2294 Perl). GNU Modula-2 can be instructed to create a swig interface when
2295 it is compiling an implementation module. Swig then uses the
2296 interface file to generate all the necessary wrapping to that the
2297 desired scripting language may access the implementation module.
2298
2299 Here is an example of how you might call upon the services of the
2300 Modula-2 library module @code{NumberIO} from Python3.
2301
2302 The following commands can be used to generate the Python3 module:
2303
2304 @example
2305 export src=@samp{directory to the sources}
2306 export prefix=@samp{directory to where the compiler is installed}
2307 gm2 -I$@{src@} -c -g -fswig $@{src@}/../../../gm2-libs/NumberIO.mod
2308 gm2 -I$@{src@} -c -g -fmakelist $@{src@}/../../../gm2-libs/NumberIO.mod
2309
2310 gm2 -I$@{src@} -c -g -fmakeinit -fshared \
2311 $@{src@}/../../../gm2-libs/NumberIO.mod
2312
2313 swig -c++ -python3 NumberIO.i
2314
2315 libtool --mode=compile g++ -g -c -I$@{src@} NumberIO_m2.cpp \
2316 -o NumberIO_m2.lo
2317
2318 libtool --tag=CC --mode=compile gm2 -g -c \
2319 -I$@{src@}../../../gm2-libs \
2320 $@{src@}/../../../gm2-libs/NumberIO.mod -o NumberIO.lo
2321
2322 libtool --tag=CC --mode=compile g++ -g -c NumberIO_wrap.cxx \
2323 -I/usr/include/python3 -o NumberIO_wrap.lo
2324
2325 libtool --mode=link gcc -g NumberIO_m2.lo NumberIO_wrap.lo \
2326 -L$@{prefix@}/lib64 \
2327 -rpath `pwd` -lgm2 -lstdc++ -lm -o libNumberIO.la
2328
2329 cp .libs/libNumberIO.so _NumberIO.so
2330 @end example
2331
2332 The first four commands, generate the swig interface file
2333 @file{NumberIO.i} and python wrap files @file{NumberIO_wrap.cxx} and
2334 @file{NumberIO.py}. The next three @file{libtool} commnads compile
2335 the C++ and Modula-2 source code into @file{.lo} objects. The last
2336 @file{libtool} command links all the @file{.lo} files into a
2337 @file{.la} file and includes all shared library dependencies.
2338
2339 Now it is possible to run the following Python script
2340 (called @file{testnum.py}):
2341
2342 @example
2343 import NumberIO
2344
2345 print ("1234 x 2 =", NumberIO.NumberIO_StrToInt("1234")*2)
2346 @end example
2347
2348 like this:
2349
2350 @example
2351 $ python3 testnum.py
2352 1234 x 2 = 2468
2353 @end example
2354
2355 @xref{Producing a Python module} for another example which
2356 uses the @code{UNQUALIFIED} keyword to reduce the module name clutter
2357 from the viewport of Python3.
2358
2359 @subsection Limitations of automatic generated of Swig files
2360
2361 This section discusses the limitations of automatically generating
2362 swig files. From the previous example we see that the module
2363 @code{NumberIO} had a swig interface file @file{NumberIO.i}
2364 automatically generated by the compiler. If we consider three of the
2365 procedure definitions in @file{NumberIO.def} we can see the
2366 success and limitations of the automatic interface generation.
2367
2368 @example
2369 PROCEDURE StrToHex (a: ARRAY OF CHAR; VAR x: CARDINAL) ;
2370 PROCEDURE StrToInt (a: ARRAY OF CHAR; VAR x: INTEGER) ;
2371 PROCEDURE ReadInt (VAR x: CARDINAL) ;
2372 @end example
2373
2374 Below are the swig interface prototypes:
2375
2376 @example
2377 extern void NumberIO_StrToHex (char *_m2_address_a,
2378 int _m2_high_a, unsigned int *OUTPUT);
2379 /* parameters: x is known to be an OUTPUT */
2380 extern void NumberIO_StrToInt (char *_m2_address_a,
2381 int _m2_high_a, int *OUTPUT);
2382 /* parameters: x is guessed to be an OUTPUT */
2383 extern void NumberIO_ReadInt (int *x);
2384 /* parameters: x is unknown */
2385 @end example
2386
2387 In the case of @code{StrToHex} it can be seen that the compiler
2388 detects that the last parameter is an output. It explicitly tells
2389 swig this by using the parameter name @code{OUTPUT} and in the
2390 following comment it informs the user that it knows this to be an
2391 output parameter. In the second procedure @code{StrToInt} it marks
2392 the final parameter as an output, but it tells the user that this is
2393 only a guess. Finally in @code{ReadInt} it informs the user that
2394 it does not know whether the parameter, @code{x}, is an output, input
2395 or an inout parameter.
2396
2397 The compiler decides whether to mark a parameter as either:
2398 @code{INPUT}, @code{OUTPUT} or @code{INOUT} if it is read before
2399 written or visa versa in the first basic block. At this point
2400 it will write output that the parameter is known. If it is not
2401 read or written in the first basic block then subsequent basic blocks
2402 are searched and the result is commented as a guess. Finally if
2403 no read or write occurs then the parameter is commented as unknown.
2404 However, clearly it is possible to fool this mechanism. Nevertheless
2405 automatic generation of implementation module into swig interface files
2406 was thought sufficiently useful despite these limitations.
2407
2408 In conclusion it would be wise to check all parameters in any
2409 automatically generated swig interface file. Furthermore you can
2410 force the automatic mechanism to generate correct interface files by
2411 reading or writing to the @code{VAR} parameter in the first basic
2412 block of a procedure.
2413
2414 @node Producing a Python module, Interface to C, Interface for Python, Using
2415 @section How to produce a Python module
2416
2417 This section describes how it is possible to produce a Python module
2418 from Modula-2 code. There are a number of advantages to this
2419 approach, it ensures your code reaches a wider audience, maybe it is
2420 easier to initialize your application in Python.
2421
2422 The example application here is a pedagogical two dimensional gravity
2423 next event simulation. The Python module needs to have a clear API
2424 which should be placed in a single definition module. Furthermore the
2425 API should only use fundamental pervasive data types and strings.
2426 Below the API is contained in the file @file{twoDsim.def}:
2427
2428 @example
2429 DEFINITION MODULE twoDsim ;
2430
2431 EXPORT UNQUALIFIED gravity, box, poly3, poly5, poly6, mass,
2432 fix, circle, pivot, velocity, accel, fps,
2433 replayRate, simulateFor ;
2434 (*
2435 gravity - turn on gravity at: g m^2
2436 *)
2437
2438 PROCEDURE gravity (g: REAL) ;
2439
2440
2441 (*
2442 box - place a box in the world at (x0,y0),(x0+i,y0+j)
2443 *)
2444
2445 PROCEDURE box (x0, y0, i, j: REAL) : CARDINAL ;
2446
2447
2448 (*
2449 poly3 - place a triangle in the world at:
2450 (x0,y0),(x1,y1),(x2,y2)
2451 *)
2452
2453 PROCEDURE poly3 (x0, y0, x1, y1, x2, y2: REAL) : CARDINAL ;
2454
2455
2456 (*
2457 poly5 - place a pentagon in the world at:
2458 (x0,y0),(x1,y1),(x2,y2),(x3,y3),(x4,y4)
2459 *)
2460
2461 PROCEDURE poly5 (x0, y0, x1, y1,
2462 x2, y2, x3, y3, x4, y4: REAL) : CARDINAL ;
2463
2464
2465 (*
2466 poly6 - place a hexagon in the world at:
2467 (x0,y0),(x1,y1),(x2,y2),(x3,y3),(x4,y4),(x5,y5)
2468 *)
2469
2470 PROCEDURE poly6 (x0, y0, x1, y1,
2471 x2, y2, x3, y3,
2472 x4, y4, x5, y5: REAL) : CARDINAL ;
2473
2474
2475 (*
2476 mass - specify the mass of an object and return the, id.
2477 *)
2478
2479 PROCEDURE mass (id: CARDINAL; m: REAL) : CARDINAL ;
2480
2481
2482 (*
2483 fix - fix the object to the world.
2484 *)
2485
2486 PROCEDURE fix (id: CARDINAL) : CARDINAL ;
2487
2488
2489 (*
2490 circle - adds a circle to the world. Center
2491 defined by: x0, y0 radius, r.
2492 *)
2493
2494 PROCEDURE circle (x0, y0, r: REAL) : CARDINAL ;
2495
2496
2497 (*
2498 velocity - give an object, id, a velocity, vx, vy.
2499 *)
2500
2501 PROCEDURE velocity (id: CARDINAL; vx, vy: REAL) : CARDINAL ;
2502
2503
2504 (*
2505 accel - give an object, id, an acceleration, ax, ay.
2506 *)
2507
2508 PROCEDURE accel (id: CARDINAL; ax, ay: REAL) : CARDINAL ;
2509
2510
2511 (*
2512 fps - set frames per second.
2513 *)
2514
2515 PROCEDURE fps (f: REAL) ;
2516
2517
2518 (*
2519 replayRate - set frames per second during replay.
2520 *)
2521
2522 PROCEDURE replayRate (f: REAL) ;
2523
2524
2525 (*
2526 simulateFor - render for, t, seconds.
2527 *)
2528
2529 PROCEDURE simulateFor (t: REAL) ;
2530
2531
2532 END twoDsim.
2533 @end example
2534
2535 The keyword @code{UNQUALIFIED} can be used to ensure that the
2536 compiler will provide externally accessible functions
2537 @code{gravity}, @code{box}, @code{poly3}, @code{poly5}, @code{poly6},
2538 @code{mass}, @code{fix}, @code{circle}, @code{pivot}, @code{velocity},
2539 @code{accel}, @code{fps}, @code{replayRate}, @code{simulateFor}
2540 rather than name mangled alternatives.
2541 Hence in our Python3 application we could write:
2542
2543 @example
2544 #!/usr/bin/env python3
2545
2546 from twoDsim import *
2547
2548 b = box (0.0, 0.0, 1.0, 1.0)
2549 b = fix (b)
2550 c1 = circle (0.7, 0.7, 0.05)
2551 c1 = mass (c1, 0.01)
2552 c2 = circle (0.7, 0.1, 0.05)
2553 c2 = mass (c2, 0.01)
2554 c2 = fix (c2)
2555 gravity (-9.81)
2556 fps (24.0*4.0)
2557 replayRate (24.0)
2558 print ("creating frames")
2559 try:
2560 simulateFor (1.0)
2561 print ("all done")
2562 except:
2563 print ("exception raised")
2564 @end example
2565
2566 which accesses the various functions defined and implemented by the
2567 module @code{twoDsim}. The Modula-2 source code is compiled via:
2568
2569 @example
2570 $ gm2 -g -fiso -c -fswig twoDsim.mod
2571 $ gm2 -g -fiso -c -fmakelist twoDsim.mod
2572 $ gm2 -g -fiso -c -fmakeinit twoDsim.mod
2573 @end example
2574
2575 The first command both compiles the source file creating
2576 @file{twoDsim.o} and produces a swig interface file @file{swig.i}. We
2577 now use @code{swig} and @code{g++} to produce and compile the
2578 interface wrappers:
2579
2580 @example
2581 $ libtool --mode=compile g++ -g -c twoDsim_m2.cpp -o twoDsim_m2.lo
2582 $ swig -c++ -python3 twoDsim.i
2583 $ libtool --mode=compile g++ -c -fPIC twoDsim_wrap.cxx \
2584 -I/usr/include/python3 -o twoDsim_wrap.lo
2585 $ libtool --mode=compile gm2 -g -fPIC -fiso -c deviceGnuPic.mod
2586 $ libtool --mode=compile gm2 -g -fPIC -fiso -c roots.mod
2587 $ libtool --mode=compile gm2 -g -fPIC -fiso -c -fswig \
2588 twoDsim.mod -o twoDsim.lo
2589 @end example
2590
2591 Finally the application is linked into a shared library:
2592
2593 @example
2594 $ libtool --mode=link gcc -g twoDsim_m2.lo twoDsim_wrap.lo \
2595 roots.lo deviceGnuPic.lo \
2596 -L$@{prefix@}/lib64 \
2597 -rpath `pwd` -lgm2 -lstdc++ -lm -o libtwoDsim.la
2598 cp .libs/libtwoDsim.so _twoDsim.so
2599 @end example
2600
2601 The library name must start with @code{_} to comply with the Python3
2602 module naming scheme.
2603
2604 @node Interface to C, Assembly language, Producing a Python module, Using
2605 @section Interfacing GNU Modula-2 to C
2606
2607 The GNU Modula-2 compiler tries to use the C calling convention
2608 wherever possible however some parameters have no C equivalent and
2609 thus a language specific method is used. For example unbounded arrays
2610 are passed as a @code{struct @{void *address, unsigned int high@}} and
2611 the contents of these arrays are copied by callee functions when they
2612 are declared as non @code{VAR} parameters. The @code{VAR} equivalent
2613 unbounded array parameters need no copy, but still use the
2614 @code{struct} representation.
2615
2616 The recommended method of interfacing GNU Modula-2 to C is by telling
2617 the definition module that the implementation is in the C language.
2618 This is achieved by using the tokens @code{DEFINITION MODULE FOR "C"}.
2619 Here is an example @file{libprintf.def}.
2620
2621 @example
2622 DEFINITION MODULE FOR "C" libprintf ;
2623
2624 EXPORT UNQUALIFIED printf ;
2625
2626 PROCEDURE printf (a: ARRAY OF CHAR; ...) : [ INTEGER ] ;
2627
2628 END libprintf.
2629 @end example
2630
2631 the @code{UNQUALIFIED} keyword in the definition module informs
2632 GNU Modula-2 not to prefix the module name to exported references
2633 in the object file.
2634
2635 The @code{printf} declaration states that the first parameter
2636 semantically matches @code{ARRAY OF CHAR} but since the module is for
2637 the C language it will be mapped onto @code{char *}. The token
2638 @code{...} indicates a variable number of arguments (varargs) and all
2639 parameters passed here are mapped onto their C equivalents. Arrays and
2640 constant strings are passed as pointers. Lastly @code{[ INTEGER ]}
2641 states that the caller can ignore the function return result if desired.
2642
2643 The hello world program can be rewritten as:
2644
2645 @example
2646 MODULE hello ;
2647
2648 FROM libprintf IMPORT printf ;
2649
2650 BEGIN
2651 printf ("hello world\n")
2652 END hello.
2653 @end example
2654
2655 and it can be compiled by:
2656
2657 @samp{gm2 -g hello.mod -lc}
2658
2659 In reality the @samp{-lc} is redundant as libc is always included in the
2660 linking process. It is shown here to emphasize that the C library or
2661 object file containing @code{printf} must be present. The search path
2662 for modules can be changed by using @samp{-I}.
2663
2664 If a procedure function is declared using varargs then some parameter
2665 values are converted. The table below summarizes the default conversions
2666 and default types used.
2667
2668 @example
2669 Actual Parameter | Default conversion | Type of actual
2670 | | value passed
2671 ===============================================================
2672 123 | none | long long int
2673 "hello world" | none | const char *
2674 a: ARRAY OF CHAR | ADR (a) | char *
2675 a: ARRAY [0..5] OF CHAR| ADR (a) | char *
2676 3.14 | none | long double
2677 @end example
2678
2679 If you wish to pass @code{int} values then you should explicitly
2680 convert the constants using one of the conversion mechanisms.
2681 For example: @code{INTEGER(10)} or @code{VAL(INTEGER, 10)} or
2682 @code{CAST(INTEGER, 10)}.
2683
2684 @node Assembly language, Alignment, Interface to C, Using
2685 @section Interface to assembly language
2686
2687 The interface for GNU Modula-2 to assembly language is almost
2688 identical to GNU C. The only alterations are that the keywords
2689 @code{asm} and @code{volatile} are in capitals, following the Modula-2
2690 convention.
2691
2692 A simple, but highly non optimal, example is given below. Here we want
2693 to add the two @code{CARDINAL}s @code{foo} and @code{bar} together and
2694 return the result. The target processor is assumed to be executing
2695 the x86_64 instruction set.
2696
2697 @example
2698 PROCEDURE Example (foo, bar: CARDINAL) : CARDINAL ;
2699 VAR
2700 myout: CARDINAL ;
2701 BEGIN
2702 ASM VOLATILE ("movl %1,%%eax; addl %2,%%eax; movl %%eax,%0"
2703 : "=rm" (myout) (* outputs *)
2704 : "rm" (foo), "rm" (bar) (* inputs *)
2705 : "eax") ; (* we trash *)
2706 RETURN( myout )
2707 END Example ;
2708 @end example
2709
2710 For a full description of this interface we refer the reader to the GNU C manual.
2711
2712 @xref{Extended Asm, ,Extensions to the C Language Family,gcc}.
2713
2714 The same example can be written using the newer extensions of naming
2715 the operands rather than using numbered arguments.
2716
2717 @example
2718 PROCEDURE Example (foo, bar: CARDINAL) : CARDINAL ;
2719 VAR
2720 myout: CARDINAL ;
2721 BEGIN
2722 ASM VOLATILE (
2723 "movl %[left],%%eax; addl %[right],%%eax; movl %%eax,%[output]"
2724 : [output] "=rm" (myout) (* outputs *)
2725 : [left] "rm" (foo), [right] "rm" (bar) (* inputs *)
2726 : "eax") ; (* we trash *)
2727 RETURN( myout )
2728 END Example ;
2729 @end example
2730
2731 Both examples generate exactly the same code. It is worth noting that
2732 the specifier ``rm'' indicates that the operand can be either a
2733 register or memory. Of course you must choose an instruction which
2734 can take either, but this allows the compiler to make more
2735 efficient choices depending upon the optimization level.
2736
2737 @node Alignment, Packed, Assembly language, Using
2738 @section Data type alignment
2739
2740 GNU Modula-2 allows you to specify alignment for types and variables.
2741 The syntax for alignment is to use the ISO pragma directives @code{<*}
2742 @code{bytealignment (} expression @code{)} and @code{*>}. These directives
2743 can be used after type and variable declarations.
2744
2745 The ebnf of the alignment production is:
2746
2747 @example
2748 Alignment := [ ByteAlignment ] =:
2749 ByteAlignment := '<*' AttributeExpression '*>' =:
2750 AlignmentExpression := "(" ConstExpression ")" =:
2751 @end example
2752
2753 The @code{Alignment} ebnf statement may be used during construction of
2754 types, records, record fields, arrays, pointers and variables. Below
2755 is an example of aligning a type so that the variable @code{bar} is
2756 aligned on a 1024 address.
2757
2758 @example
2759 MODULE align ;
2760
2761 TYPE
2762 foo = INTEGER <* bytealignment(1024) *> ;
2763
2764 VAR
2765 z : INTEGER ;
2766 bar: foo ;
2767 BEGIN
2768 END align.
2769 @end example
2770
2771 The next example aligns a variable on a 1024 byte boundary.
2772
2773 @example
2774 MODULE align2 ;
2775
2776 VAR
2777 x : CHAR ;
2778 z : ARRAY [0..255] OF INTEGER <* bytealignment(1024) *> ;
2779 BEGIN
2780 END align2.
2781 @end example
2782
2783 Here the example aligns a pointer on a 1024 byte boundary.
2784
2785 @example
2786 MODULE align4 ;
2787
2788 FROM SYSTEM IMPORT ADR ;
2789 FROM libc IMPORT exit ;
2790
2791 VAR
2792 x : CHAR ;
2793 z : POINTER TO INTEGER <* bytealignment(1024) *> ;
2794 BEGIN
2795 IF ADR(z) MOD 1024=0
2796 THEN
2797 exit(0)
2798 ELSE
2799 exit(1)
2800 END
2801 END align4.
2802 @end example
2803
2804 In example @code{align5} record field @code{y} is aligned on a 1024
2805 byte boundary.
2806
2807 @example
2808 MODULE align5 ;
2809
2810 FROM SYSTEM IMPORT ADR ;
2811 FROM libc IMPORT exit ;
2812
2813 TYPE
2814 rec = RECORD
2815 x: CHAR ;
2816 y: CHAR <* bytealignment(1024) *> ;
2817 END ;
2818 VAR
2819 r: rec ;
2820 BEGIN
2821 IF ADR(r.y) MOD 1024=0
2822 THEN
2823 exit(0)
2824 ELSE
2825 exit(1)
2826 END
2827 END align5.
2828 @end example
2829
2830 In the example below module @code{align6} declares @code{foo} as an
2831 array of 256 @code{INTEGER}s. The array @code{foo} is aligned on a
2832 1024 byte boundary.
2833
2834 @example
2835 MODULE align6 ;
2836
2837 FROM SYSTEM IMPORT ADR ;
2838 FROM libc IMPORT exit ;
2839
2840 TYPE
2841 foo = ARRAY [0..255] OF INTEGER <* bytealignment(1024) *> ;
2842
2843 VAR
2844 x : CHAR ;
2845 z : foo ;
2846 BEGIN
2847 IF ADR(z) MOD 1024=0
2848 THEN
2849 exit(0)
2850 ELSE
2851 exit(1)
2852 END
2853 END align6.
2854 @end example
2855
2856 @node Packed, Built-ins, Alignment, Using
2857 @section Packing data types
2858
2859 The pragma @code{<* bytealignment(0) *>} can be used to specify that
2860 the fields within a @code{RECORD} are to be packed. Currently this
2861 only applies to fields which are declared as subranges, ordinal types
2862 and enumerated types. Here is an example of how two subranges might
2863 be packed into a byte.
2864
2865 @example
2866 TYPE
2867 bits3c = [0..7] ;
2868 bits3i = [-4..3] ;
2869
2870 byte = RECORD
2871 <* bytealignment(0) *>
2872 x: bits3c ;
2873 <* bitsunused(2) *>
2874 y: bits3i ;
2875 END ;
2876 @end example
2877
2878 Notice that the user has specified that in between fields @code{x} and
2879 @code{y} there are two bits unused.
2880
2881 Now the user wishes to create a record with byte numbers zero and one
2882 occupied and then an @code{INTEGER32} field which is four byte
2883 aligned. In this case byte numbers two and three will be unused. The
2884 pragma @code{bytealignment} can be issued at the start of the record
2885 indicating the default alignment for the whole record and this can be
2886 overridden by individual fields if necessary.
2887
2888 @example
2889 rec = RECORD
2890 <* bytealignment (1) *> ;
2891 a, b: byte ;
2892 x: INTEGER32 <* bytealignment(4) *> ;
2893 END ;
2894 @end example
2895
2896 In the following example the user has specified that a record has two
2897 fields @code{p} and @code{q} but that there are three bytes unused between
2898 these fields.
2899
2900 @example
2901 header = RECORD
2902 <* bytealignment(1) *>
2903 p: byte ;
2904 <* bytesunused(3) *>
2905 q: byte ;
2906 END ;
2907 @end example
2908
2909 The pragma @code{<* bytesunused(x) *>} can only be used if the current
2910 field is on a byte boundary. There is also a @code{SYSTEM} pseudo
2911 procedure function @code{TBITSIZE(T)} which returns the minimum number of
2912 bits necessary to represent type @code{T}.
2913
2914 Another example of packing record bit fields is given below:
2915
2916 @example
2917 MODULE align21 ;
2918
2919 FROM libc IMPORT exit ;
2920
2921 TYPE
2922 colour = (red, blue, green, purple, white, black) ;
2923
2924 soc = PACKEDSET OF colour ;
2925
2926 rec = RECORD
2927 <* bytealignment(0) *>
2928 x: soc ;
2929 y: [-1..1] ;
2930 END ;
2931
2932 VAR
2933 r: rec ;
2934 v: CARDINAL ;
2935 BEGIN
2936 v := SIZE(r) ;
2937 IF SIZE(r)#1
2938 THEN
2939 exit(1)
2940 END ;
2941 r.x := soc@{blue@} ;
2942 IF r.x#soc@{blue@}
2943 THEN
2944 exit(2)
2945 END
2946 END align21.
2947 @end example
2948
2949 Here we see that the total size of this record is one byte and consists
2950 of a six bit set type followed by a 2 bit integer subrange.
2951
2952 @node Built-ins, The PIM system module, Packed, Using
2953 @section Accessing GNU Modula-2 Built-ins
2954
2955 This section describes the built-in constants and functions defined in
2956 GNU Modula-2. The following compiler constants can be accessed using
2957 the @code{__ATTRIBUTE__} @code{__BUILTIN__} keywords. These are not
2958 part of the Modula-2 language and they may differ depending upon the
2959 target architecture but they provide a method whereby common
2960 libraries can interface to a different underlying architecture.
2961
2962 The built-in constants are: @code{BITS_PER_UNIT}, @code{BITS_PER_WORD},
2963 @code{BITS_PER_CHAR} and @code{UNITS_PER_WORD}. They are integrated into
2964 GNU Modula-2 by an extension to the @code{ConstFactor} rule:
2965
2966 @example
2967 ConstFactor := ConstQualidentOrSet | Number | ConstString |
2968 "(" ConstExpression ")" | "NOT" ConstFactor |
2969 ConstAttribute =:
2970
2971 ConstAttribute := "__ATTRIBUTE__" "__BUILTIN__" "(" "(" Ident ")" ")" =:
2972 @end example
2973
2974 Here is an example taken from the ISO library @code{SYSTEM.def}:
2975
2976 @example
2977 CONST
2978 BITSPERLOC = __ATTRIBUTE__ __BUILTIN__ ((BITS_PER_UNIT)) ;
2979 LOCSPERWORD = __ATTRIBUTE__ __BUILTIN__ ((UNITS_PER_WORD)) ;
2980 @end example
2981
2982 Built-in functions are transparent to the end user. All built-in
2983 functions are declared in @code{DEFINITION MODULE}s and are imported
2984 as and when required. Built-in functions are declared in definition
2985 modules by using the @code{__BUILTIN__} keyword. Here is a section of
2986 the ISO library @code{LongMath.def} which demonstrates this feature.
2987
2988 @example
2989 PROCEDURE __BUILTIN__ sqrt (x: LONGREAL): LONGREAL;
2990 (* Returns the square root of x *)
2991 @end example
2992
2993 This indicates that the function @code{sqrt} will be implemented using
2994 the gcc built-in maths library. If gcc cannot utilize the built-in
2995 function (for example if the programmer requested the address of
2996 @code{sqrt}) then code is generated to call the alternative function
2997 implemented in the @code{IMPLEMENTATION} @code{MODULE}.
2998
2999 Sometimes a function exported from the @code{DEFINITION} @code{MODULE}
3000 will have a different name from the built-in function within gcc. In
3001 such cases the mapping between the GNU Modula-2 function name and the
3002 gcc name is expressed using the keywords @code{__ATTRIBUTE__}
3003 @code{__BUILTIN__} @code{((Ident))}. For example the function
3004 @code{sqrt} in @code{LongMath.def} maps onto the gcc built-in function
3005 @code{sqrtl} and this is expressed as:
3006
3007 @example
3008 PROCEDURE __ATTRIBUTE__ __BUILTIN__ ((sqrtl)) sqrt
3009 (x: LONGREAL) : LONGREAL;
3010 (* Returns the positive square root of x *)
3011 @end example
3012
3013 The following module @code{Builtins.def} enumerates the list of
3014 built-in functions which can be accessed in GNU Modula-2. It also
3015 serves to define the parameter and return value for each function:
3016
3017 @include m2/Builtins.texi
3018
3019 Although this module exists and will result in the generation of
3020 in-line code if optimization flags are passed to GNU Modula-2, users
3021 are advised to utilize the same functions from more generic libraries.
3022 The built-in mechanism will be applied to these generic
3023 libraries where appropriate. Note for the mathematical routines to
3024 be in-lined you need to specify the @samp{-ffast-math -O} options.
3025
3026 @node The PIM system module, The ISO system module, Built-ins, Using
3027 @section The PIM system module
3028
3029 @include m2/SYSTEM-pim.texi
3030
3031 The different dialects of Modula-2 PIM-[234] and ISO Modula-2 declare
3032 the function @code{SIZE} in different places. PIM-[34] and ISO
3033 Modula-2 declare @code{SIZE} as a pervasive function (declared in the
3034 base module). PIM-2 defined @code{SIZE} in the @code{SYSTEM} module
3035 (as shown above).
3036
3037 GNU Modula-2 allows users to specify the dialect of Modula-2 by using
3038 the @code{-fiso} and @code{-fpim2} command line switches.
3039
3040 The data types @code{CSIZE_T}, @code{CSSIZE_T} and @code{COFF_T} are
3041 also exported from the @code{SYSTEM} module. The type @code{CSIZE_T}
3042 is unsigned and is mapped onto the target C data type @code{size_t}
3043 whereas the type @code{CSSIZE_T} is mapped onto the signed C data type
3044 @code{ssize_t}. The default size for the signed type @code{COFF_T} is
3045 the same as @code{CSSIZE_T} and this can be overridden by the
3046 @code{-fm2-file-offset-bits=} command line option.
3047
3048 It is anticipated that these should only be used to provide cross
3049 platform definition modules for C libraries.
3050
3051 There are also a variety of fixed sized @code{INTEGER} and
3052 @code{CARDINAL} types. The variety of the fixed sized types will
3053 depend upon the target architecture.
3054
3055 @node The ISO system module, Release map, The PIM system module, Using
3056 @section The ISO system module
3057
3058 @include m2/SYSTEM-iso.texi
3059
3060 The data types @code{CSIZE_T}, @code{CSSIZE_T} and @code{COFF_T} are
3061 also exported from the @code{SYSTEM} module. The type @code{CSIZE_T}
3062 is unsigned and is mapped onto the target C data type @code{size_t}
3063 whereas the type @code{CSSIZE_T} is mapped onto the signed C data type
3064 @code{ssize_t}. The default size for the signed type @code{COFF_T} is
3065 the same as @code{CSSIZE_T} and this can be overridden by the
3066 @code{-fm2-file-offset-bits=} command line option.
3067
3068 It is anticipated that these should only be used to provide cross
3069 platform definition modules for C libraries.
3070
3071 There are also a variety of fixed sized @code{INTEGER} and
3072 @code{CARDINAL} types. The variety of the fixed sized types will
3073 depend upon the target architecture.
3074
3075 @node Release map, Documentation, The ISO system module, Using
3076 @section Release map
3077
3078 GNU Modula-2 is now part of GCC and therefore will adopt the GCC
3079 release schedule. It is intended that GNU Modula-2 implement more of
3080 the GCC builtins (vararg access) and GCC features.
3081
3082 There is an intention to implement the ISO generics and the M2R10
3083 dialect of Modula-2. It will also implement all language changes. If
3084 you wish to see something different please email
3085 @email{gm2@@nongnu.org} with your ideas.
3086
3087 @node Documentation, Regression tests, Release map, Using
3088 @section Documentation
3089
3090 The GNU Modula-2 documentation is available online at
3091 @url{https://gcc.gnu.org/onlinedocs/}
3092 in the PDF, info, and HTML file formats.
3093
3094 @node Regression tests, Limitations, Documentation, Using
3095 @section Regression tests for gm2 in the repository
3096
3097 The regression testsuite can be run from the gcc build directory:
3098
3099 @example
3100 $ cd build-gcc
3101 $ make check -j 24
3102 @end example
3103
3104 which runs the complete testsuite for all compilers using 24 parallel
3105 invocations of the compiler. Individual language testsuites can be
3106 run by specifying the language, for example the Modula-2 testsuite can
3107 be run using:
3108
3109 @example
3110 $ cd build-gcc
3111 $ make check-m2 -j 24
3112 @end example
3113
3114 Finally the results of the testsuite can be emailed to the
3115 @url{https://gcc.gnu.org/lists.html, gcc-testresults} list using the
3116 @file{test_summary} script found in the gcc source tree:
3117
3118 @example
3119 $ @samp{directory to the sources}/contrib/test_summary
3120 @end example
3121
3122 @node Limitations, Objectives, Regression tests, Using
3123 @section Limitations
3124
3125 The Logitech compatibility library is incomplete. The primary
3126 modules for this platform exist, though for a comprehensive list
3127 of completed modules please check the documentation.
3128
3129 @node Objectives, FAQ, Limitations, Using
3130 @section Objectives
3131
3132 @itemize @bullet
3133
3134 @item
3135 The intention of GNU Modula-2 is to provide a production Modula-2
3136 front end to GCC.
3137
3138 @item
3139 It should support all Niklaus Wirth PIM Dialects [234] and also ISO
3140 Modula-2 including a re-implementation of all the ISO modules.
3141
3142 @item
3143 There should be an easy interface to C.
3144
3145 @item
3146 Exploit the features of GCC.
3147
3148 @item
3149 Listen to the requests of the users.
3150 @end itemize
3151
3152 @node FAQ, Community, Objectives, Using
3153 @section FAQ
3154
3155 @subsection Why use the C++ exception mechanism in GCC, rather than a bespoke Modula-2 mechanism?
3156
3157 The C++ mechanism is tried and tested, it also provides GNU Modula-2
3158 with the ability to link with C++ modules and via swig it can raise
3159 Python exceptions.
3160
3161 @node Community, Other languages, FAQ, Using
3162 @section Community
3163
3164 You can subscribe to the GNU Modula-2 mailing by sending an
3165 email to:
3166 @email{gm2-subscribe@@nongnu.org}
3167 or by
3168 @url{https://lists.nongnu.org/mailman/listinfo/gm2}.
3169 The mailing list contents can be viewed
3170 @url{https://lists.gnu.org/archive/html/gm2/}.
3171
3172 @node Other languages, , Community, Using
3173 @section Other languages for GCC
3174
3175 These exist and can be found on the frontends web page on the
3176 @uref{https://gcc.gnu.org/frontends.html, GCC web site}.
3177
3178 @node License, Copying, Using, Top
3179 @section License of GNU Modula-2
3180
3181 GNU Modula-2 is free software, the compiler is held under the GPL v3
3182 @uref{http://www.gnu.org/licenses/gpl-3.0.txt},
3183 its libraries (pim, iso and Logitech compatible) are under the
3184 GPL v3 with the GCC run time library exception clause.
3185
3186 Under Section 7 of GPL version 3, you are granted additional
3187 permissions described in the GCC Runtime Library Exception, version
3188 3.1, as published by the Free Software Foundation.
3189
3190 You should have received a copy of the GNU General Public License and
3191 a copy of the GCC Runtime Library Exception along with this program;
3192 see the files COPYING3 and COPYING.RUNTIME respectively. If not, see
3193 <http://www.gnu.org/licenses/>.
3194
3195 More information on how these licenses work is available
3196 @uref{http://www.gnu.org/licenses/licenses.html} on the GNU web site.
3197
3198 @node Copying, Contributing, License, Top
3199 @include gpl_v3_without_node.texi
3200
3201 @node Contributing, EBNF, Copying, Top
3202 @section Contributing to GNU Modula-2
3203
3204 Please do and please read the GNU Emacs info under
3205
3206 @example
3207 * Standards: (standards). GNU coding standards.
3208 * Intellectual Property:: Keeping Free Software Free
3209 * Reading Non-Free Code:: Referring to Proprietary Programs
3210 * Contributions:: Accepting Contributions
3211 @end example
3212
3213 You might consider joining the GM2 Mailing list before you start
3214 coding. The mailing list may be subscribed via a web interface
3215 @uref{https://lists.nongnu.org/mailman/listinfo/gm2} or via email
3216 @email{gm2-subscribe@@nongnu.org}.
3217
3218 Many thanks and enjoy your coding!
3219
3220 @c @node Internals, , ,
3221
3222 @c This section is still being written.
3223 @c @include gm2-internals.texi
3224
3225 @node EBNF, Libraries, Contributing, Top
3226 @chapter EBNF of GNU Modula-2
3227
3228 This chapter contains the EBNF of GNU Modula-2. This grammar currently
3229 supports both PIM and ISO dialects. The rules here are automatically
3230 extracted from the crammer files in GNU Modula-2 and serve to document
3231 the syntax of the extensions described earlier and how they fit in
3232 with the base language.
3233
3234 Note that the first six productions are built into the lexical analysis
3235 phase.
3236
3237 @include m2/gm2-ebnf.texi
3238
3239 @node Libraries, Indices, EBNF, Top
3240 @chapter PIM and ISO library definitions
3241
3242 This chapter contains M2F, PIM and ISO libraries.
3243
3244 @include m2/gm2-libs.texi
3245
3246 @node Indices, , Libraries, Top
3247 @section Indices
3248
3249 @ifhtml
3250 @menu
3251 * Contents:: Section and subsections.
3252 * Functions:: Function, constants, types, ebnf indices.
3253 @end menu
3254
3255 @node Contents, , ,
3256 @section Section and subsections
3257 @printindex cp
3258
3259 @node Functions, , ,
3260 @section Function, constants, types, ebnf indices.
3261 @end ifhtml
3262
3263 @printindex fn
3264
3265 @summarycontents
3266 @contents
3267 @bye