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
- program is the main unit. Every executable starts there, and a file may hold at most one main program but any number of the other units.
- module is a named collection of declarations, constants, types and procedures. It holds no statements that run; its job is to be used. A module can use another module.
- subroutine is a procedure called with call. It takes arguments, may change them, and returns nothing but through them.
- function is a procedure used inside an expression. It returns one value, and in a contains section or a module it also declares the type of that value.
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
- Move square out of the module into the program's contains section. How many files do you build now?
- Remove private from the module and try to call describe from another module. What changes?
- Delete mathmod.mod and run the two-file build again. Does it work, and why?
- 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.
-
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.
-
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.
-
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.
-
What does
use mathmod, only: squaredo?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.
-
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.
-
What does
-cdo?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.
-
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.
-
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 pAnswer
8
Procedures in a contains section are visible in the whole program unit.
-
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.
-
What does
privateat 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