|
PSCF v1.1
|
Out-of-Source and In-Source Builds (Prev) Makefile targets (Next)
The PSCF build system is designed to allow users to enable or disable conditional compilation of optional features during compilation. Thus far the only such optional features are "debugging" and "CUDA" features. The "debugging" feature is used to add additional run-time sanity checks (such as run-time checking of array index bounds) at a slight cost in performance. The CUDA feature enables conditional compilation of CUDA code on machines that have an appropriate nVidia GPU and CUDA development kit.
The pscfpp/src and pscfpp/bld directories are used as build directories for in-source and out-of source compilation, respectively. After the setup script has been run, each of these two standard build directories will contain an exectuable shell script named "configure". The configure script can be used to modify configuration files that control what features are enabled when code is compiled. The configure 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 pscfpp/ root directory also contains a similar .configure script that can be invoked to apply identical changes in compile-time features to the configuration files in both the src/ and bld/ directories.
The configure script functions by editing configuration files that are used by the makefile system to define what actions should be taken during compilation. These configuration files are installed by the setup script. The configure script must thus be invoked after the setup script, but before compiling.
The "debugging" feature is enabled or disabled by invoking configure script with the "-d" option with an option parameter "1" to enable or "0" to disable, before compiling source code. The debuggin 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 pscfpp/ root directory. To disable debugging before compiling, one would instead enter
The same commands can also be invoked from bld/ or src/ directory to enable or disable debugging only in a single build directory.
Compilation of CUDA code can be enabled or disabled by invoking a configure script with the "-c" option, with an option parameter "1" to enable CUDA compilation or "0" to disable CUDA compilation. Compilation of CUDA code is disabled by default. To enable compilation of CUDA source files in any code compiled in either the bld/ or src/ directory, one would enter
from the pscfpp/ 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).
Before attempting to compile CUDA code, one should use the configure script to set compiler to generate code 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 code for a particular GPU architecture. As also discussed here, this architecture id is a string of the form "sm_IJ" in which I and J represent the major and minor version numbers for the CUDA "compute capability" of the relevant GPU. This command sets the value of the variable NVARCH which is defined in file src/config.mk or bld/config.mk, and which is passed as an argument of the "-arch" option to the nvcc compiler. By default, NVARCH is set to "sm_35", corresponding to compute capability 3.5, which is the appropriate level for a K40 GPU.
The -q command line option of the configure 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 pscfpp/bld/ directory and then enter
This should result 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 "./configure -q" from the pscfpp/ root directory instead yields a report that shows which optional features are enabled in both the bld/ and src/ directory.
Invoking the configure script with the -h ("help") option, by entering
produces a list of all command line options accepted by the script.
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 configure 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/, fd1d/, pscpc/, and pspg/ 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 setup 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)
1.9.5