Out-of-Source and In-Source Builds (Prev) Makefile targets (Next)
The PSCF build system provides a set of scripts named "setopts" that allow the users to set some optional compile-time features of the package to be enabled or disabled when it is compiled, and to set some parameters that are passed to the compiler.
The "setopts" scripts
The PSCF src/ and bld/ directories are used as build directories for in-source and out-of source compilation, respectively. After the configure script has been run, each of these two standard build directories will contain an exectuable shell script named "setopts". A setopts script can be used to modify configuration files that control what features are enabled when code is compiled.
The setopts script in each build directory may be invoked from within that directory (i.e., from the src/ or bld/ directory) in order to modify which features will be enabled and disabled in code that is subsequently compiled in that build directory.
The PSCF root directory (usually named pscfpp/) also contains an analogous setopts script. That "global" setopts script can be invoked to apply identical changes in compile-time features to the configuration files in both the src/ and bld/ directories.
The setopts scripts function by editing configuration files that are used by the makefile system to define what actions should be taken during compilation. These configuration files, all of which are named config.mk, are installed by the configure script. A setopts script must thus be invoked after running the configure script, but before compiling.
Enabling or disabling debugging
The "debugging" feature of PSCF can be enabled to add additional run-time sanity checks (such as run-time checking of array index bounds) at a slight cost in performance. The "debugging" feature is enabled or disabled by invoking setopts script before compiling the package with the "-d" option, using an option parameter "1" to enable debugging or "0" to disable it. The debugging feature is disabled by default. To enable debugging checks in the code built in either the src/ or bld/ directory one would enter
from the PSCF root directory. To instead disable debugging before compiling, one would enter
The same commands can also be invoked from bld/ or src/ directory to enable or disable debugging only in a single build directory.
Enabling or disabling CUDA compilation
The CUDA feature enables conditional compilation of CUDA code on machines that have an appropriate nVidia GPU and CUDA development kit. Compilation of CUDA code is disabled by default. Compilation of CUDA code can be enabled or disabled by invoking a setopts script with the "-c" option, with an option parameter "1" to enable CUDA compilation or "0" to disable CUDA compilation.
To enable compilation of CUDA source files in any code compiled in either the bld/ or src/ directory, one would enter
from the PSCF root directory. To disable CUDA compilation, one would instead enter
The same commands can be invoked from a specific build directory (i.e., from within the source or src/ or bld/ directory) to enable or disable compilation of CUDA code only in that build directory (i.e,. only in code that is compiled out-of-source or in-source).
Setting a target GPU architecture
Before attempting to compile CUDA code, one should use a setopts script to set the compiler to generate code optimized for the specific type of NVIDIA GPU that is installed on the computer on which the program will be run. This is done by issuing a command of the form
in which [architecture id] represents a string identifier for a particular GPU architecture.
The architecture id that is passed to the -a option is a string of the form "sm_MN" in which M and N represent the major (M) and minor (N) version numbers for the CUDA "compute capability" of the relevant GPU. This command sets the value of the makefile variable NVARCH, which is defined in the file src/config.mk or bld/config.mk. The value of this variable is passed to the NVIDIA nvcc CUDA compiler as the parameter of the "-arch" compiler option. By default, NVARCH is set to "sm_35", corresponding to compute capability 3.5, which is the appropriate level for a K40 GPU.
The "query" (-q) option
The -q command line option of the setopts script may be used to query what optional features are currently set to be enabled or disabled during compilation. To see an example, change directory (cd) to the PSCF bld/ directory and then enter
This should result, for example, in the output
if debugging and CUDA compilation are both disabled (the default configuration), or
if debugging is disabled but CUDA compilation has been enabled.
Entering "./setopts -q" from the PSCF root directory instead yields a report that shows which optional features are enabled in both the bld/ and src/ directory.
The "help" (-h) option
Invoking the setopts script with the -h ("help") option, by entering
produces a list of all command line options accepted by the script.
Build configuration files
The configuration of the build system is actually defined by the contents of a set of files named "config.mk" in the src/ and bld/ directories. These files, which we refer to as build configuration files, are makefile fragments that are included by other makefiles during the build process. The setopts scripts work by editing the build configuration files.
Users may also edit these files directly if they are comfortable doing so. The configuration files contain comments that explain the meaning and usage of all of the variables defined there.
The directories src/ and bld/ contain analogous directory structures, and similar sets of build configuration files. In what follows, we will refer to src/ and bld/ generically as build directories. Both of these directories contains a set of five subdirectories named util/, pscf/, r1d/, pscpc/, and rpg/ that each contain C++ source files from a single C++ namespace. We refer to these top-level subdirectories of bld/ and src/ as "namespace-level" subdirectories.
After the configure script has been run, each build directory will contain 6 build configuration files files named "config.mk", with one in the root of the build directory (i.e., in src/ and bld/) and one in each of the 5 namespace-level subdirectories of that directory. The config.mk file in the root directory of each build directory tree is the main build configuration file for code built in that directory. This file controls the choice of compiler and general options that are applied to all code built there. The config.mk files in the namespace level directories each specify more specialized options that are only relevant for code in specific subdirectories or C++ namespaces.
Out-of-Source and In-Source Builds (Prev) Installation (Up) Makefile targets (Next)
Generated on Fri Mar 28 2025 00:57:29 for PSCF by
1.12.0