Modules, .mod files and separate compilation

A Fortran project of more than one file is compiled one file at a time, and the order is not free: a module writes a .mod file when it is compiled, and every file that says use of it needs that file to exist first. This lesson takes a three-file project through the sequence, looks at what lands in the build directory, links the objects, and reads the error of a compile that was done in the wrong order.

A three-file project

One module of a constant, one module that uses it and offers a procedure, and a program that uses the second. The dependency is a chain: mod_b needs mod_a, and main needs mod_b.

The file mod_a.f90:

module mod_a implicit none private public :: factor real, parameter :: factor = 2.5 end module mod_a

The file mod_b.f90:

module mod_b use mod_a, only: factor implicit none private public :: scale_all contains elemental function scaled(x) result(y) real, intent(in) :: x real :: y y = factor * x end function scaled subroutine scale_all(v) real, intent(inout) :: v(:) v = scaled(v) end subroutine scale_all end module mod_b

The file main.f90:

program app use mod_b, only: scale_all implicit none real :: v(4) v = [1.0, 2.0, 3.0, 4.0] call scale_all(v) print '(a,4f6.2)', 'scaled =', v end program app

The order of the compiles

Three compiles, in the order of the dependency chain, each writing an object and a module file into build/:

mkdir -p build
gfortran -Wall -Wextra -std=f2018 -c mod_a.f90 -J build -o build/mod_a.o
gfortran -Wall -Wextra -std=f2018 -c mod_b.f90 -J build -o build/mod_b.o
gfortran -Wall -Wextra -std=f2018 -c main.f90 -J build -o build/main.o

mod_b.f90:8:2:

8 | elemental function scaled(x) result(y)
| 1
Warning: 'scaled' declared at (1) may shadow the intrinsic of the same name. In order to call the intrinsic, explicit INTRINSIC declarations may be required. [-Wintrinsic-shadow]

The warning is real and the name is the reason: scaled is not an intrinsic, but gfortran compares it with the intrinsic scale it resembles and warns that a reader may confuse them. The build continues, and the same warning appears in every compile of the file that contains it, which is a good argument for renaming the function rather than silencing the flag.

The .mod files

After the three compiles the build directory holds five files: three objects and two module files.

ls build/

main.o
mod_a.mod
mod_a.o
mod_b.mod
mod_b.o

The .mod file is not a header and not documentation: it is a compiler-generated binary description of the module's interface, and only the same compiler version can read it. That is why build/ is not a thing to copy between machines, why deleting a .mod forces the next build to recompile the module, and why a project that changes compiler versions starts from a clean directory.

The link

The link takes the objects in any order, because the linker resolves names rather than sequence:

gfortran build/mod_a.o build/mod_b.o build/main.o -o app
./app

scaled = 2.50 5.00 7.50 10.00

Four values multiplied by the constant of mod_a, which the program never mentions: it used mod_b, and mod_b used the constant. That is the shape of a project, each file knowing only its own dependencies and the compiler following the chain at build time.

A build script

A shell script that encodes the order is enough for three files, and it is the fallback when a project has no makefile. The order of the compiles is the only thing it has to get right:

#!/bin/sh set -e FC=gfortran FFLAGS="-Wall -Wextra -std=f2018" mkdir -p build $FC $FFLAGS -c mod_a.f90 -J build -o build/mod_a.o $FC $FFLAGS -c mod_b.f90 -J build -o build/mod_b.o $FC $FFLAGS -c main.f90 -J build -o build/main.o $FC build/mod_a.o build/mod_b.o build/main.o -o app

set -e is the important line: without it a failed compile leaves the old object file in place and the link succeeds with a stale binary, which is the worst kind of build. The script recompiles everything every time, which for three files is right and for three hundred is the reason make exists, the subject of the next lesson.

Out of order

Compile mod_b.f90 before mod_a.f90 and the compiler stops at the use:

gfortran -Wall -Wextra -std=f2018 -c mod_b.f90 -J build2 -o build2/mod_b.o

mod_b.f90:2:7:

2 | use mod_a, only: factor
| 1
Fatal Error: Cannot open module file 'mod_a.mod' for reading at (1): No such file or directory
compilation terminated.

Note the wording: the compiler is not looking for the source of mod_a, it is looking for the interface file, and it does not search the current directory tree for it. A -I build flag points it at another directory; without one it looks where -J put the files in the same directory as the source.

Rules for a build

Compile modules before their users, and let a tool hold the order rather than a person. Put objects and module files in a build directory so that the source tree stays clean, and pass the same flags to every compile, because a module compiled with different flags is a module whose interface may not match. Delete the build directory when the compiler changes, and never ship a .mod file.

One habit is worth more than the rest: make a failed compile stop the build. A script with set -e or a makefile does that by default, and a hand-typed sequence of commands on a terminal does not, which is why the sequence in this lesson is shown as a script a reader can save.

Exercises

  1. Rename scaled to times_factor and rebuild. Which warning disappears?
  2. Compile mod_b.f90 with -I build from a directory where mod_a.mod is in build/ and -J points elsewhere. Does it work?
  3. Add a fourth file that uses mod_a directly and link all four objects. In which order do the compiles have to run?
  4. Delete build/mod_b.mod and relink without recompiling. Does the program still run, and what breaks at the next compile of main.f90?

Questions

A new set of questions in a new order every time. Choose one answer for each, then check.

  1. What is written when a module is compiled?

    Answer

    An object file and a .mod file with the interface

    The .mod file is what the users read.

  2. Which file must be compiled first?

    Answer

    The module that others use

    A user needs the .mod file of its module.

  3. What does -J build change?

    Answer

    Where the .mod files are written

    -o names the object file separately.

  4. What does this command print? gfortran -Wall -Wextra -std=f2018 -c mod_b.f90 -J build2 -o build2/mod_b.o when build2 does not contain mod_a.mod?

    Answer

    Fatal Error: cannot open module file mod_a.mod

    The compiler needs the interface before it can compile a use.

  5. Why is a .mod file not a C header?

    Answer

    It is a binary description readable only by the same compiler version

    That is why it is never shipped or copied.

  6. What does the link care about?

    Answer

    The names in the objects, not their order

    The linker resolves symbols.

  7. Why does a build script need set -e?

    Answer

    A failed compile would otherwise leave a stale object and a successful link

    A stale binary is the worst kind of build.

  8. What does the compiler look for when it meets use mod_a?

    Answer

    The interface file mod_a.mod

    It does not search the tree for sources.

  9. When must the build directory be thrown away?

    Answer

    When the compiler version or the flags change

    The module format belongs to the compiler.

  10. What does -Wintrinsic-shadow warn about?

    Answer

    A user name that looks like an intrinsic and may confuse a reader

    scaled against the intrinsic scale in this build.

The programs on this page were built with GNU Fortran (Alpine 15.2.0) 15.2.0 and run on Alpine Linux 3.24.3 (x86_64) in a Docker container.

Article author: Arthur Isaev