make and a project layout
Three compiles and a link are five commands to type and one order to remember, and a build that has to be retyped is a build that gets skipped. This lesson puts the project of lesson 111 under make: a src/ folder, a build/ folder, a Makefile that knows which module comes first, and four builds that show what a makefile does and does not redo.
The layout
The sources are the three files of the previous lesson, in src/; the build directory does not exist until make creates it:
tree .
.
├── Makefile
└── src
├── main.f90
├── mod_a.f90
└── mod_b.f90
1 directories, 4 files
The program is the one of lesson 111, main.f90 with its two modules, and it is the only file make has to be told about by name:
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 Makefile
A Makefile is a list of targets, each with its prerequisites and the command that builds it. What makes it correct for Fortran is the prerequisite of a module: build/mod_b.o depends on build/mod_a.o because it needs the module file that compiling mod_a writes.
The file Makefile:
FC = gfortran
FFLAGS = -Wall -Wextra -std=f2018
BUILD = build
all: $(BUILD)/app
$(BUILD):
mkdir -p $(BUILD)
$(BUILD)/mod_a.o: src/mod_a.f90 | $(BUILD)
$(FC) $(FFLAGS) -c $< -J $(BUILD) -o $@
$(BUILD)/mod_b.o: src/mod_b.f90 $(BUILD)/mod_a.o | $(BUILD)
$(FC) $(FFLAGS) -c $< -J $(BUILD) -o $@
$(BUILD)/main.o: src/main.f90 $(BUILD)/mod_b.o | $(BUILD)
$(FC) $(FFLAGS) -c $< -J $(BUILD) -o $@
$(BUILD)/app: $(BUILD)/mod_a.o $(BUILD)/mod_b.o $(BUILD)/main.o
$(FC) $^ -o $@
clean:
rm -rf $(BUILD)
.PHONY: all clean
Three details carry the whole thing. The commands are indented with a tab, not with spaces, or make refuses the file. $< is the first prerequisite and $@ the target, so the compile line names its source and its object without repetition. And | $(BUILD) is an order-only prerequisite: the directory must exist before the compile, but its timestamp is not a reason to rebuild.
The first build
make prints every command it runs, so the transcript of a build is also the documentation of it:
make
mkdir -p build
gfortran -Wall -Wextra -std=f2018 -c src/mod_a.f90 -J build -o build/mod_a.o
gfortran -Wall -Wextra -std=f2018 -c src/mod_b.f90 -J build -o build/mod_b.o
gfortran -Wall -Wextra -std=f2018 -c src/main.f90 -J build -o build/main.o
gfortran build/mod_a.o build/mod_b.o build/main.o -o build/app
./build/app
scaled = 2.50 5.00 7.50 10.00
Five commands and the program, and the order is the dependency chain of the previous lesson written down once. The binary lives in build/, so the source tree holds no object file and the clean target is one directory removal.
Rebuilds
Running make again does nothing, because every target is newer than its prerequisites:
make
make: Nothing to be done for 'all'.
Touching src/main.f90 recompiles that file and relinks, and nothing else:
touch src/main.f90
make
gfortran -Wall -Wextra -std=f2018 -c src/main.f90 -J build -o build/main.o
gfortran build/mod_a.o build/mod_b.o build/main.o -o build/app
Touching src/mod_a.f90 rebuilds the chain, because the module file changed and everything that uses it is out of date:
touch src/mod_a.f90
make
gfortran -Wall -Wextra -std=f2018 -c src/mod_a.f90 -J build -o build/mod_a.o
gfortran -Wall -Wextra -std=f2018 -c src/mod_b.f90 -J build -o build/mod_b.o
gfortran -Wall -Wextra -std=f2018 -c src/main.f90 -J build -o build/main.o
gfortran build/mod_a.o build/mod_b.o build/main.o -o build/app
The last two transcripts are the reason to write a makefile at all. The dependency is expressed once, by hand, and every rebuild after that is correct without anyone remembering which module comes first. A large numerical project is a hundred of those chains, and the two or three that a person would get wrong are exactly the ones that matter.
A failed compile
A typo in one source stops make at that file and returns a non-zero status, which a test script or a continuous integration job can see:
make
gfortran -Wall -Wextra -std=f2018 -c src/main.f90 -J build -o build/main.o
src/main.f90:8:3:
8 | printt '(a,4f6.2)', 'scaled =', v
| 1
Error: Unclassifiable statement at (1)
make: *** [Makefile:17: build/main.o] Error 1
The run ends with exit status 2, and the line make: *** [Makefile:17: build/main.o] Error 1 names the target and the line of the makefile. The old build/main.o is left in place, which is why the next make tries again rather than linking a binary from the previous source.
fpm is not in this image
The modern Fortran Package Manager, fpm, writes this makefile for you: it reads the use statements of the sources, works out the dependency graph, and builds in a directory of its own. A project with an fpm.toml builds with fpm build and tests with fpm test, and the order problem of this lesson does not arise.
It is not installed in this container, so this page does not show it and no output of it appears anywhere in the course. The makefile above is what fpm would have generated for three files, which is the honest reason to learn it once: the tool is convenient, and the dependencies it resolves are the ones written down here.
Exercises
- Add a fourth source that uses mod_a and is called from main. Which lines of the Makefile change?
- Replace the indentation of one command with spaces and run make. What does it say, and which line of the file does it name?
- Add a target run that depends on $(BUILD)/app and runs it. Why does it belong in .PHONY?
- Delete build/mod_a.mod by hand and run make. What happens, and what would have happened without the dependency on $(BUILD)/mod_a.o?
Questions
A new set of questions in a new order every time. Choose one answer for each, then check.
-
Why does
build/mod_b.odepend onbuild/mod_a.o?Answer
Compiling mod_b needs the module file that compiling mod_a writes
The prerequisite carries the Fortran module order.
-
What does
$<mean in a make rule?Answer
The first prerequisite
$@ is the target, $^ all the prerequisites.
-
What does
| $(BUILD)express?Answer
An order-only prerequisite: the directory must exist, its timestamp does not matter
Without it a changed directory would rebuild everything.
-
What does this make print after a successful build with no changes?
makeAnswer
make: Nothing to be done for 'all'.
Every target is newer than its prerequisites.
-
What does touching a module source rebuild?
Answer
The module and everything that uses it, then the link
The dependency chain follows the module files.
-
How must the commands of a make rule be indented?
Answer
With a tab
A space-indented recipe is refused.
-
What does make do when a compile fails?
Answer
It stops with a non-zero status and names the target and line
The transcript ends with "Error 1" and status 2.
-
What would fpm add to this project?
Answer
A dependency graph from the USE statements, so the order needs no writing
It is not installed here, so no output is shown.
-
Why keep the objects in build/?
Answer
The source tree stays clean and clean is one directory removal
It is a layout decision, and a good one.
-
What does
.PHONY: all cleantell make?Answer
These targets are not files, so always run their commands
A file named clean would otherwise confuse it.
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