|
PSCF v1.1
|
Environment Variables (Prev) Out-of-Source and In-Source Builds (Next)
Users must run a bash script named "setup" after installing all required dependencies before attempting to compile any code in the PSCF package. This script is located in the pscfpp/ root directory, and must be executed from this directory. It is usually only necessary to invoke the setup script once, before the first time you compile any code.
The setup script installs several files that are needed to compile pscfpp but that are not installed by cloning the github repository. Most of the files installed by this script are files that the user may need to modify in order to customize or extend the package. These include include configuration files that a user may need to modify in order to adapt the simpatico build system to a particular environment or to enable optional features.
The most important file created by the setup script is a file named config.mk that is installed in the root directory of both the pscfpp/bld and pscfpp/src directory trees. This is a makefile fragment that acts as the main configuration file for compilation. It assigns values to makefile variables that define the compiler executable names for C++ and CUDA code, command line options passed to the compilers, paths to various directories used by the package during compilation or execution (e.g., paths to source code, build, installation and data directories), and paths for required external libraries.
The copy of the config.mk file that is installed in the the pscfpp/bld directory is used as the main configuration file for an out-of-source build, in which intermediate files are created in the bld/ directory tree. The copy in the pscfpp/src directory is the main configuration file for an in-source build. The brief overview of directions for compilation given on a previous page give instructions for an out-of-source build.
To create a default configuration appropriate for a generic unix-like environment, change directory (cd) to the pscfpp/ root directory, and then enter:
Note the dot and backslash ("./") before the name of the script. These must be included to tell the unix shell to look for an executable file named setup in the current working directory, rather than searching the directories listed in the PATH environment variable for an executable with this name.
The default configuration should work for most linux environments. It also should work for a Mac with an Intel CPU in which the "homebrew" package manager was used to install GSL and FFTW. The definitions used in this default configuration are defined in a file named pscfpp/make/compiler/default.
To create an environment that should work correctly for a newer Mac with Apple silicon (i.e., the Apple M1 or M2 chip) on which homebrew was used to install dependencies, enter:
This will use a compiler setup file pscfpp/make/compiler/mac-si-homebrew that was designed for such an environment. This setup file adds paths to appropriate subdirectories of /opt/homebrew to search paths used by the compiler to find header files and libraries.
The hardware used for a Mac OS system is relevant if homebrew was used to install dependencies because the homebrew project decided to use the introduction of new CPU hardware (apple silicon vs Intel chips) as an opportunity to introduce new conventions for paths without breaking backwards compatibility on existing computers. As a result of this decision, homebrew uses completely different path conventions on Intel and Apple-Si Macs.
The setup script creates the main config.mk files that are installed in the pscfpp/bld and pscfpp/src by reading a compiler setup file from the pscfpp/make/compiler directory and concatenating the contents of that file with other makefile fragments. The compiler setup file is a relatively short makefile fragment that contains definitions of makefile variables that define compiler names, a variety of compiler options and paths that the compiler uses to find header and library files for external packages that PSCF depends on.
When the "setup" script is invoked with no argument, the setup script uses a file named pscfpp/make/compiler/default for this purpose. This file contains a default configuration appropriate for a generic linux-like system in which the "g++" command is used to invoke the gnu C++ compiler to compile C++ files, the "nvcc" command is used to invoke the NVIDIA CUDA compiler, and paths to the gsl and fftw libraries are in standard locations.
When the "setup" script is invoked with one argument, that argument is interpreted as the name of a file in the pscfpp/make/compiler directory that should be used as the compiler setup file. For example, the command "./setup mac-si-homebrew" causes the script system to read and use the contents of the file pscfpp/make/compiler/mac-si-homebrew. The command "./setup", with no argument, is equivalent to "./setup default".
Users can create additional customized compiler setup files to adapt compiler options to the environment that exists on a specific computer. For example, suppose that a user created a file named pscfpp/make/compiler/local by making a copy of the "default" file from the same directory, and edited the variable definitions in that file to account for pecularities of the user's machine. Invoking the command
would then cause the setup script to create config.mk configuration files in both the src/ and bld/ directories that both include the contents of the customized file make/compiler/local.
In order to create a customized compiler setup file, a user will need to understand the meanings of some of the variables defined in such files. Toward this end, we recommend that users first read the comments in the file make/compiler/default that explain the meaning and use of each of the makefile variables. Users should then run the setup script with no argument and inspect the file bld/config.mk, which is created by the setup script. If you compare the contents of the files bld/config.mk and make/compiler/default, you will see that the contents of the "default" compiler setup file will have simply been copied verbatim into the middle part of the resulting bld/config.mk file.
For most users, the first step in creating a customized compiler setup file, if needed, will be to copy either the default or mac-si-homebrew file in the make/compiler directory to another file with a different name in the same directory (e.g., "local"), and use this copy as a starting point for customization.
Users can change values of variables defined in the main config.mk configuration files either by creating a customized compiler setup file in the make/compiler directory before running the setup script, as described above, or by directly editing the files bld/config.mk and/or src/config.mk files after running the setup script.
In order to figure out what modifications work on your system, you may find it useful to first run the setup script with one of the existing compiler setup files (default or mac-si-homebrew) and then edit resulting config.mk file in the bld/ or src/ directory to try out possible modifications.
After you have figured out what modifications are needed by this method, you can copy the modified set of definitions to a modified compiler setup file. Suppose that you have created such a file named "local" and installed it in the make/compiler directory. To use this file, and test that it works as intended, first enter
from the pscfpp/ root directory to remove all the files installed by the preceding setup process, including any edited config.mk files. Then enter "./setup local" to repeat the setup process while using use your customized setup file.
The advantages of putting required customizations in a modified compiler setup file are that:
If you ever decide to rename or move the root directory for the pscfpp repository, you should run "make veryclean" before moving this directory, and will then need to rerun the setup script after moving it.
Rationale: The setup script queries the operating system to identify the absolute path to the root directory that contains this script. This path is then stored in a variable that is used as a prefix to construct absolute paths to various subdirectories such as the src/, bld/, and data/ directories. The setup script thus must to be rerun after the path to the root directory is changed in order to update these stored path variables.
Environment Variables (Prev) Installation (Up) Out-of-Source and In-Source Builds (Next)
1.9.5