Environment Variables (Prev) Out-of-Source and In-Source Builds (Next)

Users must run a bash script named "configure" after installing all required dependencies and before attempting to compile any code in the PSCF package. This script is located in the PSCF root directory, which is named pscfpp/ by default. It is usually only necessary to invoke the configure script once, before the first time you compile any code.

Purpose

The configure script installs several files that are needed to compile PSCF 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 configuration files that a user may need to modify in order to adapt the PSCF build system to a particular environment or to enable optional features.

The most important type of file created by the configure script is a file named config.mk that is installed in the root directory of both the bld/ and 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 PSCF 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 src/ directory is the main configuration file for an in-source build. The overview of directions for compilation given on a previous page are instructions for an out-of-source build.

Default configuration

To run the configure script with default settings, change directory (cd) to the PSCF root directory (i.e., the pscfpp/ directory), and then enter:

./configure

Note the dot and slash ("./") before the name of the script. These two characters should be included to tell the unix shell to look for an executable file named configure in the current working directory, rather than searching the directories listed in the PATH environment variable for an executable with this name.

When the configure script is invoked with no command line arguments, as shown above, the script examines the operating system and environment, and attempts to choose settings appropriate to the detected environment. In our experience, this normally works for standard linux environments, and for Apple Mac computers on which the Homebrew package manager has been used to install GSL and FFTW.

If you run the configure script more than once, for any reason, we recommend that you always invoke

make veryclean

from the root PSCF directory before re-invoking the configure script. The "make veryclean" command removes all files that may have been created by the configure script or created by compiling PSCF.

Compiler configuration files

The configure script creates the main config.mk files that are installed in the pscfpp/bld and pscfpp/src directories. To do so, it chooses a so-called "compiler configuration file" from among several such files in the make/compiler directory and copies the contents of that file into a middle section of each of the config.mk files. For example, the compiler configuration file used for most linux environment is named make/compiler/linux-default. The compiler configuration file is a relatively short makefile fragment that defines all of the makefile variables that might require different values in different environments. Among these are makefile variables that define the C++ compiler name, a variety of compiler options, and paths that the compiler uses to find header and library files for external packages used by PSCF.

Letting the script choose a configuration file:

When the "configure" script is invoked with no argument, as described above, this script attempts to detect the operating system environment and choose an compiler configuration file that is appropriate for the environment. Currently, this mode can only choose between a file named "linux-default", which is the default choice, and file named "mac-si-homebrew", which is designed specifically for Apple Macs that use an Apple silicon M(X) CPU and the homebrew package manager.

The configuration file named make/compiler/linux-default is used if the script detects either a linux environment or an Apple OS X environment that does not have a homebrew installation configured for use with Apple silicon. The linux-default file is also used by default when no better choice can be identified. This file defines a default configuration in which the "g++" command is used to invoke the gnu C++ compiler, the "nvcc" command is used to invoke the NVIDIA CUDA compiler, and the gsl and fftw header files and libraries have been installed in standard subdirectories of /usr/local.

The configure script instead uses the file make/compiler/mac-si-homebrew if it detects a Mac OS X operating system and an installation of the homebrew package manager that is installed in the location used by homebrew for Macs with Apple Si M(X) CPU chips.

Relevance of CPU hardware on Apple Macs that use homebrew:

When PSCF is compiled on an Apple Mac on which the homebrew package manager was used to install dependencies, the type of CPU hardware on the computer is relevant because homebrew uses different path conventions for machines with Intel and Apple silicon CPUs. This is because the homebrew project decided to use the introduction of new Apple silicon M(X) CPU chips as an opportunity to introduce new conventions for file paths on new machines without breaking backwards compatibility on existing Intel computers. On older Macs with Intel CPUs, homebrew used path conventions consistent with those used by linux package managers, in which header and library files are installed in standard subdirectories of /user/local. This convention allows the use of the linux-default configuration file to compile PSCF on these machines. On Macs that use Apple silicon, homebrew instead installs header and library files in subdirectories of the /opt/homebrew directory, requiring the use of the specialized mac-si-homebrew file for this case.

