GM2(1)

✨ GM2(1) ✨

Okay bestie, this one is from the GNU manual crew 🌈 and it's all about the GNU Modula-2 compiler 💖 (part 1 of 2)

💖 NAME

gm2 - The GNU Modula-2 Compiler. Yes, this is the whole compiler, and it's giving main character energy 👑

🧚 SYNOPSIS

🌸 DESCRIPTION

🦋 OPTIONS

okay so for any input file, the file name suffix decides what kind of compilation happens. These are the input file name kinds that are supported:

• file.mod — Modula-2 implementation or program source files. If your project uses a different source file extension, check out -fmod= 💅
• file.def — Modula-2 definition module source files. These aren't compiled on their own. Instead, definition modules get parsed whenever a program or implementation module gets compiled 🫶 If your project uses a different source file extension, see -fdef=.

You can specify more than one input file on the gm2 command line, 💕

• -g — creates debugging info so debuggers like gdb can inspect and control your executables 🔍
• -I — sets the search path for definition and implementation modules. For example: gm2 -g -c -I.:../../libs foo.mod. If you don't specify this, the default path is the current directory, followed by the right language dialect library directories 📂
• -fobject-path= — sets the path for objects during the linking stage. For example: gm2 -g -fobject-path=.:../../libs/O2 -I.:../../libs foo.mod. Pairing -I with -fobject-path= lets projects keep different styles of objects separate from their source. You could compile implementation modules with different levels of optimization, with or without debugging, and stash each in its own directory ✨ If you skip -fobject-path=, it gets set from whatever -I says. If -I wasn't specified either, it uses the current directory. Either way, the right language dialect library directories get tacked onto the end of the path.
• -fdebug-builtins — calls a real function instead of the builtin equivalent. This is super useful for debugging the parameter values passed to a builtin function, because you can single step your code right into a real function 🐛
• -fdump-system-exports — displays all inbuilt system items. This one is an internal command line option, so it's more for the compiler people 🤓
• -fswig — generates a swig interface file 🦋
• -fshared — generates a shared library from the module 🌈
• -fmakeinit — generates the start up C++ code for the module. It creates a file called _m2_modulename.cpp. This is also an internal command line option 🔧
• -fruntime-modules= — lets you list the runtime modules and their order, separated by commas. These modules get initialized first, before any other modules in the application dependency chain. By default the list is Storage,SYSTEM,M2RTS,RTExceptions,IOLink. These modules only get linked into your executable if they're actually required. So adding a long list of dependent modules won't change your executable's size. It just sets the initialization order, should they be needed 📋
• -fnil — generates code that detects accessing data through a NIL value pointer 🚨
• -fno-nil — does not generate that NIL pointer detection code 🙅‍♀️
• -fwholediv — generates code that detects whole number division by zero, or modulus by zero ➗
• -fno-wholediv — does not generate that division by zero detection code 🙅‍♀️
• -findex — generates code that checks whether array index values are out of bounds 📏
• -fno-index — does not generate those array bounds checks 🙅‍♀️
• -frange — generates code that checks the assignment range, the return value range, the set range and the constructor range 🎯
• -fno-range — does not generate those range checks 🙅‍♀️
• -freturn — generates code that checks functions always exit with a RETURN and never just fall out the end 🏁
• -fcase — turns on compile time checking for whether a CASE statement needs an ELSE clause when you didn't write one 🧐
• -fsoft-check-all — turns on all runtime checks. It's the same as invoking GNU Modula-2 with -fnil -frange -findex -fwholediv -fcase -freturn 💯
• -fauto-init — turns on auto initialization of pointers to NIL. Whenever a block is created, every pointer declared within that scope gets its address assigned to NIL 🌸
• -fno-exceptions — turns off all generation of exception handling code, and nothing references the runtime exception libraries 🚫
• -v — displays every call to subsidiary programs, like the C preprocessor and the GNU Modula-2 linker and compiler 📢
• -fm2-statistics — generates quadruple information: how many quadruples were generated, how many are left after optimisation, and how many source lines were compiled 📊
• -fm2-whole-program — compiles all implementation modules and the program module all at once. Heads up, you need to take care if you're compiling different dialect modules (especially with negative operands to modulus) 👀 But this option, paired with -O3, can deliver huge performance improvements 🚀
• -fm2-g — makes debugging easier for new programmers, at the cost of generating nop instructions when needed. This makes sure single stepping is precise over all the code-related keywords. For example, when a list of nested IF statements ends, the multiple END keywords get mapped onto a sequence of nop instructions 🧸
• -fm2-lower-case — renders keywords in error messages in lower case 🔡
• -fmakelist — only applies when linking a program module. The compiler generates a modulename.lst file that lists the initialization order of all the modules that are going to be linked. The actual link does not happen. The GNU Modula-2 linker scans all IMPORTs, builds a list of dependencies, and produces an ordered list for initialization.

It will probably get the order wrong if your project has cyclic dependencies. The good news is the .lst file is plain text, so you can edit it if you need to 📝 Once the .lst file exists, the compiler can use it to link your project through the -fuselist option. This has no effect if -c is present.

