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:

  1. 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.
  2. 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.
  3. Replace DO 10 ... and its CONTINUE with DO and END DO, and indent the body.
  4. Replace the labelled FORMAT and PRINT 20 with a format string in the PRINT.
  5. 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

  1. 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?
  2. Put the table in a file and read it with READ and IOSTAT. Which unit changes, and which does not?
  3. 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?
  4. 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.

  1. What is the first thing a port needs?

    Answer

    The recorded output of the old program

    Without it there is nothing to compare against.

  2. What replaces the common block?

    Answer

    A module with the variables in it

    The module is compiled with its users.

  3. What replaces the labelled DO?

    Answer

    DO ... END DO

    The label and the CONTINUE disappear.

  4. 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.

  5. What does diff old.txt new.txt print when the port is right?

    Answer

    Nothing

    Identical files.

  6. Which step comes first?

    Answer

    Replacing the storage

    A module makes the rest checkable.

  7. 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.

  8. When can the legacy flag go?

    Answer

    When the program builds and runs without it

    Otherwise the program was reformatted, not ported.

  9. What does the ported program keep identical?

    Answer

    The arithmetic and its order

    Only the shape changes.

  10. 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