|
Simpatico
v1.10
|
2.3.2 Initial setup (Prev) 2.2.4 Configuring MPI (Next)
Compilation and installation of simpatico is controlled by a system of unix makefiles. Some of these files, which we will refer to as configuration files, define makefile variables whose values control the options that are passed to the compiler when the code is compiled. Among these are variables that control which optional features of the source code will be enabled in the resulting executable files, as well as others that control the name of the compiler executable and various optimization or warning options that should be passed to the compiler. Simpatico is distributed with a shell script, named "configure", that can be used to modify the values of some of these makefile variables, and thus control the configuration of the code from the command line. Users may also change the configuration by manually editing the relevant configuration files.
The remainder of this page explains the two different possible ways of compiling simpatico ("out-of-source" vs. "in-source"), discusses some basic information about the makefile system and configuration files, and explains how to use the "configure" script to control program configuration before compiling.
Users who would simply like to compile the default versions of all of the simpatico programs, with the features that are enabled by default, can skip this page on first reading. After successfully compiling the default versions of the code, one can always use the configure script to change the configuration and recompile the code. The build systems is designed to automatically note changes in the configuration files, and will correctly choose which files need to be recompiled if the user invokes one of the main make targets (e.g., "make mcMd" or make "ddMd") after changing the configuration.
The simpatico makefile system can build the package either "out-of-source" or "in-source". When the package is built "in-source", object files, static library files and other non-executable files that are generated during compilation are placed in the src/ directory tree, alongside the corresponding C++ source files. When it is built "out-of-source", these generated files are placed in a separate "build" directory tree, outside the source tree. In either case, the executable files for all programs are installed in the simpatico/bin directory by default.
We recommend that most users build simpatico out of source. The overview of instructions for compiling the code given in a previous page (here) were instructions for performing an out-of-source build.
To perform a standard out-of-source build of any simpatico program, one invokes "make" with an appropriate target (e.g., "make mcMd" or "make ddMd") from the simpatico/ root directory, as described in the short instructions. That is, for example, to compile and install the mcSim and mdSim programs, one invokes "make mcMd" from the simpatico/ root directory. The makefile in the root directory will automatically build out-of-source, and uses different build directories for serial (single-processor) and parallel (mpi-enabled) programs. The serial mcSim, mdSim, and mdPp programs are built in the simpatico/bld/serial/ directory, whereas the ddSim parallel MD program and the multi-processor versions of mcSim and mdSim are built in the simpatico/bld/parallel directory.
The ability to perform an in-source build is provided as a convenience for developers. To peform an in-source build of any program, one should simply invoke "make" with an appropriate target from the simpatico/src/ directory, rather than from the simpatico/ root directory. The same commands are used as those used to build out-of-source from the root directory. For example, invoking "make mcMd" from the src/ directory performs an in-source build of mcSim and mdSim, and invoking "make ddMd" from src/ performs an in-source build of ddSim. In-source builds are discussed in greater detail here.
Hereafter, when not otherwise stated, we will assume that all simpatico programs are built out-of-source, by invoking the make utility from the simpatico/ root directory.
The directories bld/serial, bld/parallel and src/ each contain the directory structure and the set of makefiles required to build any version of simpatico. In what follows, we will refer to these three directories collectively as build directories. Each of these build directories contains a tree of subdirectories similar to that of the src/ directory. Each build directory contains a set of five subdirectories named util/, simp/, mcMd/, ddMd/, and tools/ that each contain all of the C++ source files in a single C++ namespace. In what follows, we will refer to these five subdirectories as "namespace-level" subdirectories of a build directory.
After setup (i.e., after the setup script has been run), each of these three build directories will contains several makefiles and a set of 6 build configuration files. The build configuration are all files named "config.mk" that are located in the root of the build directory (i.e., in bld/serial, bld/parallel, or src/) and in each of the 5 namespace-level subdirectories of the build directory (i.e., in the util/, simp/, mcMd/ and ddMd/, and tools/ subdirectories). The config.mk file in the root directory of the build directory tree is the main build configuration file. This controls the choice of compiler and options that are passed to the compiler when compiling all code. The config.mk files in the namespace level control options that are only relevant for code in specific namespaces. The six config.mk files in each build directory together specify the configuration of any code compiled in that directory. Specifically, they specify the name of compiler executable, what command line options will be passed to the compiler, and which optional features will be enabled or disabled in any code built in that directory. The config.mk configuration files are all makefile fragments that are included by the actual makefiles that are read by the make utility.
Users may change the configuration of code built in a particular build directory before compiling either by: (1) manually editing the config.mk configuration files, or (2) by using a script named "configure" to enable or disable specific features. We recommend using the configure script (discussed in more detail below) to change configuration whenever possible, but some changes require manual editing.
The src/ directory also contains a corresponding set of 6 files named config.mk_r. Each of these is a default version of a corresponding config.mk file. Only the files named "config.mk_r" are stored in the git source-code repository. (The suffix _r stands for "repository".) The setup script creates a default version of each config.mk file by making a copy of the corresponding config.mk_r files in the src/ directory. In the process, the setup script also modifies a few lines of the main configuration files to reflect the location of the build directory and its purpose. For example, MPI is enabled by default in the bld/parallel directory and disabled by default in the bld/serial directory. Users may modify the config.mk files as needed, but should generally avoid modifying the config.mk_r default versions.
Each build directory (i.e., bld/serial, bld/parallel, and src/) contains a bash script named "configure" that can be used enabled or disable specific compile time features. There is also an analogous script in the simpatico/ root directory which can be used to apply the same set of changes simultaneously to configuration files in the bld/serial and bld/parallel directories.
The configure script in each build directory does its work by editing the build configuration files, which control what options will be passed to the compiler during any subsequent compilation. The configure script in each build directory must be invoked from the directory that contains the script (i.e., from bld/serial, bld/parallel, and src/), and only affects the configuration of code that is compiled in that build directory.
The configure script in the root simpatico/ directory works by invoking the configure scripts in the bld/parallel and bld/serial with the same options, thus applying the same changes to configuration files in both of these directories.
The -q command line option of a configure script may be used to query which optional features are currently set to be enabled or disabled, and the current values of variables that specify the choice of compiler and environment. To see how this works, after the setup script has been run, cd to the bld/serial directory and enter
The -q command line option cause the script to print a list of which optional features are currently enabled, and the name of the current choice of compiler. The resulting output for the default configuration should look something like this:
Each line of this output before the last two shows whether an optional feature is currently set to be enabled (ON) or disabled (OFF). Note that only the nonbonded pair potential and bond potential are enabled by default, and that the angle, dihedral and other potentials are disabled by default. If you need to run a simulation that uses any of these other types of potential, you will need to use the configure script to enable the relevant features before compiling.
The last two line of the query output give the value of a makefile variable named COMPILER that is an identifier for the choice of compiler (gcc, by default), and an identifier OS for the environment (generic, by default).
The output produced by running the configure script in the bld/parallel directory after setup looks similiar to that shown above, except that it should indicate that MPI is ON (enabled) by default in that directory.
Invoking the configure script from the simpatico/ root directory with the -q option produces a output that first shows the current settings in both the bld/serial directory, which control the configuration of single-processor programs, and then the current setting in the bld/parallel directory, which control the configuration of MPI programs. If all changes have been applied using the configure script in the root directory, the settings in these two directories should be the same, except that MPI should be disabled in bld/serial and enabled in bld/parallel.
In the output produced by invoking configure with the -q option, each line of the output before the last two begins with the name of the command line option for the configure script (a dash followed by a letter) that can be used to enable or disable an associated feature. For example, the "debugging" feature is enabled or disabled using the "-g" option. Each feature can be enabled by using the associated command line option followed by "1" (ON), or disabled by using the option followed by "0" (OFF).
For example, to enable debugging (which enables extensive run-time sanity checks, at a slight cost in speed) in code built in one build directory, one would enter
either from the root of the relevant build directory or from the simpatico/ root directory. Invoking this command from a build directory enables debugging in that build directory, whereas invoking it from the simpatico/ root directory enables debugging in both the bld/serial and bld/parallel directories, thus applying the change to all code that compiled out of source. Running "./configure -q" again after this change would show that debugging is now enabled. To disable debugging before compiling, one would instead enter
These and any other desired changes in compile-time configuration must be made before invoking make to compile a program.
Several features may be enabled and/or disabled in a single command. For example, to enable the use of angle and dihedral potentials, which are disabled by default, one would invoke
either from a build directory or the simpatico root directory.
The -j option option of the configure script may be used to set the value of the COMPILER identifier string, which chooses a compiler. This option takes the desired value of the COMPILER identifier as an argument. The only allowed options are "gcc" or "intel". The -o option can be used to set the value of the OS identifier, which is set to "generic" by default.
Invoking the configure script with the -h ("help") option gives a list of all command line options accepted by the configure command, along with some information about what C++ preprocessor macros are defined or undefined by specific commands. All of the available optional features of the various simpatico programs are also discussed elsewhere in the web documentation.
The configure script in the simpatico/ root directory can be used to apply the same set of changes simultaneously to configuration files in the bld/serial and bld/parallel directories. This version of the script should be invoked from the root directory. It accepts the same options as the configure scripts in the build directories, with one exception: It does not accept the "-m" option, which enables or disables MPI, because MPI should normally be enabled bld/parallel and disabled in bld/serial. The root directory configure script works by simply invoking the ./configure scripts in the bld/serial and bld/parallel directories. Changes made with this script do not effect the configuration of in-source builds.
The choice of what compiler executable to use for compiling code that does not use MPI is specified in by the value of the COMPILER makefile variable defined in the config.mk file in each build directory. The choice of compiler for code that uses MPI is more complicated, and is discussed separately below.
By default, the build system uses the gnu compiler collection (gcc) C++ compiler for serial code. If you are satisifed with the gcc compiler and these compiler options, you can skip the rest of this section.
If you prefer to use the intel compiler (and if it is installed on your computer), enter the command
from the simpatico root/ directory and/or the simpatico/src directory. Entering this command from the simpatico/ directory selects the intel compiler for use in code built out-of-source the bld/serial directory. Entering this command from the simpatico/src directory selects the intel compiler for use in in-source builds.
To explicitly choose the gcc compiler (e.g., after choosing the intel compiler and then changing your mind), instead enter "./configure -j gcc".
Details:
The choice of compiler for use in each build directory is specified by the value of a makefile variable named COMPILER that is defined the main config.mk configuration file. Thus far, the only valid values for this identifier are "gcc" or "intel". The default value, COMPILER=gcc, selects the gnu C++ compiler, for which the compiler command name is "g++". Setting COMPILER=intel selects the intel C++ compiler, for which the compiler command is "icpc".
The value of the COMPILER variable is used to select definitions of other variables in the main config.mk file that define the command line options that will be passed to the compiler. The CXX_FLAGS variable defines most of the options that effect the behavior of the compiler after the preprocessing stage, such as optimization and warning flags. To change the options passed to a particular compiler, one must manually edit the main config.mk file in the build directory. Users who wish to do this should read the documentation in the config.mk file, which explains the purpose of each of the relevant makefile variables. Experienced users should find it straightforward to modify this file as needed to modify compiler options or to allow use of another compiler.
MPI is enabled by defining the makefile variable UTIL_MPI in the main configuration file in a build directory. When MPI is enabled, by default, the build system sets the name of the compiler executable to "mpicxx". This is the name of a relatively standard wrapper script that is installed as part of the installation of almost all MPI libraries. The mpicxx is designed to simplify compilation of MPI programs by invoking the compiler that was used to compile the MPI library, while automatically adding options required to guarantee that the compiler can find any header or library files associated with the MPI library. When MPI is enabled in the simpatico build system, by default, both the choice of compiler and the addition of any non-standard paths the search paths used by the compiler is left to the mpicxx script. Users who know what they are doing can, of course, override this behavior by editing the main config.mk file in the build directory used to compile MPI code.
By default, the simpatico build system automatically generates a "dependency" file, with a suffix *.d, whenever it compiles a *.cpp source file. The dependency file is placed in the build directory tree in same directory as the corresponding object *.o file. The dependency files are used by the build system to decide what files need to be recompiled after the user modifies either a C++ file or a configuration file.
The system for generating dependency files uses the g++ compiler, which does the actual analysis of dependencies among C++ files. It also uses a python script named simpatico/scripts/python/makeDepend.py to do some text processing on the list of dependencies produced by the compiler. To function correctly, this system requires that:
The build system requires that a g++ compiler is available because the g++ compiler is used for dependency analysis even if another compiler (e.g., the intel compiler) is used for compilation. A g++ compiler and python interpreter is normally available on any modern linux distribution, and on any Mac OS X environment that is correctly set up for C++ development.
Automatic generation of dependency files is an essential feature for developers - It makes it possible to safely rebuild a program after you modify a few C++ files or configuration files, and have the build system recompile only what needs to be recompiled. It is possible to disable automatic dependency generation in any build directory by entering "./configure -k0" from the root of that build directory, but we strongly recommend against doing so.
2.3.2 Initial setup (Prev) 2.2 Compiling (Up) 2.2.4 Configuring MPI (Next)
1.8.11