Updated installation instructions for using CMake.

docs/source/usersguide/install.rst

@@ -50,6 +50,15 @@ Prerequisites
 
           sudo apt-get install gfortran
 
+    * CMake_ cross-platform build system
+
+      The compiling and linking of source files is handled by CMake in a
+      platform-independent manner. If you are using Debian or a Debian
+      derivative such as Ubuntu, you can install CMake using the following
+      command::
+
+          sudo apt-get install cmake
+
 .. admonition:: Optional
 
     * An MPI implementation for distributed-memory parallel runs
@@ -98,6 +107,7 @@ Prerequisites
     * git_ version control software for obtaining source code
 
 .. _gfortran: http://gcc.gnu.org/wiki/GFortran
+.. _CMake: http://www.cmake.org
 .. _OpenMPI: http://www.open-mpi.org
 .. _MPICH: http://www.mpich.org
 .. _HDF5: http://www.hdfgroup.org/HDF5/
@@ -131,50 +141,95 @@ switch to the source of the latest stable release, run the following commands::
 Build Configuration
 -------------------
 
-All configuration for OpenMC is done within the Makefile located in
-``src/Makefile``. In the Makefile, you will see that there are a number of User
-Options which can be changed. It is recommended that you do not change anything
-else in the Makefile unless you are experienced with compiling and building
-software using Makefiles. The following parameters can be set from the User
-Options sections in the Makefile:
+Compiling OpenMC with CMake is carried out in two steps. First, ``cmake`` is run
+to determine the compiler, whether optional packages (MPI, HDF5, PETSc) are
+available, to generate a list of dependencies between source files so that they
+may be compiled in the correct order, and to generate a normal Makefile. The
+Makefile is then used by ``make`` to actually carry out the compile and linking
+commands. A typical out-of-source build would thus look something like the
+following
 
-COMPILER
-  This variable tells the Makefile which compiler to use. Valid options are
-  gnu, intel, pgi, ibm, and cray. The default is gnu (gfortran).
+.. code-block:: sh
 
-DEBUG
+    mkdir src/build
+    cd src/build
+    cmake ..
+    make
+
+Note that first a build directory is created as a subdirectory of the source
+directory. The Makefile in ``src/`` will automatically perform an out-of-source
+build with default options.
+
+CMakeLists.txt Options
+++++++++++++++++++++++
+
+The following options are available in the CMakeLists.txt file:
+
+debug
   Enables debugging when compiling. The flags added are dependent on which
   compiler is used.
 
-PROFILE
+profile
   Enables profiling using the GNU profiler, gprof.
 
-OPTIMIZE
+optimize
   Enables high-optimization using compiler-dependent flags. For gfortran and
   Intel Fortran, this compiles with -O3.
 
-MPI
-  Enables parallel runs using the Message Passing Interface. The MPI_DIR
-  variable should be set to the base directory of the MPI implementation.
-
-OPENMP
+openmp
   Enables shared-memory parallelism using the OpenMP API. The Fortran compiler
   being used must support OpenMP.
 
-HDF5
-  Enables HDF5 output in addition to normal screen and text file output. The
-  HDF5_DIR variable should be set to the base directory of the HDF5
-  installation.
-
-PETSC
+petsc
   Enables PETSc for use in CMFD acceleration. The PETSC_DIR variable should be
   set to the base directory of the PETSc installation.
 
-It is also possible to change these options from the command line itself. For
-example, if you want to compile with DEBUG turned on without actually change the
-Makefile, you can enter the following from a terminal::
+To set any of these options (e.g. turning on debug mode), the following form
+should be used:
 
-    make DEBUG=yes
+.. code-block:: sh
+
+    cmake -Ddebug=on /path/to/src
+
+Compiling with MPI
+++++++++++++++++++
+
+To compile with MPI, set the FC environment variable to the path to the MPI
+Fortran wrapper. For example, in a bash shell:
+
+.. code-block:: sh
+
+    export FC=mpif90
+    cmake /path/to/src
+
+Note that in many shells, an environment variable can be set for a single
+command, i.e.
+
+.. code-block:: sh
+
+    FC=mpif90 cmake /path/to/src
+
+Compiling with HDF5
++++++++++++++++++++
+
+To compile with MPI, set the FC environment variable to the path to the HDF5
+Fortran wrapper. For example, in a bash shell:
+
+.. code-block:: sh
+
+    export FC=h5fc
+    cmake /path/to/src
+
+As noted above, an environment variable can typically be set for a single
+command, i.e.
+
+.. code-block:: sh
+
+    FC=h5fc cmake /path/to/src
+
+To compile with support for both MPI and HDF5, use the parallel HDF5 wrapper
+``h5pfc`` instead. Note that this requires that your HDF5 installation be
+compiled with ``--enable-parallel``.
 
 Compiling on Linux and Mac OS X
 -------------------------------
@@ -202,9 +257,10 @@ a Linux-like environment for Windows. You will need to first `install
 Cygwin`_. When you are asked to select packages, make sure the following are
 selected:
 
-* Devel: gcc4-core
-* Devel: gcc4-fortran
+* Devel: gcc-core
+* Devel: gcc-fortran
 * Devel: make
+* Devel: cmake
 
 If you plan on obtaining the source code directly using git, select the
 following packages: