Source File Lists (Prev) Coding Standards (Next)
The build system for PSCF relies on the unix "make" utility, and is controlled by a system of makefiles. Understanding of the build system thus requires some familiarity with make and the syntax of makefiles. The discussion of make and makefiles in given below is intended to serve as an initial introduction for developers and users who have little or no experience with make, while also providing some information about conventions used in makefiles within PSCF. Much more complete documentation of the make command is provided by the online manual for the GNU make command.
Make and makefiles
The "make" command is a standard unix utility that is used to control compilation and installation of large programs and software packages. The command is invoked from a unix command line by typing "make", optionally followed by one or more command line arguments.
Whenever make is invoked, it searches for an associated "makefile" that specifies the actions that can be performed by make. This makefile must be a file named "makefile" or "Makefile" in the current working directory (i.e,. in the directory from which the make command was invoked).
Makefile rules
A makefile generally contains a set of "rules". Each rule provide instructions for how to perfom a specific action or type of action, and may contain information about the dependencies among different files. The general syntax for a makefile rule is:
The "target" is a character string that may be either the name of a file that would be created by the associated action or a label that simply describes the purpose of the recipte. The "recipe" associated with a rule is a sequence of unix shell commands that required to perform an action. The "prerequisites" entry is a list of the names of files that are required as inputs to the rule. The list of prerequisites must appear on the same line as the target, separated from the target by a colon. The recipe must start on the line after the line containing the target, and may span one or more lines. In a peculiar quirk of makefile syntax, every line of a makefile recipe must start with an invisible tab character.
The simplest type of makefile rule is one in which the target is the name of an object file that is created by compiling a source file. In this case, the list of prerequisites normally contains the name of the associated *.cpp C++ source file and names of all of the *.h header files that the source file directly or indirectly includes. In simple cases, the recipe for such a rule could be a command that calls the compiler to compile the source file and create the target object file.
As example, suppose A is the name of a class that is defined in a header file A.h for which member functions that are defined in a source file A.cpp in the current working directory. A simple makefile rule for using the gcc compiler to create an associated object file named A.o might look like this:
The list of prerequisites for such a rule should include names of all header files that are directly or indirectly included into the source code file that is compiled. For example, if either A.h or A.cpp contained statements to include the header file "B.h" that contains the definition of another class named B, then B.h would also need to be included in the list of prerequisites for the target A.o.
The make utility uses prerequisite lists to make decisions about what existing files need to be rebuilt if related files are modified. The process for doing this is based on examination of file time stamps. Time stamps are metadata associated with files that indicate the most recent time that a file was modified, and when the file was first created. An existing file that is the target of a makefile rule is out-of-date, and thus needs to be rebuilt, if any file listed as a prerequisite of that target is either: (a) a file that has been modified since the last time that the target file was created or modified, or (b) the target of another makefile rule that can be shown to be out-of-date by examination of the prerequisites of that rule. A file that does not exist is also always out-of-date.
When a makefile rule is invoked, the make command will always first identify any out-of-date prerequisites of that rule that are targets of other makefile rules, then recursively apply any rules required to update all out-of-date prerequisites, and only then perform any actions specified by the recipe for the original rule. This behavior can cause invocation of a rule that builds one file to cause to a cascade of actions that build other related files.
As an example of this behavior, consider the case of a rule that builds an executable file. The rule for constructing an executable file often has a recipe that links an object file to one or more library files, and a list of prerequisites that includes the object file and the required libraries. Each library file may itself be the target of a rule that lists the object files that the library contains as prerequisites. Each of those object files is the target of a rule that compiles a corresponding source file. Invocation of a rule to build an executable file can thus cause the make utility to first compile a set of related source files to create or update any outdated object files, then use an archiver to create or update any outdated library files, and finally use a linker to create the requested executable file.
Makefile rules can contain the following three different types of target:
- File name targets, for which the target is the name of a specific file that needs to be created by the build system, such as an object, library or executable file.
- File patterns targets, for which the target is given by a filename pattern that, for example, might match any filename with a specific file name extension.
- Phony targets, for which in which the target is a label such as "clean" or "all" but that is neither a file name or a file name pattern, but merely serves as a label for the rule.
Rules with targets that are file name patterns or phony targets are referred to here pattern rules.
Pattern rules
A pattern rule is typically used to specify a general procedure for creating any target file with a specific file extension by applying a specific recipe to any corresponding files with the same base name but a different file name extension. The target of a pattern rule must contain exactly one instance of the wildcard symbol %, which may be matched by any continuous string of charcters. The % symbol may also used in one or more of the pre-requisites of a pattern rule to represent the same string as the one that matches % in the pattern for the target. For example, a rule with a target and prerequisite of the form
specifies how make any object file with of the form name.o from a source and header file with the same base name, with names of the form name.cpp and name.h.
Other automatically defined variables may be used in the recipe associated with a pattern rule to refer to the target and various prerequisites. Specifically, the symbol $@ refers to the target, $< refers to the first pre-requisite, and $^ refers to a list of all pre-requisites separated by spaces.
Rules for building individual files can be combined with pattern rules to concisely define build instructions. PSCF makefiles generally include a specific rule for each relevant *.o object file target in which the rule lists all of the prerequisites of that target file but does not explicitly specify a recipe. In this case, no recipe is required because make can infer the required recipe from a related pattern rule for which target file name matches the target pattern.
More detailed documentation of pattern rules is available here .
Phony targets
A makefile rule target that is not a file name or a file name pattern is referred to as a "phony" target. Rules with phony targets are used to label an action that is not designed to build a specific target file. Invoking make with an argument that is the name of a phony target always causes the make to rebuild any outdated pre-requisites of that target and then apply any associated recipe.
PSCF makefiles generally contain several standard phony targets. Every makefile contains named "all" and "clean". Upper level and namespace level directories generally have a targets named "veryclean". The purposes of these standard targets are:
- "all" builds all of the target files for which rules are defined in the makefile
- "clean" removes any files that were generated by making the "all" target.
- "veryclean" removes files that were generated either by calling the configure script or by running making "all".
The "all" target generally specifies a list of prerequisites but but no recipe. Invocation of the "all" rule thus causes make to rebuild any out-of-date prerequisites of the rule. The list of pre-requisites of the "all" target normally includes all of the file targets that the makefile is responsible for constructing.
The "clean" and "veryclean" targets instead generally include recipes but no pre-requisites. Invoking either of these rules simply causes make to apply the recipe, which removes files created previously by the build system.
Makefiles can specify that particular targets are phony (i.e., do not correspond to file names) by listing them as prerequisites of a standard built-in target named .PHONY. Thus for example, a makefile with three phony targets named "all", "clean" and "veryclean" could include a rule of the form
as a way of declaring that these three names are phony targets. The effect of the .PHONY target is to guarantee that the names of each pre-requisites will be treated as a phony targets even even if files with the names were found to exist.
Makefile variables
Makefiles may define and use variables. Each makefile variable is a symbolic name for a character string, which is known as the value of the variable. By convention, almost all variable names used in PSCF are strings of upper case letters and underscores, such SRC_DIR.
An expression for assigning a value to a makefile variable contains the name of the variable on the left of an equals sign and the value to the right. For example,
assigns an absolute path string as the value of variable ROOT_DIR.
A reference to the value of a variable is represented by a symbol in which the variable name in enclose in parentheses and a $ sign is placed before the opening parenthesis. For example, the symbol represents the value of the variable ROOT_DIR.
References to makefile variable values may be used on the right hand side of assignments and in other makefile expressions. For example, the makefile variable SRC_DIR is assigned a value by the expression
in which $ is expanded into the actual value of ROOT_DIR (i.e., the path to the PSCF root directory) and then concatenated with the string "/src" to obtain a string that is the path to the PSCF src directory.
Makefile include directive
Makefiles can use the "include" directive to include other make files or makefile fragments. For example, the directive
would cause the sources.mk file in the PSCF src/pscf directory to be copied verbatim into the current makefile.
Calling the make command
When make is invoked with a single argument that is the target of a makefile rule, and that target is either the name of a file or a phony target, then the make command will execute the action associated with that rule. For example,
will cause make to apply the recipe associated with the "clean" target in the associated makefile.
If make is invoked without any argument, by typing
on a line by itself, then, by default, the make command invokes the first rule in the associated makefile, which is known as the default rule. The default rule in every makefile in the PSCF repository has a phony target named "all". In the PSCF build system, the commands "make" and "make all" thus always have the same effect. The effect of either command is generally to create or recreate all of the main targets of the makefile and all of their pre-requisites.
When "make" or "make all" is invoked from the root, bld or src directory, make will build the entire PSCF package. When "make" or "make all" is invoked from a namespace level subdirectory of src or bld, make will compile almost all of the source files in that namespace level subdirectory tree and creates an associated library containing all of the resulting object files. (The only source files that are not compiled in this case are source files associated with unit tests in the tests subdirectory of a namespace level directory). When "make" or "make all" is invoked in the r1d, rpc, or rpg namespace level subdirectory of either the src or bld directory, make will also create an associated executable file named pscf_1d, pscf_pc, or pscf_pg, respectively, and install that file in the PSCF bin directory.
Dependency files (*.d files)
The pattern rules used by PSCF to compile a source file with file extension .cpp or .cu create both an object file with file extension .o and a dependency file with file extension *.d whenever a source file is compiled. The resulting dependency file defines a makefile rule that lists all of the prerequisites of the corresponding object file, but that has no associated recipe. The dependency file associated with an object file named Class.o defines a makefile rule that, is simplified form, might something like this:
The rule defined in a dependency file does not contain a recipe because the make utility can infer the required recipe from related pattern rules that specifies how to create any *.o object file from either *.cpp or *.cu source file with the same base name. The list of prerequisites for each object (*.o) file target includes the corresponding source file (with extension .cpp or .cu) and all of the header files (extension .h) that this source file directly or indirectly includes via C/C++ preprocessor #include directives. This list of prerequisites is generated automatically by using a compiler option to analyze these include directives. The list of prerequisites generated by the PSCF build system also generally includes one or more config.mk configuration files that define makefile variables whose values can affect conditional compilation of some features. Though not shown in the above example, the paths to the target and its prerequisites given in the rule defined in a dependency file are all given as absolute paths, defined relative to the root of the entire filesystem.
Makefiles that are located in subdirectories of the PSCF src or bld directories all contain expressions that include multiple dependency files via include directives of the form
In this type of expression, [directory] represents the mangled name of a directory, and [directory])_OBJS is the name of a makefile variable that lists all of the object file targets in that directory. The expression ([directory]_OBJS:.o=.d) uses a makefile text manipulation operator to replace the .o file extension in each file in this list by .d extension, thus creating a corresponding list of dependency files. The effect of this include directive is thus to instruct make to attempt to include the *.d dependency files associated with each of the object files listed in variable [directory]_OBJS.
The dash in front of the "include" keyword instructs make to continue quietly if any particular dependency file does not yet exist.
Because dependency files are created as a side effect of compilation, the dependency file associated with a source file does not exist before the first time that source file compiled. In this case, however, because the associated object file does not yet exist, the object file target is always out-of-date, since non-existent files are always out of date, and so will always be built if the object file target is is needed as a prerequisite of another target (e.g,, as a prerequisite of a library or executable file). The list of prerequisistes of an object file is thus actually not needed or relevant until the object file exists - the list of prerequisites of a makefile rule is only used to determine if an existing target file is out-of-date and thus needs to be recreated.
Build configuration files (config.mk files)
The PSCF src, bld and src/util directories each contain a file named config.mk that we refer to as a build configuration file. These are files that define and assign values to a variety of makefile variables that are needed throughout the build system, and that are included verbatim by other makefiles. Default versions of these three build configuration files are installed by the configure script. Configuration may be modified by the user, either by manually editing them or (more often) by using the setopt script to enable, disable or modify definitions of specific variables from the command line.
The config.mk files in the srd and bld directories are nearly identical files that contain code to assign values to the same set of variables, with equal default values for almost all variables. The only variable that is treated differently in these files by default is the variable BLD_DIR, which is assigned different values in src/config.mk and bld/config.mk in order to enable users to perform either out-of-source or in-source builds, as discussed elsewhere).
Most of the variables defined in the src/config.mk and bld/config.mk files fall into one of the following three categories:
- Directory path variables: The variables ROOT_DIR, SRC_DIR, BLD_DIR, and BIN_DIR specify absolute paths to the PSCF root directory and several of its subdirectories, as discussed in a previous manual page.
- Variables that enable optional features: The variables UITL_DEBUG and PSCF_CUDA control whether or not particular optional features are enabled when PSCF is compiled, as discussed here.
- Variables used in pattern rules: A variety of variables such as CXX, CPP_FLAGS, CXX_FLAGS, LD_FLAGS are used in the pattern rules for compilation of individual source files.
The meaning and usage of many of the variables defined in the these two very similar files is discussed in extensive comments with these files, as well as in the discussion of pattern rules given below.
Makefiles in upper-level directories (root, bld/ and src/ directories)
Complete instructions for users for how to compile and build PSCF are given in a another section of this manual. From the point of view of a user, the key step is simply to invoke "make" or (equivalently) "make all" from within any of three possible locations: Invoking make from either the PSCF root directory or the build directory performs an out-of-source build, while invoking make from the src/ directory performs an in-source build.
The recipes for the "all" target of the makefiles in the root, bld/ and src/ directories are all simply wrappers for make commands in lower-level subdirectories.
The rule for the "all" target for the makefile in the PSCF root directory is given by:
Here, is a standard variable that represents the name of the make command, so this recipe is equivalent to
This recipe instructs make to change directory to the bld/ directory and then invoke from there. Invoking make in the root directory is thus completely equivalent to invoking it from bld/. Invoking make from either of these locations performs an out-of-source build in which intermediate files are installed in the bld/ directory.
The makefiles in the bld/ and src/ directories each include the "config.mk" file located in the same directory. The "all" target in each of these two makefiles is given by:
In this rule, "all-cpu" refers to the phony target of a related rule
The recipe for the all-cpu target, which is invoked by the recipe for all, instructs make to simply cd into 5 of the 6 namespace level directories of src/ or bld/ and invoke make from within each of them. The 5 namespace directories that appear in the reciple for the all-cpu rule contain all of the code required to build the CPU programs pscf_1d and pscf_pc, but not that required to build the GPU program pscf_pg. The remaining line of the recipe for the "all" rule, contains the pair of commands "cd rpg; $(MAKE)$" that cause make to cd into rpg and call make from there in order to compile the code required to build the pscf_pg GPU program. This last line is surrounded by a makefile "ifdef ... if" block, however, that allows it to be executed if and only if compilation of CUDA code has been enabled by defining the variable PSCF_CUDA in the associated config.mk file.
Recipes for the "all" targets in these upper level makefiles thus simply instruct make to descent into to namespace level subdirectories of bld/ or src/ and recursively invoke itself from within these directories. Most of the nontrivial makefile code required to build PSCF thus appears within makefiles in the namespace level directories.
Makefiles in namespace-level directories
As already discussed, the src/ and bld/ directories have analogous internal structures, and either can be used as the "build" directory for, respectively, out-of-source or in-source builds. The src/ and bld/ directories each contain 6 subdirectories named named util/, pscf/, prdc/ r1d/, rpc/, rpg/ that we refer to as namespace level directories, because each contains the source code defined in a particular C++ namespace. Each namespace level subdirectory of src/ and bld/ contains a makefile that controls compilation of source files located in the corresponding subdirectory of src/.
The "all" target
The makefile in each namespace level subdirectory of src/ or bld/ contains a rule with a phony target named "all". Invoking "make" or "make all" from a namespace level directory invokes the "all" rule, and causes make to perform the following actions:
- The "all" rule compiles all of the source files in the corresponding namespace level subdirectory of src/, and places the resulting object and dependency files within the namespace level subdirectory from which make was invoked.
- The "all" rule creates a static library files that contains the contents of the resulting object files, and places that file in the root of the namespace level directory from which make was invoked.
- When invoked from the r1d/, rpc/ or rpg/ namespace level subdirectory of src/ or bld/, the "all" rule also creates an executable program file named pscf_1d, pscf_pc, or pscf_pg, respectively, and installs that file in the PSCF bin/ directory.
Each of these processes is described in a bit more detail below.
The object and dependency files that are created by compiling a source file both have the same base name as the corresponding source file, with different file name extensions. This object and dependency file are both placed either in the same directory as the source file, in the case of an in-source build, or in an analogous directory within the bld/ directory, in the case of an out-of-source build.
The library file that is created by the "all" rule of a namespace level has a name of the form lib[namespace].a, in which [namespace] denotes the name of the relevant namespacel level directory. For example, the library that is created by invoking "make" or "make all" from the bld/prdc/ directory is named bld/prdc/libprdc.a. This library is an archive that contains the contents of object files created by compiling all source files in the src/prdc directory.
The r1d/, rpc/, and rpg/ directories each contain a single source file named pscf_1d.cpp, pscf_pc.cpp, or pscf_pg.cu, respectively, that implements the main function for one of the executable programs created by PSCF. We refer to these as program source files. Invoking "make" or "make all" from within the r1d/, rpc/, or rpg/ namespace level directory of either bld/ or src/ will cause this file to be compiled and linked to library files in order to create a corresponding executable file that, by default, is installed in the PSCF bin/ directory. For example, invoking "make all" from either src/rpc or bld/rpc causes the creation of the executable file bin/pscf_pc.
Makefile fragments
In addition to a makefile, each namespace level subdirectory of the src/ directory contains 3 makefile fragments that are included by other makefiles. The names and contents of these three makefile fragments are summarized below:
| Filename | Contents |
|---|---|
| sources.mk | Lists of object file targets, rule for library |
| patterns.mk | Pattern rules for source file compilation |
| includes.mk | List of files to be included by makefiles |
Each of these types of file is described in more detail below.
Source list files (sources.mk)
As discussed in a previous manual page, the sources.mk file in each namespace level directory defines a makefile variable whose value is a list of the object files that should be created by compiling source files in that directory. The name of this variable is a string of the form [namespace]_OBJS, in which [namespace] represents the name of the relevant namespace level directory. For example, the file src/prdc/sources.mk file defines a variable of this kind that is named prdc_OBJS. Every file listed in the value of this variable is given as an absolute path to a file in the relevant build directory with a name that ends with file extension .o.
Each sources.mk file also defines variable whose value is the path to the associated library, and a makefile rule for constructing that library. The variable contains the path to the library has a name of the form [namespace]_LIB, where [namespace] represents the name of the namespace level directory. As an example, the relevant part of the file src/prdc/sources.mk file is shown below:
The first two lines of this makefile snippet assign prdc_LIB a value that is the absolute path to a file named libprdc.a in the prdc/ subdirectory of the relevant build directory (i.e., bld/ or src/). The absolute path to the build directory is given in the definition of prdc_LIB by the value of the makefile variable BLD_DIR.
Pattern rule files (patterns.mk):
The patterns.mk file in each namespace level directory defines the pattern rules that are used to compile *.cpp C++ files and *.cu CUDA C++ files in that namespace level directory. These pattern rules are discussed in more detail below.
Include list files (includes.mk):
The includes.mk file in each namespace level directory is a short makefile fragment that contains "include" statements that include makefile fragments that are required by all makefiles in the same directory and its subdirectories.
As example, the src/prdc/include.mk file contains the following include statements:
Comments:
- This file includes not only the patterns.mk and sources.mk file from the same prdc/ namespace level subdirectory of src/, but also sources.mk files from two other namespace level directories (util/ and pscf/) that contain code that are used within the prdc/ directory.
- This file also includes the config.mk build configuration file from the util/ subdirectory of the build directory, because this build configuration file contains a some makefile variable definitions that are needed elsewhere.
- This include.mk file does not include the main build configuration file located at /config.mk, for reasons that are explained below.
Example: namespace level makefile, with no program file
We are now in a position to explain the essential components of a makefile in a namespace-level subdirectory of bld/ or src/. We first consider the structure of a makefile in a namspace level directory such as pscf/ or prdc/ that does not contain a program file. As an example, the following code snippet shows the essential elements of the file bld/prdc/makefile that are necessary to execute the "all" rule defined in this file:
In this example, the three vertical dots below the makefile rule with the target "all" are used to indicate a section of the file that has been omitted for clarity. The omitted section of this file contains rules with targets named "clean" and "veryclean" that we do not need to consider in order to understand the implementation of the "all" rule.
This makefile has three sections that are marked by comments and horizontal separators.
The first section contains directives that includes several related makefile fragments, as indicated by the associated comment. In the first line of this section, the variable BLD_DIR_REL is assigned a value ".." that gives the relative path from the directory bld/prdc that contains this file to the build directory bld/, which is the parent directory. The string ".." is standard notation for the path to a parent directory in a unix filesystem. The following line then includes the build configuration file bld/config.mk in this parent directory. The last line of this section includes the file src/prdc/include.mk fle, which thus indirectly includes the required patterns.mk file and several other makefile fragments, as discussed above.
Note that the directive that includes the configuration file bld/config.mk uses a relative path to refer to the bld/ directory, rather than referencing the variable BLD_DIR to indicate this directory as done in most other places in the build system. This is necesssary because the variable BLD_DIR is defined in this config.mk configuration file, and so cannot be used until after this file has been included.
The second section of this makefile file lists several main makefile rules. All of these have been omitted here except for the rule with the target "all", which is the focus of this discussion. The list of prerequisites for the "all" rule contains all of the files in the list of object files in the relevant namespace-level directory, plus the associated library file . (Recall that prdc_OBJS and prdc_LIB are both defined in the file src/prdc/sources.mk that is indirectly included via the include.mk file). Invocation of the "all" rule thus causes any of the files in this list that are non-existent or out-of-date to be created or re-created.
The last section of this makefile uses the "include" directive to automatically include several long lists of dependency files into this makefile. Each of the included *.d dependency file contains a makefile rule that lists the prerequisites for a corresponding object file, and thus provides the information necessary for make to decide when a particular object file that already exists needs to be rebuilt because one or more of its prerequisites has been modified or become out-of-date.
Example: namespace level makefile, with a program file
Makefiles for the r1d/, rpc/, rpg/ namespace-level directories are slightly more complicated than the example given above because they each contain an additional rule to create an executable file.
As an example, we consider the makefile in directory src/rpc, which contains source code for pscf_pc program. This directory contains a file src/rpc/pscf_pc.cpp that defines the main function for the pscf_pc executable, which we refer to as the program source file. The object file that is created by compiling the program source file is listed as a pre-requisite of the corresponding executable file, which is created by the "all" rule because the executable file is listed as a pre-requisite of the "all" target.
The essential elements of the makefile in the src/rpc directory are shown below, with a few sections omitted for clarity:
As in the first example, we use vertical dots to indicate sections of the file that have been ommitted for clarity.
The following new elements are present this makefile, but do not exist in a namespace-level makefile for a directory that does not contain a program source file:
- Definition of a variable PSCF_PC gives the shared part of the paths for the object and dependency file that will be created by compiling the program source file src/pscf_pc.cpp, without the .o and .d file name extensions.
- Definition of a variable PSCF_PC_EXE gives the path to the resulting executable file, /pscf_pc.
- The executable file is listed as an additional pre-requisite of the "all" target.
- This makefile contains an additional rule to construct the executable by linking the object file .o to a list of libraries given by the value of the variable
- The dependency file .d that is created by compiling the program source file is included in the last line of the makefile
Invoking the "all" rule for this makefile builds all of the object files in the list , builds the resulting library , and also constructs the executable .
In a namespace-level directory that contains a program source file, the object file that is created by compiling the program source file is added to the object file list for that directory, and so is not added to the associated static library. This object file is instead created by the "all" rule because it is listed as a pre-requisite of the executable, and thus must be created in order to create the executable.
Pattern rules (patterns.mk files)
Each namespace level subdirectory of the src/ directory has a makefile fragment named "patterns.mk". This file defines pattern rules for compiling *.cpp and *.cu source files in that directory or namespace. These pattern rules have the same structure in all six namespace level directories.
The patterns.mk file in each namespace level source directory contains a pattern rule for compiling C++ source files with extension .cpp that always looks like this:
In directories that contain CUDA C++ source files, indicated by an extension *.cu, the patterns.mk file also contains an analogous pattern rule for compiling these files, which uses the NVidia CUDA compiler rather than a C++ compiler. Both of the patterns creates rules for creating an object file with file extension *.o in a subdirectory of the build directory $(BLD_DIR) by compiling a *.cpp or *.cu source file with the same base name in the corresponding subdirectory of the source directory $(SRC_DIR).
In these pattern rules, the symbol % is a wildcard that represents a string that appears in the path for the target file that may also appear in one or more pre-requisites. The rule shown above thus describes how to create a target object file in the build directory with a path of the form $(BLD_DIR)%.o by compiling a corresponding source file in the source directory with a path of the form $(SRC_DIR)/%.cpp, in which % represents the common part of the two paths. The common part of these paths may include one or more directory separator symbols and the name or names of subdirectories of the src directory, as well as the base file name. In order for this pattern rule to work correctly for out-of-source builds, the PSCF bld directory must have the same internal directory structure as the src directory.
The recipe for this rule contains two lines with different purposes. The first line of the recipe actually calls the compiler command, represented by value of the variable $(CXX), to compile the source file and create the object file. The second line is contained within a makefile ifdef construct that executes the second line if and only if the makefile variable MAKEDEP is defined (which it normally is). This second line calls a script whose name is given by the variable $(MAKEDEP) to create a corresponding dependency file with extension .d as a side-effect of compilation.
The following makefile variables are used in the first line of the recipe to define a rule for compiling a source file:
- BLD_DIR: Absolute path to the build directory
- SRC_DIR: Absolute path to the pscfpp/src directory
- CXX: name of the C++ compiler executable
- CPPFLAGS: flags for the C preprocessor
- CXXFLAGS: general flags for the C++ compiler (optimization, warnings, etc.)
- INCLUDES: directories to search for C++ header files, using the -I option
- DEFINES: String of any C++ preprocessor macro definitions
Values for the variables BLD_DIR, SRC_DIR, CXX, CPPFLAGS, CXXFLAGS and INCLUDES are all defined in the main config.mk configuration located in the root of the build directory.
The DEFINES variable, if not empty, contains a series of preprocessor macro definitions that are defined using the "-D" compiler option, which can be used to control use of the C/C++ preprocessor to control conditional compilation of some features. Thus, for example, if both debugging and CUDA compilation are enabled, the value $(DEFINES) within the file src/pscf/patterns.mk might expand to
The DEFINES variable is assigned a value in the patterns.mk files of each namespace level subdirectory of src/, and is assigned slightly different values in different directories.
The variables MAKEDEP and MAKE_DEPS are used only in the second line of this recipe, in order to construct a *.d dependency file.
The value of MAKEDEP is the name of a script that is used to generate dependency files. The value of this variable is assigned in the main config.mk configuration file in the build directory, and assigned a value bin/makeDep by default.
The value of MAKE_DEPS is a list of build configuration files that the script that creates dependency files should list as additional pre-requisites for all object files in the relevant namespace. Each additional dependency in this list is preceded by the symbol "-A" which the MAKEDEP script recognizes as a label for an additional dependency. The value of this variable usually expands to a string
that lists the config.mk configuration files in the build directory and in the util subdirectory of the build directory as additional pre-requisites. These files are listed as extra pre-requisites in the makefile rule for building an object file because they each contain definitions of makefile variables that, if modified, can change the list of preprocessor macros that are passed to the compiler via the DEFINES variable, and thereby change the assembly code that is produced by compilation.
The definitions of DEFINES and MAKE_DEPS within the file src/rpc/patterns.mk are shown below as an example:
The DEFINES variable is constructing by concatenating the variables (UTIL_DEFS, PSCF_DEFS, etc.) for this namespace (i.e., RPC_DEFS) and for all namespaces upon which this namespace depends (i.e., UTIL_DEFS, PSCF_DEFS, and PRDC_DEFS). The resulting string contains all of the preprocessor definitions that are allowed to be used by code in this namespace.
The MAKE_DEPS variable contains a list of build configuration files whose contents can effect compilation of source code in this namespace. This list always contains the main config.mk file from the parent build directory, the config.mk file for the namespace level directory of interest, and config.mk files for any namespace level directories upon which this directory depends. For the src/rpc directory, the MAKE_DEPS thus contains paths to the config.mk files in the pscf/, prdc/ and util/ subdirectories, as well as the main config file /config.mk. These build configuration files are added to the list of dependencies for every object file in this namespace because changes to these config.mk files can change which preprocessor macros are defined or which compiler options are set, and thus can change the contents of the resulting object files.
Makefiles in lower-level src subdirectories
As a convenience for developers, every subdirectory of the namespace level directories also contains a makefile. The "all" target of each such src/ subdirectory makefile executes an in-source build of the files in the subdirectory that contains makefile and any of its subdirectories. The structure of the makefiles in subdirectories of the namespace level directories is very similar to that of the namespace level makefiles, except that the all targets does not build a library or executable.
During development, if you are working from the command line using a text editor, one convenient way to test whether a source file that you have just modified compiles correctly is usually to just enter
from the directory that contains the new or newly modified source file. If automatic dependency generation is enabled, and if you only modify one class at a time, this will normally cause the build system to compile only the source file that you have just modified. If a directory contains more than one incomplete or broken file, you should usually comment out out all but one of these broken files (the one you are working on) in the definition of the [directory]_ variable in the corresponding sources.mk file, and then uncomment each such file when you are ready to work on it.
Use of absolute paths for object file targets
The file name conventions used in the PSCF makefile system make it awkward for a user to explictly request compilation of a specific source file by using the name of that file as an argument of the make command. The awkwards arises from the fact that the build system uses absolute paths for all object files targets, and the fact that the "make" program is not smart enough to recognize when an absolute and relative path are equivalent. As a result, the only way explicitly request compilation of a single source file is to use the absolute path to the object file as the argument of the make command. For example, if the absolute path to the root PSCF directory within a user account named "smith" was "/users/smith/pscfpp/", user "smith" could compile the source file src/rpc/simulate/Simulator.cpp by entering
or
from either the src/rpc/simulate or src/rpc directory. The need to type out such long absolute paths is so inconvenient, however, that we recommend developers instead who want to compile single files in-source instead get in the habit of simply using "make all" from the directory that contains the file of interest, as described above.
Source File Lists (Prev) Developer Information (Up) Coding Standards (Next)
Generated on Fri Mar 28 2025 00:57:29 for PSCF by
1.12.0