Program units: program, module, subroutine, function

A Fortran file is not a program. It is a sequence of program units, each with its own start, its own end and its own set of declarations, and one of them is the main program that the linker turns into an executable. This lesson names the four kinds of unit, shows what each one may hold, and builds a module and a program as two separate files, which is where the build order of Fortran comes from.

The four program units

The fifth kind, submodule, arrived with Fortran 2008 and lets a module's interfaces live apart from their implementations. It is a tool for large projects and later lessons do not need it.

Each unit is independent: the variables of one are not visible in another unless they are passed as arguments or reached through a module. That is a stronger rule than C's, where everything at file scope is global, and it is the reason a Fortran program of ten thousand lines can still be read one unit at a time.

A module

The module below holds one function and one subroutine. private makes everything in it hidden by default and public names the two procedures a user may call; without the pair, everything would be public and a change of an internal name could break other files.

The file mathmod.f90:

module mathmod implicit none private public :: square, describe contains pure function square(x) result(y) real, intent(in) :: x real :: y y = x * x end function square subroutine describe(name, value) character(len=*), intent(in) :: name real, intent(in) :: value print *, name, "=", value end subroutine describe end module mathmod

Every body sits after the single contains of the unit, never before it. Compile the file on its own, without linking, and gfortran writes two outputs next to it.

gfortran -Wall -Wextra -std=f2018 -c mathmod.f90
ls

mathmod.f90
mathmod.mod
mathmod.o
use_mod.f90

mathmod.o is the machine code, the same kind of object file a C compiler makes. mathmod.mod is the interesting one: a small binary file with the interface of the module, meaning the names, types and argument lists of everything public. It is not documentation and not a header in the C sense; the compiler reads it when another file says use mathmod.

A program that uses it

The program names the module and the two procedures it needs. only keeps the rest of the module out of its namespace, so a name in the module that clashes with a name in the program is not a problem.

The file use_mod.f90:

program use_mathmod use mathmod, only: square, describe implicit none call describe("square of 3", square(3.0)) call describe("square of 0.5", square(0.5)) end program use_mathmod

Compile this file before the module exists and the build stops. The compiler is not looking for the source of the module and cannot see it; it wants the interface file, and there is none.

gfortran -Wall -Wextra -std=f2018 -c use_mod.f90

use_mod.f90:2:7:

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

Fatal Error means the compiler could not carry on: without the interface it does not know that square takes a real and returns a real, and guessing is not allowed. That is also the good news in the message: the interface is checked, so a call with the wrong number of arguments is an error at the call, not a crash at run time.

The build order

The module comes first, because the program needs its .mod file. In a folder where mathmod.mod already exists from the compile above, one command builds both files and links the binary, and the order of the names on the command line then does not matter.

gfortran -Wall -Wextra -std=f2018 use_mod.f90 mathmod.f90 -o use_mod
./use_mod

square of 3= 9.00000000
square of 0.5= 0.250000000

A Makefile states the order once instead of remembering it: the target use_mod.o depends on mathmod.mod, which depends on mathmod.o. gfortran can also write those dependencies itself, -MM for the ones outside the standard library, and the lesson on make builds the rule from them.

Deleting a .mod file is safe: it is generated, and the next build writes it again. Deleting a .o file is safe for the same reason. Editing a .mod file by hand is not: the format is the compiler's, and a hand edit can make the compiler read a module that does not match its object code.

Procedures inside a program

A main program may hold its own procedures in a contains section, after the last executable statement. They see the variables of the program, which makes a short helper cheap to write and a long one dangerous: a procedure inside the program cannot be tested on its own, because there is no way to call it without running the program.

The file inner.f90:

program inner implicit none print *, "square of 5:", square(5.0) contains pure function square(x) result(y) real, intent(in) :: x real :: y y = x * x end function square end program inner

gfortran -Wall -Wextra -std=f2018 inner.f90 -o inner
./inner

square of 5: 25.0000000

The rule of thumb this course follows: a procedure used once and shorter than twenty lines goes inside the program; anything else goes into a module, where a test can call it directly.

Exercises

  1. Move square out of the module into the program's contains section. How many files do you build now?
  2. Remove private from the module and try to call describe from another module. What changes?
  3. Delete mathmod.mod and run the two-file build again. Does it work, and why?
  4. Add a second module that uses mathmod. Which file must be compiled first?

Questions

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

  1. How many main programs may a file hold?

    Answer

    One

    A file may hold any number of modules, subroutines and functions, but one main program.

  2. What does a module contain that runs at program start?

    Answer

    Nothing: a module holds declarations and procedures, not statements that execute

    A module is compiled for its interface; its procedures run only when called.

  3. What is stored in a .mod file?

    Answer

    The interface of the module, for the compiler of another file

    The .mod file carries names, types and argument lists; the machine code is in the .o file.

  4. What does use mathmod, only: square do?

    Answer

    It imports square and nothing else from the module

    The only list keeps the other public names of the module out of the program.

  5. Which error does a program that uses an uncompiled module give?

    Answer

    Fatal Error: Cannot open module file 'mathmod.mod' for reading at (1): No such file or directory

    The compiler looks for the interface file and stops when it is missing.

  6. What does -c do?

    Answer

    It compiles to an object file and does not link

    Compile-only: the output is the .o file, and for a module also the .mod file.

  7. Which unit returns a value used inside an expression?

    Answer

    A function

    A function returns one value; a subroutine is called with CALL and returns through its arguments.

  8. What does this program print? program p implicit none print *, twice(4) contains integer function twice(n) result(r) integer, intent(in) :: n r = 2 * n end function twice end program p

    Answer

    8

    Procedures in a contains section are visible in the whole program unit.

  9. Why does the build order matter for modules?

    Answer

    A user of the module needs the .mod file that its compile writes

    The compiler reads the interface file, which exists only after the module is compiled.

  10. What does private at the top of a module change?

    Answer

    Everything is hidden unless a public statement names it

    The default flips to private, and public :: names the exceptions.

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