| \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 |
| |
| @include m2/version.texi |
| @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 |
| |
| @ifinfo |
| @node Top, Overview, (dir), (dir) |
| @top Introduction |
| @end ifinfo |
| |
| @menu |
| * Overview:: What is GNU Modula-2. |
| * Using:: Using GNU Modula-2. |
| * Licence:: Licence of GNU Modula-2. |
| * Contributing:: Contributing to GNU Modula-2. |
| * Internals:: GNU Modula-2 internals. |
| * EBNF:: EBNF of GNU Modula-2 |
| * Copying:: GNU Public Licence V3. |
| * 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. |
| * News:: Latest news about GNU Modula-2. |
| * Development:: How to get source code using git. |
| * Obtaining:: Where to get the 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. |
| |
| 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. |
| |
| gm2 can produce swig interface headers to allow access from Python and |
| other scripting languages. 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. |
| |
| @node Release map, News, 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 with a git branches matching the various GCC release |
| numbers. 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 M2R10 dialect of Modula-2 and |
| any of the language changes. If you wish to see something different |
| please email @email{gm2@@nongnu.org} with your ideas. |
| |
| @node News, Features, Release map, Using |
| @section News |
| |
| @table @code |
| |
| @item gm2 release numbers |
| are now superceded by gcc branch numbers as gm2 |
| is tracking the gcc release model. |
| |
| @item accuracy of error messages |
| has been improved and offending subexpressions are now highlighted. |
| |
| @item new type checker |
| has been implemented which will check |
| all data types, including recursive procedure parameter types. |
| |
| @item libraries |
| the gm2 driver program has been enhanced to allow 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 |
| @code{foo}. |
| |
| @item libpth |
| has been removed from gm2 and the coroutines are now implemented using |
| the gcc portable threading library. |
| |
| @item libulm |
| the Ulm libraries have been removed from the gm2 tree as they were not |
| GPL3. |
| |
| @item Talk given at The GNU Tools Cauldron 2018 |
| here is a talk on GNU Modula-2 given at |
| @url{https://gcc.gnu.org/wiki/cauldron2018,The GNU Tools Cauldron}, |
| Manchester on 8th September 2018. |
| The title is, ``GNU Modula-2 update, catching semantic errors post |
| code optimisation and improved debugging'' |
| [@url{http://floppsie.comp.glam.ac.uk/Papers/paper23/gaius-mulley-gnu-m2.pdf,slides} |
| and @url{https://www.youtube.com/watch?v=6jf6weRuHjk,video}]. |
| |
| @item gm2 1.8.2 |
| was released on Aug 30th 2018. gm2-1.8.2 grafts onto gcc-8.2.0 |
| and contains integer overflow detection for addition, subtraction, |
| negation and multiplication. It also detects and traps when |
| a floating point nan occurs. This is the first release with the |
| new semantic checking plugin which checks whether any exception |
| will occur post optimization (see -fsoft-check-all). The compiler |
| also works well with the automake tools. |
| |
| @item gm2 1.2.0 |
| was released on May 11th 2017. gm2-1.2.0 grafts onto gcc-5.2.0 and |
| supports much better line number accuracy in debugging output. |
| Source to code relationship can be further improved by the new option |
| -fm2-g. -fm2-whole-program also provides whole program optimization. |
| @item Talk given at The GNU Tools Cauldron 2016 |
| here is a talk on GNU Modula-2 given at |
| @url{https://gcc.gnu.org/wiki/cauldron2016,The GNU Tools Cauldron}, |
| Hebden Bridge on 9th September 2016. |
| The title is, ``GNU Modula-2 status, whole |
| program optimisation and language interoperability'' |
| [@url{http://floppsie.comp.glam.ac.uk/Papers/paper22/gaius-gcc-cauldron-2016.pdf,slides} |
| and @url{https://www.youtube.com/watch?v=8GMyxwHdr1E,video}]. |
| @item gm2 1.1.6 |
| was released on February 22nd 2016. gm2-1.1.6 grafts onto gcc-4.7.4. |
| @item gm2 1.1.5 |
| was released on September 3 2015, passes all regression tests and has |
| many bug fixes applied. Arrays and Records can be assigned to and from |
| WORD, LOC, BYTE providing sizes permit. Also a small number of fixes |
| to the library module MemStream.mod. Fixed a number of bugs shown by |
| valgrind. |
| @item gm2 1.1.3 |
| was released on April 15 2015. gm2-1.1.3 passes all regression |
| tests on Debian Wheezy (x86_64) and (i686). Also passes all regression tests |
| under Debian Jessie (x86_64). It also builds on armv7l Ubuntu Trusty Tahr. |
| @item gm2 1.1.1 |
| was released on January 26 2015. gm2-1.1.1 passes all regression |
| tests on Debian Wheezy (x86_64) and (i686). Also passes all regression tests |
| under Debian Jessie (x86_64). |
| @item gm2 1.1.0 |
| was released on January 02 2015. gm2-1.1.0 passes all regression |
| tests on Debian Wheezy (x86_64) and (i686). |
| @item gm2 1.0.9 |
| Beta was released on September 23 2014, all regressions passed on |
| x86_64 Debian Wheezy. |
| @item gm2 1.0.4 |
| was released on September 30 2011. This is a bug fix release. |
| @item gm2 1.0 |
| was released on December 11 2010. |
| @end table |
| |
| @node Development, Obtaining, News, Using |
| @section How to get source code using git |
| |
| GNU Modula-2 is in the process of migrating into the |
| @url{https://gcc.gnu.org/git.html, GCC git tree}. The development |
| branch is available via git: |
| |
| @example |
| $ git clone git://gcc.gnu.org/git/gcc.git gcc-git-devel-modula2 |
| $ cd gcc-git-devel-modula2 |
| $ git checkout devel/modula-2 |
| $ cd .. |
| @end example |
| |
| @node Obtaining, Features, Development, Using |
| |
| GNU Modula-2 is in the process of migrating into the |
| @url{https://gcc.gnu.org/git.html, GCC git tree}. |
| @xref{Development, , ,gm2} section in this GM2 documentation for git |
| details and @xref{Downloading the source, , ,gcc} in the GCC |
| documentation. |
| |
| @node Features, Documentation, News, 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, Papers and talks, 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 Papers and talks, , Other languages, Using |
| @section Papers and talks |
| |
| A paper was presented at the @uref{http://www.gccsummit.org/2006, |
| GCC 2006 conference} on |
| @uref{http://floppsie.comp.glam.ac.uk/Papers/paper15/mulley-proc.pdf, |
| the state of GNU Modula-2}. |
| |
| A @uref{http://www.gccsummit.org/2010/speakers.php?types=LIGHTNING, |
| lightening talk} has been given at the GCC 2010 conference titled |
| "Exploiting front end knowledge to effortlessly create Python modules" |
| and the slides are |
| @uref{http://floppsie.comp.glam.ac.uk/Papers/paper20/talk.pdf, |
| available}. |
| |
| @node Using, , Overview, Top |
| @chapter Using GNU Modula-2 |
| |
| @menu |
| * Example usage:: Example compile and link. |
| * Compiler options:: GNU Modula-2 compiler options. |
| * Environment variables:: GNU Modula-2 related environment variables. |
| * 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. |
| * Papers and talks:: Papers and talks. |
| * 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. |
| * News:: News. |
| * Development:: Development. |
| * Obtaining:: How to Obtain GNU Modula-2. |
| * 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. Throughout this document the GNU Modula-2 |
| front end is often referred to as @samp{gm2-@value{version-GM2}} or |
| @samp{gm2} for short. This corresponds to GCC version |
| @value{version-GCC} and GNU Modula-2 version @value{version-GM2}. |
| |
| @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, Environment variables, 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. |
| |
| @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. |
| |
| @item -fdump-system-exports |
| display all inbuilt system items. |
| This is an internal command line option. |
| |
| @item -fswig |
| generate a swig interface file. |
| |
| @item -fshared |
| generate a shared library from the module. |
| |
| @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 -fnil |
| generate code to detect accessing data through a |
| @code{NIL} value pointer. |
| |
| @item -fno-nil |
| do not generate code to detect accessing data through a |
| @code{NIL} value pointer. |
| |
| @item -fwholediv |
| generate code to detect whole number division by zero or modulus by zero. |
| |
| @item -fno-wholediv |
| do not generate code to detect whole number division by zero or |
| modulus by zero. |
| |
| @c @item -fwholevalue |
| @c generate code to detect whole number overflow and underflow. |
| |
| @c @item -fno-wholevalue |
| @c do not generate code to detect whole number overflow and underflow. |
| |
| @c @item -frealdiv |
| @c generate code to detect real number division by zero. |
| |
| @c @item -fno-realdiv |
| @c do not generate code to detect real number division by zero. |
| |
| @c @item -frealvalue |
| @c generate code to detect @code{NaN}s real number overflow and underflow. |
| |
| @c @item -fno-realvalue |
| @c do not generate code to detect @code{NaN}s real number overflow and underflow. |
| |
| @item -findex |
| generate code to check whether array index values are out of bounds. |
| |
| @item -fno-index |
| do not generate code to check whether array index values are out of |
| bounds. |
| |
| @item -frange |
| generate code to check the assignment range, return value range |
| set range and constructor range. |
| |
| @item -fno-range |
| do not generate code to check the assignment range, return value range |
| set range and constructor range. |
| |
| @item -freturn |
| generate code to check that functions always exit with a @code{RETURN} |
| and do not fall out at the end. |
| |
| @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 -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} |
| @c @code{-fwholevalue} --fixme-- add this when working |
| @code{-fwholediv} @code{-fcase} @code{-freturn}. |
| |
| @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 -fno-exceptions |
| turns off all generation of exception handling code and no references |
| are made to the runtime exception libraries. |
| |
| @item -v |
| display all calls to subsidiary programs, such as the C preprocessor, |
| the GNU Modula-2 linker and compiler. |
| |
| @item -fm2-statistics |
| generates quadruple information: number of quadruples generated, |
| number of quadruples remaining after optimisation and number of source |
| lines compiled. |
| |
| @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 -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 fno-pthread |
| do not automatically link against the pthread library. This option is |
| likely useful if gm2 is configured as a cross compiler targetting |
| embedded systems. By default GNU Modula-2 uses the GCC pthread |
| libraries to implement coroutines (see the SYSTEM implementation |
| module). |
| |
| @item -fuselist=@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. |
| |
| @item -fscaffold-static |
| the option ensures that @samp{gm2} will generate a static scaffold |
| within the program module. The static scaffold is useful for |
| debugging and single stepping the initialization blocks of |
| implementation modules. |
| |
| @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-dynamic}. |
| |
| @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}. |
| |
| @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 -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 -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. |
| |
| @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 -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 -fdef= |
| recognise 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 -fmod= |
| recognise 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 -fxcode |
| issues all errors and warnings in the @file{Xcode} format. |
| |
| @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 -O option is specified. |
| |
| @item -Wverbose-unbounded |
| inform the user which non @code{VAR} unbounded parameters will be |
| passed by reference. This only produces output if the option |
| @samp{-funbounded-by-reference} is also supplied on the command line. |
| |
| @item -Wstudents |
| checks for bad programming style. This option is aimed at new users of |
| Modula-2 in that it checks for situations which might cause confusion |
| and thus mistakes. It checks whether variables of the same name are |
| declared in different scopes and whether variables look like keywords. |
| Experienced users might find this option too aggressive. |
| |
| @item -Wpedantic |
| forces the compiler to reject nested @code{WITH} statements |
| referencing the same record type. Does not allow multiple imports of |
| the same item from a module. It also checks that: procedure variables |
| are written to before being read; variables are not only written to |
| but read from; variables are declared and used. If the compiler |
| encounters a variable being read before written it will terminate with |
| a message. It will check that @code{FOR} loop indices are not used |
| outside the end of this loop without being reset. |
| |
| @item -Wpedantic-param-names |
| procedure parameter names are checked in the definition module |
| against their implementation module counterpart. This is not |
| necessary in ISO or PIM versions of Modula-2, but it can be |
| extremely useful, as long as code is intentionally |
| written in this way. |
| |
| @item -Wpedantic-cast |
| warns if the ISO system function is used and if the size of |
| the variable is different from that of the type. This is legal |
| in ISO Modula-2, however it can be dangerous. Some users may prefer |
| to use @code{VAL} instead in these situations and use @code{CAST} |
| exclusively for changes in type on objects which have the same size. |
| |
| @item -Wunused-variable |
| warns if a variable has been declared and it not used. |
| |
| @item -Wunused-parameter |
| warns if a parameter has been declared and it not used. |
| |
| @item -Wall |
| turn on all Modula-2 warnings. |
| |
| @end table |
| |
| @c man end |
| |
| @node Environment variables, Elementary data types, Compiler options, Using |
| @section GNU Modula-2 related environment variables |
| |
| @c man begin ENVIRONMENT gm2 |
| |
| This section descibes the environment variables used by GNU Modula-2 and |
| how they can be used to switch between releases of the compiler. Other |
| environment variables can be set to modify the default library path. |
| Initially we will consider environment variables most likely used by |
| the end user. These two environment variables are @code{GM2IPATH} |
| and @code{GM2OPATH}. |
| |
| For example suppose a compile and link on the command line looks like |
| this: |
| |
| @example |
| $ gm2 -g -c -I. -I../project -I../project/unix foo.mod |
| $ gm2 -fonlylink -g -I. -I../project -I../project/unix \ |
| -fobject-path=../project/obj -Iobject-path=../project/unix/obj \ |
| -I. foo.mod |
| @end example |
| |
| they can be simplified by utilising two environment variables to do |
| exactly the same compile and link. |
| |
| @example |
| $ export GM2IPATH=../project:../project/unix |
| $ export GM2OPATH=../project/obj:../project/unix/obj |
| $ gm2 -g -I. foo.mod |
| @end example |
| |
| It is important to note that the two environment variables |
| @code{GM2IPATH} and @code{GM2OPATH} have a lower priority than any |
| @code{-I} or @code{-fobject-path=} command line option. The search |
| order for compiling and linking is: command line switches followed by |
| environment variable paths followed by default runtime libraries or |
| Modula-2 dialect libraries. If in doubt include the @code{-v} option |
| to see the search path used between the compiler subcomponents. |
| |
| @c man end |
| |
| @node Elementary data types, Standard procedures, Environment variables, 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: <any signed type>) : <any signed type> ; |
| |
| @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 <whole number type> into a CHAR. |
| CHR(x) is shorthand for VAL(CHAR, x). |
| *) |
| |
| @findex CHR |
| PROCEDURE CHR (x: <whole number type>) : 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:<any pointer type>) ; |
| @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: <any base type>; [n: <any base type> = 1]) ; |
| @end example |
| |
| @example |
| |
| (* |
| EXCL - excludes bit element e from a set type s. |
| *) |
| |
| @findex EXCL |
| PROCEDURE EXCL (VAR s: <any set type>; e: <element of set type s>) ; |
| @end example |
| |
| @example |
| |
| (* |
| FLOAT - will return a REAL number whose value is the same as o. |
| *) |
| |
| @findex FLOAT |
| PROCEDURE FLOAT (o: <any whole number type>) : REAL ; |
| @end example |
| |
| @example |
| |
| (* |
| FLOATS - will return a SHORTREAL number whose value is the same as o. |
| *) |
| |
| @findex FLOATS |
| PROCEDURE FLOATS (o: <any whole number type>) : REAL ; |
| @end example |
| |
| @example |
| |
| (* |
| FLOATL - will return a LONGREAL number whose value is the same as o. |
| *) |
| |
| @findex FLOATL |
| PROCEDURE FLOATL (o: <any whole number type>) : 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: <any base type>; [n: <any base type> = 1]) ; |
| @end example |
| |
| @example |
| |
| (* |
| INCL - includes bit element e to a set type s. |
| *) |
| |
| @findex INCL |
| PROCEDURE INCL (VAR s: <any set type>; e: <element of set type s>) ; |
| @end example |
| |
| @example |
| |
| (* |
| LFLOAT - will return a LONGREAL number whose value is the same as o. |
| *) |
| |
| @findex LFLOAT |
| PROCEDURE LFLOAT (o: <any whole number type>) : LONGREAL ; |
| @end example |
| |
| @example |
| |
| (* |
| LTRUNC - will return a LONG<type> number whose value is the |
| same as o. PIM2, PIM3 and ISO Modula-2 will return |
| a LONGCARD whereas PIM4 returns LONGINT. |
| *) |
| |
| @findex LTRUNC |
| PROCEDURE LTRUNC (o: <any floating point type>) : LONG<type> ; |
| @end example |
| |
| @example |
| |
| (* |
| MIN - returns the lowest legal value of an ordinal type. |
| *) |
| |
| @findex MIN |
| PROCEDURE MIN (t: <ordinal type>) : <ordinal type> ; |
| |
| @end example |
| |
| @example |
| |
| (* |
| MAX - returns the largest legal value of an ordinal type. |
| *) |
| |
| @findex MAX |
| PROCEDURE MAX (t: <ordinal type>) : <ordinal type> ; |
| |
| @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:<any pointer type>) ; |
| @end example |
| |
| @example |
| |
| (* |
| ODD - returns TRUE if the value is not divisible by 2. |
| *) |
| |
| @findex ODD |
| PROCEDURE ODD (x: <whole number type>) : BOOLEAN ; |
| |
| @end example |
| |
| @example |
| |
| (* |
| SFLOAT - will return a SHORTREAL number whose value is the same |
| as o. |
| *) |
| |
| @findex SFLOAT |
| PROCEDURE SFLOAT (o: <any whole number type>) : SHORTREAL ; |
| @end example |
| |
| @example |
| |
| (* |
| STRUNC - will return a SHORT<type> number whose value is the same |
| as o. PIM2, PIM3 and ISO Modula-2 will return a |
| SHORTCARD whereas PIM4 returns SHORTINT. |
| *) |
| |
| @findex STRUNC |
| PROCEDURE STRUNC (o: <any floating point type>) : SHORT<type> ; |
| @end example |
| |
| @example |
| |
| (* |
| TRUNC - will return a <type> number whose value is the same as o. |
| PIM2, PIM3 and ISO Modula-2 will return a CARDINAL |
| whereas PIM4 returns INTEGER. |
| *) |
| |
| @findex TRUNC |
| PROCEDURE TRUNC (o: <any floating point type>) : <type> ; |
| @end example |
| |
| @example |
| |
| (* |
| TRUNCS - will return a <type> number whose value is the same |
| as o. PIM2, PIM3 and ISO Modula-2 will return a |
| SHORTCARD whereas PIM4 returns SHORTINT. |
| *) |
| |
| @findex TRUNCS |
| PROCEDURE TRUNCS (o: <any floating point type>) : <type> ; |
| @end example |
| |
| @example |
| |
| (* |
| TRUNCL - will return a <type> number whose value is the same |
| as o. PIM2, PIM3 and ISO Modula-2 will return a |
| LONGCARD whereas PIM4 returns LONGINT. |
| *) |
| |
| @findex TRUNCL |
| PROCEDURE TRUNCL (o: <any floating point type>) : <type> ; |
| @end example |
| |
| @example |
| |
| (* |
| VAL - converts data i of <any simple data type 2> to |
| <any simple data type 1> and returns this value. |
| No range checking is performed during this conversion. |
| *) |
| |
| @findex VAL |
| PROCEDURE VAL (<any simple data type 1>, |
| i: <any simple data type 2>) : <any simple data type 1> ; |
| |
| @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: <any complex type>) : <floating point type> ; |
| @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: <any ordinal type>) : 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: <any whole number type>) : 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: <any complex type>) : <floating point type> ; |
| @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 utilise |
| @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 initialiser |
| 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 categorises 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 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 -I. 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. |
| |
| If a procedure function is declared using varargs then some parameter |
| values are converted. The table below summarises 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 utilise 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, Contributing, 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 |
| <http://www.gnu.org/licenses/>. |
| |
| More information on how these licences work is available |
| @uref{http://www.gnu.org/licenses/licenses.html} on the GNU web site. |
| |
| @include gpl_v3.texi |
| |
| @node Contributing, Internals, Licence, 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 |