
/** \page compile Compiling

<ul>
  <li> \ref compiledownload
  <li> \ref compilepre   
  <li> \ref compilepreopt
  <li> \ref compileconf  
  <li> \ref Compilers  
  <li> \ref Libraries  
  <li> \ref compilecomp
  <li> \ref compilecheck
</ul>

\section compiledownload Obtaining the code

   The latest version of the source code is available from
   <a href="https://github.com/ValeevGroup/mpqc">Github</a>.
   Public stable releases of MPQC have not occured since 2006.
   Therefore it is recommended that the users
   obtain the latest source code directly from the code repository.

\section compilepre Prerequisites

MPQC is a complex piece of software and can be customized extensively. For example, to use MPQC on a parallel machine an MPI library
(see below) may be needed. While the basic subset of MPQC features will work on all platforms, advanced features of MPQC
will require additional prerequisites.

The following programs are necessary to compile even a bare-bones version of MPQC. Most are
available on any modern computer system.

  - Code building is performed by <a href="http://cmake.org/">CMake</a>, version 2.8.8 or higher, and GNU Make.

  - Compilers for the C, C++, and FORTRAN languages are needed. The compilers listed below are
    known to work.  Other ISO C++ compilers should work as well.

      - GCC 4.8 and later, available from <a href="http://gcc.gnu.org">http://gcc.gnu.org</a>.
      - The Intel C/C++ compilers version 12 and later.
      - The C/C++ compiler frontend to LLVM (clang/clang++).

  - The Basic Linear Algebra Subprograms (BLAS) and
    the Linear Algebra Package (LAPACK) 3.0 are required.
    It is preferable to use vendor-provided optimized libraries,
    such as Intel Math Kernel Library (MKL) or Apple's Accelerate
    framework. A reference copy of <a href="http://netlib.org/">netlib.org</a>
    LAPACK+BLAS is included and can be automatically built by cmake.

  - (optional) perl: This is used to generate and check the validation suite etc.

  - (developers-only) If you modify the scanner source file, then a
    lexical analyzer generator is required to generate code to read
    input files.  The <tt>flex</tt> program is used for this purpose.

  - (developers-only) If you modify a parser source file, then GNU bison (version 1.24
    or greater) is needed.  This is a parser generator used to
    generate code to read input files.

\section compilepreopt Advanced Prerequisites

Certain advanced features of MPQC require additional packages.

  -    A Message Passing Interface (MPI) is required to use MPQC in
       parallel on distributed memory machines. A thread-safe version of
       MPI is recommended.

  -    A C++ compiler with support for the C++11 standard. Most recent versions
       of gcc, clang, and Intel C/C++ compiler are sufficient.

  -    Libint (version 2.1.0(beta) or higher): This is a machine-generated
       library that can be used for evaluation of certain molecular
       integrals. Explicitly-correlated methods in MPQC require
       Libint. The library is freely available under GNU Public License
       (GPL) from <a
       href="https://github.com/evaleev/libint">Github</a>.
       A copy of Libint is bundled in ./external/libint*.tgz and will be built if requested. <b>NOTE</b> you may
       require custom version of Libint for some functionaility, such as interfacing with GAMESS.

  -    <a href="https://github.com/ValeevGroup/tiledarray">TiledArray</a> is a block-sparse parallel tensor framework.
       TiledArray must be compiled manually,
       preferably with support for <a href="http://libelemental.org/">Elemental</a>.
  -    <a href="http://eigen.tuxfamily.org/">Eigen</a> is a modern C++ library for linear algebra.
       A recent version is bundled in ./external/eigen.tar.gz; it will be unpacked if needed (this library is headers-only
       and does not need to be compiled).
  -    <a href="http://www.boost.org/">Boost</a> is a collection of modern C++ libraries. A recent version is bundled
       in ./external/boost*.tar.bz2; it will be built regardless of whether there is one is installed, since usability of Boost
       depends heavily on compiler.
  -    <a href="http://www.psicode.org/">Psi3</a> is the old generation of Psi code. Psi3 is bundled in ./external/psi3.tar.gz
       and will be compiled if needed. <b>NOTE:</b> Psi4 does not work with MPQC.
  -    <a href="http://www.hdfgroup.org/HDF5/">HDF5</a> is a high-performance data format library. It will be downloaded
       and built only if not found on the system.

\section compileconf Configuration

 You can build MPQC in the source code directory or you can make a
companion target directory which will be used to hold all of the files generated
by the compilation.  You may name this directory anything you want.
Typically, this directory is named to indicate the architecture
(e.g. <tt>mpqc.i686-linux</tt>) and will be referred to as the target
directory below.

 A <tt>configure</tt> script is used to prepare MPQC for compilation.
In the target directory execute the <tt>configure</tt> command which is
located in the source directory.  Use the absolute pathname to the
configure script.  This command should build a hierarchy of target
directories and the necessary makefiles. Do a <tt>configure --help</tt> to
see a list of options.  Options are specified with an equals sign, as in
<tt>configure --prefix=/usr/local</tt>.  Some options, such as all the
<tt>enable</tt> and <tt>disable</tt> options, do not require an argument.
The most useful options to configure include:

<dl>

<dt><tt>--prefix</tt><dd>Specifies the installation directory.  The default
  is <tt>/usr/local/mpqc/</tt><i>version-number</i>

<dt><tt>--debug</tt><dd>Options for debugging will be given to the
  compiler.

<dt><tt>--new-features</tt><dd>Enables compilations of all advanced features of MPQC,
hence most, if not all, prerequisites will be checked and built, if needed.

</dl>

  If you would like to further customize your target directory,
you can edit <tt>src/lib/mpqc_config.h</tt> to
suit your needs.  The next time you run configure, this files and
all the makefiles will be overwritten.

@section Compilers Compilers
   
   @subsection GNU

   To compile with GNU compilers:
   @code
   ./configure CXX=g++
   @endcode

   We are not aware of any significant issues with the GNU compilers.


   @subsection Intel

   To compile with Intel compilers, set appropriate CXX (and optionally C and FC):
   @code
   ./configure CXX=icpc
   @endcode
   
   C++11 support is incomplete as of version 13.
   See
   <a href="http://software.intel.com/en-us/articles/c0x-features-supported-by-intel-c-compiler">
   C++11 Features Supported by Intel® C++ Compiler
   </a>

   Compiling Eigen generates lots of warnings #2536 and #2196.  
   Those can be disabled with <tt>-wd</tt> switch, eg:
   @code
   ./configure CXX=icpc CXXFLAGS="-wd2536,2196"
   @endcode

   Using for range loops and openmp causes Intel compilers (at least version 13.0.1) to segfault,
   <tt>internal error: assertion failed at: "shared/cfe/edgcpfe/checkdir.c", line 5406<\tt>.
   As a workaround in production code use @link foreach @endlink macro.

@section Libraries Libraries
   
   @subsection LibrariesMath BLAS/LAPACK Math Libraries

   CMake will try to find BLAS/LAPACK automatically.
   If it fails, a Netlib Lapack will be built and used (this is NOT recommended).
   You can also specify BLAS/LAPACK libraries with \c --lapack option.

   BLAS/LAPACK libraries have \c INTEGER types that do not necessarily map to
   default C/C++ \c int type.  The default is to assume that \c INTEGER
   type is 4-bytes.
   In case the BLAS/LAPACK library uses 8-byte types add \c --integer8 flag:
   @code
   ./configure --integer8
   @endcode

   To use MKL (with GNU gfortran, GNU OpenMP, and 8-byte integers):
   @code
   ./configure --integer8 \
       --lapack="-Wl,--start-group  $(MKLROOT)/lib/intel64/libmkl_gf_ilp64.a $(MKLROOT)/lib/intel64/libmkl_core.a $(MKLROOT)/lib/intel64/libmkl_gnu_thread.a -Wl,--end-group -ldl -lpthread -lm"
   @endcode

   To use MKL with Intel compiler:
   @code
   ./configure --lapack="-mkl"
   @endcode


\section compilecomp Compilation

 Now you are ready to build the libraries and executables.  Do this by
typing <tt>make</tt> in your target directory.  If you are running on a
symmetric multi-processor, you can use GNU make to parallelize the
compilation.  To compile four files at a time, type <tt>make -j4</tt>.

 You can install the executables and data files with <tt>make install</tt>. Starting with
 version 3, this will also install the libraries and header files needed for development.

\section compilecheck Checking the Compilation

See \ref mpqcval for instructions for checking your compilation.

*/
