M2(1)

📦
version 12-20220319 · 7 versions
, in ubuntu jammy

okay bestie, buckle UP 💖 this is M2(1), the manual page for gm2 — yes, the GNU Modula-2 Compiler. She's long, she's iconic, and we're doing her in multiple parts, so hydrate and stay with me. ✨

🌸 NAME 🌸

gm2 — the GNU Modula-2 Compiler. That's her. That's the whole name. Periodt. 💅

🎀 SYNOPSIS 🎀

ngl the synopsis section is literally empty in the original, bestie. Nothing. Void. A vibe. 🫥 It's giving "the compiler will simply know what you meant." Moving on. 💖

🦋 DESCRIPTION 🦋

And the description section… also empty. 😭 Truly a minimal queen. No cap, there's nothing here — the OPTIONS section is where all the lore lives. 👑

✨ OPTIONS ✨

Okay so — for any input file you hand over, the file name suffix decides what kind of compilation happens. It's giving "your extension is your destiny." 🧚 Here are the input file name kinds that are supported:

  • file.mod — Modula-2 implementation or program source files. 💜 Psst: go look at the -fmod= option if you wanna compile a project that uses a different source file extension.
  • file.def — Modula-2 definition module source files. Important tea: definition modules are not compiled separately — in GNU Modula-2, definition modules get parsed as required when program or implementation modules are compiled. So they're like the supportive bestie that shows up exactly when needed. 🫶 And see the -fdef= option if you wanna compile a project that uses a different source file extension.

Also: you can specify more than one input file on the gm2 command line, 💅

  • -g — creates debugging information so debuggers like gdb can inspect and control executables. 🔍 Your future self, crying with gratitude, thanks you.
  • -I — used to specify the search path for definition and implementation modules. Example time, bestie:
gm2 -g -c -I.:../../libs foo.mod

If this option isn't specified, then the default path gets added, which consists of the current directory followed by the appropriate language dialect library directories. 🗂️✨

  • -fobject-path= — used to specify the path for objects during the linking stage. Example, served fresh:
gm2 -g -fobject-path=.:../../libs/O2 -I.:../../libs foo.mod

The combo of -I and -fobject-path= lets projects keep various styles of objects separate from their source counterparts. 🧺 For example, you could compile implementation modules with different levels of optimization and with/without debugging and keep them in separate directories. Organizational queen behavior.

If the -fobject-path= option isn't specified, then it's set internally by using the path as specified by the -I option. And if the -I was also not specified, then it uses the current directory. In all cases the appropriate language dialect library directories are appended to the end of the path. 💫

  • -fdebug-builtins — call a real function, rather than the builtin equivalent. This can be useful for debugging parameter values to a builtin function because it lets users single step code into a real function. 🐛 Single-stepping into the real thing? We love to see it.
  • -fdump-system-exports — display all inbuilt system items. This is an internal command line option. 🤫
  • -fswig — generate a swig interface file. 🐍✨
  • -fshared — generate a shared library from the module. 🧩
  • -fmakeinit — generate the start up C++ code for the module, and a file _m2_modulename.cpp is created. This is an internal command line option. 🔧
  • -fruntime-modules= — specify, using a comma separated list, the runtime modules and their order. 📝 These modules will be initialized first before any other modules in the application dependancy. By default the runtime modules list is set to:
Storage,SYSTEM,M2RTS,RTExceptions,IOLink

