Compile Time Options (Prev) Generating Documentation (Next)
The build system for PSCF is based on unix makefiles.
Using the "make" command
Individual programs or groups of programs may be compiled by invoking the "make" command with an appropriate target name, using the syntax
where "target" represents a target name such as "all" or "pscf_pc". The command "make" with no target is equivalent to "make all".
The make utility may be invoked from the PSCF root directory (named pscfpp/ by default), or from either the src/ or bld/ build subdirectories of this root directory. The same names are used for the main make targets in all the three cases. Invoking make from the bld/ directory performs an out-of-source compilation in which intermediate files are installed in the bld/ directory tree. Invoking make from the PSCF root directory with a target that causes compilation generally has the same effect as invoking make with the same target from the bld/ directory, and so also performs an out-of-source compilation. Invoking make from within the PSCF src/ directory, however, will instead perform an in-source compilation that installs intermediate files in the src/ directory, alongside the source files. Makefile targets that create executable programs all install the resulting executable files in the PSCF bin/ directory by default, for either out-of-source or in-source compilation.
This page explains the most important makefile targets in more detail than given in the overview of instructions. The following instructions assume that you have already made the required changes to environment variables and run the configure script before using the make utility to compile.
Compilation
All of the makefile targets described below can be invoked either from either the PSCF root directory or bld/ directory to perform out-of-source compilation, or from the src/ directory to perform in-source compilation.
all:
To compile all programs in the PSCF package, enter either
with no target or (equivalently)
The behavior of this command depends on whether CUDA compilation has been enabled. If CUDA compilation is disabled (which is the default behavior), then the "make all" command only compiles the CPU programs pscf_1d and pscf_pc. If CUDA compilation has been enabled, this command also compiles the GPU-enabled pscf_pg program.
CUDA compilation can be enabled or disabled by using the -c option of the setopts script, e.g., by entering "./setopts -c1" to enable CUDA compilation or "./setopts -c0" to disable CUDA, , as discussed in more detail here. When CUDA compilation is disabled, "make all" is equivalent to "make all-cpu". When CUDA compilation is enabled, "make all" equivalent to calling "make all-cpu" followed by "make pscf_pg".
pscf_1d:
To compile only the pscf_1d program, simply enter:
If entered before compiling any other code, this command will:
- Compile a large number *.cpp files in the util/, pscf/ and r1d/ namespace-level subdirectories of the src/ directory.
- Install corresponding object (*.o) and dependency (*.d) files in corresponding locations within the chosen build directory (i.e., in either the bld/ or src/ directory)
- Create a static library (with file extension *.a) in each of these three namespace-level subdirectories of the build directory.
- Compile and link the main program file src/r1d/pscf_1d.cpp and install an executable file named pscf_1d in the PSCF bin/ directory.
To recompile these programs after making any changes to configuration files (e.g., after enabling or disabling the debugging feature or changing compiler command line options), simply reissue the "make r1d" command. The build system will detect if you have changed any of the relevant configuration files, and will recompile any file that might be effected by such changes.
pscf_pc:
To compile only the pscf_pc CPU program for periodic structures, enter:
from the PSCF root, bld/ or src/ directory. This command will cause the system to:
- If needed, compile all *.cpp files in the src/util/, src/pscf/, and src/prdc directories that have not been previously compiled, and create associated static library files in these directories.
- Compile all of the *.cpp class files in the src/rpc/ directory, and ' create a corresponding static library file named librpc.a.
- Compile and link the main program pscf_pc.cpp, and install an executable program file named pscf_pc in the PSCF bin/ directory.
all-cpu:
To explicitly build the pscf_1d and pscf_pc CPU programs, but not the GPU-enable pscf_pg program, enter
This is equivalent to entering "make pscf_1d" followed by "make pscf_pc".
pscf_pg:
This pscf_pg target only functions if CUDA has been enabled (e.g., by entering "./setopts -c1") on a computer with an appropriate NVIDIA GPU and CUDA development kit. To compile the pscf_pg GPU-enabled program for periodic structures on such a computer, enter
from either the PSCF root directory or the desired build directory. If successful, this will compile code from the rpg/ subdirectory of the src/ directory, compile code from the util/, pscf/ and prdc/ directories if needed, place object, dependency and library files in subdirectories of the chosen build tree, and install an executable named pscf_pg in the PSCF bin/ directory.
Documentation
To create a local copy of the html files for this web manual, enter
from either the PSCF root directory or docs./ subdirectory. This procedure requires that doxygen be installed, as discussed in greater detail on the following page.
Clean-up
The following makefile targets remove files in order to clean up after compilation, rather than creating files.
clean:
If, for any reason, you would like to clean up after compiling by removing all of the object, dependency and library files that are generated during compilation, you may enter
from either the relevant build directory or from the PSCF root directory. The clean target removes all the intermediate files generated by compilation, but does not remove the final executable files or any files that were installed by the configure script.
If "make clean" is invoked from the PSCF root directory, it removes all such intermediate files in both the bld/ and src/ directory trees. If "make clean" is invoked from the src/ or bld/ directory, it only removes such files from the build directory tree in which it is invoked.
The "make clean" command can also be invoked from almost any subdirectory of the src/ directory tree in order to remove recursively remove intermediate files from that directory and its subdirectories, or from namespace level subdirectories of the bld/ directory.
clean-bin:
The "clean-bin" command removes all pscf executable files with names of the form pscf_* from the PSCF bin/ directory, which is where they are normally installed. It does not remove any other executable files that are installed in the bin/ directory by the configure script.
clean-docs:
The "clean-docs" command removes any files that have been generated in the docs/ directory by the doxygen documentation generation utility, including all of the html files that are created in the docs/html directory.
veryclean:
The "make clean" and "make clean-bin" commands discussed above remove files that are generated by compilation, but do not remove various files that are installed by the configure script, among which are a variety of makefile fragments and C++ header files. To remove these files in addition to all of those removed by the "clean", "clean-bin" and "clean-docs" targets, enter
from the PSCF root directory. This command returns the entire PSCF directory tree to a state very similar to the state it had immediately after the repository was created by cloning a remote repository.
After you run "make veryclean", you will need to rerun the configure script before attempting to compile any code.
The "veryclean" target erases all of the files that are generated by the configure script, compilation, and the documentation generator. There are, however, a few types of files that do not exist in the repository but that it will not erase. Specifically, it will not erase any compiler configuration files files that the user may have created in the make/compiler directory. After invoking "make veryclean", a user can thus invoke the configure script again with the name of a previously created compiler configuration file as an argument in order to recreate a previous initial configuration.
Invoking make from within src/
When compiling in-source, by invoking make from within the src/ directory tree, users may also invoke "make all" from almost any subdirectory of src/ in order to compile a smaller set of source files. Invoking the command
from almost any subdirectory of the src/ directory tree will compile all C++ files in the tree rooted at that subdirectory, without compiling any code outside of that subdirectory.
Invoking "make all" from a subdirectory of a namespace level directory (i.e., a subdirectory of the src/util, src/pscf, src/r1d, src/prdc, src/rpc, or src/rpg directory) will generally compile all the *.cpp and (if CUDA is enabled) *.cu source files in that directory and any nested subdirectories.
Invoking "make all" from any namespace level subdirectory of src/ will compile of all the *.cpp and (as appropriate) *.cu source files in the directory tree, and also create a static library file containing all of the resulting object code. In addition, invoking "make all" from the r1d/, rpc/ or rpg/ subdirectories of src/ will compile, link and install an executable program located in that directory. For example, entering "make all" from src/r1d directory will create a static library named src/r1d/libr1d.a, and install an executable named pscf_1d in the bin/ directory.
Rationale : The ability to invoke "make all" from a subdirectory of src/ is designed to allow developers to use the command line to easily recompile a a few recently modified files from within the directory in which they are working. Typically, when a developer is adding a new feature or fixing a bug, they will be usually be actively editing only a few files within a single subdirectory of the src/ directory. Other files in the same subdirectory will often be left untouched during this process. The system for keeping track of dependencies used by the PSCF build system guarantees that invoking "make all" from the directory containing the files of immediate interest will only cause recompilation of source files that have been modified since they were last compiled or include header files that have recently been modified. A common work flow during development for those who use a command line interface for development is thus to edit a file, exit the editor, and then invoke "make all" from the directory containing the modified file to attempt compilation of the modified file.
Comment : Invoking make with the name of a single file as a target (e.g., with the name of a *.o object file) generally does not work as intended, unless one uses the full absolute path to the file as the make target. The reason for this is that patterns and dependency files used by the PSCF makefile system all use absolute paths. The build system thus may not recognize a relative path to a file as equivalent to the absolute paths used in the files that define makefile patterns and dependencies among files. Consistent use of "make all" from within a subdirectory of src/ for in-source compilation avoids this problem, because "make all" causes the "make" utility to try to compile a list of source files whose locations are specified within the makefile system as absolute paths.
Compile Time Options (Prev) Installation (Up) Generating Documentation (Next)
Generated on Mon Apr 14 2025 16:29:26 for PSCF by
1.12.0