Out-of-Source and In-Source Builds (Prev) Makefile targets (Next)
Users of PSCF may modify several settings before compiling the package to control whether particular features are enabled or disabled when the package is later compiled, and to set some parameters that are passed to the compiler. A set of bash scripts named "setopts" is provided to simplify the process of modifying these compile-time options.
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". The setopts script in each build directory (i.e., in src or bld) may be invoked from within that directory to modify which features will be enabled or disabled in code that is subsequently compiled in that build directory.
Each setopts script changes settings by editing build configuration files that are used by the makefile system to define what actions should be taken during compilation. These configuration files are files named config.mk that are installed by the configure script in the bld and src directories. To change which features are enabled when PSCF is compiled, the setopts script must thus be invoked after running the configure script, but before compiling.
The PSCF root directory also contains an analogous setopts script, which we refer to as the "global" setopts script. The 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.
Enabling or disabling debugging
The "debugging" feature of PSCF can be enabled to add additional run-time sanity checks, at a slight cost in performance. One important additional type of check enabled by this feature is run-time checking of array index bounds in the code used to access elements of the collection of array containers used throughout PSCF. The debugging feature is disabled by default, for efficiency, but we recommend that developers enable it at times during debugging and testing of new code.
The "debugging" feature is enabled or disabled by invoking a setopts script with the "-d" option before compiling the package. Invoking the "-d" with an optiona parameter "1" enables debugging, while an option parameter "0" disables debuggin. One could thus enter
to enable the debugging feature, or
to disable debugging. Entering setopts with the -d option from the PSCF root directory enables or disables debugging checks for both in-source and out-of-source compilation, while entering the same commands from the src or bld directory enables or disables this feature only for in-source or out-of-source compilation, respectively.
Enabling or disabling CUDA compilation
The CUDA feature enables conditional compilation of CUDA code on machines that have an appropriate nVidia GPU and a 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. One could thus enter
to enable CUDA compilation, or
to disable it. Executing the setopts script with the -c option from the PSCF root directory enables or disables CUDA compilation for both in-source and out-of-source compilation, while entering the same commands from within the src or bld directory enables or disables CUDA compilation only for in-source or out-of-source compilation, respectively.
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_70", corresponding to compute capability 7.0, which is the appropriate level for a V100 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
If debugging and CUDA compilation were both disabled (the default configuration), this would result in the output
If debugging were disabled but CUDA compilation had been enabled, the output might instead look something like this:
The value of the CUDA architecture id (the string set by the -a option) is printed only if CUDA compilation is enabled.
Entering "./setopts -q" from either the bld or scr directory yields a report that shows which optional features are enabled or disabled by settings in the config.mk file in the same directory. Entering "./setopts -q" from the PSCF root directory instead yields a report that shows current settings for both the bld and src directories.
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
All mutable attributes of the PSCF build system are defined by the contents of a pair of files named "config.mk" that are installed in the src and bld directories by the configure script. We refer to these two "config.mk" files as build configuration files. The build configuraiton files are makefile fragments that contain definitions of makefile variables, and that are included by other makefiles during the build process. The file bld/config.mk defines the configuration used for out-of-source compilation, while src/config.mk defines the configuration for in-source compilation.
The setopts scripts use standard unix utilities (such as the "sed" stream editor) to make required modifications of these build configuration files. Users may instead use a text editor to modify the config.mk files directly, rather than by using the setopts scripts, if they are comfortable doing so. The configuration files contain extensive comments that explain the meaning and usage of all of the makefile variables defined in those files.
Out-of-Source and In-Source Builds (Prev) Installation (Up) Makefile targets (Next)
Generated on for PSCF by
1.14.0