Modules against headers

Both languages split a program into compilation units, and both need a way to tell one unit about the interface of another. C++ does it with a header the programmer writes and the preprocessor copies into every file that includes it. Fortran does it with a module the compiler writes: USE reads a small binary file that the compiler produced from the module source, and that file holds the interface, not a copy of a declaration. The difference decides which mistakes are caught at compile time and which are caught at link time, and this page measures it with the same library in both languages.

The module and its .mod

A statistics module with two functions, mean and sd, in a file of its own. Nothing in the file says which functions are visible except the PUBLIC line: the rest is the compiler's business.

The file stats_mod.f90:

module stats_mod use, intrinsic :: iso_fortran_env, only: dp => real64 implicit none private public :: mean, sd contains pure function mean(v) result(m) real(dp), intent(in) :: v(:) real(dp) :: m m = sum(v) / real(size(v), dp) end function mean pure function sd(v) result(s) real(dp), intent(in) :: v(:) real(dp) :: s, m integer :: n n = size(v) m = mean(v) s = sqrt(sum((v - m)**2) / real(n - 1, dp)) end function sd end module stats_mod

The program that uses it names the module and nothing else:

The file main.f90:

program use_stats use stats_mod use, intrinsic :: iso_fortran_env, only: dp => real64 implicit none real(dp) :: x(4) x = [2.0_dp, 4.0_dp, 4.0_dp, 5.0_dp] print '(a,f8.3)', 'mean = ', mean(x) print '(a,f8.3)', 'sd = ', sd(x) end program use_stats

The header and its declarations

The C++ version needs a header, and the header is a promise that the programmer writes by hand:

The file stats.hpp:

#pragma once double mean(const double* v, int n);

The definition has to match it exactly, and the compiler of the definition never sees the caller:

The file stats.cpp:

#include "stats.hpp" double mean(const double* v, long n) { double s = 0.0; for (long i = 0; i < n; ++i) { s += v[i]; } return s / static_cast<double>(n); }

And a third file with the main includes the header and calls the two functions. The C++ side of this page is three files where the Fortran side is two, and the extra one is the interface written by hand.

Two builds

The Fortran build compiles the module first, because USE reads the .mod file that the first command writes, and links after:

gfortran -Wall -Wextra -std=f2018 -c stats_mod.f90
ls -l stats_mod.mod
gfortran -Wall -Wextra -std=f2018 stats_mod.o main.f90 -o use_stats
./use_stats

-rw-r--r--    1 agent    agent         359 Nov 18 21:03 stats_mod.mod
mean =    3.750
sd   =    1.258

The .mod file is 359 bytes and it is not text: it is the compiler's record of the interface, including the types, the ranks, the PURE attribute and the PUBLIC list. It is also why the build order cannot be left to chance: a project that compiles the files in the wrong order fails with Cannot open module file, which is what lessons 111 and 112 are about.

The C++ build compiles each translation unit and lets the linker join them:

g++ -std=c++23 -Wall -Wextra -c stats.cpp
g++ -std=c++23 -Wall -Wextra main.cpp stats.o -o use_stats_cpp
./use_stats_cpp

mean =    3.750

Both programs print the same mean. The C++ main.cpp is four lines and a call; the Fortran main.f90 is the same idea with the module name instead of an include.

Two mistakes

Now the part that decides which language catches what. Change the Fortran call to pass an argument the function does not take, mean(x, 4), and compile against the module:

gfortran -Wall -Wextra -std=f2018 stats_mod.o wrong.f90 -o /dev/null

wrong.f90:8:10:

   8 |   print *, mean(x, 4)
      |          1
Error: More actual than formal arguments in procedure call at (1)

A compile error, at the line of the call, because the .mod file told the compiler what mean takes. The same mistake in C++ is a different kind of mistake. Declare the function in the header with an int and define it with a long:

g++ -std=c++23 -Wall -Wextra -c stats.cpp
g++ -std=c++23 -Wall -Wextra main.cpp stats.o -o use_stats_cpp

/usr/lib/gcc/x86_64-alpine-linux-musl/15.2.0/../../../../x86_64-alpine-linux-musl/bin/ld: /tmp/ccEhfpFG.o: in function `main':
main.cpp:(.text+0x58): undefined reference to `mean(double const*, int)'
collect2: error: ld returned 1 exit status

A link error, from the linker, quoting a mangled name that is the type signature. The compiler of stats.cpp was happy: it saw a definition that matched the header it included. The compiler of main.cpp was happy: it saw a declaration. Only the linker noticed that the two names do not match, and it can only notice because C++ mangles the parameter types into the symbol. Had the two declarations differed in a way that keeps the same mangled name, such as a const on a by-value parameter, the program would have linked and done something surprising.

What each catches where

mistakeFortranC++
wrong number of argumentscompile error, at the callcompile error, at the call
wrong type of an argumentcompile error, at the callcompile error if a prototype is visible, else a warning or nothing
header or interface out of dateimpossible: the .mod is generatedlink error, or a wrong answer
two definitions of one functionnot possible in a modulelink error, or one silently chosen for an inline
a name that changed in one filecompile error at the USElink error, with the mangled name in it

The Fortran advantage is real and it is narrow: the interface is generated from the definition, so it cannot be stale. The C++ advantage is that the header is a document a reader can open, and that the same header works for templates, for other languages with a C ABI and for documentation tools. A project that has both languages in it usually keeps the header for the boundary and the module for everything inside.

Exercises

  1. Delete stats_mod.mod and build again. Which command fails, and what does it say?
  2. Add a third function to the module and forget to make it public. What does the caller see when it tries to use it?
  3. Change the C++ header to double mean(const double* v, long n); and rebuild both files. Does the link error change?
  4. Build the Fortran module with .mod, and does the check still apply to the call?

The programs on this page were built with GNU Fortran (Alpine 15.2.0) 15.2.0 and G++ (Alpine 15.2.0) 15.2.0 and run on Alpine Linux 3.24.3 (x86_64) in a Docker container. This page builds a two-file example, which the course checker cannot assemble from one block; the transcripts above are the builds that were run.

Article author: Arthur Isaev