Explicitly choosing a configuration file:

The configure script may also be invoked with a command line argument that explicitly specifies the name of a compiler configuration file located in the make/compiler directory. For example, the command

./configure linux-default

would explicitly specify use of the make/compiler/linux-default configuration file. If the configure script is invoked with a command line argument, then that argument is interpreted as the name of a file in the make/compiler directory, and the specified file is always used. In this case, the script does not attempt to inspect the environment or choose an appropriate file.

Creating a customized configuration file:

The only compiler configuration files that are currently distributed as part of the PSCF package are the files linux-default and mac-si-homebrew. If neither of these files proves sufficient, a user can create an new customized compiler configuration file in the make/compiler directory to adapt the compiler options and paths to their computer environment.

For example, suppose that a user created a file named make/compiler/local by making a copy of the "linux-default" file from the same directory, and edited the variable definitions in that file to account for pecularities of that user's computer. Invoking the command

./configure local

would then cause the configure script to copy the contents of the file make/compiler/local file into the config.mk files that it creates in both the src/ and bld/ directories.

In order to create a customized compiler configuration file, a user will need to understand the meanings of the variables defined in such files. Towards that end, we recommend that any such user first read the comments in the file make/compiler/linux-default that explain the meaning and use of each of the basic makefile variables. The user should then run the configure script with no argument and inspect the file bld/config.mk and/or src/config.mk that will be created by the configure script. Upon comparing the contents of the files bld/config.mk and make/compiler/linux-default, one should see that the contents of the linux-default file have been copied verbatim into the middle section of both config.mk files.

For most users, the first step in creating a customized compiler configuration file should be to copy either the linux-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.

Editing compiler configuration files vs. editing config.mk files:

Users can use either of two methods to change values of variables that are defined in the main config.mk files in the src/ and bld/ directories. They may either:

Create and modify a customized compiler configuration file in the make/compiler directory, before running the configure script, and pass the name of this file as an argument to the configure script, as described above.
Directly edit the config.mk files that the configure script creates in the bld and/or src directories, after running the configure script.

In order to figure out what modifications work on your system, users may find it useful to first run the configure script with one of the existing compiler configuration files (linux-default or mac-si-homebrew), then edit the resulting config.mk file in the bld/ or src/ directory, and compile in that build directory to test changes. After all required modifications have been identified, however, we recommend that users copy any required modifications to a new compiler configuration file in the make/compiler directory, run "make veryclean" from the PSCF root directory, and then rerun the configure script to recreate modified config.mk files.

The advantages of putting required changes in a compiler configuration file in the make/compiler directory are that:

Changes made in a compiler configuration file will be copied into both the src/config.mk and bld/config.mk files by the configure script, and will thus be used for both in-source and out-of-source builds.
The src/config.mk and bld/config.mk files are both erased when "make veryclean" is invoked from the PSCF root directory, but user-created compiler configuration files in the make/compiler directory are not erased by this command.

By creating a customized compiler configuration file, users can thus store required changes in a form that can survive possible repeated cycles of "make veryclean" and "./configure" commands.

Reconfigure after moving the root directory

Users can move or rename the root directory of their local PSCF repository at any time after the repository is created. To do so after having run the configure script, one should first run "make veryclean" from the old root directory location, then move or rename the root repository, and finally rerun the configure script after moving the directory.

Rationale: The configure script queries the operating system to identify the absolute path to the PSCF root directory, which is the directory that contains the configure script. This path is then used as a prefix to construct values for makefile variables that represent absolute paths to several subdirectories of the root directory, such as the src/, bld/, data/, and bin/ directories. The configure script thus must be rerun after the root directory is moved or renamed in order to update values of these path variables.

Environment Variables (Prev) Installation (Up) Out-of-Source and In-Source Builds (Next)