source: ThirdParty/mpqc_open/doc/compile.dox@ 788dce

/** \page compile Compiling

<ul>
  <li> \ref compilepre   
  <li> \ref compilepreopt
  <li> \ref compileconf  
  <ul>
    <li> \ref compilecca
  </ul>
  <li> \ref compilecomp
  <li> \ref compilecheck
</ul>

\section compilepre Prerequisites

Make sure that you have the following programs available. Most can be found
at any GNU software FTP repository.

<ul>

    <li> Compilers for the C, C++, and FORTRAN languages are needed.  The
         FORTRAN compiler is used to determine the linkage conventions for
         the BLAS libraries, however, you can turn off the use of a FORTRAN
         compiler by giving <tt>--without-f77</tt> as an option to the
         configure script, however, this will not work unless you
         only want the utility libraries.  The compilers listed below are
         known to work.  Other ISO C++ compilers should work as well.

       <ul>

           <li> GCC 2.96 and later, available from <a
                href="http://gcc.gnu.org">http://gcc.gnu.org</a>.  However,
                the 3.0 and 3.0.1 releases of GCC are not recommended.

           <li> IBM xlC 5.0.2 and later work with both 32 and 64 bit modes
                Use the versions of the compilers with the "_r" appended to
                the name, since SC uses multi-threading.  You must also
                specify that RTTI is used: <tt>--with-cxx='xlC_r
                -qrtti'</tt>.

           <li> Compaq/Alpha/Linux with Compaq C++ 6.3.6.8 and later work.
                Special configure options are needed: <tt>--with-cxx='cxx
                -D__USE_STD_IOSTREAM'</tt>

           <li> The Intel 5.0.1 Linux compilers for IA-32 work.  Version
                5.0.1 for IA-64 will not work.

           <li> The KAI version 4.0e1 compiler works.  Special configure
                options are needed: <tt>--with-cxx='KCC
                --one_instantiation_per_object' --with-ar=KCC
                --with-ar-flags=-o</tt>

       </ul>

    <li> The Basic Linear Algebra Subprograms (BLAS) are required.  A
         prepackaged version of BLAS is available for most machines.
         Consult you operating system documentation for more information.
         If precompiled BLAS routines are not available for your machine,
         the source can be obtained from <a
         href="http://www.netlib.org/blas">http://www.netlib.org/blas</a>.
         The file blas.tgz contains the source for all of the BLAS
         routines.  If the BLAS library is not named libblas.a or is not
         installed in the default library search path, then configure must
         be given --with-libs, --with-libdirs, or both.

    <li> The Linear Algebra Package (LAPACK) 3.0 is required.  A
         prepackaged version of LAPACK is available for most machines.
         Consult you operating system documentation for more information.
         If a precompiled LAPACK is not available for your machine, the
         source can be obtained from <a
         href="http://www.netlib.org/lapack">http://www.netlib.org/lapack</a>.
         The file lapack.tgz contains the source for all of the LAPACK
         routines.  If the LAPACK library is not named liblapack.a or is
         not installed in the default library search path, then configure
         must be given --with-libs, --with-libdirs, or both.

    <li> If you modify the scanner source file, then a
         lexical analyzer generator is required to generate code to read
         input files.  The flex program is used for this purpose.
         However, the most common version of flex, 2.5.4a, does
         not generate legal C++.  It may be necessary to download,
         compile, and install a more recent version of flex from <a
         href="http://lex.sourceforge.net">http://lex.sourceforge.net</a>.

         Make sure that <tt>FlexLexer.h</tt> from flex is in your include
         path. You may need to give the path to <tt>FlexLexer.h</tt> to
         configure with an argument that looks something like:
         <tt>--with-include=-I/usr/local/include</tt>

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

    <li> GNU gmake (version 3.70 or greater): GNU specific extensions to make
         are used extensively.

    <li> perl: This is used to convert template classes to macros, generate
         and check the validation suite etc.  To compile SC, either perl 4
         or perl 5 will work.  To generate the validation inputs and
         automatically check the outputs, perl 5.003 or later is needed.

  </ul>

\section compilepreopt Optional Packages

The following packages are not necessary to compile MPQC, but may provide additional
features.

<ul>

    <li> A Message Passing Interface (MPI) is required to use MPQC in
         parallel on distributed memory machines.

    <li> The parallel MP2 and MP2-R12 methods require direct access to
         remote memory.  This requires one of two features: A thread-safe
         MPI (<a href="http://www.mpi-softtech.com">MPI Software
         Technology, Inc.</a> has developed a thread-safe MPI) or the <a
         href="http://www.emsl.pnl.gov/docs/parsoft/armci/">Aggregate
         Remote Memory Copy Interface (ARMCI)</a>.  These respectively
         permit remote memory access through the ARMCIMemoryGrp and the
         MTMPIMemoryGrp classes, respectively.

    <li> Libint (version 1.1.0 or higher): This is a machine-generated
         library that can be used for evaluation of certain molecular
         integrals. IntegralCints and MBPT2_R12 classes depend on this
         library. The library is freely available under GNU Public License
         (GPL) from <a
         href="http://www.ccmst.gatech.edu/evaleev/libint/">www.ccmst.gatech.edu/evaleev/libint/</a>.

    <li> Cca-chem-generic (version 0.2.0 or higher, and associated CCA tools):
         This package allows both stand-alone and embedded component applications  
         to be formed using MPQC-based components.  Visit the
         <a href="http://cca-forum.org/~cca-chem">CCA Chemistry Component Toolkit Homepage</a>
         for information on the freely available source code.

</ul>

\section compileconf Configuration

 You can build MPQC in the source code directory or you can make a
companion 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.

 In the target directory execute the <tt>configure</tt> command which is
located in the SC 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.
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>--enable-debug</tt><dd>Options for debugging will be given to the
  compiler.  Use <tt>--enable-debug=opt</tt> to use both debugging and
  optimization options.

<dt><tt>--with-default-parallel</tt><dd>Gives the default parallism
  specializations.  Can be <tt>none</tt> for no default or <tt>mtmpi</tt>
  for MTMPIMemoryGrp (MPI must be fully thread-safe) and MPIMessageGrp
  specializations.  The parallelism model can be overridden with command
  line arguments or environmental variables.

<dt><tt>--enable-always-use-mpi</tt>This can be given if MPIMessageGrp
  is to be the only MessageGrp that will be used.  This option should
  be given if the real argc and argv must be given to MPI_Init.

<dt><tt>--disable-parallel</tt><dd>Do not try to find communications
  libraries.

<dt><tt>--disable-threads</tt><dd>Do not try to find the multi-thread
  libraries.

<dt><tt>--enable-shared</tt><dd>Use shared libraries.  This will
  reduce the size of executables, if shared libraries are supported
  on your system.

<dt><tt>--disable-static</tt><dd>Do not build libraries for static linking.

<dt><tt>--enable-ref-debug</tt><dd>Check for overwrites and overflows of
  reference counts.  Implied by ``--enable-debug''.

<dt><tt>--disable-ref-macros</tt><dd>Use template classes for reference
  counting.  The default is to use a CPP macro to generate a class
  definition.

<dt><tt>--enable-cross-compile</tt><dd>If this option is set then the
  configure script will take care to not execute any compiled test
  programs.

<dt><tt>--enable-shared-libs</tt><dd>This will generate shared objects and
  link with them instead of standard ``.a'' libraries.  This works on a
  Linux-ELF system.

<dt><tt>--enable-components</tt><dd>This will generate CCA components and
  enable embedded CCA frameworks within MPQC.

<dt><tt>--with-build-id</tt><dd>This is used to generate unique shared
  library names and a unique default prefix for an MPQC installation.
  Unique shared library names must be used used by package distributors if
  a non-official ABI is used.  The official ABI is GCC-3.2.  Earlier
  versions of GCC are not compatible.  Installations with multiple C++
  compilers that use shared libraries should use --with-build-id to avoid
  accidentally dynamically linking with the wrong libraries.

<dt><tt>--with-default-memory</tt><dd>This specifies the default
memory allocation, which is used in absense of the memory> keyword in user's input.
The default is 32 million bytes (roughly, 32 MB).

<dt><tt>--with-cc</tt><dd>Gives the name of the C compiler.

<dt><tt>--with-cc-optflags</tt><dd>By default configure will attempt to
  guess a reasonable set of optimization flags.  These flags will be
  overridden by the argument given to this keyword.

<dt><tt>--with-cxx</tt><dd>Gives the name of the C++ compiler.

<dt><tt>--with-cxx-optflags</tt><dd>By default configure will attempt to
  guess a reasonable set of optimization flags.  These flags will be
  overridden by the argument given to this keyword.

<dt><tt>--with-f77</tt><dd>Gives the name of the FORTRAN compiler.

<dt><tt>--without-f77</tt><dd>configure will not try to find a FORTRAN
  compiler.  This can only be used if nothing more than the utility
  libraries are needed.

<dt><tt>--with-ranlib</tt><dd>Gives the name of the archive indexing
  utility.

<dt><tt>--with-ar</tt><dd>Gives the name of the program that makes
  libraries.

<dt><tt>--with-ld</tt><dd>Gives the name of the object linker.

<dt><tt>--with-include</tt><dd>Gives directories in which include files
  should be sought.  For example, <tt>--with-include="-I/u/local/inc
  -I/u/cljanss/include"</tt>

<dt><tt>--with-libs</tt><dd>Specifies libraries that executables should be
  linked with.  For example, <tt>--with-libs=-llapack_IRIX.a</tt>.

<dt><tt>--with-libdirs</tt><dd>Gives the directories in which libraries
  should be sought.  For example,
  <tt>--with-libdirs=-L/usr/local/lib64</tt>.

<dt><tt>--with-cca-chem-config</tt><dd>Specifies the config script for the
  cca-chem-generic package (prerequisite for CCA components).

</dl>

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

\subsection compilecca Notes on CCA Configuration

<ul>
  <li> Use the <tt>--enable-components</tt> flag to generate CCA components and enable 
       embedded frameworks within MPQC.  
  <li> The <tt>cca-chem-config</tt> script must be found in the user's path or 
       specified using the <tt>--with-cca-chem-config</tt>.
  <li> To fully support runtime configuration of component applications, 
       compile using <tt>--enable-shared</tt>.
  <li> Run <tt>make install_devel</tt> after compiling to install the <tt>sc-config</tt>
       script (required by <tt>cca-chem-apps</tt>).
</ul>

\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>.
This feature works correctly with GNU make version 3.78.1 or later; for
older versions of GNU make use <tt>make JOBS=-j4</tt>.

 You can install the executables and data files with <tt>make install</tt>.

 You can install the libraries and header files with <tt>make
install_devel</tt>, however, <tt>make install</tt> must be also be run to
install the files needed for run-time support.

\section compilecheck Checking the Compilation

See \ref mpqcval for instructions for checking your compilation.

*/