Porting a legacy program
A port is a change of shape that must not change the answer. The program below computes a mean and a maximum from a table in a common block, in fixed form with a labelled DO and a labelled FORMAT; the port puts the table in a module, the procedure in a module procedure with intents, and the loop in DO ... END DO. Both are built and run here, and a diff of their output is empty.
The old program
Two units share a table of five values through COMMON /DATA/, the main program fills it and the subroutine returns the mean and the maximum. The loop is closed by the label 10, and the result is printed through the label 20.
The file legacy.f:
C LEGACY: MEAN AND MAXIMUM OF A TABLE
PROGRAM LEGACY
IMPLICIT NONE
INTEGER N
REAL V(5), MEAN, VMAX
COMMON /DATA/ V, N
N = 5
V(1) = 3.0
V(2) = 8.0
V(3) = 1.0
V(4) = 6.0
V(5) = 4.0
CALL STATS(MEAN, VMAX)
PRINT 20, MEAN, VMAX
20 FORMAT('MEAN = ', F6.2, ' MAX = ', F5.1)
END
SUBROUTINE STATS(MEAN, VMAX)
IMPLICIT NONE
INTEGER N, I
REAL V(5), MEAN, VMAX, SUM
COMMON /DATA/ V, N
SUM = 0.0
VMAX = V(1)
DO 10 I = 1, N
SUM = SUM + V(I)
IF (V(I) .GT. VMAX) VMAX = V(I)
10 CONTINUE
MEAN = SUM / N
END
gfortran -Wall -Wextra -std=legacy -ffixed-form legacy.f -o legacy
./legacy
MEAN = 4.40 MAX = 8.0
The program is correct, which is the starting point of every port: the old code works, and the reason to change it is that a reader cannot see its data flow and a compiler cannot check it. V and N arrive in the subroutine through a declaration that has to match the main program exactly, and MEAN leaves through a dummy argument with no INTENT, so nothing says which way the value travels.
The five steps
The port keeps the arithmetic and changes one thing at a time:
- Put the shared data in a module. V and N become module variables with a default value, and the COMMON statement disappears from both units.
- Put the subroutine in the same module, after CONTAINS, and give the dummy arguments INTENT(OUT). The unit can now see the table without declaring it.
- Replace DO 10 ... and its CONTINUE with DO and END DO, and indent the body.
- Replace the labelled FORMAT and PRINT 20 with a format string in the PRINT.
- Move the filling of the table into a procedure of the module, so the main program is three statements, and rename the units so that the file says what the code does.
Each step keeps the program runnable, and the output is compared after every one. That is the whole method: a port that cannot be checked against the old output is a rewrite, and a rewrite of numerical code needs a test suite before it starts, not after.
The ported program
The file modern.f90, two modules and a program in one file:
module stats_data
implicit none
integer :: n = 0
real :: v(5) = 0.0
end module stats_data
module stats_mod
use stats_data
implicit none
private
public :: stats, fill
contains
subroutine fill()
v = [3.0, 8.0, 1.0, 6.0, 4.0]
n = size(v)
end subroutine fill
subroutine stats(mean, vmax)
real, intent(out) :: mean, vmax
integer :: i
real :: total
total = 0.0
vmax = v(1)
do i = 1, n
total = total + v(i)
if (v(i) > vmax) vmax = v(i)
end do
mean = total / real(n)
end subroutine stats
end module stats_mod
program legacy
use stats_mod
implicit none
real :: mean, vmax
call fill()
call stats(mean, vmax)
print '(a,f6.2,a,f5.1)', 'MEAN = ', mean, ' MAX = ', vmax
end program legacy
gfortran -Wall -Wextra -std=f2018 modern.f90 -o modern
./modern
MEAN = 4.40 MAX = 8.0
The arithmetic is the same to the statement: the same sum, the same comparison, the same division, in the same order. What changed is that the table is now visible to a reader of the module and to the compiler, the two dummy arguments say which way they carry values, and the loop ends where a reader expects it to. The program is free form, so -std=f2018 is enough and the legacy flag is gone.
The same output
The check that the port is right is a diff of the two outputs, and it is empty:
./legacy > old.txt
./modern > new.txt
diff old.txt new.txt
(no output: the files are identical)
The two binaries are already in the same folder at this point, which is why the page builds the old one first. A real project keeps the old binary or its recorded output in the test tree, adds the new program beside it, and makes the diff part of the build; a difference is then a failure with the two numbers in it.
The output comparison is necessary and not sufficient. It proves that the port did not change the answer for this input, and it says nothing about the inputs nobody recorded: a table of five values covers neither the empty table nor the table with a repeated maximum. That is why the port of a program that matters is also the point at which a test suite is written, and why the next part of the course is about testing and the capstones.
Rules for a port
Record the output before the first change, with the real input, and keep it. Change one thing at a time and run the comparison after each step. Replace the storage before the control flow, because a module makes the rest of the unit checkable. Keep the arithmetic in the same order until the output is known to be stable, then improve it with a test that shows the improvement. And delete the legacy flag last: a program that still needs -std=legacy has not been ported, it has been reformatted.
Exercises
- Change the order of the two additions in stats and see whether the mean changes. What does that say about a port that reorders arithmetic?
- Put the table in a file and read it with READ and IOSTAT. Which unit changes, and which does not?
- Add an INTENT(IN) dummy for the table and pass it as an argument instead of using the module. Which version is easier to test?
- Build legacy.f with -std=f2018 and -ffixed-form. Which warnings appear, and which of them would you fix first?
Questions
A new set of questions in a new order every time. Choose one answer for each, then check.
-
What is the first thing a port needs?
Answer
The recorded output of the old program
Without it there is nothing to compare against.
-
What replaces the common block?
Answer
A module with the variables in it
The module is compiled with its users.
-
What replaces the labelled DO?
Answer
DO ... END DO
The label and the CONTINUE disappear.
-
Why give the dummy arguments INTENT?
Answer
So the compiler checks which way a value travels
A port that cannot be checked is a rewrite.
-
What does
diff old.txt new.txtprint when the port is right?Answer
Nothing
Identical files.
-
Which step comes first?
Answer
Replacing the storage
A module makes the rest checkable.
-
Why is an identical output not enough?
Answer
It covers only the inputs that were recorded
The empty table and the repeated maximum are unrecorded.
-
When can the legacy flag go?
Answer
When the program builds and runs without it
Otherwise the program was reformatted, not ported.
-
What does the ported program keep identical?
Answer
The arithmetic and its order
Only the shape changes.
-
Which is the better test of a port?
Answer
A recorded output compared after every step
One step at a time, one comparison at a time.
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