From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mail-lf1-x12b.google.com (mail-lf1-x12b.google.com [IPv6:2a00:1450:4864:20::12b]) by sourceware.org (Postfix) with ESMTPS id 8045F388BA7C for ; Sun, 11 Dec 2022 08:44:13 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org 8045F388BA7C Authentication-Results: sourceware.org; dmarc=pass (p=none dis=none) header.from=gmail.com Authentication-Results: sourceware.org; spf=pass smtp.mailfrom=gmail.com Received: by mail-lf1-x12b.google.com with SMTP id bp15so13658871lfb.13 for ; Sun, 11 Dec 2022 00:44:13 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=cc:to:subject:message-id:date:from:in-reply-to:references :mime-version:from:to:cc:subject:date:message-id:reply-to; bh=UUIo6ADCIo2ZMgmMr/91q1DObOBLjXyMk5NrmA/jj70=; b=gi8Gn4LGzIbtfmR3A22v0XCTW5xuhp6/vi6E+aC2996PRdiF+MXCLgdjH2gE3f2t+E k+B7IR2efX62GqTZEbtnFT5aNcZJEW1ljl/ZNeDroeDMoTOqt1DYUPJ5YjtMv++0hLT2 kS91Ih0AVWhH46Ua35HYlH+icdd9EjJdRs4gwUurXzZRXIXI8+EBK0XtXmeciRbo3rbD Vhof7MQ+2kbcBLmZn4itT2BEorTXZvusaelmnYq2imRFjcsu02e71gzrmZIogFoGZelC wKPmnjoLAheZ8XcYE0CIH1hjK8IemkZCPnbvhyrkGfTFUnpTFDtLj0fyUg50GRoUrKc5 cZ9w== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=cc:to:subject:message-id:date:from:in-reply-to:references :mime-version:x-gm-message-state:from:to:cc:subject:date:message-id :reply-to; bh=UUIo6ADCIo2ZMgmMr/91q1DObOBLjXyMk5NrmA/jj70=; b=PneqScqCasKh9/7P6ZVAGP+LAfAftRP0AHOguUtjssLpI6PCiBUua5T59+ivyf2uQ6 pfBdyJcN0mx4ZV5zs81UjyLYHnooXUd7F9cssYg9IUbiTkAl7XkVMxhFiRHjKyKgo+I5 Ggw0k5/sKs8h6Ve9XM7gzIpxqfPHRxy8FSL6YvhrYzYkmOGw6ezyzcuW1O9ymqHEH1Xb PyA0BodElPkULEqDW53jas5aJMkZBhqKSjYsLIA1i4OJvl8fZFiIVCxf1IGyiI2KKHe2 1zAZrWiLzna8qsLM8EPMDPxyHQ5LrUzhN9AemTerdAWJ4+fZSuIWx1CN6p2C4R8ihask ZrLA== X-Gm-Message-State: ANoB5pn2jFQfQH5HtLGkEYZ2VuuoXM9FRKosiXOpXTU7pETuSzgsv9ir oLcHsg7L8qDnuTT2or+o+gNfE1BvSfRajMXgXdU= X-Google-Smtp-Source: AA0mqf4iuD/f0zNxZZc5hflRWjjn/n3w8WMdyEMXmRA19MlGZY8NC2W5+Mjsuj2Ind0t3OaiTVxHI+QvxZTXv+tttF4= X-Received: by 2002:ac2:4c42:0:b0:4a5:bf09:a700 with SMTP id o2-20020ac24c42000000b004a5bf09a700mr24975916lfk.656.1670748249645; Sun, 11 Dec 2022 00:44:09 -0800 (PST) MIME-Version: 1.0 References: <87pmcrpkfv.fsf@debian> In-Reply-To: <87pmcrpkfv.fsf@debian> From: Richard Biener Date: Sun, 11 Dec 2022 09:43:55 +0100 Message-ID: Subject: Re: [PATCH v5 1/19] modula2 front end: changes outside gcc/m2, libgm2 and gcc/testsuite. Addendum. To: Gaius Mulley Cc: gcc-patches@gcc.gnu.org Content-Type: text/plain; charset="UTF-8" X-Spam-Status: No, score=-1.1 required=5.0 tests=BAYES_00,DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,DKIM_VALID_EF,FREEMAIL_FROM,KAM_SHORT,RCVD_IN_DNSWL_NONE,SPF_HELO_NONE,SPF_PASS,TXREP autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on server2.sourceware.org List-Id: On Sat, Dec 10, 2022 at 12:29 PM Gaius Mulley via Gcc-patches wrote: > > > This patch contains a replacement doc/gm2.texi which uses American > spelling, all references to gm2 outside the gcc tree purged and the > News/Obtaining sections have been removed. > > Also included at the end is the lang.opt file for reference. LGTM. > > diff -ruw /dev/null gcc-git-devel-modula2/gcc/doc/gm2.texi > --- /dev/null 2022-08-24 16:22:16.888000070 +0100 > +++ gcc-git-devel-modula2/gcc/doc/gm2.texi 2022-12-10 10:58:06.177440039 +0000 > @@ -0,0 +1,2843 @@ > +\input texinfo > +@c -*-texinfo-*- > +@c Copyright (C) 2001-2022 Free Software Foundation, Inc. > +@c This is part of the GM2 manual. > + > +@c User level documentation for GNU Modula-2 > +@c > +@c header > + > +@setfilename gm2.info > +@settitle The GNU Modula-2 Compiler > + > +@set version-python 3.5 > + > +@include gcc-common.texi > + > +@c Copyright years for this manual. > +@set copyrights-gm2 1999-2022 > + > +@copying > +@c man begin COPYRIGHT > +Copyright @copyright{} @value{copyrights-gm2} Free Software Foundation, Inc. > + > +Permission is granted to copy, distribute and/or modify this document > +under the terms of the GNU Free Documentation License, Version 1.3 or > +any later version published by the Free Software Foundation; with no > +Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. > +A copy of the license is included in the > +@c man end > +section entitled ``GNU Free Documentation License''. > +@ignore > +@c man begin COPYRIGHT > +man page gfdl(7). > +@c man end > +@end ignore > +@end copying > + > +@ifinfo > +@format > +@dircategory Software development > +@direntry > +* gm2: (gm2). A GCC-based compiler for the Modula-2 language > +@end direntry > +@end format > + > +@insertcopying > +@end ifinfo > + > +@titlepage > +@title The GNU Modula-2 Compiler > +@versionsubtitle > +@author Gaius Mulley > + > +@page > +@vskip 0pt plus 1filll > +Published by the Free Software Foundation @* > +51 Franklin Street, Fifth Floor@* > +Boston, MA 02110-1301, USA@* > +@sp 1 > +@insertcopying > +@end titlepage > +@contents > +@page > + > +@c `Top' Node and Master Menu > + > +@node Top, Overview, (dir), (dir) > +@top Introduction > + > +@menu > +* Overview:: What is GNU Modula-2. > +* Using:: Using GNU Modula-2. > +* Licence:: Licence of GNU Modula-2 > +* Copying:: GNU Public Licence V3. > +* Contributing:: Contributing to GNU Modula-2 > +* Internals:: GNU Modula-2 internals. > +* EBNF:: EBNF of GNU Modula-2 > +* Libraries:: PIM and ISO library definitions. > +* Indices:: Document and function indices. > +@end menu > + > +@node Overview, Using, Top, Top > +@chapter Overview of GNU Modula-2 > + > +@menu > +* What is GNU Modula-2:: Brief description of GNU Modula-2. > +* Why use GNU Modula-2:: Advantages of GNU Modula-2. > +* Development:: How to get source code using git. > +* Features:: GNU Modula-2 Features > +@end menu > + > +@node What is GNU Modula-2, Why use GNU Modula-2, , Using > +@section What is GNU Modula-2 > + > +GNU Modula-2 is a @uref{http://gcc.gnu.org/frontends.html, front end} > +for the GNU Compiler Collection (@uref{http://gcc.gnu.org/, GCC}). > +The GNU Modula-2 compiler is compliant with the PIM2, PIM3, PIM4 and > +ISO dialects. Also implemented are a complete set of free ISO > +libraries and PIM libraries. > + > +@footnote{The four Modula-2 dialects supported are defined in the following > +references: > + > +PIM2: 'Programming in Modula-2', 2nd Edition, Springer Verlag, 1982, > +1983 by Niklaus Wirth (PIM2). > + > +PIM3: 'Programming in Modula-2', 3rd Corrected Edition, Springer Verlag, > +1985 (PIM3). > + > +PIM4: 'Programming in Modula-2', 4th Edition, Springer Verlag, 1988 > +(@uref{http://freepages.modula2.org/report4/modula-2.html, PIM4}). > + > +ISO: the ISO Modula-2 language as defined in 'ISO/IEC Information > +technology - programming languages - part 1: Modula-2 Language, > +ISO/IEC 10514-1 (1996)' > +} > + > +@node Why use GNU Modula-2, Release map, What is GNU Modula-2, Using > +@section Why use GNU Modula-2 > + > +There are a number of advantages of using GNU Modula-2 rather than > +translate an existing project into another language. > + > +The first advantage is of maintainability of the original sources > +and the ability to debug the original project source code using a > +combination of gm2 and gdb. > + > +The second advantage is that gcc runs on many processors and > +platforms. gm2 builds and runs on powerpc64le, amd64, i386, aarch64 > +to name but a few processors. > + > +gm2 can produce swig interface headers to allow access from Python and > +other scripting languages. It can also be used with C/C++ and > +generate shared libraries. > + > +The compiler provides semantic analysis and runtime checking (full ISO > +Modula-2 checking is implemented) and there is a plugin which can, > +under certain conditions, detect runtime errors at compile time. > + > +The compiler supports PIM2, PIM3, PIM4 and ISO dialects of Modula-2, > +work is underway to implement M2R10. Many of the GCC builtins are > +available and access to assembly programming is achieved using the > +same syntax as that used by GCC. > + > +The gm2 driver allows third party libraries to be installed alongside > +gm2 libraries. For example if the user specifies library @code{foo} > +using @code{-flibs=foo} the driver will check the standard GCC install > +directory for a subdirectory. > + > +@node Release map, Development, Why use GNU Modula-2, Using > +@section Release map > + > +GNU Modula-2 is now part of GCC and therefore will adopt the GCC > +release schedule. It is intended that GNU Modula-2 implement more of > +the GCC builtins (vararg access) and GCC features. > + > +There is an intention to implement the ISO generics and the M2R10 > +dialect of Modula-2. It will also implement all language changes. If > +you wish to see something different please email > +@email{gm2@@nongnu.org} with your ideas. > + > +@node Development, Features, Release map, Using > +@section How to get source code using git > + > +GNU Modula-2 is now in the @url{https://gcc.gnu.org/git.html, GCC git > +tree}. > + > +@node Features, Documentation, Development, Using > +@section GNU Modula-2 Features > + > +@itemize @bullet > + > +@item > +the compiler currently complies with Programming in Modula-2 Edition > +2, 3, 4 and ISO Modula-2. Users can switch on specific language > +features by using: @samp{-fpim}, @samp{-fpim2}, @samp{-fpim3}, > +@samp{-fpim4} or @samp{-fiso}. > + > +@item > +the option @samp{-fswig} will automatically create a swig interface > +file which corresponds to the definition module of the file being > +compiled. > + > +@item > +exception handling is compatible with C++ and swig. Modula-2 code can > +be used with C or C++ code. > + > +@item > +Python can call GNU Modula-2 modules via swig. > + > +@item > +shared libraries can be built. > + > +@item > +fixed sized types are now available from @samp{SYSTEM}. > + > +@item > +support for dynamic @code{ARRAY}s has been added into @samp{gdb}. > + > +@item > +variables can be declared at addresses. > + > +@item > +much better dwarf-2 debugging support and when used with > +@samp{gdb} the programmer can display @code{RECORD}s, > +@code{ARRAY}s, @code{SET}s, subranges and constant char literals > +in Modula-2 syntax. > + > +@item > +supports sets of any ordinal size (memory permitting). > + > +@item > +easy interface to C, and varargs can be passed to C routines. > + > +@item > +many Logitech libraries have been implemented and can be accessed via: > +@samp{-flibs=m2log,m2pim,m2iso}. > + > +@item > +coroutines have been implemented in the PIM style and these are > +accessible from SYSTEM. A number of supporting libraries (executive > +and file descriptor mapping to interrupt vector libraries are > +available through the @samp{-flibs=m2iso,m2pim} switch). > + > +@item > +can be built as a cross compiler (for embedded microprocessors > +such as the AVR and the ARM). > + > +@end itemize > + > +@node Documentation, Regression tests, Features, Using > +@section Documentation > + > +The GNU Modula-2 documentation is available on line > +@url{https://www.nongnu.org/gm2/homepage.html,at the gm2 homepage} > +or in the pdf, info, html file format. > + > +@node Regression tests, Limitations, Documentation, Using > +@section Regression tests for gm2 in the repository > + > +The regression testsuite can be run from the gcc build directory: > + > +@example > +$ cd build-gcc > +$ make check -j 24 > +@end example > + > +which runs the complete testsuite for all compilers using 24 parallel > +invocations of the compiler. Individual language testsuites can be > +run by specifying the language, for example the Modula-2 testsuite can > +be run using: > + > +@example > +$ cd build-gcc > +$ make check-m2 -j 24 > +@end example > + > +Finally the results of the testsuite can be emailed to the > +@url{https://gcc.gnu.org/lists.html, gcc-testresults} list using the > +script: > + > +@example > +$ @file{gccsrcdir/contrib/test_summary} > +@end example > + > +@node Limitations, Objectives, Regression tests, Using > +@section Limitations > + > +Logitech compatibility library is incomplete. The principle modules > +for this platform exist however for a comprehensive list of completed > +modules please check the documentation > +@url{gm2.html}. > + > +@node Objectives, FAQ, , Using > +@section Objectives > + > +@itemize @bullet > + > +@item > +The intention of GNU Modula-2 is to provide a production Modula-2 > +front end to GCC. > + > +@item > +It should support all Niklaus Wirth PIM Dialects [234] and also ISO > +Modula-2 including a reimplementation of all the ISO modules. > + > +@item > +There should be an easy interface to C. > + > +@item > +Exploit the features of GCC. > + > +@item > +Listen to the requests of the users. > +@end itemize > + > +@node FAQ, Community, Objectives, Using > +@section FAQ > + > +@subsection Why use the C++ exception mechanism in GCC, rather than a bespoke Modula-2 mechanism? > + > +The C++ mechanism is tried and tested, it also provides GNU Modula-2 > +with the ability to link with C++ modules and via swig it can raise > +Python exceptions. > + > +@node Community, Other languages, FAQ, Using > +@section Community > + > +You can subscribe to the GNU Modula-2 mailing by sending an > +email to: > +@email{gm2-subscribe@@nongnu.org} > +or by > +@url{http://lists.nongnu.org/mailman/listinfo/gm2}. > +The mailing list contents can be viewed > +@url{http://lists.gnu.org/archive/html/gm2}. > + > +@node Other languages, , Community, Using > +@section Other languages for GCC > + > +These exist and can be found on the frontends web page on the > +@uref{http://gcc.gnu.org/frontends.html, gcc web site}. > + > +@node Using, , Community, Top > +@chapter Using GNU Modula-2 > + > +@menu > +* Example usage:: Example compile and link. > +* Compiler options:: GNU Modula-2 compiler options. > +* Linking:: Linking options in more detail. > +* Elementary data types:: Data types supported by GNU Modula-2. > +* Standard procedures:: Permanently accessible base procedures. > +* Dialect:: GNU Modula-2 supported dialects. > +* Exceptions:: Exception implementation > +* Semantic checking:: How to detect runtime problems at compile time. > +* Extensions:: GNU Modula-2 language extensions. > +* Type compatibility:: Data type compatibility. > +* Unbounded by reference::Explanation of a language optimization. > +* Building a shared library:: How to build a shared library. > +* Interface for Python:: How to produce swig interface files. > +* Producing a Python module:: How to produce a Python module. > +* Interface to C:: Interfacing GNU Modula-2 to C. > +* Assembly language:: Interface to assembly language. > +* Alignment:: Data type alignment. > +* Packed:: Packing data types. > +* Built-ins:: Accessing GNU Modula-2 Built-ins. > +* The PIM system module:: SYSTEM data types and procedures. > +* The ISO system module:: SYSTEM data types, procedures and run time. > +* Other languages:: Other languages for GCC. > +* What is GNU Modula-2:: Brief description of GNU Modula-2. > +* Why use GNU Modula-2:: Advantages of GNU Modula-2. > +@ifnothtml > +@c omit these nodes if generating gm2 webpage as these are hand written. > +* Release map:: Release map. > +* Development:: Development. > +* Features:: Features of the implementation. > +* Documentation:: Placeholder for how to access the documentation online. > +* Regression tests:: How to run the testsuite. > +* Limitations:: Current limitations. > +* Objectives:: Objectives of the implementation. > +* FAQ:: Frequently asked questions. > +* Community:: How to join the community. > +@end ifnothtml > +@end menu > + > +This document contains the user and design issues relevant to the > +Modula-2 front end to gcc. > + > +@node Example usage, Compiler options, Using, Using > +@section Example compile and link > + > +@ignore > +@c man begin SYNOPSIS gm2 > +gm2 [@option{-c}|@option{-S}] [@option{-g}] [@option{-pg}] > + [@option{-O}@var{level}] [@option{-W}@var{warn}@dots{}] > + [@option{-I}@var{dir}@dots{}] [@option{-L}@var{dir}@dots{}] > + [@option{-f}@var{option}@dots{}] [@option{-m}@var{machine-option}@dots{}] > + [@option{-o} @var{outfile}] [@@@var{file}] @var{infile}@dots{} > + > +Only the most useful options are listed here; see below for the > +remainder. > +@c man end > +@c man begin SEEALSO > +gpl(7), gfdl(7), fsf-funding(7), gcc(1) > +and the Info entries for @file{gm2} and @file{gcc}. > +@c man end > +@end ignore > + > +@c man begin DESCRIPTION gm2 > + > +The @command{gm2} command is the GNU compiler for the Modula-2 language and > +supports many of the same options as @command{gcc}. @xref{Option Summary, , > +Option Summary, gcc, Using the GNU Compiler Collection (GCC)}. > +This manual only documents the options specific to @command{gm2}. > + > +@c man end > + > +This section describes how to compile and link a simple hello world > +program. It provides a few examples of using the different options > +mentioned in @pxref{Compiler options, , ,gm2}. Assuming that you have > +a file called @file{hello.mod} in your current directory which > +contains: > + > +@example > +MODULE hello ; > + > +FROM StrIO IMPORT WriteString, WriteLn ; > + > +BEGIN > + WriteString('hello world') ; WriteLn > +END hello. > +@end example > + > +You can compile and link it by: @samp{gm2 -g hello.mod}. > +The result will be an @samp{a.out} file created in your directory. > + > +You can split this command into two steps if you prefer. The compile > +step can be achieved by: @samp{gm2 -g -c -fscaffold-main hello.mod} > +and the link via: @samp{gm2 -g hello.o}. > + > +@footnote{To see all the compile actions taken by @samp{gm2} users can also > +add the @samp{-v} flag at the command line, for example: > + > +@samp{gm2 -v -g -I. hello.mod} > + > +This displays the subprocesses initiated by @samp{gm2} which can be useful > +when trouble shooting.} > + > +@node Compiler options, Elementary data types, Example usage, Using > +@section Compiler options > + > +This section describes the compiler options specific to GNU Modula-2 > +for generic flags details @xref{Invoking GCC, , ,gcc}. > + > +@c man begin OPTIONS > + > +For any given input file, the file name suffix determines what kind of > +compilation is done. The following kinds of input file names are supported: > + > +@table @gcctabopt > +@item @var{file}.mod > +Modula-2 implementation or program source files. See the > +@samp{-fmod=} option if you wish to compile a project which uses a > +different source file extension. > +@item @var{file}.def > +Modula-2 definition module source files. Definition modules are not > +compiled separately, in GNU Modula-2 definition modules are parsed as > +required when program or implementation modules are compiled. See the > +@samp{-fdef=} option if you wish to compile a project which uses a > +different source file extension. > +@end table > + > +You can specify more than one input file on the @command{gm2} command line, > + > +@table @code > + > +@item -g > +create debugging information so that debuggers such as @file{gdb} > +can inspect and control executables. > + > +@item -I > +used to specify the search path for definition and implementation > +modules. An example is: @code{gm2 -g -c -I.:../../libs foo.mod}. > +If this option is not specified then the default path is added > +which consists of the current directory followed by the appropriate > +language dialect library directories. > + > +@c ordered list of options from here. > + > +@item -fauto-init > +turns on auto initialization of pointers to NIL. Whenever a block is > +created all pointers declarated within this scope will have their > +addresses assigned to NIL. > + > +@item -fbounds > +turns on runtime subrange, array index and indirection via @code{NIL} > +pointer checking. > + > +@item -fcase > +turns on compile time checking to check whether a @code{CASE} > +statement requires an @code{ELSE} clause when on was not specified. > + > +@item -fcpp > +preprocess the source with @samp{cpp -lang-asm -traditional-cpp} > +For further details about these options @xref{Invocation, , ,cpp}. > +If @samp{-fcpp} is supplied then all definition modules and > +implementation modules which are parsed will be preprocessed by > +@samp{cpp}. > + > +@c fcpp-end > +@c Modula-2 > +@c passed to the preprocessor if -fcpp is used (internal switch) > + > +@c fcpp-begin > +@c Modula-2 > +@c passed to the preprocessor if -fcpp is used (internal switch) > + > +@item -fdebug-builtins > +call a real function, rather than the builtin equivalent. This can > +be useful for debugging parameter values to a builtin function as > +it allows users to single step code into a real function. > + > +@c fd > +@c Modula-2 > +@c turn on internal debugging of the compiler (internal switch) > + > +@c fdebug-trace-quad > +@c Modula-2 > +@c turn on quadruple tracing (internal switch) > + > +@c fdebug-trace-api > +@c Modula-2 > +@c turn on the Modula-2 api tracing (internal switch) > + > +@c fdebug-function-line-numbers > +@c Modula-2 > +@c turn on the Modula-2 function line number generation (internal switch) > + > +@item -fdef= > +recognize the specified suffix as a definition module filename. > +The default implmentation and module filename suffix is @file{.def}. > +If this option is used GNU Modula-2 will still fall back to this > +default if a requested definition module is not found. > + > +@item -fdump-system-exports > +display all inbuilt system items. > +This is an internal command line option. > + > +@item -fexceptions > +turn on exception handling code. By default this option is on. > +Exception handling can be disabled by @samp{-fno-exceptions} > +and no references are made to the runtime exception libraries. > + > +@item -fextended-opaque > +allows opaque types to be implemented as any type. This is a GNU > +Modula-2 extension and it requires that the implementation module > +defining the opaque type is available so that it can be resolved when > +compiling the module which imports the opaque type. > + > +@item -ffloatvalue > +turns on runtime checking to check whether a floating point number is > +about to exceed range. > + > +@item -fgen-module-list=@file{filename} > +attempt to find all modules when linking and generate a module list. > +If the @file{filename} is @samp{-} then the contents are not written > +and only used to force the linking of all module ctors. > +This option cannot be used if @samp{-fuse-list=} is enabled. > + > +@item -findex > +generate code to check whether array index values are out of bounds. > +Array index checking can be disabled via @samp{-fno-index}. > + > +@item -fiso > +turn on ISO standard features. Currently this enables the ISO > +@code{SYSTEM} module and alters the default library search path so > +that the ISO libraries are searched before the PIM libraries. It also > +effects the behaviour of @code{DIV} and @code{MOD} operators. > +@xref{Dialect, , ,gm2}. > + > +@item -flibs= > +modifies the default library search path. The libraries supplied are: > +m2pim, m2iso, m2min, m2log and m2cor. These map onto the > +Programming in Modula-2 base libraries, ISO standard libraries, minimal > +library support, Logitech compatible library and Programming in > +Modula-2 with coroutines. > +Multiple libraries can be specified and are comma separated with precidence > +going to the first in the list. It is not necessary to use -flibs=m2pim or > +-flibs=m2iso if you also specify -fpim, -fpim2, -fpim3, -fpim4 or > +-fiso. Unless you are using -flibs=m2min you should include m2pim as > +the they provide the base modules which all other dialects utilize. > +The option @samp{-fno-libs=-} disables the @samp{gm2} driver from > +modifying the search and library paths. > + > +@c flocation= > +@c Modula-2 Joined > +@c set all location values to a specific value (internal switch) > + > +@item -fm2-g > +improve the debugging experience for new programmers at the expense > +of generating @code{nop} instructions if necessary to ensure single > +stepping precision over all code related keywords. An example > +of this is in termination of a list of nested @code{IF} statements > +where multiple @code{END} keywords are mapped onto a sequence of > +@code{nop} instructions. > + > +@item -fm2-lower-case > +render keywords in error messages using lower case. > + > +@item -fm2-plugin > +insert plugin to identify runtime errors at compiletime (default on). > + > +@item -fm2-statistics > +generates quadruple information: number of quadruples generated, > +number of quadruples remaining after optimisation and number of source > +lines compiled. > + > +@item -fm2-strict-type > +experimental flag to turn on the new strict type checker. > + > +@item -fm2-whole-program > +compile all implementation modules and program module at once. Notice > +that you need to take care if you are compiling different dialect > +modules (particularly with the negative operands to modulus). But > +this option, when coupled together with @code{-O3}, can deliver huge > +performance improvements. > + > +@item -fmod= > +recognize the specified suffix as implementation and module filenames. > +The default implmentation and module filename suffix is @file{.mod}. > +If this option is used GNU Modula-2 will still fall back to this > +default if it needs to read an implmentation module and the specified > +suffixed filename does not exist. > + > +@item -fnil > +generate code to detect accessing data through a @code{NIL} value > +pointer. Dereferencing checking through a @code{NIL} pointer can be > +disabled by @samp{-fno-nil}. > + > +@item -fpim > +turn on PIM standard features. Currently this enables the PIM > +@code{SYSTEM} module and determines which identifiers are pervasive > +(declared in the base module). If no other @samp{-fpim[234]} switch is > +used then division and modulus operators behave as defined in PIM4. > +@xref{Dialect, , ,gm2}. > + > +@item -fpim2 > +turn on PIM-2 standard features. Currently this removes @code{SIZE} > +from being a pervasive identifier (declared in the base module). It > +places @code{SIZE} in the @code{SYSTEM} module. It also effects the > +behaviour of @code{DIV} and @code{MOD} operators. > +@xref{Dialect, , ,gm2}. > + > +@item -fpim3 > +turn on PIM-3 standard features. Currently this only effects the > +behaviour of @code{DIV} and @code{MOD} operators. > +@xref{Dialect, , ,gm2}. > + > +@item -fpim4 > +turn on PIM-4 standard features. Currently this only effects the > +behaviour of @code{DIV} and @code{MOD} operators. > +@xref{Dialect, , ,gm2}. > + > +@item -fpositive-mod-floor-div > +forces the @code{DIV} and @code{MOD} operators to behave as defined by PIM4. > +All modulus results are positive and the results from the division are > +rounded to the floor. > +@xref{Dialect, , ,gm2}. > + > +@item -fpthread > +link against the pthread library. By default this option is on. It > +can be disabled by @samp{-fno-pthread}. GNU Modula-2 uses the GCC > +pthread libraries to implement coroutines (see the SYSTEM > +implementation module). > + > +@c -fq > +@c -Modula-2 > +@c -internal compiler debugging information, dump the list of quadruples > + > +@item -frange > +generate code to check the assignment range, return value range > +set range and constructor range. Range checking can be disabled > +via @samp{-fno-range}. > + > +@item -freturn > +generate code to check that functions always exit with a @code{RETURN} > +and do not fall out at the end. Return checking can be disabled > +via @samp{-fno-return}. > + > +@item -fruntime-modules= > +specify, using a comma separated list, the runtime modules and their > +order. These modules will initialized first before any other modules > +in the application dependency. By default the runtime modules list is > +set to @code{Storage,SYSTEM,M2RTS,RTExceptions,IOLink}. Note that > +these modules will only be linked into your executable if they are > +required. So adding a long list of dependant modules will not effect > +the size of the executable it merely states the initialization order > +should they be required. > + > +@item -fscaffold-dynamic > +the option ensures that @samp{gm2} will generate a dynamic scaffold > +infastructure when compiling implementation and program modules. > +By default this option is on. Use @samp{-fno-scaffold-dynamic} > +to turn it off or select @samp{-fno-scaffold-static}. > + > +@item -fscaffold-c > +generate a C source scaffold for the current module being compiled. > + > +@item -fscaffold-c++ > +generate a C++ source scaffold for the current module being compiled. > + > +@item -fscaffold-main > +force the generation of the @samp{main} function. This is not > +necessary if the @samp{-c} is omitted. > + > +@item -fscaffold-static > +the option ensures that @samp{gm2} will generate a static scaffold > +within the program module. The static scaffold consists of sequences > +of calls to all dependent module initialization and finalialization > +procedures. The static scaffold is useful for debugging and single > +stepping the initialization blocks of implementation modules. > + > +@item -fshared > +generate a shared library from the module. > + > +@item -fsoft-check-all > +turns on all runtime checks. This is the same as invoking > +GNU Modula-2 using the command options > +@code{-fnil} @code{-frange} @code{-findex} > +@code{-fwholevalue} > +@code{-fwholediv} @code{-fcase} @code{-freturn}. > + > +@item -fsources > +displays the path to the source of each module. This option > +can be used at compile time to check the correct definition module > +is being used. > + > +@item -fswig > +generate a swig interface file. > + > +@item -funbounded-by-reference > +enable optimization of unbounded parameters by attempting to pass non > +@code{VAR} unbounded parameters by reference. This optimization > +avoids the implicit copy inside the callee procedure. GNU Modula-2 > +will only allow unbounded parameters to be passed by reference if, > +inside the callee procedure, they are not written to, no address is > +calculated on the array and it is not passed as a @code{VAR} > +parameter. Note that it is possible to write code to break this > +optimization, therefore this option should be used carefully. > +For example it would be possible to take the address of an array, pass > +the address and the array to a procedure, read from the array in > +the procedure and write to the location using the address parameter. > + > +Due to the dangerous nature of this option it is not enabled > +when the @samp{-O} option is specified. > + > +@item -fuse-list=@file{filename} > +if @samp{-fscaffold-static} is enabled then use the file > +@file{filename} for the initialization order of modules. Whereas if > +@samp{-fscaffold-dynamic} is enabled then use this file to force > +linking of all module ctors. > +This option cannot be used if @samp{-fgen-module-list=} is enabled. > + > +@item -fwholediv > +generate code to detect whole number division by zero or modulus by > +zero. > + > +@item -fwholevalue > +generate code to detect whole number overflow and underflow. > + > +@c the following warning options are complete but need to be > +@c regression tested against all other front ends > +@c to ensure the options do not conflict. > + > +@c @item -Wall > +@c turn on all Modula-2 warnings. > + > +@c @item -Wpedantic > +@c forces the compiler to reject nested @code{WITH} statements > +@c referencing the same record type. Does not allow multiple imports of > +@c the same item from a module. It also checks that: procedure variables > +@c are written to before being read; variables are not only written to > +@c but read from; variables are declared and used. If the compiler > +@c encounters a variable being read before written it will terminate with > +@c a message. It will check that @code{FOR} loop indices are not used > +@c outside the end of this loop without being reset. > + > +@c @item -Wpedantic-cast > +@c warns if the ISO system function is used and if the size of > +@c the variable is different from that of the type. This is legal > +@c in ISO Modula-2, however it can be dangerous. Some users may prefer > +@c to use @code{VAL} instead in these situations and use @code{CAST} > +@c exclusively for changes in type on objects which have the same size. > + > +@c @item -Wpedantic-param-names > +@c procedure parameter names are checked in the definition module > +@c against their implementation module counterpart. This is not > +@c necessary in ISO or PIM versions of Modula-2. > + > +@c @item -Wstyle > +@c checks for poor programming style. This option is aimed at new users of > +@c Modula-2 in that it checks for situations which might cause confusion > +@c and thus mistakes. It checks whether variables of the same name are > +@c declared in different scopes and whether variables look like keywords. > +@c Experienced users might find this option too aggressive. > + > +@c @item -Wunused-variable > +@c warns if a variable has been declared and it not used. > + > +@c @item -Wunused-parameter > +@c warns if a parameter has been declared and it not used. > + > +@c @item -Wverbose-unbounded > +@c inform the user which non @code{VAR} unbounded parameters will be > +@c passed by reference. This only produces output if the option > +@c @samp{-funbounded-by-reference} is also supplied on the command line. > + > +@end table > + > +@c man end > + > +@node Elementary data types, Standard procedures, Compiler options, Using > +@section Elementary data types > + > +This section describes the elementary data types supported by GNU > +Modula-2. It also describes the relationship between these data types > +and the equivalent C data types. > + > +The following data types are supported: @code{INTEGER}, > +@code{LONGINT}, @code{SHORTINT}, @code{CARDINAL}, @code{LONGCARD}, > +@code{SHORTCARD}, @code{BOOLEAN}, @code{REAL}, @code{LONGREAL}, > +@code{SHORTREAL}, @code{COMPLEX}, @code{LONGCOMPLEX}, > +@code{SHORTCOMPLEX} and @code{CHAR}. > + > +An equivalence table is given below: > + > +@example > +GNU Modula-2 GNU C > +====================================== > +INTEGER int > +LONGINT long long int > +SHORTINT short int > +CARDINAL unsigned int > +LONGCARD long long unsigned int > +SHORTCARD short unsigned int > +BOOLEAN int > +REAL double > +LONGREAL long double > +SHORTREAL float > +CHAR char > +SHORTCOMPLEX complex float > +COMPLEX complex double > +LONGCOMPLEX complex long double > +@end example > + > +Note that GNU Modula-2 also supports fixed sized data types which are > +exported from the @code{SYSTEM} module. > +@xref{The PIM system module, , ,gm2}. > +@xref{The ISO system module, , ,gm2}. > + > +@node Standard procedures, Dialect, Elementary data types, Using > +@section Permanently accessible base procedures. > + > +This section describes the procedures and functions which are > +always visible. > + > +@subsection Standard procedures and functions common to PIM and ISO > + > +The following procedures are implemented and conform with Programming > +in Modula-2 and ISO Modula-2: @code{NEW}, @code{DISPOSE}, @code{INC}, > +@code{DEC}, @code{INCL}, @code{EXCL} and @code{HALT}. The standard > +functions are: @code{ABS}, @code{CAP}, @code{CHR}, @code{FLOAT}, > +@code{HIGH}, @code{LFLOAT}, @code{LTRUNC}, @code{MIN}, @code{MAX}, > +@code{ODD}, @code{SFLOAT}, @code{STRUNC} @code{TRUNC} and > +@code{VAL}. All these functions and procedures (except @code{HALT}, > +@code{NEW}, @code{DISPOSE} and, under non constant conditions, > +@code{LENGTH}) generate in-line code for efficiency. > + > +@example > + > +(* > + ABS - returns the positive value of i. > +*) > + > +@findex ABS > +PROCEDURE ABS (i: ) : ; > + > +@end example > + > +@example > + > +(* > + CAP - returns the capital of character ch providing > + ch lies within the range 'a'..'z'. Otherwise ch > + is returned unaltered. > +*) > + > +@findex CAP > +PROCEDURE CAP (ch: CHAR) : CHAR ; > + > +@end example > + > +@example > + > +(* > + CHR - converts a value of a into a CHAR. > + CHR(x) is shorthand for VAL(CHAR, x). > +*) > + > +@findex CHR > +PROCEDURE CHR (x: ) : CHAR ; > + > +@end example > + > +@example > + > +(* > + DISPOSE - the procedure DISPOSE is replaced by: > + DEALLOCATE(p, TSIZE(p^)) ; > + The user is expected to import the procedure DEALLOCATE > + (normally found in the module, Storage.) > + > + In: a variable p: of any pointer type which has been > + initialized by a call to NEW. > + Out: the area of memory > + holding p^ is returned to the system. > + Note that the underlying procedure DEALLOCATE > + procedure in module Storage will assign p to NIL. > +*) > + > +@findex DISPOSE > +PROCEDURE DISPOSE (VAR p:) ; > +@end example > + > +@example > + > +(* > + DEC - can either take one or two parameters. If supplied > + with one parameter then on the completion of the call to > + DEC, v will have its predecessor value. If two > + parameters are supplied then the value v will have its > + n'th predecessor. For these reasons the value of n > + must be >=0. > +*) > + > +@findex DEC > +PROCEDURE DEC (VAR v: ; [n: = 1]) ; > +@end example > + > +@example > + > +(* > + EXCL - excludes bit element e from a set type s. > +*) > + > +@findex EXCL > +PROCEDURE EXCL (VAR s: ; e: ) ; > +@end example > + > +@example > + > +(* > + FLOAT - will return a REAL number whose value is the same as o. > +*) > + > +@findex FLOAT > +PROCEDURE FLOAT (o: ) : REAL ; > +@end example > + > +@example > + > +(* > + FLOATS - will return a SHORTREAL number whose value is the same as o. > +*) > + > +@findex FLOATS > +PROCEDURE FLOATS (o: ) : REAL ; > +@end example > + > +@example > + > +(* > + FLOATL - will return a LONGREAL number whose value is the same as o. > +*) > + > +@findex FLOATL > +PROCEDURE FLOATL (o: ) : REAL ; > +@end example > + > +@example > + > +(* > + HALT - will call the HALT procedure inside the module M2RTS. > + Users can replace M2RTS. > +*) > + > +@findex HALT > +PROCEDURE HALT ; > +@end example > + > +@example > + > +(* > + HIGH - returns the last accessible index of an parameter declared as > + ARRAY OF CHAR. Thus > + > + PROCEDURE foo (a: ARRAY OF CHAR) ; > + VAR > + c: CARDINAL ; > + BEGIN > + c := HIGH(a) > + END foo ; > + > + BEGIN > + foo('hello') > + END > + > + will cause the local variable c to contain the value 4 > +*) > + > +@findex HIGH > +PROCEDURE HIGH (a: ARRAY OF CHAR) : CARDINAL ; > +@end example > + > +@example > + > +(* > + INC - can either take one or two parameters. If supplied > + with one parameter then on the completion of the call to > + INC, v will have its successor value. If two > + parameters are supplied then the value v will have its > + n'th successor. For these reasons the value of n > + must be >=0. > +*) > + > +@findex INC > +PROCEDURE INC (VAR v: ; [n: = 1]) ; > +@end example > + > +@example > + > +(* > + INCL - includes bit element e to a set type s. > +*) > + > +@findex INCL > +PROCEDURE INCL (VAR s: ; e: ) ; > +@end example > + > +@example > + > +(* > + LFLOAT - will return a LONGREAL number whose value is the same as o. > +*) > + > +@findex LFLOAT > +PROCEDURE LFLOAT (o: ) : LONGREAL ; > +@end example > + > +@example > + > +(* > + LTRUNC - will return a LONG number whose value is the > + same as o. PIM2, PIM3 and ISO Modula-2 will return > + a LONGCARD whereas PIM4 returns LONGINT. > +*) > + > +@findex LTRUNC > +PROCEDURE LTRUNC (o: ) : LONG ; > +@end example > + > +@example > + > +(* > + MIN - returns the lowest legal value of an ordinal type. > +*) > + > +@findex MIN > +PROCEDURE MIN (t: ) : ; > + > +@end example > + > +@example > + > +(* > + MAX - returns the largest legal value of an ordinal type. > +*) > + > +@findex MAX > +PROCEDURE MAX (t: ) : ; > + > +@end example > + > +@example > + > +(* > + NEW - the procedure NEW is replaced by: > + ALLOCATE(p, TSIZE(p^)) ; > + The user is expected to import the procedure ALLOCATE > + (normally found in the module, Storage.) > + > + In: a variable p: of any pointer type. > + Out: variable p is set to some allocated memory > + which is large enough to hold all the contents of p^. > +*) > + > +@findex NEW > +PROCEDURE NEW (VAR p:) ; > +@end example > + > +@example > + > +(* > + ODD - returns TRUE if the value is not divisible by 2. > +*) > + > +@findex ODD > +PROCEDURE ODD (x: ) : BOOLEAN ; > + > +@end example > + > +@example > + > +(* > + SFLOAT - will return a SHORTREAL number whose value is the same > + as o. > +*) > + > +@findex SFLOAT > +PROCEDURE SFLOAT (o: ) : SHORTREAL ; > +@end example > + > +@example > + > +(* > + STRUNC - will return a SHORT number whose value is the same > + as o. PIM2, PIM3 and ISO Modula-2 will return a > + SHORTCARD whereas PIM4 returns SHORTINT. > +*) > + > +@findex STRUNC > +PROCEDURE STRUNC (o: ) : SHORT ; > +@end example > + > +@example > + > +(* > + TRUNC - will return a number whose value is the same as o. > + PIM2, PIM3 and ISO Modula-2 will return a CARDINAL > + whereas PIM4 returns INTEGER. > +*) > + > +@findex TRUNC > +PROCEDURE TRUNC (o: ) : ; > +@end example > + > +@example > + > +(* > + TRUNCS - will return a number whose value is the same > + as o. PIM2, PIM3 and ISO Modula-2 will return a > + SHORTCARD whereas PIM4 returns SHORTINT. > +*) > + > +@findex TRUNCS > +PROCEDURE TRUNCS (o: ) : ; > +@end example > + > +@example > + > +(* > + TRUNCL - will return a number whose value is the same > + as o. PIM2, PIM3 and ISO Modula-2 will return a > + LONGCARD whereas PIM4 returns LONGINT. > +*) > + > +@findex TRUNCL > +PROCEDURE TRUNCL (o: ) : ; > +@end example > + > +@example > + > +(* > + VAL - converts data i of to > + and returns this value. > + No range checking is performed during this conversion. > +*) > + > +@findex VAL > +PROCEDURE VAL (, > + i: ) : ; > + > +@end example > + > +@subsection ISO specific standard procedures and functions > + > +The standard function @code{LENGTH} is specific to ISO Modula-2 and > +is defined as: > + > +@example > + > +(* > + IM - returns the imaginary component of a complex type. > + The return value will the same type as the imaginary field > + within the complex type. > +*) > + > +@findex IM > +PROCEDURE IM (c: ) : ; > +@end example > + > +@example > + > +(* > + INT - returns an INTEGER value which has the same value as v. > + This function is equivalent to: VAL(INTEGER, v). > +*) > + > +@findex INT > +PROCEDURE INT (v: ) : INTEGER ; > +@end example > + > +@example > + > +(* > + LENGTH - returns the length of string a. > +*) > + > +@findex LENGTH > +PROCEDURE LENGTH (a: ARRAY OF CHAR) : CARDINAL ; > +@end example > + > +This function is evaluated at compile time, providing that string > +@code{a} is a constant. If @code{a} cannot be evaluated then a call is > +made to @code{M2RTS.Length}. > + > +@example > + > +(* > + ODD - returns a BOOLEAN indicating whether the whole number > + value, v, is odd. > +*) > + > +@findex ODD > +PROCEDURE ODD (v: ) : BOOLEAN ; > +@end example > + > +@example > + > +(* > + RE - returns the real component of a complex type. > + The return value will the same type as the real field > + within the complex type. > +*) > + > +@findex RE > +PROCEDURE RE (c: ) : ; > +@end example > + > +@node Dialect, Exceptions, Standard procedures, Using > +@section GNU Modula-2 supported dialects > + > +This section describes the dialects understood by GNU Modula-2. > +It also describes the differences between the dialects and > +any command line switches which determine dialect behaviour. > + > +The GNU Modula-2 compiler is compliant with four dialects of Modula-2. > +The language as defined in 'Programming in Modula-2' 2nd Edition, > +Springer Verlag, 1982, 1983 by Niklaus Wirth (PIM2), 'Programming in > +Modula-2', 3rd Corrected Edition, Springer Verlag, 1985 (PIM3) and > +'Programming in Modula-2', 4th Edition, Springer Verlag, 1988 (PIM4) > +@uref{http://freepages.modula2.org/report4/modula-2.html} and the ISO > +Modula-2 language as defined in ISO/IEC Information technology - > +programming languages - part 1: Modula-2 Language, ISO/IEC 10514-1 > +(1996) (ISO). > + > +The command line switches @samp{-fpim2}, @samp{-fpim3}, @samp{-fpim4} > +and @samp{-fiso} can be used to force mutually exclusive > +features. However by default the compiler will not aggressively fail > +if a non mutually exclusive feature is used from another dialect. For > +example it is possible to specify @samp{-fpim2} and still utilize > +@samp{DEFINITION} @samp{MODULES} which have no export list. > + > +Some dialect differences will force a compile time error, for example > +in PIM2 the user must @code{IMPORT} @code{SIZE} from the module > +@code{SYSTEM}, whereas in PIM3 and PIM4 @code{SIZE} is a pervasive > +function. Thus compiling PIM4 source code with the @samp{-fpim2} > +switch will cause a compile time error. This can be fixed quickly > +with an additional @code{IMPORT} or alternatively by compiling with > +the @samp{-fpim4} switch. > + > +However there are some very important differences between the dialects > +which are mutually exclusive and therefore it is vital that users > +choose the dialects with care when these language features are used. > + > +@subsection Integer division, remainder and modulus > + > +The most dangerous set of mutually exclusive features found in the > +four dialects supported by GNU Modula-2 are the @code{INTEGER} > +division, remainder and modulus arithmetic operators. It is important > +to note that the same source code can be compiled to give different > +runtime results depending upon these switches! The reference manual > +for the various dialects of Modula-2 are quite clear about this > +behaviour and sadly there are three distinct definitions. > + > +The table below illustrates the problem when a negative operand is > +used. > + > +@example > + Pim2/3 Pim4 ISO > + ----------- ----------- ---------------------- > +lval rval DIV MOD DIV MOD DIV MOD / REM > + 31 10 3 1 3 1 3 1 3 1 > +-31 10 -3 -1 -4 9 -4 9 -3 -1 > + 31 -10 -3 1 -3 1 Exception -3 1 > +-31 -10 3 -1 4 9 Exception 3 -1 > +@end example > + > +See also P24 of PIM2, P27 of PIM3, P29 of PIM4 and P201 of the ISO > +Standard. At present all dialect division, remainder and modulus are > +implemented as above, apart from the exception calling in the ISO > +dialect. Instead of exception handling the results are the same as the > +PIM4 dialect. This is a temporary implementation situation. > + > +@node Exceptions, Semantic checking, Dialect, Using > +@section Exception implementation > + > +This section describes how exceptions are implemented in GNU Modula-2 > +and how command line switches affect their behaviour. The option > +@samp{-fsoft-check-all} enables all software checking of nil > +dereferences, division by zero etc. Additional code is produced to > +check these conditions and exception handlers are invoked if the > +conditions prevail. > + > +Without @samp{-fsoft-check-all} these exceptions will be caught by > +hardware (assuming the hardware support exists) and a signal handler > +is invoked. The signal handler will in turn @code{THROW} an exception > +which will be caught by the appropriate Modula-2 handler. However the > +action of throwing an exception from within a signal handler is > +implementation defined (according to the C++ documentation). For > +example on the x86_64 architecture this works whereas on the i686 > +architecture it does not. Therefore to ensure portability it is > +recommended to use @samp{-fsoft-check-all}. > + > +@footnote{@samp{-fsoft-check-all} can be effectively combined with > +@samp{-O2} to semantically analyse source code for possible runtime > +errors at compile time.} > + > +@node Semantic checking, Extensions, Exceptions, Using > +@section How to detect runtime problems at compile time > + > +Consider the following program: > + > +@example > +MODULE assignvalue ; (*!m2iso+gm2*) > + > +PROCEDURE bad () : INTEGER ; > +VAR > + i: INTEGER ; > +BEGIN > + i := -1 ; > + RETURN i > +END bad ; > + > +VAR > + foo: CARDINAL ; > +BEGIN > + (* the m2rte plugin will detect this as an error, post > + optimization. *) > + foo := bad () > +END assignvalue. > +@end example > + > +here we see that the programmer has overlooked that the return value > +from @samp{bad} will cause an overflow to @samp{foo}. If we compile > +the code with the following options: > + > +@example > +$ gm2 -g -fsoft-check-all -O2 -c assignvalue.mod > +assignvalue.mod:16:0:inevitable that this error will occur at runtime, > +assignment will result in an overflow > +@end example > + > +The gm2 semantic plugin is automatically run and will generate a > +warning message for every exception call which is known as reachable. > +It is highly advised to run the optimizer (@samp{-O2} or @samp{-O3}) > +with @samp{-fsoft-check-all} so that the compiler is able to run the > +optimizer and perform variable and flow analysis before the semantic > +plugin is invoked. > + > +@node Extensions, Type compatibility, Semantic checking, Using > +@section GNU Modula-2 language extensions > + > +This section introduces the GNU Modula-2 language extensions. > +The GNU Modula-2 compiler allows abstract data types to be any type, > +not just restricted to a pointer type providing the > +@samp{-fextended-opaque} option is supplied > +@xref{Compiler options, , ,gm2}. > + > +Declarations can be made in any order, whether they are > +types, constants, procedures, nested modules or variables. > +@c (@xref{Passes, , ,}.) > + > +GNU Modula-2 also allows programmers to interface to @code{C} and > +assembly language. > + > +GNU Modula-2 provides support for the special tokens @code{__LINE__}, > +@code{__FILE__}, @code{__FUNCTION__} and @code{__DATE__}. Support for > +these tokens will occur even if the @samp{-fcpp} option is not > +supplied. A table of these identifiers and their data type and values > +is given below: > + > +@example > +Scope GNU Modula-2 token Data type and example value > + > +anywhere __LINE__ Constant Literal compatible > + with CARDINAL, INTEGER and WORD. > + Example 1234 > + > +anywhere __FILE__ Constant string compatible > + with parameter ARRAY OF CHAR or > + an ARRAY whose SIZE is >= string > + length. Example > + "hello.mod" > + > +procedure __FUNCTION__ Constant string compatible > + with parameter ARRAY OF CHAR or > + an ARRAY whose SIZE is >= string > + length. Example > + "calc" > + > +module __FUNCTION__ Example > + "module hello initialization" > + > +anywhere __DATE__ Constant string compatible > + with parameter ARRAY OF CHAR or > + an ARRAY whose SIZE is >= string > + length. Example > + "Thu Apr 29 10:07:16 BST 2004" > + > +anywhere __COLUMN__ Gives a contant literal number > + determining the left hand column > + where the first _ appears in > + __COLUMN__. The left most column > + is 1. > + > +@end example > + > +The preprocessor @samp{cpp} can be invoked via the @samp{-fcpp} > +command line option. This in turn invokes @samp{cpp} with the > +following arguments @samp{-traditional -lang-asm}. These options > +preserve comments and all quotations. @samp{gm2} treats a @samp{#} > +character in the first column as a preprocessor directive. > + > +For example here is a module which calls @code{FatalError} > +via the macro @code{ERROR}. > + > +@example > +MODULE cpp ; > + > +FROM SYSTEM IMPORT ADR, SIZE ; > +FROM libc IMPORT exit, printf, malloc ; > + > +PROCEDURE FatalError (a, file: ARRAY OF CHAR; > + line: CARDINAL; > + func: ARRAY OF CHAR) ; > +BEGIN > + printf("%s:%d:fatal error, %s, in %s\n", > + ADR(file), line, ADR(a), ADR(func)) ; > + exit(1) > +END FatalError ; > + > +#define ERROR(X) FatalError(X, __FILE__, __LINE__, __FUNCTION__) > + > +VAR > + pc: POINTER TO CARDINAL; > +BEGIN > + pc := malloc(SIZE(CARDINAL)) ; > + IF pc=NIL > + THEN > + ERROR('out of memory') > + END > +END cpp. > +@end example > + > +Another use for the C preprocessor in Modula-2 might be to turn on > +debugging code. For example the library module > +@file{FormatStrings.mod} uses procedures from @file{DynamicStrings.mod} > +and to track down memory leaks it was useful to track the source file > +and line where each string was created. Here is a section of > +@file{FormatStrings.mod} which shows how the debugging code was > +enabled and disabled by adding @code{-fcpp} to the command line. > + > +@example > +FROM DynamicStrings IMPORT String, InitString, InitStringChar, Mark, > + ConCat, Slice, Index, char, > + Assign, Length, Mult, Dup, ConCatChar, > + PushAllocation, PopAllocationExemption, > + InitStringDB, InitStringCharStarDB, > + InitStringCharDB, MultDB, DupDB, SliceDB ; > + > +(* > +#define InitString(X) InitStringDB(X, __FILE__, __LINE__) > +#define InitStringCharStar(X) InitStringCharStarDB(X, __FILE__, \ > + __LINE__) > +#define InitStringChar(X) InitStringCharDB(X, __FILE__, __LINE__) > +#define Mult(X,Y) MultDB(X, Y, __FILE__, __LINE__) > +#define Dup(X) DupDB(X, __FILE__, __LINE__) > +#define Slice(X,Y,Z) SliceDB(X, Y, Z, __FILE__, __LINE__) > +*) > + > +PROCEDURE doDSdbEnter ; > +BEGIN > + PushAllocation > +END doDSdbEnter ; > + > +PROCEDURE doDSdbExit (s: String) ; > +BEGIN > + s := PopAllocationExemption(TRUE, s) > +END doDSdbExit ; > + > +PROCEDURE DSdbEnter ; > +BEGIN > +END DSdbEnter ; > + > +PROCEDURE DSdbExit (s: String) ; > +BEGIN > +END DSdbExit ; > + > +(* > +#define DBsbEnter doDBsbEnter > +#define DBsbExit doDBsbExit > +*) > + > +PROCEDURE Sprintf1 (s: String; w: ARRAY OF BYTE) : String ; > +BEGIN > + DSdbEnter ; > + s := FormatString(HandleEscape(s), w) ; > + DSdbExit(s) ; > + RETURN( s ) > +END Sprintf1 ; > +@end example > + > +It is worth noting that the overhead of this code once @code{-fcpp} is > +not present and -O2 is used will be zero since the local empty > +procedures @code{DSdbEnter} and @code{DSdbExit} will be thrown away by > +the optimization passes of the GCC backend. > + > +@subsection Optional procedure parameter > + > +GNU Modula-2 allows the last parameter to a procedure or function > +parameter to be optional. For example in the ISO library > +@file{COROUTINES.def} the procedure @code{NEWCOROUTINE} is defined as > +having an optional fifth argument (@code{initProtection}) which, if > +absent, is automatically replaced by @code{NIL}. > + > +@example > +@findex NEWCOROUTINE > +PROCEDURE NEWCOROUTINE (procBody: PROC; workspace: SYSTEM.ADDRESS; > + size: CARDINAL; VAR cr: COROUTINE; > + [initProtection: PROTECTION = NIL]); > + > + (* Creates a new coroutine whose body is given by procBody, > + and returns the identity of the coroutine in cr. > + workspace is a pointer to the work space allocated to > + the coroutine; size specifies the size of this workspace > + in terms of SYSTEM.LOC. > + > + The optional fifth argument may contain a single parameter > + which specifies the initial protection level of the coroutine. > + *) > +@end example > + > +The implementation module @file{COROUTINES.mod} implements this > +procedure using the following syntax: > + > +@example > +PROCEDURE NEWCOROUTINE (procBody: PROC; workspace: SYSTEM.ADDRESS; > + size: CARDINAL; VAR cr: COROUTINE; > + [initProtection: PROTECTION]); > +BEGIN > + > +END NEWCOROUTINE ; > +@end example > + > +Note that it is illegal for this declaration to contain an initializer > +value for @code{initProtection}. However it is necessary to surround > +this parameter with the brackets @code{[} and @code{]}. This serves to > +remind the programmer that the last parameter was declared as optional > +in the definition module. > + > +Local procedures can be declared to have an optional final parameter > +in which case the initializer is mandatory in the implementation or > +program module. > + > +GNU Modula-2 also provides additional fixed sized data types which > +are all exported from the @code{SYSTEM} module. > +@xref{The PIM system module, , ,gm2}. > +@xref{The ISO system module, , ,gm2}. > + > +@node Type compatibility, Unbounded by reference, Extensions, Using > +@section Type compatibility > + > +This section discuss the issues surrounding assignment, expression > +and parameter compatibility, their effect of the additional > +fixed sized datatypes and also their effect of runtime checking. > +The data types supported by the compiler are: > + > +@example > +GNU Modula-2 scope switches > +============================================= > +INTEGER pervasive > +LONGINT pervasive > +SHORTINT pervasive > +CARDINAL pervasive > +LONGCARD pervasive > +SHORTCARD pervasive > +BOOLEAN pervasive > +BITSET pervasive > +REAL pervasive > +LONGREAL pervasive > +SHORTREAL pervasive > +CHAR pervasive > +SHORTCOMPLEX pervasive > +COMPLEX pervasive > +LONGCOMPLEX pervasive > + > +LOC SYSTEM -fiso > +BYTE SYSTEM > +WORD SYSTEM > +ADDRESS SYSTEM > + > +The following extensions are supported for > +most architectures (please check SYSTEM.def). > +============================================= > +INTEGER8 SYSTEM > +INTEGER16 SYSTEM > +INTEGER32 SYSTEM > +INTEGER64 SYSTEM > +CARDINAL8 SYSTEM > +CARDINAL16 SYSTEM > +CARDINAL32 SYSTEM > +CARDINAL64 SYSTEM > +BITSET8 SYSTEM > +BITSET16 SYSTEM > +BITSET32 SYSTEM > +WORD16 SYSTEM > +WORD32 SYSTEM > +WORD64 SYSTEM > +REAL32 SYSTEM > +REAL64 SYSTEM > +REAL96 SYSTEM > +REAL128 SYSTEM > +COMPLEX32 SYSTEM > +COMPLEX64 SYSTEM > +COMPLEX96 SYSTEM > +COMPLEX128 SYSTEM > +@end example > + > +The Modula-2 language categorizes compatibility between entities of > +possibly differing types into three subcomponents: expressions, > +assignments, and parameters. Parameter compatibility is further > +divided into two sections for pass by reference and pass by value > +compatibility. > + > +For more detail on the Modula-2 type compatibility see the Modula-2 > +ISO standard BS ISO/IEC 10514-1:1996 page 121-125. For detail on the > +PIM type compatibility see Programming in Modula-2 Edition 4 page 29, > +(Elementary Data Types). > + > +@subsection Expression compatibility > + > +Modula-2 restricts the types of expressions to the same type. > +Expression compatibility is a symmetric relation. > + > +For example two sub expressions of @code{INTEGER} and @code{CARDINAL} > +are not expression compatible > +(@uref{http://freepages.modula2.org/report4/modula-2.html} and ISO > +Modula-2). > + > +In GNU Modula-2 this rule is also extended across all fixed sized data > +types (imported from SYSTEM). > + > +@subsection Assignment compatibility > + > +This section discusses the assignment issues surrounding assignment > +compatibility of elementary types (@code{INTEGER}, @code{CARDINAL}, > +@code{REAL} and @code{CHAR} for example). The information here is > +found in more detail in the Modula-2 ISO standard BS ISO/IEC > +10514-1:1996 page 122. > + > +Assignment compatibility exists between the same sized elementary > +types. > + > +Same type family of different sizes are > +also compatible as long as the @code{MAX(}type@code{)} and > +@code{MIN(}type@code{)} is known. So for example this includes the > +@code{INTEGER} family, @code{CARDINAL} family and the @code{REAL} > +family. > + > +The reason for this is that when the assignment is performed > +the compiler will check to see that the expression (on the right of > +the @code{:=}) lies within the range of the designator type (on the > +left hand side of the @code{:=}). Thus these ordinal types can be > +assignment compatible. However it does mean that @code{WORD32} is not > +compatible with @code{WORD16} as @code{WORD32} does not have a minimum > +or maximum value and therefore cannot be checked. The compiler does > +not know which of the two bytes from @code{WORD32} should be copied > +into @code{WORD16} and which two should be ignored. Currently the > +types @code{BITSET8}, @code{BITSET16} and @code{BITSET32} are > +assignment incompatible. However this restriction maybe lifted when > +further runtime checking is achieved. > + > +Modula-2 does allow @code{INTEGER} to be assignment compatible with > +@code{WORD} as they are the same size. Likewise GNU Modula-2 allows > +@code{INTEGER16} to be compatible with @code{WORD16} and the same for > +the other fixed sized types and their sized equivalent in either > +@code{WORD}n, @code{BYTE} or @code{LOC} types. However it prohibits > +assignment between @code{WORD} and @code{WORD32} even though on many > +systems these sizes will be the same. The reasoning behind this rule > +is that the extended fixed sized types are meant to be used by > +applications requiring fixed sized data types and it is more portable > +to forbid the bluring of the boundaries between fixed sized and > +machine dependant sized types. > + > +Intemediate code runtime checking is always generated by the front > +end. However this intemediate code is only translated into actual > +code if the appropriate command line switches are specified. This > +allows the compiler to perform limited range checking at compile time. > +In the future it will allow the extensive GCC optimisations to > +propagate constant values through to the range checks which if they > +are found to exceed the type range will result in a compile time > +error message. > + > +@subsection Parameter compatibility > + > +Parameter compatibility is divided into two areas, pass by value and > +pass by reference (@code{VAR}). In the case of pass by value the > +rules are exactly the same as assignment. However in the second case, > +pass by reference, the actual parameter and formal parameter must be > +the same size and family. Furthermore @code{INTEGER} and > +@code{CARDINAL}s are not treated as compatible in the pass by > +reference case. > + > +The types @code{BYTE}, @code{LOC}, @code{WORD} and @code{WORD}n > +derivitives are assignment and parameter compatible with any data type > +of the same size. > + > +@node Unbounded by reference, Building a shared library, Type compatibility, Using > +@section Unbounded by reference > + > +This section documents a GNU Modula-2 compiler switch which implements > +a language optimisation surrounding the implementation of unbounded > +arrays. In GNU Modula-2 the unbounded array is implemented by > +utilising an internal structure @code{struct @{dataType *address, > +unsigned int high@}}. So given the Modula-2 procedure declaration: > + > +@example > +PROCEDURE foo (VAR a: ARRAY OF dataType) ; > +BEGIN > + IF a[2]= (* etc *) > +END foo ; > +@end example > + > +it is translated into GCC @code{tree}s, which can be represented > +in their C form thus: > + > +@example > +void foo (struct @{dataType *address, unsigned int high@} a) > +@{ > + if (a.address[2] == /* etc */ > +@} > +@end example > + > +Whereas if the procedure @code{foo} was declared as: > + > +@example > +PROCEDURE foo (a: ARRAY OF dataType) ; > +BEGIN > + IF a[2]= (* etc *) > +END foo ; > +@end example > + > +then it is implemented by being translated into the following > +GCC @code{tree}s, which can be represented in their C form thus: > + > +@example > +void foo (struct @{dataType *address, unsigned int high@} a) > +@{ > + dataType *copyContents = (dataType *)alloca (a.high+1); > + memcpy(copyContents, a.address, a.high+1); > + a.address = copyContents; > + > + if (a.address[2] == /* etc */ > +@} > +@end example > + > +This implementation works, but it makes a copy of each non VAR > +unbounded array when a procedure is entered. If the unbounded array > +is not changed during procedure @code{foo} then this implementation > +will be very inefficient. In effect Modula-2 lacks the @code{REF} > +keyword of Ada. Consequently the programmer maybe tempted to > +sacrifice semantic clarity for greater efficiency by declaring the > +parameter using the @code{VAR} keyword in place of @code{REF}. > + > +The @code{-funbounded-by-reference} switch instructs the compiler to > +check and see if the programmer is modifying the content of any > +unbounded array. If it is modified then a copy will be made upon > +entry into the procedure. Conversely if the content is only read and > +never modified then this non @code{VAR} unbounded array is a candidate > +for being passed by reference. It is only a candidate as it is still > +possible that passing this parameter by reference could alter the > +meaning of the source code. For example consider the following case: > + > +@example > +PROCEDURE StrConCat (VAR a: ARRAY OF CHAR; b, c: ARRAY OF CHAR) ; > +BEGIN > + (* code which performs string a := b + c *) > +END StrConCat ; > + > +PROCEDURE foo ; > +VAR > + a: ARRAY [0..3] OF CHAR ; > +BEGIN > + a := 'q' ; > + StrConCat(a, a, a) > +END foo ; > +@end example > + > +In the code above we see that the same parameter, @code{a}, is being > +passed three times to @code{StrConCat}. Clearly even though parameters > +@code{b} and @code{c} are never modified it would be incorrect to > +implement them as pass by reference. Therefore the compiler checks to > +see if any non @code{VAR} parameter is type compatible with any > +@code{VAR} parameter and if so it generates runtime procedure entry > +checks to determine whether the contents of parameters @code{b} or > +@code{c} matches the contents of @code{a}. If a match is detected > +then a copy is made and the @code{address} in the unbounded > +@code{struct}ure is modified. > + > +The compiler will check the address range of each candidate against > +the address range of any @code{VAR} parameter, providing they are type > +compatible. For example consider: > + > +@example > +PROCEDURE foo (a: ARRAY OF BYTE; VAR f: REAL) ; > +BEGIN > + f := 3.14 ; > + IF a[0]=BYTE(0) > + THEN > + (* etc *) > + END > +END foo ; > + > +PROCEDURE bar ; > +BEGIN > + r := 2.0 ; > + foo(r, r) > +END bar ; > +@end example > + > +Here we see that although parameter, @code{a}, is a candidate for the > +passing by reference, it would be incorrect to use this > +transformation. Thus the compiler detects that parameters, @code{a} > +and @code{f} are type compatible and will produce runtime checking > +code to test whether the address range of their respective contents > +intersect. > + > +@node Linking, Building a shared library, Unbounded by reference, Using > + > +This section describes the linking related options. There are three > +linking strategies available which are dynamic scaffold, static > +scaffold and user defined. The dynamic scaffold is enabled by default > +and each module will register itself to the runtime @samp{M2RTS} via > +a constructor. The static scaffold mechanism will invoke each modules > +@samp{_init} and @samp{_finish} function in turn via a sequence of > +calls from within @samp{main}. Lastly the user defined strategy > +can be implemented by turning off the dynamic and static options via > +@samp{-fno-scaffold-dynamic} and @samp{-fno-scaffold-static}. > + > +In the simple test below: > + > +@example > +$ gm2 hello.mod > +@end example > + > +the driver will add the options @samp{-fscaffold-dynamic} and > +@samp{-fgen-module-list=-} which generate a list of application > +modules and also creates the @samp{main} function with calls to > +@samp{M2RTS}. It can be useful to add the option @samp{-fsources} > +which displays the source files as they are parsed and summarizes > +whether the source file is required for compilation or linking. > + > +If you wish to split the above command line into a compile and link > +then you could use these steps: > + > +@example > +$ gm2 -c -fscaffold-main hello.mod > +$ gm2 hello.o > +@end example > + > +The @samp{-fscaffold-main} informs the compiler to generate the > +@samp{main} function and scaffold. You can enable the environment > +variable @samp{GCC_M2LINK_RTFLAG} to trace the construction and > +destruction of the application. The values for > +@samp{GCC_M2LINK_RTFLAG} are shown in the table below: > + > +@example > +value | meaning > +================= > +all | turn on all flags below > +module | trace modules as they register themselves > +pre | generate module list prior to dependency resolution > +dep | trace module dependency resolution > +post | generate module list after dependency resolution > +force | generate a module list after dependency and forced > + | ordering is complete > +@end example > + > +The values can be combined using a comma separated list. > + > +One of the advantages of the dynamic scaffold is that the driver > +behaves in a similar way to the other front end drivers. > +For example consider a small project consisting of 4 definition > +implementation modules (@samp{a.def}, @samp{a.mod}, @samp{b.def}, > +@samp{b.mod}, @samp{c.def}, @samp{c.mod}, @samp{d.def}, @samp{d.mod}) > +and a program module @samp{program.mod}. > + > +To link this project we could: > + > +@example > +$ gm2 -g -c a.mod > +$ gm2 -g -c b.mod > +$ gm2 -g -c c.mod > +$ gm2 -g -c d.mod > +$ gm2 -g program.mod a.o b.o c.o d.o > +@end example > + > +The module initialization sequence is defined by the ISO standard to > +follow the import graph traversal. The initialization order is the > +order in which the corresponding separate modules finish the > +processing of their import lists. > + > +However, if required, you can override this using > +@samp{-fruntime-modules=a,b,c,d} for example which forces the > +initialization sequence to @samp{a}, @samp{b}, @samp{c} and @samp{d}. > + > +@node Building a shared library, Interface for Python, Unbounded by reference, Using > +@section Building a shared library > + > +This section describes building a tiny shared library implemented in > +Modula-2 and built with @file{libtool}. Suppose a project consists of > +two definition modules and two implementation modules and a program > +module @file{a.def}, @file{a.mod}, @file{b.def}, @file{b.mod} and > +@file{c.mod}. The first step is to compile the modules using position > +independent code. This can be achieved by the following three > +commands: > + > +@example > +libtool --tag=CC --mode=compile gm2 -g -c a.mod -o a.lo > +libtool --tag=CC --mode=compile gm2 -g -c b.mod -o b.lo > +libtool --tag=CC --mode=compile gm2 -g -c c.mod -o c.lo > +@end example > + > +The second step is to generate the shared library initialization and > +finalization routines. We can do this by asking gm2 to generate a > +list of dependant modules and then use this to generate the scaffold. > +We also must compile the scaffold. > + > +@example > +gm2 -c -g -fmakelist c.mod > +gm2 -c -g -fmakeinit -fshared c.mod > +libtool --tag=CC --mode=compile g++ -g -c c_m2.cpp -o c_m2.lo > +@end example > + > +The third step is to link all these @file{.lo} files. > + > +@example > +libtool --mode=link gcc -g c_m2.lo a.lo b.lo c.lo \ > + -L$(prefix)/lib64 \ > + -rpath `pwd` -lgm2 -lstdc++ -lm -o libabc.la > +@end example > + > +At this point the shared library @file{libabc.so} will have been > +created inside the directory @file{.libs}. > + > +@node Interface for Python, Producing a Python module, Building a shared library, Using > +@section How to produce swig interface files > + > +This section describes how Modula-2 implementation modules can be > +called from Python (and other scripting languages such as TCL and > +Perl). GNU Modula-2 can be instructed to create a swig interface when > +it is compiling an implementation module. Swig then uses the > +interface file to generate all the necessary wrapping to that the > +desired scripting language may access the implementation module. > + > +Here is an example of how you might call upon the services of the > +Modula-2 library module @code{NumberIO} from Python3. > + > +The following commands can be used to generate the Python3 module: > + > +@example > +export src=@samp{directory to the sources} > +export prefix=@samp{directory to where the compiler is installed} > +gm2 -I$@{src@} -c -g -fswig $@{src@}/../../../gm2-libs/NumberIO.mod > +gm2 -I$@{src@} -c -g -fmakelist $@{src@}/../../../gm2-libs/NumberIO.mod > + > +gm2 -I$@{src@} -c -g -fmakeinit -fshared \ > + $@{src@}/../../../gm2-libs/NumberIO.mod > + > +swig -c++ -python3 NumberIO.i > + > +libtool --mode=compile g++ -g -c -I$@{src@} NumberIO_m2.cpp \ > + -o NumberIO_m2.lo > + > +libtool --tag=CC --mode=compile gm2 -g -c \ > + -I$@{src@}../../../gm2-libs \ > + $@{src@}/../../../gm2-libs/NumberIO.mod -o NumberIO.lo > + > +libtool --tag=CC --mode=compile g++ -g -c NumberIO_wrap.cxx \ > + -I/usr/include/python3 -o NumberIO_wrap.lo > + > +libtool --mode=link gcc -g NumberIO_m2.lo NumberIO_wrap.lo \ > + -L$@{prefix@}/lib64 \ > + -rpath `pwd` -lgm2 -lstdc++ -lm -o libNumberIO.la > + > +cp .libs/libNumberIO.so _NumberIO.so > +@end example > + > +The first four commands, generate the swig interface file > +@file{NumberIO.i} and python wrap files @file{NumberIO_wrap.cxx} and > +@file{NumberIO.py}. The next three @file{libtool} commnads compile > +the C++ and Modula-2 source code into @file{.lo} objects. The last > +@file{libtool} command links all the @file{.lo} files into a > +@file{.la} file and includes all shared library dependencies. > + > +Now it is possible to run the following Python script > +(called @file{testnum.py}): > + > +@example > +import NumberIO > + > +print ("1234 x 2 =", NumberIO.NumberIO_StrToInt("1234")*2) > +@end example > + > +like this: > + > +@example > +$ python3 testnum.py > +1234 x 2 = 2468 > +@end example > + > +@xref{Producing a Python module, , ,gm2} for another example which > +uses the @code{UNQUALIFIED} keyword to reduce the module name clutter > +from the viewport of Python3. > + > +@subsection Limitations of automatic generated of Swig files > + > +This section discusses the limitations of automatically generating > +swig files. From the previous example we see that the module > +@code{NumberIO} had a swig interface file @file{NumberIO.i} > +automatically generated by the compiler. If we consider three of the > +procedure definitions in @file{NumberIO.def} we can see the > +success and limitations of the automatic interface generation. > + > +@example > +PROCEDURE StrToHex (a: ARRAY OF CHAR; VAR x: CARDINAL) ; > +PROCEDURE StrToInt (a: ARRAY OF CHAR; VAR x: INTEGER) ; > +PROCEDURE ReadInt (VAR x: CARDINAL) ; > +@end example > + > +Below are the swig interface prototypes: > + > +@example > +extern void NumberIO_StrToHex (char *_m2_address_a, > + int _m2_high_a, unsigned int *OUTPUT); > +/* parameters: x is known to be an OUTPUT */ > +extern void NumberIO_StrToInt (char *_m2_address_a, > + int _m2_high_a, int *OUTPUT); > +/* parameters: x is guessed to be an OUTPUT */ > +extern void NumberIO_ReadInt (int *x); > +/* parameters: x is unknown */ > +@end example > + > +In the case of @code{StrToHex} it can be seen that the compiler > +detects that the last parameter is an output. It explicitly tells > +swig this by using the parameter name @code{OUTPUT} and in the > +following comment it informs the user that it knows this to be an > +output parameter. In the second procedure @code{StrToInt} it marks > +the final parameter as an output, but it tells the user that this is > +only a guess. Finally in @code{ReadInt} it informs the user that > +it does not know whether the parameter, @code{x}, is an output, input > +or an inout parameter. > + > +The compiler decides whether to mark a parameter as either: > +@code{INPUT}, @code{OUTPUT} or @code{INOUT} if it is read before > +written or visa versa in the first basic block. At this point > +it will write output that the parameter is known. If it is not > +read or written in the first basic block then subsequent basic blocks > +are searched and the result is commented as a guess. Finally if > +no read or write occurs then the parameter is commented as unknown. > +However, clearly it is possible to fool this mechanism. Nevertheless > +automatic generation of implementation module into swig interface files > +was thought sufficiently useful despite these limitations. > + > +In conclusion it would be wise to check all parameters in any > +automatically generated swig interface file. Furthermore you can > +force the automatic mechanism to generate correct interface files by > +reading or writing to the @code{VAR} parameter in the first basic > +block of a procedure. > + > +@node Producing a Python module, Interface to C, Interface for Python, Using > +@section How to produce a Python module > + > +This section descibes how it is possible to produce a Python module > +from Modula-2 code. There are a number of advantages to this > +approach, it ensures your code reaches a wider audience, maybe it is > +easier to initialize your application in Python. > + > +The example application here is a pedagogical two dimensional gravity > +next event simulation. The Python module needs to have a clear API > +which should be placed in a single definition module. Furthermore the > +API should only use fundamental pervasive data types and strings. > +Below the API is contained in the file @file{twoDsim.def}: > + > +@example > +DEFINITION MODULE twoDsim ; > + > +EXPORT UNQUALIFIED gravity, box, poly3, poly5, poly6, mass, > + fix, circle, pivot, velocity, accel, fps, > + replayRate, simulateFor ; > +(* > + gravity - turn on gravity at: g m^2 > +*) > + > +PROCEDURE gravity (g: REAL) ; > + > + > +(* > + box - place a box in the world at (x0,y0),(x0+i,y0+j) > +*) > + > +PROCEDURE box (x0, y0, i, j: REAL) : CARDINAL ; > + > + > +(* > + poly3 - place a triangle in the world at: > + (x0,y0),(x1,y1),(x2,y2) > +*) > + > +PROCEDURE poly3 (x0, y0, x1, y1, x2, y2: REAL) : CARDINAL ; > + > + > +(* > + poly5 - place a pentagon in the world at: > + (x0,y0),(x1,y1),(x2,y2),(x3,y3),(x4,y4) > +*) > + > +PROCEDURE poly5 (x0, y0, x1, y1, > + x2, y2, x3, y3, x4, y4: REAL) : CARDINAL ; > + > + > +(* > + poly6 - place a hexagon in the world at: > + (x0,y0),(x1,y1),(x2,y2),(x3,y3),(x4,y4),(x5,y5) > +*) > + > +PROCEDURE poly6 (x0, y0, x1, y1, > + x2, y2, x3, y3, > + x4, y4, x5, y5: REAL) : CARDINAL ; > + > + > +(* > + mass - specify the mass of an object and return the, id. > +*) > + > +PROCEDURE mass (id: CARDINAL; m: REAL) : CARDINAL ; > + > + > +(* > + fix - fix the object to the world. > +*) > + > +PROCEDURE fix (id: CARDINAL) : CARDINAL ; > + > + > +(* > + circle - adds a circle to the world. Center > + defined by: x0, y0 radius, r. > +*) > + > +PROCEDURE circle (x0, y0, r: REAL) : CARDINAL ; > + > + > +(* > + velocity - give an object, id, a velocity, vx, vy. > +*) > + > +PROCEDURE velocity (id: CARDINAL; vx, vy: REAL) : CARDINAL ; > + > + > +(* > + accel - give an object, id, an acceleration, ax, ay. > +*) > + > +PROCEDURE accel (id: CARDINAL; ax, ay: REAL) : CARDINAL ; > + > + > +(* > + fps - set frames per second. > +*) > + > +PROCEDURE fps (f: REAL) ; > + > + > +(* > + replayRate - set frames per second during replay. > +*) > + > +PROCEDURE replayRate (f: REAL) ; > + > + > +(* > + simulateFor - render for, t, seconds. > +*) > + > +PROCEDURE simulateFor (t: REAL) ; > + > + > +END twoDsim. > +@end example > + > +The keyword @code{UNQUALIFIED} can be used to ensure that the > +compiler will provide externally accessible functions > +@code{gravity}, @code{box}, @code{poly3}, @code{poly5}, @code{poly6}, > +@code{mass}, @code{fix}, @code{circle}, @code{pivot}, @code{velocity}, > +@code{accel}, @code{fps}, @code{replayRate}, @code{simulateFor} > +rather than name mangled alternatives. > +Hence in our Python3 application we could write: > + > +@example > +#!/usr/bin/env python3 > + > +from twoDsim import * > + > +b = box (0.0, 0.0, 1.0, 1.0) > +b = fix (b) > +c1 = circle (0.7, 0.7, 0.05) > +c1 = mass (c1, 0.01) > +c2 = circle (0.7, 0.1, 0.05) > +c2 = mass (c2, 0.01) > +c2 = fix (c2) > +gravity (-9.81) > +fps (24.0*4.0) > +replayRate (24.0) > +print ("creating frames") > +try: > + simulateFor (1.0) > + print ("all done") > +except: > + print ("exception raised") > +@end example > + > +which accesses the various functions defined and implemented by the > +module @code{twoDsim}. The Modula-2 source code is compiled via: > + > +@example > +$ gm2 -g -fiso -c -fswig twoDsim.mod > +$ gm2 -g -fiso -c -fmakelist twoDsim.mod > +$ gm2 -g -fiso -c -fmakeinit twoDsim.mod > +@end example > + > +The first command both compiles the source file creating > +@file{twoDsim.o} and produces a swig interface file @file{swig.i}. We > +now use @code{swig} and @code{g++} to produce and compile the > +interface wrappers: > + > +@example > +$ libtool --mode=compile g++ -g -c twoDsim_m2.cpp -o twoDsim_m2.lo > +$ swig -c++ -python3 twoDsim.i > +$ libtool --mode=compile g++ -c -fPIC twoDsim_wrap.cxx \ > + -I/usr/include/python3 -o twoDsim_wrap.lo > +$ libtool --mode=compile gm2 -g -fPIC -fiso -c deviceGnuPic.mod > +$ libtool --mode=compile gm2 -g -fPIC -fiso -c roots.mod > +$ libtool --mode=compile gm2 -g -fPIC -fiso -c -fswig \ > + twoDsim.mod -o twoDsim.lo > +@end example > + > +Finally the application is linked into a shared library: > + > +@example > +$ libtool --mode=link gcc -g twoDsim_m2.lo twoDsim_wrap.lo \ > + roots.lo deviceGnuPic.lo \ > + -L$@{prefix@}/lib64 \ > + -rpath `pwd` -lgm2 -lstdc++ -lm -o libtwoDsim.la > +cp .libs/libtwoDsim.so _twoDsim.so > +@end example > + > +The library name must start with @code{_} to comply with the Python3 > +module naming scheme. > + > +@node Interface to C, Assembly language, Producing a Python module, Using > +@section Interfacing GNU Modula-2 to C > + > +The GNU Modula-2 compiler tries to use the C calling convention > +wherever possible however some parameters have no C equivalent and > +thus a language specific method is used. For example unbounded arrays > +are passed as a @code{struct @{void *address, unsigned int high@}} and > +the contents of these arrays are copied by callee functions when they > +are declared as non @code{VAR} parameters. The @code{VAR} equivalent > +unbounded array parameters need no copy, but still use the > +@code{struct} representation. > + > +The recommended method of interfacing GNU Modula-2 to C is by telling > +the definition module that the implementation is in the C language. > +This is achieved by using the tokens @code{DEFINITION MODULE FOR "C"}. > +Here is an example @file{libprintf.def}. > + > +@example > +DEFINITION MODULE FOR "C" libprintf ; > + > +EXPORT UNQUALIFIED printf ; > + > +PROCEDURE printf (a: ARRAY OF CHAR; ...) : [ INTEGER ] ; > + > +END libprintf. > +@end example > + > +the @code{UNQUALIFIED} keyword in the definition module informs > +GNU Modula-2 not to prefix the module name to exported references > +in the object file. > + > +The @code{printf} declaration states that the first parameter > +semantically matches @code{ARRAY OF CHAR} but since the module is for > +the C language it will be mapped onto @code{char *}. The token > +@code{...} indicates a variable number of arguments (varargs) and all > +parameters passed here are mapped onto their C equivalents. Arrays and > +constant strings are passed as pointers. Lastly @code{[ INTEGER ]} > +states that the caller can ignore the function return result if desired. > + > +The hello world program can be rewritten as: > + > +@example > +MODULE hello ; > + > +FROM libprintf IMPORT printf ; > + > +BEGIN > + printf("hello world\n") > +END hello. > +@end example > + > +and it can be compiled by: > + > +@samp{gm2 -g hello.mod -lc} > + > +In reality the @samp{-lc} is redundant as libc is always included in the > +linking process. It is shown here to emphasize that the C library or > +object file containing @code{printf} must be present. The search path > +for modules can be changed by using @samp{-I}. > + > +If a procedure function is declared using varargs then some parameter > +values are converted. The table below summarizes the default conversions > +and default types used. > + > +@example > +Actual Parameter | Default conversion | Type of actual > + | | value passed > +=============================================================== > +123 | none | long long int > +"hello world" | none | const char * > +a: ARRAY OF CHAR | ADR(a) | char * > +a: ARRAY [0..5] OF CHAR| ADR(a) | char * > +3.14 | none | long double > +@end example > + > +If you wish to pass @code{int} values then you should explicitly > +convert the constants using one of the conversion mechanisms. > +For example: @code{INTEGER(10)} or @code{VAL(INTEGER, 10)} or > +@code{CAST(INTEGER, 10)}. > + > +@node Assembly language, Alignment, Interface to C, Using > +@section Interface to assembly language > + > +The interface for GNU Modula-2 to assembly language is almost > +identical to GNU C. The only alterations are that the keywords > +@code{asm} and @code{volatile} are in capitals, following the Modula-2 > +convention. > + > +A simple, but highly non optimal, example is given below. Here we want > +to add the two @code{CARDINAL}s @code{foo} and @code{bar} together and > +return the result. The target processor is assumed to be executing > +the x86_64 instruction set. > + > +@example > +PROCEDURE Example (foo, bar: CARDINAL) : CARDINAL ; > +VAR > + myout: CARDINAL ; > +BEGIN > + ASM VOLATILE ("movq %1,%%rax; addq %2,%%rax; movq %%rax,%0" > + : "=rm" (myout) (* outputs *) > + : "rm" (foo), "rm" (bar) (* inputs *) > + : "rax") ; (* we trash *) > + RETURN( myout ) > +END Example ; > +@end example > + > +For a full description of this interface we refer the reader to the GNU C manual. > + > +@xref{Extended Asm, ,Extensions to the C Language Family,gcc}. > + > +The same example can be written using the newer extensions of naming > +the operands rather than using numbered arguments. > + > +@example > +PROCEDURE Example (foo, bar: CARDINAL) : CARDINAL ; > +VAR > + myout: CARDINAL ; > +BEGIN > + ASM VOLATILE ( > + "movq %[left],%%rax; addq %[right],%%rax; movq %%rax,%[output]" > + : [output] "=rm" (myout) (* outputs *) > + : [left] "rm" (foo), [right] "rm" (bar) (* inputs *) > + : "rax") ; (* we trash *) > + RETURN( myout ) > +END Example ; > +@end example > + > +Both examples generate exactly the same code. It is worth noting that > +the specifier ``rm'' indicates that the operand can be either a > +register or memory. Of course you must choose an instruction which > +can take either, but this allows the compiler to take make more > +efficient choices depending upon the optimization level given to the > +compiler. > + > +@node Alignment, Packed, Assembly language, Using > +@section Data type alignment > + > +GNU Modula-2 allows you to specify alignment for types and variables. > +The syntax for alignment is to use the ISO pragma directives @code{<*} > +@code{bytealignment (} expression @code{)} and @code{*>}. These directives > +can be used after type and variable declarations. > + > +The ebnf of the alignment production is: > + > +@example > +Alignment := [ ByteAlignment ] =: > +ByteAlignment := '<*' AttributeExpression '*>' =: > +AlignmentExpression := "(" ConstExpression ")" =: > +@end example > + > +The @code{Alignment} ebnf statement may be used during contruction of > +types, records, record fields, arrays, pointers and variables. Below > +is an example of aligning a type so that the variable @code{bar} is > +aligned on a 1024 address. > + > +@example > +MODULE align ; > + > +TYPE > + foo = INTEGER <* bytealignment(1024) *> ; > + > +VAR > + z : INTEGER ; > + bar: foo ; > +BEGIN > +END align. > +@end example > + > +The next example aligns a variable on a 1024 byte boundary. > + > +@example > +MODULE align2 ; > + > +VAR > + x : CHAR ; > + z : ARRAY [0..255] OF INTEGER <* bytealignment(1024) *> ; > +BEGIN > +END align2. > +@end example > + > +Here the example aligns a pointer on a 1024 byte boundary. > + > +@example > +MODULE align4 ; > + > +FROM SYSTEM IMPORT ADR ; > +FROM libc IMPORT exit ; > + > +VAR > + x : CHAR ; > + z : POINTER TO INTEGER <* bytealignment(1024) *> ; > +BEGIN > + IF ADR(z) MOD 1024=0 > + THEN > + exit(0) > + ELSE > + exit(1) > + END > +END align4. > +@end example > + > +In example @code{align5} record field @code{y} is aligned on a 1024 > +byte boundary. > + > +@example > +MODULE align5 ; > + > +FROM SYSTEM IMPORT ADR ; > +FROM libc IMPORT exit ; > + > +TYPE > + rec = RECORD > + x: CHAR ; > + y: CHAR <* bytealignment(1024) *> ; > + END ; > +VAR > + r: rec ; > +BEGIN > + IF ADR(r.y) MOD 1024=0 > + THEN > + exit(0) > + ELSE > + exit(1) > + END > +END align5. > +@end example > + > +In the example below module @code{align6} declares @code{foo} as an > +array of 256 @code{INTEGER}s. The array @code{foo} is aligned on a > +1024 byte boundary. > + > +@example > +MODULE align6 ; > + > +FROM SYSTEM IMPORT ADR ; > +FROM libc IMPORT exit ; > + > +TYPE > + foo = ARRAY [0..255] OF INTEGER <* bytealignment(1024) *> ; > + > +VAR > + x : CHAR ; > + z : foo ; > +BEGIN > + IF ADR(z) MOD 1024=0 > + THEN > + exit(0) > + ELSE > + exit(1) > + END > +END align6. > +@end example > + > +@node Packed, Built-ins, Alignment, Using > +@section Packing data types > + > +The pragma @code{<* bytealignment(0) *>} can be used to specify that > +the fields within a @code{RECORD} are to be packed. Currently this > +only applies to fields which are declared as subranges, ordinal types > +and enumerated types. Here is an example of how two subranges might > +be packed into a byte. > + > +@example > +TYPE > + bits3c = [0..7] ; > + bits3i = [-4..3] ; > + > + byte = RECORD > + <* bytealignment(0) *> > + x: bits3c ; > + <* bitsunused(2) *> > + y: bits3i ; > + END ; > +@end example > + > +Notice that the user has specified that in between fields @code{x} and > +@code{y} there are two bits unused. > + > +Now the user wishes to create a record with byte numbers zero and one > +occupied and then an @code{INTEGER32} field which is four byte > +aligned. In this case byte numbers two and three will be unused. The > +pragma @code{bytealignment} can be issued at the start of the record > +indicating the default alignment for the whole record and this can be > +overridden by individual fields if necessary. > + > +@example > + rec = RECORD > + <* bytealignment (1) *> ; > + a, b: byte ; > + x: INTEGER32 <* bytealignment(4) *> ; > + END ; > +@end example > + > +In the following example the user has specified that a record has two > +fields @code{p} and @code{q} but that there are three bytes unused between > +these fields. > + > +@example > + header = RECORD > + <* bytealignment(1) *> > + p: byte ; > + <* bytesunused(3) *> > + q: byte ; > + END ; > +@end example > + > +The pragma @code{<* bytesunused(x) *>} can only be used if the current > +field is on a byte boundary. There is also a @code{SYSTEM} pseudo > +procedure function @code{TBITSIZE(T)} which returns the minimum number of > +bits necessary to represent type @code{T}. > + > +Another example of packing record bit fields is given below: > + > +@example > +MODULE align21 ; > + > +FROM libc IMPORT exit ; > + > +TYPE > + colour = (red, blue, green, purple, white, black) ; > + > + soc = PACKEDSET OF colour ; > + > + rec = RECORD > + <* bytealignment(0) *> > + x: soc ; > + y: [-1..1] ; > + END ; > + > +VAR > + r: rec ; > + v: CARDINAL ; > +BEGIN > + v := SIZE(r) ; > + IF SIZE(r)#1 > + THEN > + exit(1) > + END ; > + r.x := soc@{blue@} ; > + IF r.x#soc@{blue@} > + THEN > + exit(2) > + END > +END align21. > +@end example > + > +Here we see that the total size of this record is one byte and consists > +of a six bit set type followed by a 2 bit integer subrange. > + > +@node Built-ins, The PIM system module, Packed, Using > +@section Accessing GNU Modula-2 Built-ins > + > +This section describes the built-in constants and functions defined in > +GNU Modula-2. The following compiler constants can be accessed using > +the @code{__ATTRIBUTE__} @code{__BUILTIN__} keywords. These are not > +part of the Modula-2 language and they may differ depending upon the > +target architecture but they provide a method whereby common > +libraries can interface to a different underlying architecture. > + > +The built-in constants are: @code{BITS_PER_UNIT}, @code{BITS_PER_WORD}, > +@code{BITS_PER_CHAR} and @code{UNITS_PER_WORD}. They are integrated into > +GNU Modula-2 by an extension to the @code{ConstFactor} rule: > + > +@example > +ConstFactor := ConstQualidentOrSet | Number | ConstString | > + "(" ConstExpression ")" | "NOT" ConstFactor | > + ConstAttribute =: > + > +ConstAttribute := "__ATTRIBUTE__" "__BUILTIN__" "(" "(" Ident ")" ")" =: > +@end example > + > +Here is an example taken from the ISO library @code{SYSTEM.def}: > + > +@example > +CONST > + BITSPERLOC = __ATTRIBUTE__ __BUILTIN__ ((BITS_PER_UNIT)) ; > + LOCSPERWORD = __ATTRIBUTE__ __BUILTIN__ ((UNITS_PER_WORD)) ; > +@end example > + > +Built-in functions are transparent to the end user. All built-in > +functions are declared in @code{DEFINITION MODULE}s and are imported > +as and when required. Built-in functions are declared in definition > +modules by using the @code{__BUILTIN__} keyword. Here is a section of > +the ISO library @code{LongMath.def} which demonstrates this feature. > + > +@example > +PROCEDURE __BUILTIN__ sqrt (x: LONGREAL): LONGREAL; > + (* Returns the square root of x *) > +@end example > + > +This indicates that the function @code{sqrt} will be implemented using > +the gcc built-in maths library. If gcc cannot utilize the built-in > +function (for example if the programmer requested the address of > +@code{sqrt}) then code is generated to call the alternative function > +implemented in the @code{IMPLEMENTATION} @code{MODULE}. > + > +Sometimes a function exported from the @code{DEFINITION} @code{MODULE} > +will have a different name from the built-in function within gcc. In > +such cases the mapping between the GNU Modula-2 function name and the > +gcc name is expressed using the keywords @code{__ATTRIBUTE__} > +@code{__BUILTIN__} @code{((Ident))}. For example the function > +@code{sqrt} in @code{LongMath.def} maps onto the gcc built-in function > +@code{sqrtl} and this is expressed as: > + > +@example > +PROCEDURE __ATTRIBUTE__ __BUILTIN__ ((sqrtl)) sqrt > + (x: LONGREAL) : LONGREAL; > + (* Returns the positive square root of x *) > +@end example > + > +The following module @code{Builtins.def} enumerates the list of > +built-in functions which can be accessed in GNU Modula-2. It also > +serves to define the parameter and return value for each function: > + > +@include m2/Builtins.texi > + > +Although this module exists and will result in the generation of > +in-line code if optimization flags are passed to GNU Modula-2, users > +are advised to utilize the same functions from more generic libraries. > +The built-in mechanism will be applied to these generic > +libraries where appropriate. Note for the mathematical routines to > +be in-lined you need to specify the @samp{-ffast-math -O} options. > + > +@node The PIM system module, The ISO system module, Built-ins, Using > +@section The PIM system module > + > +@include m2/SYSTEM-pim.texi > + > +The different dialects of Modula-2 PIM-[234] and ISO Modula-2 declare > +the function @code{SIZE} in different places. PIM-[34] and ISO > +Modula-2 declare @code{SIZE} as a pervasive function (declared in the > +base module). PIM-2 defined @code{SIZE} in the @code{SYSTEM} module > +(as shown above). > + > +GNU Modula-2 allows users to specify the dialect of Modula-2 by using > +the @code{-fiso} and @code{-fpim2} command line switches. > + > +The data types @code{CSIZE_T} and @code{CSSIZE_T} are also exported from > +the @code{SYSTEM} module. The type @code{CSIZE_T} is unsigned and is > +mapped onto the target C data type @code{size_t} whereas the type > +@code{CSSIZE_T} is mapped onto the signed C data type @code{ssize_t}. > + > +It is anticipated that these should only be used to provide cross > +platform definition modules for C libraries. > + > +There are also a variety of fixed sized @code{INTEGER} and > +@code{CARDINAL} types. The variety of the fixed sized types will > +depend upon the target architecture. > + > +@node The ISO system module, , The PIM system module, Using > +@section The ISO system module > + > +@include m2/SYSTEM-iso.texi > + > +The data types @code{CSIZE_T} and @code{CSSIZE_T} are also exported from > +the @code{SYSTEM} module. The type @code{CSIZE_T} is unsigned and is > +mapped onto the target C data type @code{size_t} whereas the type > +@code{CSSIZE_T} is mapped onto the signed C data type @code{ssize_t}. > + > +It is anticipated that these should only be used to provide cross > +platform definition modules for C libraries. > + > +There are also a variety of fixed sized @code{INTEGER} and > +@code{CARDINAL} types. The variety of the fixed sized types will > +depend upon the target architecture. > + > +@node Licence, Copying, The ISO system module, Top > +@section Licence of GNU Modula-2 > + > +GNU Modula-2 is free software, the compiler is held under the GPL v3 > +@uref{http://www.gnu.org/licenses/gpl.txt}, > +its libraries (pim, iso and Logitech compatible) are under the > +GPL v3 with the GCC runtime library exception clause. > + > +Under Section 7 of GPL version 3, you are granted additional > +permissions described in the GCC Runtime Library Exception, version > +3.1, as published by the Free Software Foundation. > + > +You should have received a copy of the GNU General Public License and > +a copy of the GCC Runtime Library Exception along with this program; > +see the files COPYING3 and COPYING.RUNTIME respectively. If not, see > +. > + > +More information on how these licences work is available > +@uref{http://www.gnu.org/licenses/licenses.html} on the GNU web site. > + > +@c Copying node is inside the gpl_v3.texi > +@include gpl_v3.texi > + > +@node Contributing, Internals, Copying, Top > +@section Contributing to GNU Modula-2 > + > +Please do. But also please read the GNU Emacs info under > + > +@example > +* Standards: (standards). GNU coding standards. > +* Intellectual Property:: Keeping Free Software Free > +* Reading Non-Free Code:: Referring to Proprietary Programs > +* Contributions:: Accepting Contributions > +@end example > + > +You might consider joining the GM2 Mailing list before you start > +coding. The mailing list may be subscribed via a web interface > +@uref{http://lists.nongnu.org/mailman/listinfo/gm2} or via email > +@email{gm2-subscribe@@nongnu.org}. > + > +Many thanks and enjoy your coding! > + > +@node Internals, EBNF, Contributing, Top > + > +This section is still being written. > +@c @include gm2-internals.texi > + > +@node EBNF, Libraries, Internals, Top > +@chapter EBNF of GNU Modula-2 > + > +This chapter contains the EBNF of GNU Modula-2. This grammer currently > +supports both PIM and ISO dialects. The rules here are automatically > +extracted from the grammer files in GNU Modula-2 and serve to document > +the syntax of the extensions described earlier and how they fit in > +with the base language. > + > +Note that the first six productions are built into the lexical analysis > +phase. > + > +@include m2/gm2-ebnf.texi > + > +@node Libraries, Indices, EBNF, Top > +@chapter PIM and ISO library definitions > + > +This chapter contains M2F, PIM and ISO libraries. > + > +@c Permission has been kindly granted by > +@c the authors of the ULM libraries to include them with GNU > +@c Modula-2. > +@c These libraries (under the GNU GPL) were written at the > +@c University of Ulm and were originally shipped with the ULM sparc > +@c Modula-2 compiler. > + > +@include m2/gm2-libs.texi > + > +@node Indices, , Libraries, Top > +@section Indices > + > +@ifhtml > +@menu > +* Contents:: Section and subsections. > +* Functions:: Function, constants, types, ebnf indices. > +@end menu > + > +@node Contents, Functions, , > +@section Section and subsections > +@printindex cp > + > +@node Functions, , Contents, > +@section Function, constants, types, ebnf indices. > +@end ifhtml > + > +@printindex fn > + > +@summarycontents > +@contents > +@bye > diff -ruw /dev/null gcc-git-devel-modula2/gcc/m2/lang.opt > --- /dev/null 2022-08-24 16:22:16.888000070 +0100 > +++ gcc-git-devel-modula2/gcc/m2/lang.opt 2022-12-10 00:04:30.319603938 +0000 > @@ -0,0 +1,352 @@ > +; Options for the Modula-2 front end. > +; > +; Copyright (C) 2016-2022 Free Software Foundation, Inc. > +; Contributed by Gaius Mulley . > +; > +; This file is part of GNU Modula-2. > +; > +; GNU Modula-2 is free software; you can redistribute it and/or modify > +; it under the terms of the GNU General Public License as published by > +; the Free Software Foundation; either version 3, or (at your option) > +; any later version. > +; > +; GNU Modula-2 is distributed in the hope that it will be useful, but > +; WITHOUT ANY WARRANTY; without even the implied warranty of > +; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU > +; General Public License for more details. > +; > +; You should have received a copy of the GNU General Public License > +; along with GNU Modula-2; see the file COPYING. If not, > +; see . *) > + > +; See the GCC internals manual for a description of this file's format. > + > +; Please try to keep this file in ASCII collating order. > + > +Language > +Modula-2 > + > +B > +Modula-2 > +; Documented in c.opt > + > +D > +Modula-2 > +; Documented in c.opt > + > +E > +Modula-2 > +; Documented in c.opt (passed to the preprocessor if -fcpp is used) > + > +I > +Modula-2 Joined Separate > +; Documented in c.opt > + > +L > +Modula-2 Joined Separate > +; Not documented > + > +M > +Modula-2 > +; Documented in c.opt > + > +O > +Modula-2 > +; Documented in c.opt > + > +Wall > +Modula-2 > +; Documented in c.opt > + > +Wpedantic > +Modula-2 > +; Documented in common.opt > + > +Wpedantic-param-names > +Modula-2 > +compiler checks to force definition module procedure parameter names with their implementation module counterpart > + > +Wpedantic-cast > +Modula-2 > +compiler warns if a cast is being used on types of differing sizes > + > +Wverbose-unbounded > +Modula-2 > +inform user which parameters will be passed by reference > + > +Wstyle > +Modula-2 > +extra compile time semantic checking, typically tries to catch poor programming style > + > +Wunused-variable > +Modula-2 > +; Documented in c.opt > + > +Wunused-parameter > +Modula-2 > +; Documented in c.opt > + > +c > +Modula-2 > +; Documented in c.opt > + > +fauto-init > +Modula-2 > +automatically initializes all pointers to NIL > + > +fbounds > +Modula-2 > +turns on runtime subrange, array index and indirection via NIL pointer checking > + > +fcase > +Modula-2 > +turns on runtime checking to check whether a CASE statement requires an ELSE clause when on was not specified > + > +fobjc-std=objc1 > +Modula-2 > +; Documented in c.opt > + > +fcpp > +Modula-2 > +use cpp to preprocess the module > + > +fcpp-end > +Modula-2 > +passed to the preprocessor if -fcpp is used (internal switch) > + > +fcpp-begin > +Modula-2 > +passed to the preprocessor if -fcpp is used (internal switch) > + > +fdebug-builtins > +Modula-2 > +call a real function, rather than the builtin equivalent > + > +fd > +Modula-2 > +turn on internal debugging of the compiler (internal switch) > + > +fdebug-trace-quad > +Modula-2 > +turn on quadruple tracing (internal switch) > + > +fdebug-trace-api > +Modula-2 > +turn on the Modula-2 api tracing (internal switch) > + > +fdebug-function-line-numbers > +Modula-2 > +turn on the Modula-2 function line number generation (internal switch) > + > +fdef= > +Modula-2 Joined > +recognise the specified suffix as a definition module filename > + > +fdump-system-exports > +Modula-2 > +display all inbuilt system items > + > +fexceptions > +Modula-2 > +; Documented in common.opt > + > +fextended-opaque > +Modula-2 > +allows opaque types to be implemented as any type (a GNU Modula-2 extension) > + > +ffloatvalue > +Modula-2 > +turns on runtime checking to check whether a floating point number is about to exceed range > + > +fgen-module-list= > +Modula-2 Joined > +create a topologically sorted module list from all dependent modules used in the application > + > +findex > +Modula-2 > +turns on all range checking for numerical values > + > +fiso > +Modula-2 > +use ISO dialect of Modula-2 > + > +flibs= > +Modula-2 Joined > +specify the library order, currently legal entries include: log, min, pim, iso or their directory name equivalent m2log, m2min, m2pim, m2iso. > + > +flocation= > +Modula-2 Joined > +set all location values to a specific value (internal switch) > + > +fm2-g > +Modula-2 > +generate extra nops to improve debugging, producing an instruction for every code related keyword > + > +fm2-lower-case > +Modula-2 > +generate error messages which render keywords in lower case > + > +fm2-plugin > +Modula-2 > +insert plugin to identify runtime errors at compiletime (default on) > + > +fm2-statistics > +Modula-2 > +display statistics about the amount of source lines compiled and symbols used > + > +fm2-strict-type > +Modula-2 > +experimental flag to turn on the new strict type checker > + > +fm2-whole-program > +Modula-2 > +compile all implementation modules and program module at once > + > +fmod= > +Modula-2 Joined > +recognise the specified suffix as implementation and module filenames > + > +fnil > +Modula-2 > +turns on runtime checking to detect accessing data through a NIL value pointer > + > +fpim > +Modula-2 > +use PIM [234] dialect of Modula-2 > + > +fpim2 > +Modula-2 > +use PIM 2 dialect of Modula-2 > + > +fpim3 > +Modula-2 > +use PIM 3 dialect of Modula-2 > + > +fpim4 > +Modula-2 > +use PIM 4 dialect of Modula-2 > + > +fpositive-mod-floor-div > +Modula-2 > +force positive result from MOD and DIV result floor > + > +fpthread > +Modula-2 > +link against the pthread library (default on) > + > +fq > +Modula-2 > +internal compiler debugging information, dump the list of quadruples > + > +frange > +Modula-2 > +turns on all range checking for numerical values > + > +freturn > +Modula-2 > +turns on runtime checking for functions which finish without executing a RETURN statement > + > +fruntime-modules= > +Modula-2 Joined > +specify the list of runtime modules and their initialization order > + > +fscaffold-dynamic > +Modula-2 > +the modules initialization order is dynamically determined by M2RTS and application dependancies > + > +fscaffold-c > +Modula-2 > +generate a C source scaffold for the current module being compiled > + > +fscaffold-c++ > +Modula-2 > +generate a C++ source scaffold for the current module being compiled > + > +fscaffold-main > +Modula-2 > +generate the main function > + > +fscaffold-static > +Modula-2 > +generate static scaffold initialization and finalization for every module inside main > + > +fshared > +Modula-2 > +generate a shared library from the module > + > +fsoft-check-all > +Modula-2 > +turns on all software runtime checking (an abbreviation for -fnil -frange -findex -fwholediv -fcase -freturn -fwholevalue -ffloatvalue) > + > +fsources > +Modula-2 > +display the location of module source files as they are compiled > + > +fswig > +Modula-2 > +create a swig interface file for the module > + > +funbounded-by-reference > +Modula-2 > +optimize non var unbounded parameters by passing it by reference, providing it is not written to within the callee procedure. > + > +fuse-list= > +Modula-2 Joined > +orders the initialization/finalializations for scaffold-static or force linking of modules if scaffold-dynamic > + > +fversion > +Modula-2 > +; Documented in common.opt > + > +fwholediv > +Modula-2 > +turns on all division and modulus by zero checking for ordinal values > + > +fwholevalue > +Modula-2 > +turns on runtime checking to check whether a whole number is about to exceed range > + > +iprefix > +Modula-2 > +; Documented in c.opt > + > +isystem > +Modula-2 > +; Documented in c.opt > + > +idirafter > +Modula-2 > +; Documented in c.opt > + > +imultilib > +Modula-2 > +; Documented in c.opt > + > +lang-asm > +Modula-2 > +; Documented in c.opt > + > +-save-temps > +Modula-2 Alias(save-temps) > + > +save-temps > +Modula-2 > +save temporary preprocessed files > + > +save-temps= > +Modula-2 Joined > +save temporary preprocessed files > + > +traditional-cpp > +Modula-2 > +; Documented in c.opt > + > +v > +Modula-2 > +; Documented in c.opt > + > +x > +Modula-2 Joined > +specify the language from the compiler driver > + > +; This comment is to ensure we retain the blank line above.