From 0c5234e9841defb747d6c3f5e9dc55c6f74fc35a Mon Sep 17 00:00:00 2001 From: Paul Romano Date: Wed, 29 Jan 2014 21:44:46 -0500 Subject: [PATCH] Updated installation instructions for using CMake. --- docs/source/usersguide/install.rst | 114 +++++++++++++++++++++-------- 1 file changed, 85 insertions(+), 29 deletions(-) diff --git a/docs/source/usersguide/install.rst b/docs/source/usersguide/install.rst index 164b0151be..30eaa5a321 100644 --- a/docs/source/usersguide/install.rst +++ b/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: