Provided by: icmake_12.03.00-1ubuntu1_amd64 
NAME
icmodmap - Initializes the maintenance of C++ projects using modules
SYNOPSIS
icmodmap [Options] start-directory
DESCRIPTION
Although modules have already been available for quite some time, the gnu g++ compiler
still shows a number of bugs related to C++ modules (cf.
https://gcc.gnu.org/bugzilla/show_bug.cgi?id=103524). So it’s possible that when using
modules you will encounter some of these (or new) bugs. The bugs will probabably have been
repaired in future releases of the compiler, and the current state of affairs at least
allows you to gain some experience in using modules.
Modules cannot mutually import each other. Consequently there’s always a linear,
non-circular module hierarchy, which should be acknowledged when compiling files defining
and using modules. The icmodmap program determines this order and prepares the
construction of modules used by programs.
Icmodmap assumes that modules are defined in separate sub-directories, and that module
interfaces are defined in (by default) files named module.cc. If a program defines two
modules First and Second (e.g., in sub-directories first and second and the
second/module.cc imports module First then first/module.cc must be compiled before
compiling second/module.cc. This is handled by icmodmap. Once the module.cc files have
been compiled the remaining source files of the program can be compiled as usual.
Icmodmap expect projects using modules to be organized as follows:
o The project’s top-level directory contains a file CLASSES, where each line
(ignoring (C++) comment) specifies the name of a sub-directory implementing one of
the project’s components. Alternatively a (subset) of the directory’s
sub-directories can be specified. Each sub-directory can define a module, a module
partition, a class (not part of a module, but maybe using modules), or global-level
functions (also maybe using modules);
o If the project defines a program, the project’s top-level directory contains source
files (like main.cc) defining the main function. The top-level directory does not
define a module, but its sources may use modules;
o Sub-directories defining modules or partitions by default contain a file module.cc,
defining the module’s name and its interface (instead of module.cc another file
name can be specified);
o Modules and partitions may define classes (one class per module, one class per
partition). If so the member functions of those classes are defined in the module
or partition’s sub-directory.
Icmodmap(1) inspects each specified sub-directory. If it contains the file module.cc (or
its alternative name), then that file (having the following structure) is inspected:
o its first non-empty line: defines the name of the module or partition;
o import lines can specify system headers, modules and/or partitions.
OPTIONS
Icmodmap supports the following options:
o --colors (-c)
by default the compiler is called using the -fdiagnostics-color=never option. Use
this option to suppress this option;
o --dependencies (-d)
the dependencies between modules is shown using this option. Module defining source
files are not compiled. Icmodmap’s output may look like this:
Square:l
DepSquare: Square
here, the :l suffix indicates that Square is a module defined by the project, not
depending on other modules. When module definitions do depend on other modules
they’re listed next: DepSquare is another module defined by the project, depending
on the Square module.
It’s also possible that modules depend on modules defined by other projects. In
that case the output may look like this:
Square:e
Mod1: Square:e
Mod2: Square:e Mod1
Mod3: Square:e Mod1 Mod2
In this example module Square is an external module, indicated by the :e suffix.
All other modules depend on Square, and (e.g.,) Mod3 also depnds on the locally
defined modules Mod1 and Mod2. In this latter example the Square.gcm file must be
available in the project’s gcm.cache directory (it could be a soft-link to the
actual file);
o --help (-h)
Provides usage info, returning 0 to the operating system;
o --module=file (-m)
By default modules are defined in module.cc source files. If modules are defined in
source files having other names then those names can be specified using this
option. E.g., when modules are defined in interface.cc files then specify option
--module interface.cc. Using differently named module definition files is not
supported;
o --subdir (-s)
By default the compiled module defining files are located in the project’s tmp/o
sub-directory where each compiled file has received an compilation order number
prefix (e.g., tmp/o/1module.o, tmp/o/2module.o, ...). When specifying the --subdir
option the compiled files are located in the same sub-directory as the module
defining files themselves (not using the order number prefix);
o --version (-v)
Displays icmodmap’s version.
o --verbose (-V)
Shows additional output when determining the module compilation order and compiling
the module definition files.
EXAMPLE
The following program defines a module Square in its sub-directory square, containing this
module.cc file:
export module Square;
export
{
double square(double value);
class Square
{
double d_amount;
public:
Square(double amount = 0); // initialize
void amount(double value); // change d_amount
double amount() const; // return d_amount
double lastSquared() const; // returns g_squared
double square() const; // returns sqr(d_amount)
};
}
double g_squared;
The main function imports the Square module and uses its facilities. It also imports the
iostream module-compiled system header. That header is not inspected by icmodmap, and must
be available before the main.cc file can be compiled. Here is the main.cc source file:
import Square;
import <iostream>;
int main(int argc, char **argv)
{
std::cout << "the square of " << argc << " is "
<< square(argc) << ’\n’;
Square obj{12};
std::cout << "the square of 12 is " << obj.square() << "\n"
"the last computed square is " <<
obj.lastSquared() << ’\n’;
}
Executing icmodmap -d . shows Square as a local module:
Square:l
Executing icmodmap -V . shows the compilation of square/module.cc:
Module: Square
square:
/bin/g++ --std=c++26 -fdiagnostics-color=never -c -fmodules-ts
-Wall -o ../tmp/o/1module.o module.cc
It also defines the gcm.cache subdirectory, containing Square.gcm and a soft-link usr ->
/usr, and because of this soft-link the compiler finds the module-compiled system header
files. It also defines the soft-link square/gcm.cache -> ../gcm.cache: those soft-links
are defined in all sub-directories used by the program, allowing all source files in all
of the program’s sub-directories to import all modules defined in the main directory’s
gcm.cache directory.
SEE ALSO
icmake(1).
BUGS
None reported.
COPYRIGHT
This is free software, distributed under the terms of the GNU General Public License
(GPL).
AUTHOR
Frank B. Brokken (f.b.brokken@rug.nl).