• fno-pthread — does not automatically link against the pthread library. This is likely useful if gm2 is configured as a cross compiler targeting embedded systems. By default GNU Modula-2 uses the GCC pthread libraries to implement coroutines (see the SYSTEM implementation module) 🧵
• -fuselist — as long as gm2 has been told to link the program module, this option uses the file modulename.lst for the initialization order of modules 🔗
• -fcpp — preprocesses 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 — turns on ISO standard features. Right now this enables the ISO SYSTEM module and changes the default library search path so the ISO libraries get searched before the PIM libraries. It also affects how the DIV and MOD operators behave. See
• -fpim — turns on PIM standard features. Right now this enables the PIM SYSTEM module and decides which identifiers are pervasive (declared in the base module). If no other -fpim[234] switch is used, the division and modulus operators behave as defined in PIM4 📜 See
• -fpim2 — turns on PIM-2 standard features. Right now this takes SIZE out of the pervasive identifiers (declared in the base module) and puts it in the SYSTEM module instead. It also affects how DIV and MOD behave. See
• -fpim3 — turns on PIM-3 standard features. Right now this only affects how DIV and MOD behave. See
• -fpim4 — turns on PIM-4 standard features. Right now this only affects how DIV and MOD behave. See
• -fpositive-mod-floor-div — forces DIV and MOD to behave as defined by PIM4. All modulus results come out positive, and division results get rounded to the floor ➕ See
• -flibs= — modifies the default library search path. The libraries you can supply are m2pim, m2iso, m2min, m2log and m2cor. These map onto the Programming in Modula-2 base libraries, the ISO standard libraries, minimal library support, the Logitech compatible library, and Programming in Modula-2 with coroutines 📚 You can specify several, separated by commas, and the first one in the list gets precedence. You don't need -flibs=m2pim or -flibs=m2iso if you also specify -fpim, -fpim2, -fpim3, -fpim4 or -fiso. Unless you're using -flibs=m2min, you should include m2pim, since it provides the base modules that all the other dialects use 💜
• -fextended-opaque — lets opaque types 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 it can be resolved when the module importing the opaque type gets compiled 🎀
• -fsources — displays the path to the source of each module. You can use this at compile time to double check the correct definition module is being used 🔎
• -fmodules — displays the path to each module's object file. This option can only be invoked with -c. It's used to see where objects are located when linking happens 📍
• -fdef= — recognises the specified suffix as a definition module filename. The default implementation and module filename suffix is .def. If you use this option, GNU Modula-2 will still fall back to that default if a requested definition module can't be found 🦋
• -fmod= — okay so this one lets you pick your own suffix for implementation and module filenames 🦋 The default is .mod. Even with this set, GNU Modula-2 will still fall back to .mod if it needs to read an implementation module and your suffixed filename isn't there 🫶
• -fxcode — every error and warning comes out in the Xcode format 💻✨
• -fonlylink — only links the Modula-2 application and skips compiling the program module beforehand 🧚
• -funbounded-by-reference — this one is a main character optimization 👑 It tries to pass non VAR unbounded parameters by reference, which skips the implicit copy inside the callee procedure. GNU Modula-2 only does this if, inside the callee, the parameters aren't written to, no address is calculated on the array, and it isn't passed as a VAR parameter. You can still write code that breaks it, so use it carefully 🙈

This option is dangerous, bestie 💀 Because of that, it is not enabled when the -O option is specified. For example, you could take the address of an array, pass both the address and the array to a procedure, read from the array in the procedure, and write to the location using the address parameter. Yikes.

• -Wverbose-unbounded — tells you which non VAR unbounded parameters will be passed by reference 📢 It only shows anything if -funbounded-by-reference is also on the command line
• -Wstudents — a style check for new Modula-2 users 🌱 It catches stuff that could cause confusion and mistakes, like variables with the same name declared in different scopes, or variables that look like keywords. Experienced users might find it a little too aggressive 🙃
• -Wpedantic — the strict one 🧐 It forces the compiler to reject nested WITH statements that reference the same record type, and it won't allow multiple imports of the same item from a module. It also checks that procedure variables are written to before being read, that variables aren't only written to but also read from, and that variables are declared and used. If the compiler finds a variable being read before it's written, it stops with a message. It also checks that FOR loop indices aren't used outside the end of the loop without being reset 💅
• -Wpedantic-param-names — checks that procedure parameter names in the definition module match their implementation module counterparts 🎀 This isn't required in ISO or PIM versions of Modula-2, but it can be super useful, as long as you're doing it on purpose
• -Wpedantic-cast — warns if the ISO system function is used and the size of the variable is different from the size of the type ⚠️ This is legal in ISO Modula-2, but it can be dangerous. Some folks prefer VAL in these situations and only use CAST for type changes on objects that are the same size 🫶
• -Wunused-variable — warns if a variable has been declared and never used 🍓
• -Wunused-parameter — warns if a parameter has been declared and never used 🌸
• -Wall — turns on all the Modula-2 warnings 🌈🔥

---

✨ ENVIRONMENT ✨

Nothing is documented in this section, so there's no environment variable tea to spill here 🫖

🌸 SEE ALSO 🌸

gpl(7), gfdl(7), fsf-funding(7), gcc(1) and the Info entries for gm2 and gcc 📚💜

🎀 COPYRIGHT 🎀

Copyright (c) 1999-2021 Free Software Foundation, Inc.

You're totally allowed to copy, distribute, and/or modify this document 🦋 under the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation. There are 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) 📜

---

That's a wrap on GM2(1) for the gcc-11 crowd, dated 2024-07-19 🌈💖 Go be iconic with your Modula-2 code, bestie 😭✨