Note: these modules will only be linked into your executable if they are required. So adding a long list of dependant modules will not affect the size of the executable — it merely states the initialisation order should they be required. 💅

  • -fnil — generate code to detect accessing data through a NIL value pointer. 🚫
  • -fno-nil — do not generate code to detect accessing data through a NIL value pointer. 🙈
  • -fwholediv — generate code to detect whole number division by zero or modulus by zero. ➗
  • -fno-wholediv — do not generate code to detect whole number division by zero or modulus by zero. 😌
  • -findex — generate code to check whether array index values are out of bounds. 📏
  • -fno-index — do not generate code to check whether array index values are out of bounds. 🛌
  • -frange — generate code to check the assignment range, return value range set range and constructor range. 📐
  • -fno-range — do not generate code to check the assignment range, return value range set range and constructor range. 🌙
  • -freturn — generate code to check that functions always exit with a RETURN and do not fall out at the end. 🏁
  • -fcase — turns on compile time checking to check whether a CASE statement requires an ELSE clause when on was not specified. 🔀
  • -fsoft-check-all — turns on all runtime checks. This is the same as invoking GNU Modula-2 using the command options -fnil -frange -findex -fwholediv -fcase -freturn. 🔥 the "yes queen, check everything" button
  • -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. 🪄
  • -fno-exceptions — turns off all generation of exception handling code and no references are made to the runtime exception libraries. 🚪
  • -v — display all calls to subsidiary programs, such as the C preprocessor, the GNU Modula-2 linker and compiler. 📢
  • -fm2-statistics — generates quadruple information: number of quadruples generated, number of quadruples remaining after optimisation and number of source lines compiled. 📊
  • -fm2-whole-program — compile all implementation modules and program module at once. ⚠️ Notice that you need to take care if you are compiling different dialect modules (particularly with the negative operands to modulus). But this option, when coupled together with -O3, can deliver huge performance improvements. 🚀
  • -fm2-g — improve the debugging experience for new programmers at the expense of generating nop instructions if necessary to ensure single stepping precision over all code related keywords. 📚 An example of this is in termination of a list of nested IF statements where multiple END keywords are mapped onto a sequence of nop instructions. 🧠
  • -fm2-lower-case — render keywords in error messages using lower case. 🔡 gentle, soft, lowercase errors
  • -fmakelist — this option is only applicable when linking a program module. The compiler will generate a modulename.lst file which contains a list indicating the initialisation order of all modules which are to be linked. The actual link does not occur. 🔗 The GNU Modula-2 linker scans all IMPORTs, generates a list of dependencies and produces an ordered list for initialisation. It will probably get the order wrong if your project has cyclic dependencies, but the .lst file is plain text and can be modified if required. 📝 Once the .lst file is created it can be used by the compiler to link your project via the -fuselist option. It has no effect if the -c option is present.
  • 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). 💫
  • -fuselist — providing gm2 has been told to link the program module, this option uses the file modulename.lst for the initialisation order of modules. 📋
  • -fcpp — preprocess the source with cpp -lang-asm -traditional-cpp. 📎 For further details about these options see If -fcpp is supplied then all definition modules and implementation modules which are parsed will be preprocessed by cpp. 👀
  • -fiso — turn on ISO standard features. Currently this enables the ISO SYSTEM module and alters the default library search path so that the ISO libraries are searched before the PIM libraries. 🌈 It also effects the behaviour of DIV and MOD operators. See
  • -fpim — turn on PIM standard features. Currently this enables the PIM SYSTEM module and determines which identifiers are pervasive (declared in the base module). 🌼 If no other -fpim[234] switch is used then division and modulus operators behave as defined in PIM4. See
  • -fpim2 — turn on PIM-2 standard features. Currently this removes SIZE from being a pervasive identifier (declared in the base module). 🚫 It places SIZE in the SYSTEM module. It also effects the behaviour of DIV and MOD operators. See
  • -fpim3 — turn on PIM-3 standard features. Currently this only effects the behaviour of DIV and MOD operators. See
  • -fpim4 — turn on PIM-4 standard features. Currently this only effects the behaviour of DIV and MOD operators. See
  • -fpositive-mod-floor-div — forces the DIV and MOD operators to behave as defined by PIM4. ➕ All modulus results are positive and the results from the division are rounded to the floor. See
  • -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. 🫶
  • -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. 🔮
  • -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. ✅
  • -fmodules — displays the path to each modules object file. 🗃️ This option can only be invoked with the -c option. It is used to see the location of objects when linking occurs. 🔗
  • -fdef= — recognise the specified suffix as a definition module filename. 🏷️ The default implmentation and module filename suffix is .def. If this option is used GNU Modula-2 will still fall back to this default if a requested definition module is not found. 🫡

okay that's part one bestie, and there's MORE coming — don't you dare leave, the rest is equally iconic 💖

  • -fmod= — tell gm2 that the suffix you're about to name is what implementation files and module files are called. The default suffix is .mod, periodt. But here's the cute part: if you use this option, GNU Modula-2 will still fall back to that default when it needs to read an implementation module and the file with your special suffix isn't there. So it's a "yes and" situation, not a replacement 💅
  • -fxcode — spits out every error and every warning in the Xcode format. Apple girlies, this one's for you 🍎
  • -fonlylink — just link the Modula-2 application, that's it. It does not compile the program module first. Link only, no compiling, we're skipping a step ✨
  • -funbounded-by-reference — okay so this one is the spicy one 🔥 it turns on an optimization for unbounded parameters by trying to pass non-VAR unbounded parameters by reference. Why do we care? Because it dodges the implicit copy that happens inside the callee procedure. Iconic.

GNU Modula-2 will only let unbounded parameters go by reference if, inside the callee procedure, they are not written to, no address is calculated on the array, and the array is not passed as a VAR parameter.

danger danger bestie — it is possible to write code that breaks this optimization, so use this option 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. That's the exact scenario that ruins your day 😭

And because this option is genuinely dangerous, it is not enabled when the -O option is specified. Not even a little.

  • -Wverbose-unbounded — this tells you which non-VAR unbounded parameters are gonna be passed by reference. It only produces output if -funbounded-by-reference is also on the command line. They're a package deal, iykyk 🫶
  • -Wstudents — checks for bad programming style ✨ this one is aimed at new Modula-2 users, checking for situations that might cause confusion and therefore mistakes. It checks whether variables of the same name are declared in different scopes, and whether variables look like keywords. Fair warning: experienced users might find this option too aggressive 💀
  • -Wpedantic — makes the compiler straight up reject nested WITH statements that reference the same record type. Also does not allow multiple imports of the same item from a module. And it 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 catches a variable being read before written, it will terminate with a message. It also checks that FOR loop indices are not used outside the end of this loop without being reset. Pedantic really said "no crumbs" 😤

  • -Wpedantic-param-names — procedure parameter names get 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 your code is intentionally written in this way 🎀
  • -Wpedantic-cast — warns you if the ISO system function is used and 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 VAL instead in these situations, and use CAST exclusively for changes in type on objects which have the same size.
  • -Wunused-variable — warns if a variable has been declared and it is not used. (We've all been that variable 🥲)
  • -Wunused-parameter — warns if a parameter has been declared and it is not used.
  • -Wall — turns on all Modula-2 warnings. The full buffet. Eat up 👑

🌈 ENVIRONMENT 🌈

So this section is just… empty, bestie 😭 the original man page lists nothing here — no environment variables, no nothing. It's giving minimalism. Moving on 💅

👀 SEE ALSO 👀

Go read them, they're the supporting cast and they ate 🫶

Copyright (c) 1999-2021 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 man page gfdl(7).

okay bestie that's the whole page, we made it 🎀 this one's from the gcc-12 era, dated 2022-03-19, and it's page M2(1) — so like, if you ever need to cite it, now you know. slay, go compile something, and remember: read your warnings 💜✨

📦 where this page comes from