# Compiling

- Prerequisites
- Optional Packages
- Configuration
  - Notes on CCA Configuration
- Compilation
- Checking the Compilation

## Prerequisites

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

- 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 `--without-f77` 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.

  - GCC 2.96 and later, available from http://gcc.gnu.org. However, the 3.0 and 3.0.1 releases of GCC are not recommended.

  - 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: `--with-cxx='xlC_r -qrtti'`.

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

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

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

- 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 http://www.netlib.org/blas. 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.

- 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 http://www.netlib.org/lapack. 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.

- 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 http://lex.sourceforge.net.

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

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

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

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

## Optional Packages

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

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

- The parallel MP2 and MP2-R12 methods require direct access to remote memory. This requires one of two features: A thread-safe MPI (MPI Software Technology, Inc. has developed a thread-safe MPI) or the Aggregate Remote Memory Copy Interface (ARMCI). These respectively permit remote memory access through the ARMCIMemoryGrp and the MTMPIMemoryGrp classes, respectively.

- 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 www.ccmst.gatech.edu/evaleev/libint/.

- 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 CCA Chemistry Component Toolkit Homepage for information on the freely available source code.

## 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. `mpqc.i686-linux`) and will be referred to as the target directory below.

In the target directory execute the `configure` 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 `configure --help` to see a list of options. Options are specified with an equals sign, as in `configure --prefix=/usr/local`. Some options, such as all the `enable` and `disable` options, do not require an argument. Useful options to configure include:

`--prefix`
  Specifies the installation directory. The default is `/usr/local/mpqc/`version-number

`--enable-debug`
  Options for debugging will be given to the compiler. Use `--enable-debug=opt` to use both debugging and optimization options.

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

`--enable-always-use-mpi`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.
`--disable-parallel`
  Do not try to find communications libraries.

`--disable-threads`
  Do not try to find the multi-thread libraries.

`--enable-shared`
  Use shared libraries. This will reduce the size of executables, if shared libraries are supported on your system.

`--disable-static`
  Do not build libraries for static linking.

`--enable-ref-debug`
  Check for overwrites and overflows of reference counts. Implied by ``--enable-debug''.

`--disable-ref-macros`
  Use template classes for reference counting. The default is to use a CPP macro to generate a class definition.

`--enable-cross-compile`
  If this option is set then the configure script will take care to not execute any compiled test programs.

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

`--enable-components`
  This will generate CCA components and enable embedded CCA frameworks within MPQC.

`--with-build-id`
  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.

`--with-default-memory`
  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).

`--with-cc`
  Gives the name of the C compiler.

`--with-cc-optflags`
  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.

`--with-cxx`
  Gives the name of the C++ compiler.

`--with-cxx-optflags`
  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.

`--with-f77`
  Gives the name of the FORTRAN compiler.

`--without-f77`
  configure will not try to find a FORTRAN compiler. This can only be used if nothing more than the utility libraries are needed.

`--with-ranlib`
  Gives the name of the archive indexing utility.

`--with-ar`
  Gives the name of the program that makes libraries.

`--with-ld`
  Gives the name of the object linker.

`--with-include`
  Gives directories in which include files should be sought. For example, `--with-include="-I/u/local/inc -I/u/cljanss/include"`

`--with-libs`
  Specifies libraries that executables should be linked with. For example, `--with-libs=-llapack_IRIX.a`.

`--with-libdirs`
  Gives the directories in which libraries should be sought. For example, `--with-libdirs=-L/usr/local/lib64`.

`--with-cca-chem-config`
  Specifies the config script for the cca-chem-generic package (prerequisite for CCA components).

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

### Notes on CCA Configuration

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

## Compilation

Now you are ready to build the libraries and executables. Do this by typing `make` 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 `make -j4`. This feature works correctly with GNU make version 3.78.1 or later; for older versions of GNU make use `make JOBS=-j4`.

You can install the executables and data files with `make install`.

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

## Checking the Compilation

See Validating MPQC for instructions for checking your compilation.