Basics: Compiling

Build Process (Prev)         Basics: Adding a New Source File (Next)

This page briefly explains how to compile either the entire PSCF package or a subset of the source code files within PSCF. The discussion assumes familiarity with the discussion of the build process given on the previous page.

Compiling with "make all"

To compile a set of PSCF source files, one generally must invoke the command "make all" from a working directory within either the src or bld directory tree. The choice of which source files will be compiled, and whether they are compiled in-source or out-of-source, is determined by the location of the working directory from which "make all" is invoked.

Invoking "make all" from within the src directory tree results in in-source compilation. Invoking it from within the bld directory instead results in out-of-source compilation. Invoking "make all" from the root of the src directory tree causes the build system to perform an in-source build of the entire package. Invoking "make all" from either the PSCF root directory or the root of the bld directory tree instead causes an out-of-source build of the entire package.

The "make all" command can also be invoked from subdirectories of the src directory in order to perform in-source compilation of a subset of the PSCF source files. Invoking "make all" from almost any subdirectory of the src directory tree causes in-source compilation of all of the .cpp and *.cu source code files in the tree rooted at that subdirectory. The main exception to this is the src/test directory, which contains header files for a unit test framework, and does not contain a makefile.

The "make all" command can also be invoked from namespace-level subdirectories of the bld directory tree directory. Doing so causes out-of-source compilation of all source code files in the corresponding namespace level directory within the src directory tree. The "make" command cannot, however, be invoked from lower-level subdirectories of the bld directory tree, which do not contain makefiles.

When "make all" is invoked from a namespace level directory of either the src or bld directory, the static library (*lib.a) file associated with that directory is also created or updated if required to keep the library file up to date. In the case of program-level directories, an executable file is also created.

Development workflows

When working on PSCF, developers may go through a cycle in which they edit a few files in a lower level directory of the src directory, then invoke "make all" from within the same directory to compile the resulting modified files, and then go back to editing. One might reasonably ask if the repeated use of "make all" in this workflow causes unnecessary recompilation of source files that have not changed. In fact, it does not, because the build system is designed to automatically keeps track of which files are out of date, and to only recreate an existing object file if it determines that it has become out-of-date because of changes to its "pre-requisite" files (i.e., changes to the associated source file or files that are directly or indirectly included into that source file). The details of how this works are described in subsequent pages.

Some developers who have worked with makefile systems for other packages may be tempted to try to explicitly re-create a single object file by giving the name of the object file as a target (i.e., a command line argument) of the "make" command. This generally does not work as intended for PSCF unless one gives the absolute path to the target object file, defined relative to root of the entire filesystem. For example, imagine that you want to explicitly rebuild the object file src/pscf/chem/Monomer.o within a PSCF root directory with an absolute path /users/smith/pscfpp, where smith the name of a user with a home directory /users/smith . You could do this by typing the command

make /users/smith/pscfpp/src/pscf/chem/Monomer.o

from with the src, src/pscf, or src/pscf/chem directory. Simply typing "make Monomer.o" from within the src/pscf/chem directory, however, would fail. An absolute path is required for this purpose because the PSCF makefile system stores all paths of object file targets and prerequisite C++ files internally as absolute paths, and the "make" command is generally unable to recognize a relative path such as "Monomer.o" as a synonynm for the corresponding absolute path. Use of the "make all" command avoids the need to type out long absolute paths, and generally does what one wants.

Cleaning up

Invoking the command "make clean" from any working directory in the src or bld directory tree that contains a makefile will remove all of the intermediate files that would be created by invoking "make all" from the same directory. Invoking "make clean" from the PSCF root directory removes all intermediate files (i.e., object, dependency and library files) from both the bld and src directories. The "make clean" command does not, however, remove any final executable files that are installed in the bin directory, and does not remove any files that were created by the configure script.

Invoking the command "make veryclean" from the pscfpp root directory removes all of the intermediate files that would be removed by the "make clean" command, and also removes the primary executable files and all files that were created by the configure script. This command thus returns a users PSCF repository to a state similar to that obtained immediately after the repository was created by cloning the pscfpp github repository.

Build Process (Prev)         Build System (Up)         Basics: Adding a New Source File (Next)