cmake (c50b1)
Using CMake to install CHARMM
CMake is an alternative to install.com for configuring, compiling,
and installing CHARMM. This file describes how to use cmake and
the configure shell script to build CHARMM.
There are two relevant files in the root CHARMM source distribution.
The CMakeLists.txt file is read by CMake to configure the source
for compilation.
The configure file is a shell script wrapper that invokes CMake.
The configure script provides a more traditional command line switch interface.
Also, if CMake is not available, the script will build and use a cmake binary
from the tool/cmake directory. The script ultimately just builds
a list of options and invokes CMake with the list.
Other methods of using CMake such as the ncurses ccmake GUI and
the Qt GUI are untested and unsupported. Support for ccmake may be added in
the future.
* Workflow | Three Steps to a CMake Install
* Configuration | The First Step
* Compilation | The Second Step
* Installation | The Third and Final Step
CMake is an alternative to install.com for configuring, compiling,
and installing CHARMM. This file describes how to use cmake and
the configure shell script to build CHARMM.
There are two relevant files in the root CHARMM source distribution.
The CMakeLists.txt file is read by CMake to configure the source
for compilation.
The configure file is a shell script wrapper that invokes CMake.
The configure script provides a more traditional command line switch interface.
Also, if CMake is not available, the script will build and use a cmake binary
from the tool/cmake directory. The script ultimately just builds
a list of options and invokes CMake with the list.
Other methods of using CMake such as the ncurses ccmake GUI and
the Qt GUI are untested and unsupported. Support for ccmake may be added in
the future.
* Workflow | Three Steps to a CMake Install
* Configuration | The First Step
* Compilation | The Second Step
* Installation | The Third and Final Step
Top
Workflow
There are three steps, configuration, compilation, and installation to create
a working install of CHARMM from the source distribution using CMake.
The first step, configuration, uses the configure script,
or the cmake command directly,
to configure the source for compiling.
The configuration step occurs in a new empty directory, the build directory.
The second step is to compile the source in the build directory by invoking
the make command which uses the makefile written by CMake in
the configuration step.
The third step is to install the binaries and support files into a path prefix
designated during configuration by typing 'make install'.
Workflow
There are three steps, configuration, compilation, and installation to create
a working install of CHARMM from the source distribution using CMake.
The first step, configuration, uses the configure script,
or the cmake command directly,
to configure the source for compiling.
The configuration step occurs in a new empty directory, the build directory.
The second step is to compile the source in the build directory by invoking
the make command which uses the makefile written by CMake in
the configuration step.
The third step is to install the binaries and support files into a path prefix
designated during configuration by typing 'make install'.
Top
Configuration
To configure the source prior to compilation, make a new directory. For example,
on a GNU/Linux system, I might have the CHARMM source in my home directory under
'charmm'.
$ cd ~
$ ls
charmm
Making a new build directory might look like the following.
$ mkdir charmm-build
$ ls
charmm charmm-build
From the new build directory, invoke the configure script with the desired
options.
$ cd charmm-build
$ ../charmm/configure ...
To see the currently supported list of options, use the --help option.
$ ../charmm/configure --help
Usage: configure [--option1] [--option2] ...
General options
-p <install path>, --prefix <install path>
install CHARMM into the given directory
-g, --debug
include debug symbols in final exec
-l, --lite
lite build of CHARMM (minimal pref.dat keywords)
turns all options off regardless of other arguments
-c <path to cmake>, --cmake <path to cmake>
use <path to cmake> to configure the build
-a <keyword1,keyword2,...,keywordN>, --add <keyword1,keyword2,...,keywordN>
add the keywords to the final pref.dat
-r <keyword1,keyword2,...,keywordN>, --remove <keyword1,keyword2,...,keywordN>
remove the keywords from the final pref.dat
-D var1=val1 -D var2=val2 ... -D varN=valN
set CMake variables to the given values
-F flag
pass a flag to CMake (eg -F '-GNinja')
--with-ninja
use ninja as the build program instead of make
--without-new-files
do not scan for new files to add as source code
Non-default features
--static
link only static libs for a portable executable
--with-abpo
include support for ABPO; requires MPI and activates ENSEMBLE
--with-blade
include support for BLaDE GPU features
--with-domdec_gpu, --domdec_gpu, -u
include support for DOMDEC_GPU
--with-ensemble
include support for ENSEMBLE replicas; requires MPI
--with-fftdock
include support for fftdock GPU features
--with-gamess, --gamess, -q
include support for GAMESS QM/MM interface
--with-gamus
include support for GAMUS
--with-ljpme
include support for LJPME features
--with-nih
include the NIH extra set of pref.dat keywords
--with-nvtx
link NVIDIA Tools Extension library for NVIDIA Nsight profiling
--with-pipf
include support for Polarizable Intermolecular Potential Function
--with-repdstr, --repdstr
include support for REPDSTR
--with-stringm, --stringm
include support for STRINGM
--with-sccdftb, --sccdftb, -s
include support for SCC-DFTB
--with-x11
include support for X11 graphics via XDISPLAY
--with-tsri
include the TSRI extra set of pref.dat keywords
--with-eabf
include eabf source files
Non-default mutually exclusive QM/MM options
--with-squantm
include support for squantum (not compatible with qchem)
--with-g09
include support for Gaussian09
--with-qturbo
include support for QTURBO
--with-mndo97
include support for MNDO97 (not compatible with qchem)
--with-qmmmsemi
include support for QMMMSEMI (AMBER semi-empirical qmmm)
Compiler options
--with-gnu, --with-gcc
finds the first gnu compilers on the path to use in the build
--with-intel
finds the first Intel compilers on the path to use in the build
--with-pgi
finds the first PGI compilers on the path to use in the build
--with-cuda-host-compiler <C/C++ compiler>
the C/C++ host compiler that nvcc will used (passed via -ccbin)
Remove default features
--without-library
only build an executable; do not build a shared library
--without-colfft
skips compiling COLFFT features
--without-cuda
skips compiling Nvidia CUDA features
--without-domdec
skips compiling DOMDEC features
--without-exafmm
skips compiling ExaFMM support
--without-fftw
skips linking in the FFTW library
--without-html
skips building and installing html documentation pages
--without-mkl
skips linking in Intel's MKL library
--without-mpi
skips compiling MPI features
--without-opencl
skip compiling OpenCL features
--without-openmm
skips compiling OpenMM features
--without-openmp
skips compiling OpenMP acceleration
--without-qchem
skips compiling Q-CHEM features including the qchem executable
--without-quantum
skips compiling QUANTUM features
Helpful variables
Setting these variables is usually unnecessary.
It is usually enough to have the feature or
a related binary first in your path.
Feature: Environment variable(s)
Compiler: CC, CXX, FC, CUDACXX, PATH
CUDA Toolkit: CUDAToolkit_ROOT
nvcc: PATH, CUDACXX
OpenMM: OPENMM_PLUGIN_DIR, OPENMM_DIR, OPENMM_HOME
FFTW: FFTW_DIR, FFTW_HOME
MKL: MKLROOT, MKL_HOME
Feature: CMake variable(s)
MPI: MPI_Fortran_COMPILER, MPI_C_COMPILER, MPI_C++_COMPILER
nvcc: CMAKE_CUDA_COMPILER, CMAKE_CUDA_HOST_COMPILER,
CMAKE_CUDA_ARCHITECTURES
CUDA Toolkit: CUDAToolkit_ROOT
OpenMM: OPENMM_PLUGIN_DIR, OPENMM_LIBRARY, OPENMM_INCLUDE_DIR
Some notable CMake variables (set with the -D <variable>=<value> option)
CMAKE_CUDA_HOST_COMPILER
the C/C++ host compiler that nvcc will used (passed via -ccbin)
optimization
The optimization level 0, 1, 2, or 3 passed to the compiler via '-O<#>'.
This will be added to the CHARMM_<Lang>_FLAGS_RELEASE CMake variable where
Lang is C, CXX, and Fortran.
It should not normally be necessary to set this flag. A default level is set
in the CMakeLists.txt file.
arch_flag_C
arch_flag_CXX
arch_flag_Fortran
A compiler option to add to the CHARMM_<Lang>_FLAGS_RELEASE CMake variable where
Lang is C, CXX, and Fortran.
It should not normally be necessary to set this flag. A default level is set
in the CMakeLists.txt file.
For example, the default switch for GNU GCC is '-march=native'
CMAKE_CUDA_ARCHITECTURES
Set a real GPU architechture for CUDA code. The CUDA code will be compiled to
the given real architechture. The CUDA driver will not use the JIT compiler at
runtime. Use the compute number times 10, for example: 32, 35, 53, 75...
For example, to configure compilation using the Intel compiler suite and
including debugging symbols:
$ ../charmm/configure --intel --debug --prefix=/home/jdoe/charmm-install
Please note that you must provide the prefix to successfully complete the final
install phase and the prefix must be the full, literal path.
Do not use shortcuts such as ~ or ..
If the configure script detects the file 'install.com' and
the directory 'build' in the current working directory, then
the script will run the cmake command from the 'build/cmake' directory
creating this directory if necessary.
After configuration, in this case, change to the 'build/cmake' directory
to run the make command or pass the '-C build/cmake' option to the make command.
A relative prefix option will be relative to the
'build/cmake' directory instead of the top-level source directory.
If no prefix option is provided, the executable and plugins will be installed
into the CHARMM source root bin and lib directories.
Configuration
To configure the source prior to compilation, make a new directory. For example,
on a GNU/Linux system, I might have the CHARMM source in my home directory under
'charmm'.
$ cd ~
$ ls
charmm
Making a new build directory might look like the following.
$ mkdir charmm-build
$ ls
charmm charmm-build
From the new build directory, invoke the configure script with the desired
options.
$ cd charmm-build
$ ../charmm/configure ...
To see the currently supported list of options, use the --help option.
$ ../charmm/configure --help
Usage: configure [--option1] [--option2] ...
General options
-p <install path>, --prefix <install path>
install CHARMM into the given directory
-g, --debug
include debug symbols in final exec
-l, --lite
lite build of CHARMM (minimal pref.dat keywords)
turns all options off regardless of other arguments
-c <path to cmake>, --cmake <path to cmake>
use <path to cmake> to configure the build
-a <keyword1,keyword2,...,keywordN>, --add <keyword1,keyword2,...,keywordN>
add the keywords to the final pref.dat
-r <keyword1,keyword2,...,keywordN>, --remove <keyword1,keyword2,...,keywordN>
remove the keywords from the final pref.dat
-D var1=val1 -D var2=val2 ... -D varN=valN
set CMake variables to the given values
-F flag
pass a flag to CMake (eg -F '-GNinja')
--with-ninja
use ninja as the build program instead of make
--without-new-files
do not scan for new files to add as source code
Non-default features
--static
link only static libs for a portable executable
--with-abpo
include support for ABPO; requires MPI and activates ENSEMBLE
--with-blade
include support for BLaDE GPU features
--with-domdec_gpu, --domdec_gpu, -u
include support for DOMDEC_GPU
--with-ensemble
include support for ENSEMBLE replicas; requires MPI
--with-fftdock
include support for fftdock GPU features
--with-gamess, --gamess, -q
include support for GAMESS QM/MM interface
--with-gamus
include support for GAMUS
--with-ljpme
include support for LJPME features
--with-nih
include the NIH extra set of pref.dat keywords
--with-nvtx
link NVIDIA Tools Extension library for NVIDIA Nsight profiling
--with-pipf
include support for Polarizable Intermolecular Potential Function
--with-repdstr, --repdstr
include support for REPDSTR
--with-stringm, --stringm
include support for STRINGM
--with-sccdftb, --sccdftb, -s
include support for SCC-DFTB
--with-x11
include support for X11 graphics via XDISPLAY
--with-tsri
include the TSRI extra set of pref.dat keywords
--with-eabf
include eabf source files
Non-default mutually exclusive QM/MM options
--with-squantm
include support for squantum (not compatible with qchem)
--with-g09
include support for Gaussian09
--with-qturbo
include support for QTURBO
--with-mndo97
include support for MNDO97 (not compatible with qchem)
--with-qmmmsemi
include support for QMMMSEMI (AMBER semi-empirical qmmm)
Compiler options
--with-gnu, --with-gcc
finds the first gnu compilers on the path to use in the build
--with-intel
finds the first Intel compilers on the path to use in the build
--with-pgi
finds the first PGI compilers on the path to use in the build
--with-cuda-host-compiler <C/C++ compiler>
the C/C++ host compiler that nvcc will used (passed via -ccbin)
Remove default features
--without-library
only build an executable; do not build a shared library
--without-colfft
skips compiling COLFFT features
--without-cuda
skips compiling Nvidia CUDA features
--without-domdec
skips compiling DOMDEC features
--without-exafmm
skips compiling ExaFMM support
--without-fftw
skips linking in the FFTW library
--without-html
skips building and installing html documentation pages
--without-mkl
skips linking in Intel's MKL library
--without-mpi
skips compiling MPI features
--without-opencl
skip compiling OpenCL features
--without-openmm
skips compiling OpenMM features
--without-openmp
skips compiling OpenMP acceleration
--without-qchem
skips compiling Q-CHEM features including the qchem executable
--without-quantum
skips compiling QUANTUM features
Helpful variables
Setting these variables is usually unnecessary.
It is usually enough to have the feature or
a related binary first in your path.
Feature: Environment variable(s)
Compiler: CC, CXX, FC, CUDACXX, PATH
CUDA Toolkit: CUDAToolkit_ROOT
nvcc: PATH, CUDACXX
OpenMM: OPENMM_PLUGIN_DIR, OPENMM_DIR, OPENMM_HOME
FFTW: FFTW_DIR, FFTW_HOME
MKL: MKLROOT, MKL_HOME
Feature: CMake variable(s)
MPI: MPI_Fortran_COMPILER, MPI_C_COMPILER, MPI_C++_COMPILER
nvcc: CMAKE_CUDA_COMPILER, CMAKE_CUDA_HOST_COMPILER,
CMAKE_CUDA_ARCHITECTURES
CUDA Toolkit: CUDAToolkit_ROOT
OpenMM: OPENMM_PLUGIN_DIR, OPENMM_LIBRARY, OPENMM_INCLUDE_DIR
Some notable CMake variables (set with the -D <variable>=<value> option)
CMAKE_CUDA_HOST_COMPILER
the C/C++ host compiler that nvcc will used (passed via -ccbin)
optimization
The optimization level 0, 1, 2, or 3 passed to the compiler via '-O<#>'.
This will be added to the CHARMM_<Lang>_FLAGS_RELEASE CMake variable where
Lang is C, CXX, and Fortran.
It should not normally be necessary to set this flag. A default level is set
in the CMakeLists.txt file.
arch_flag_C
arch_flag_CXX
arch_flag_Fortran
A compiler option to add to the CHARMM_<Lang>_FLAGS_RELEASE CMake variable where
Lang is C, CXX, and Fortran.
It should not normally be necessary to set this flag. A default level is set
in the CMakeLists.txt file.
For example, the default switch for GNU GCC is '-march=native'
CMAKE_CUDA_ARCHITECTURES
Set a real GPU architechture for CUDA code. The CUDA code will be compiled to
the given real architechture. The CUDA driver will not use the JIT compiler at
runtime. Use the compute number times 10, for example: 32, 35, 53, 75...
For example, to configure compilation using the Intel compiler suite and
including debugging symbols:
$ ../charmm/configure --intel --debug --prefix=/home/jdoe/charmm-install
Please note that you must provide the prefix to successfully complete the final
install phase and the prefix must be the full, literal path.
Do not use shortcuts such as ~ or ..
If the configure script detects the file 'install.com' and
the directory 'build' in the current working directory, then
the script will run the cmake command from the 'build/cmake' directory
creating this directory if necessary.
After configuration, in this case, change to the 'build/cmake' directory
to run the make command or pass the '-C build/cmake' option to the make command.
A relative prefix option will be relative to the
'build/cmake' directory instead of the top-level source directory.
If no prefix option is provided, the executable and plugins will be installed
into the CHARMM source root bin and lib directories.
Top
Compilation
After configuration completes with no errors,
invoke make in the build directory.
$ make -j3
Compilation
After configuration completes with no errors,
invoke make in the build directory.
$ make -j3
Top
Finally, if compilation completes with no error,
invoke 'make install' to install binaries and support files into
the user specified prefix directory.
The binaries will be installed to <prefix>/bin
To run the test cases from the installed <prefix> test directory,
give test.com the first argument cmake intead of gnu or em64t.
$ cd <prefix>/test
$ ./test.com cmake ...
Options given to configure and cmake as well as the original source directory
can be printed from a charmm script prompt or file using the charmm command
CONF. For example,
CHARMM> conf
configure command line arguments ->-g --with-ninja<-
cmake command line arguments -> -DCMAKE_BUILD_TYPE=Debug -GNinja -DCMAKE_INSTALL_PREFIX=/home/bucknerj/src/charmm_builds/gnu -Din_place_install=ON<-
original source dir ->/home/testy/src/charmm_builds/gnu<-
Finally, if compilation completes with no error,
invoke 'make install' to install binaries and support files into
the user specified prefix directory.
The binaries will be installed to <prefix>/bin
To run the test cases from the installed <prefix> test directory,
give test.com the first argument cmake intead of gnu or em64t.
$ cd <prefix>/test
$ ./test.com cmake ...
Options given to configure and cmake as well as the original source directory
can be printed from a charmm script prompt or file using the charmm command
CONF. For example,
CHARMM> conf
configure command line arguments ->-g --with-ninja<-
cmake command line arguments -> -DCMAKE_BUILD_TYPE=Debug -GNinja -DCMAKE_INSTALL_PREFIX=/home/bucknerj/src/charmm_builds/gnu -Din_place_install=ON<-
original source dir ->/home/testy/src/charmm_builds/gnu<-