Basics: Compiling (Prev) Make and Makefiles (Next)

In order to add new features to PSCF, developers often need to add new compilable source files to the src directory. This page briefly explains how to add edit files used by the build system to tell the build system to compile any such new source files.

Almost every subdirectory of the src directory tree contain a file named "sources.mk". This file is a makefile fragment that is included into multiple makefiles. The purpose of each such file is to maintain a list of all of the *.cpp and *.cu files in that directory that should be compiled when PSCF is built. The most important part of this file is a statement near the top that assigns a makefile variable a value that contains a list of source files in the relevant directory. To tell the build system to compile a new source file, this file simply needs to be added to this list in the sources.mk file within the directory that contains the new source file.

For example, consider the sources.mk file in the directory src/r1d/iterator. This directory contains source code files for several classes that implement different SCFT iteration algorithms that can used by the pscf_1d program, and a few related classses. The relevant part of in this directory, which appears at the top of the file, is a makefile statement that looks like this:

r1d_iterator_=\
  r1d/iterator/Iterator.cpp \
  r1d/iterator/IteratorFactory.cpp \
  r1d/iterator/NrIterator.cpp \
  r1d/iterator/BinaryRelaxIterator.cpp \
  r1d/iterator/AmIterator.cpp

In this statement, the string r1d_iterator_ is the name of a makefile variable whose value is a space separated list of names of compilable source files in the relevant directory r1d/iterator. The name of the corresponding variable defined in the sources.mk in each subdirectory of the src directory is given by mangled form of the path to that subdirectory from the src directory, in which the slash characters that separate directory names in the actual directory path are replaced by understores, and an extra underscore is appended at the end. In this example, the path r1d/iterator of the relevant directory relative to the src directory is translated into a variable name r1d_iterator_. The value of this variable must be a space-separated list containing paths to all of the source files in this directory that should be compiled by the build system. The path for each file in this list must be given as its path relative to the src directory. This list given in this example is formatted with one file per line, but the backslash at the end of each line is a symbol used by the make command to indicate continuation of a line. The resulting string is thus equivalent to one we could also obtain by writing all of these paths on single line, separated by spaces.

Suppose that one had created a new SCFT iteration algorithm for use by this program that was implemented as a new class named NewIterator. Suppose that this class is defined by several files that are located in the rpc/iterator directory, including a new compilable source file named NewIterator.cpp To add a the new source file to the build system, one would simply add a backslash to the end of the last line of the existing definition of rpc_iterator_, and then add the path to the new source file as an additional line. The modified definition of r1d_iterator_ would like like this:

r1d_iterator_=\
  r1d/iterator/Iterator.cpp \
  r1d/iterator/IteratorFactory.cpp \
  r1d/iterator/NrIterator.cpp \
  r1d/iterator/BinaryRelaxIterator.cpp \
  r1d/iterator/AmIterator.cpp \
  r1d/iterator/NewIterator.cpp

The path to each new file must be given as a path relative to the src directory, as for existing files.

The content of sources.mk files, including elements that are not shown here, is discussed in more detail on a separate page.

Basics: Compiling (Prev) Build System (Up) Make and Makefiles (Next)