Modules, USE and ONLY
A module is the unit that holds what a program shares: constants, types and procedures. Its users say use and get the interface of every public name with the name itself, which is why a module is both the code and the documentation of a library. This lesson builds two modules, imports from them with only, hides one name, renames another, and looks at the file the compiler leaves behind.
A module
The file module.f90 has a module of constants, a module of geometry that uses it, and a program that uses both:
module constants
implicit none
real, parameter :: pi = 3.14159265
real, parameter :: e = 2.71828183
end module constants
module circle
use constants, only: pi
implicit none
private
public :: area, circumference, radius_of
real, parameter :: default_radius = 1.0
contains
function area(r) result(a)
real, intent(in) :: r
real :: a
a = pi * r * r
end function area
function circumference(r) result(c)
real, intent(in) :: r
real :: c
c = 2.0 * pi * r
end function circumference
function radius_of(a) result(r)
real, intent(in) :: a
real :: r
r = sqrt(a / pi)
end function radius_of
end module circle
program module_demo
use circle, only: area, circumference, radius_of
use constants, only: eulers => e
implicit none
print '(a,f10.4)', "area r=2 : ", area(2.0)
print '(a,f10.4)', "circumference : ", circumference(2.0)
print '(a,f10.4)', "radius of 50 : ", radius_of(50.0)
print '(a,f10.4)', "e : ", eulers
end program module_demo
gfortran -Wall -Wextra -std=f2018 module.f90 -o module
./module
area r=2 : 12.5664
circumference : 12.5664
radius of 50 : 3.9894
e : 2.7183
The area and the circumference of a circle of radius two happen to be the same number, which is the arithmetic of the two formulas and not a mistake: 4 pi and 4 pi. The radius of a disc of area fifty is about 3.99, and the constant e arrived under the name eulers.
USE and ONLY
use circle, only: area imports one name and nothing else. Without the only the whole public interface of the module arrives, which is convenient in a small program and unhelpful in a large one: a reader can no longer tell where a name came from, and two modules with a name of the same kind clash.
The rule worth keeping is that every use in a new program has an only list, and the list is sorted, so the imports of a file are its dependencies at a glance. The program units lesson has the order in which the compiler needs the modules.
PRIVATE and PUBLIC
private with no list makes every name of the module private, and the public lines then name the interface the module offers. The helper constant default_radius stays inside; a program that asks for it is refused:
module hidden
implicit none
private
integer, parameter :: secret = 42
integer, parameter :: shown = 7
public :: shown
end module hidden
program baduse
use hidden, only: secret
implicit none
print *, secret
end program baduse
gfortran -Wall -Wextra -std=f2018 baduse.f90 -o baduse
baduse.f90:10:19:
10 | use hidden, only: secret
| 1
Error: Symbol 'secret' referenced at (1) not found in module 'hidden'
baduse.f90:12:17:
12 | print *, secret
| 1
Error: Symbol 'secret' at (1) has no IMPLICIT type
Two errors for one mistake: the name is not in the module interface, so the import fails, and the print then has a name with no type. A private default with a public list is the layout to write: a name that is not listed is not part of the promise, and the promise is the module.
Renaming a name
use constants, only: eulers => e imports e and calls it eulers inside this program. The form is local => remote, it works for a constant, a variable, a type and a procedure, and it is how two modules with a name of the same kind are used together.
A rename is local: the module keeps its name and every other user keeps it too. A program that renames a long-standing name in its own scope is telling a reader that the two names are the same thing, which is worth a comment when the reason is not obvious.
The .mod file
Compiling the file above wrote circle.mod and constants.mod into the working directory, one per module and named after it. The file holds the interface a user needs: the names, the types, the parameters and the bodies of the procedures it can inline. It is not portable between compilers, and it is not meant to be read.
The consequence is the build order. A program that uses circle cannot be compiled before circle.mod exists, so a Makefile lists the module before its users, and a build from scratch has to respect that. The build lessons write the Makefile; submodules, the next subject, are the way to keep the interface in the module and the code somewhere else.
A module layout
A program of more than a few hundred lines is a set of modules with one job each: one for the types, one for the arithmetic on them, one for the input and output, and a program that uses the first three. The constants module of this lesson is the smallest useful example, and the geometry module shows the other rule: a module imports with only and exports with public, so its dependencies and its promises are both visible at the top of the file.
A module has no state of its own unless it declares a variable, and a variable declared in a module is shared by every user for the life of the program. That is convenient for a constant and dangerous for anything else: a module variable is a global, and a program that keeps its data in its procedures does not need one.
Exercises
- Import e without a rename and print it. Which name do you use?
- Make pi private in the constants module. Which line of circle then fails, and why?
- Add a public function to circle that returns the diameter, and call it from the program. Which lines change?
- Write two modules that both declare a constant called n and use them in one program with a rename. Does it build?
Questions
A new set of questions in a new order every time. Choose one answer for each, then check.
-
What does a module hold?
Answer
Constants, types and procedures that other program units can use
The module is the unit of sharing in Fortran.
-
What does
use circle, only: areaimport?Answer
The name area and nothing else from the module
ONLY restricts the import to the listed names.
-
What does this program print?
module m implicit none integer, parameter :: a = 3 end module m program p use m, only: b => a implicit none print *, b + 1 end program pAnswer
4
The constant arrives as b and the sum is four.
-
What does
privatewith no list do in a module?Answer
Makes every name private unless a PUBLIC line names it
The default flips and the public list becomes the interface.
-
What is the form of a rename in a USE statement?
Answer
local => remote
The new name is on the left of the arrow.
-
What does compiling a module write?
Answer
A .mod file named after the module
The .mod file carries the interface.
-
Why does the build order matter with modules?
Answer
A user of a module cannot be compiled before its .mod file exists
The compiler reads the interface from the .mod file.
-
What is a variable declared in a module?
Answer
A value shared by every user of the module
It is a global with module scope.
-
Why is
onlyworth writing on every USE?Answer
It records the dependencies and prevents name clashes
The list shows where each name came from.
-
What does gfortran report when a program imports a private name?
Answer
Error: Symbol ... not found in module
A private name is not part of the module interface.
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