CHARMM c42b2 cmake.doc

File: Cmake -=- Node: Top
Up: (charmm.doc) -=- Previous: (install.doc) -=- Next: (usage.doc)

                  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.

* Menu:

* Workflow::      Three Steps to a CMake Install
* Configuration:: The First Step
* Compilation::   The Second Step
* Installation::  The Third and Final Step

File: Cmake -=- Node: Workflow
Up: Top -=- Previous: Top -=- Next: Machines

                      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'. 

File: Cmake -=- Node: Configuration
Up: Top -=- Previous: Workflow -=- Next: Compilation

                      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] ...

Options:
-a <keyword1,keyword2,...,keywordN>, --add <keyword1,keyword2,...,keywordN>
               add the keywords to the final pref.dat
-c <path to cmake>, --cmake <path to cmake>
               use <path to cmake> to configure the build
-g, --debug    include debug symbols in final exec
-i, --intel    force use of intel compiler suite
-l, --lite     compile only lite version (very few keywords)
-m, --mpi      include support for openmpi
-o, --openmm   include support for OpenMM
-p <install path>, --prefix <install path>
               install CHARMM into the given directory
-r <keyword1,keyword2,...,keywordN>, --remove <keyword1,keyword2,...,keywordN>
               remove the keywords from the final pref.dat

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. A relative prefix option will be relative to the
'build/cmake' directory instead of the top-level source directory.

File: Cmake -=- Node: Compilation
Up: Top -=- Previous: Configuration -=- Next: Installation

                   Compilation

After configuration completes with no errors,
invoke make in the build directory.

$ make -j3

File: Cmake -=- Node: Installation
Up: Top -=- Previous: Compilation -=- Next: 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 ...