Build System (Prev/Up) Basics: Compiling (Next)

PSCF is compiled using a system of unix makefiles. This page gives an overview of the build process, i.e., the process of compiling the PSCF source code and creating executable files. The discussion given here and in subsequent pages assumes familiarity with discussion of the PSCF directory structure given in a previous page .

Compilation and installation of PSCF involves the following operations:

Compiling all compilable source files in the src directory
Creating a static library file in each namespace-level subdirectory of the src directory
Creating the executable files (pscf_r1d, pscf_rpc, and optionally pscf_rpg) and installing them in the bin directory by default

Various types of file involved in this process are described below.

Source file compilation

All files in the PSCF repository that contain C++ or CUDA C++ code are located in the src directory tree. Files with file name suffix *.cpp or *.cu are compiled by the build system, and are referred to here as either compilable source files or simply source files. When each such source file is compiled, the build system creates two associated files that we refer to as an object file and a dependency file:

An object file is a file with file name suffix .o that contains the object code created by compiling the associated source file.
A dependency file is a makefile fragment with file name suffix .d that contains a lists of all the the prerequisites of the associated object file.

The object and dependency file that are created by compiling a source file have the same base file name as the associated source file, with different file name suffixs.

Each dependency file contains a list of paths to files that are "prerequisites" of the corresponding object file. This list includes the associated source file and all other C++ files (header files) that are directly or indirectly included into the source file via C/C++ preprocessor "include" directives. This list of prerequisites is used by the PSCF build system to keep track of when an existing object file has become out-of-date due to modifications of one or more of its prerequisite files.

Namespace-level library files

The PSCF build system also creates a static library with file name suffix .a in each namespace-level subdirectory of the src directory. Each such library contains all of the object code that is created by compiling the source files in the corresponding namespace-level directory. The name of each library file is given by a prefix "lib", followed by the base name of the associated namespace-level directory, followed by a suffix ".a". For example, the file "librpc.a" is a library file located in the src/rpc directory that contains the contents of all of the object files that are created by compiling source files in the src/rpc namespace-level directory.

Intermediate files and build directories (bld or src)

The object (*.o), dependency (*.d), and library (*.a) files that are created during the build process are referred to collectively as "intermediate" files. The directory in which all such intermediate files are placed is referred to as the build directory.

The PSCF makefile system is designed to allow a user to perform either an "out-of-source" build or an "in-source" build. An "out-of-source" build places all of these intermediate files in a build directory that is distinct from the src directory. By default, PSCF uses the bld subdirectory of the PSCF root directory as the build directory for out-of-source builds. In an "in-source" build, these intermediate files are instead placed within the src directory.

During an in-source build, the PSCF build system places the *.o object file and the *.d dependency file that are created by compiling each source file in the same subdirectory of src as the associated source (*.cpp or *.cu) file. During an out-of-source build, these two files are instead placed in an analogous subdirectory of the bld directory tree. To make this possible, the bld directory is required to have an internal directory structure analogous to that of the src directory.

The library file that contains object code created by compiling all the source files in a namespace level directory of the src directory is placed in the root of the corresponding namespace level directory of the chosen build directory. The file librpc.a is thus placed in the directory bld/rpc during an out-of-source build or in directory src/rpc during an in-source build.

Main program files and executable files

The three program-level subdirectories of the src directory (named r1d, rpc, and rpg) each have a source file that contains the main program function for one of the three PSCF programs (i.e., the C function named "main"). The base name of this main program file is the same as the name of the executable file that is created from it. For example, the main program source file in directory src/rpc is named pscf_rpc.cpp, and this is used to create the executable file named pscf_rpc.

When the code in one of the three program-level directories of the build directory is compiled, the build system:

compiles all the source files in the program-level directory other than the main program file
creates a static library containing the resulting object files
compiles the main program file, and links the resulting object file to all relevant library files to create an executable file

By default, the resulting executable file is created in the PSCF bin directory.

In each program-level subdirectory of src, the makefile rule that creates the executable file links to library files located in other namespace-level directories on which the relevant program-level depends. Thus, for example, the rule to create the pscf_rpc executable (which is defined in the file src/rpc/makefile) links the object file src/rpc/pscf_rpc.o that is created by compiling the main program file src/rpc/pscf_rpc.cpp is linked to library files src/util/libutil.a, src/pscf/libpscf.a, src/prdc/libprdc.a, and src/rpc/librpc.a. Each of these library files is also listed as a prerequisite to the rule that creates the executable file, which force the build system to create or recreate any non-existent or out-of-date libraries as needed before attempting to create an executable.

Build System (Prev / Up) Basics: Compiling (Next)