\chapter{Installing Mesquite} \label{sec:install}

\section{Requirements}

\subsection{Downloading Mesquite}
The Mesquite distribution (in source form) may be obtained at the following URL:
\begin{center}
\url{http://www.cs.sandia.gov/~web1400/1400\_download.html}
\end{center}

\subsection{Supported Platforms and Build Requirements}
The Mesquite source code will compile in any environment comforming to the ISO/IEC 9899-1999 (C99), ISO/IEC 14882-1998 (C++98) and ISO/IEC 9945:2003 (POSIX) standards. It may also compile under many other environments.

Mesquite requires a reasonably standards-conforming C++ compiler and corresponding libraries.  No additional libraries are required to build the core Mesquite library. Several optional features have additional requirements.  These are listed in the next section.

Mesquite uses the GNU autotools build system.  The Makefiles generated by the
configure script should work on any Unix-like platform using the build tools
(e.g. make) provided with that platform.  The minimal requires beyond a C++
compiler are a Bourne shell (typically \texttt{/bin/sh}) implementation and
a minimal corresponding command environment and an implementation of the \texttt{make} utility.

Support for building Mesquite with Microsoft Visual Studio is no longer available as of Mesquite version 2.0.  Mesquite can still be built with Visual Studio but features added since the 2.0 release, such as building the iMeshP (Parallel) version, is not supported via CMake.

%Mesquite is regularly compiled and tested on GNU/Linux with g++ 3.2 or later %and Sun with the Sun Forte C++ compiler.  

\subsection{Optional Libraries and Utilities}
\label{sec:depends}
\begin{itemize}
\item Unit tests:  Mesquite provides a series of unit tests that may be used
to verify the correct behavior of a build of the Mesquite library.  These tests
are implemented using CppUnit framework.  The CppUnit framework must be installed
to compile and run these tests.  It is available at this URL:
\begin{center}
\url{http://cppunit.sourceforge.net}
\end{center}

To run the unit tests on Unix-like platforms:
\begin{verbatim}
  - build and install CppUnit.
  - If using CMake:
      o Set Mesquite_ENABLE_TEST to ON
      o search for 'cppunit' in CMake.
      o set CPPUNIT_INCLUDES to '<cppunit_install_dir>/include'  
      o set CPPUNIT_LIBRARY to '<cppunit_install_dir>/lib/libcppunit.so' 
      o Congigure and then Generate to produce CMake files
      o After generation, exit CMake and cd to the build directory specified
        in CMake.  
      o Enter:
           $ make
           $ ctest

  - If using GNU Autotools:
      o From the top-level mesquite directory, Enter:
           $ ./configure --with-cppunit=<cppunit_install_dir>
           $ make
           $ make check

\end{verbatim}
\item ExodusII support:  To enable support for reading or writing ExodusII files in Mesquite, the header files for the ExodusII library must be available and the library supporting ExodusII, the ExodusII library and possibly the NetCDF library must be available. If you need to build the ExodusII libraries from source, you will need to build the NetCDF library first.  ExodusII files can be read via the MeshImpl::read\_exodus(...) function and written via the MeshImpl::write\_exodus(...) function. 

 The ExodusII library can be obtained at the following URL:
\begin{center}
\begin{small}\url{http://sourceforge.net/projects/exodusii}\end{small}
\end{center}

The NetCDF library can be obtained at the following URL:
\begin{center}
\begin{small}\url{http://www.unidata.ucar.edu/downloads/netcdf/index.jsp}\end{small}
\end{center}


\end{itemize}

\section{Release and Debug Builds}
Mesquite can be built in either a Release or Debug mode. On Unix-like systems the type of build is specified via an option on the configure command as detailed in Section \ref{build_options}. On Windows systems the type of build is selected through the CMake utility as explained in Section \ref{windows_build}. For Mac systems, the build type is specified in the do-configure script as shown in Section \ref{building_mac}.  The default mode on all systems is Release.


\section{Building Mesquite}
\label{sec:compiling}
After downloading and unpacking the Mesquite source, the next step is to 
configure and build and install the Mesquite library.  
\subsection{Compiling on Unix-like systems}
This section presents the steps required to compile Mesquite with the default
options.  It is typically required
that Mesquite be "installed" before it is used in an application.  The default 
installation location is the system-wide \texttt{/usr/local} directory.  
It is more common to specify an alternate directory in which to install 
the Mesquite library and headers.  This can be done using the \texttt{--prefix}
option to the \texttt{configure} script.  Additional options are available for
fine-grained control of installation locations.
\begin{enumerate}
\item Change your working directory to the top-level Mesquite source
      directory (typically \texttt{mesquite-<version>/}).
\item Run the configure script with the command: 
\begin{center}
\texttt{./configure --prefix=<installdir>},
\end{center}
      replacing \texttt{<installedir>} with the location in which the finished
      Mesquite library is to be placed.
\item Compile Mesquite with the command: \texttt{make} 
\item Optionally verify that Mesquite compiled correctly with the command: \texttt{make check}
\item Move resulting files into the destination (install) directory with the command: \texttt{make install}
\end{enumerate}
If the configure step failed, please consult the following section describing 
some of the optional arguments to the \texttt{./configure} script. 

CMake can also be used to build Mesquite on Unix-like systems.  With a version of CMake in your path, the command \texttt{ccmake} will invoke a text-based version of CMake, the command \texttt{cmake-gui} runs a graphical version. Instructions for configuring with CMake are found in Section \ref{windows_build}.  After generating the make files, exit CMake and cd to the specified build directory and enter the command: \texttt{make}.  

\subsection{Options for Unix-like systems}
\label{build_options}
This section describes the options available for customizing the build
system and the resulting Mesquite library.  An brief description of these
and other options is available with the command: \texttt{./configure --help}.

\label{mes_vars_and_defs}
The following values may be specified as environmental variables, as arguments
to the configure script using the NAME=VALUE syntax, or as arguments to \texttt{make}
using the NAME=VALUE syntax.  The value of these variables (if set) during the
configure step will become the default for the compile step.  The value of any
of these variables will override the default if specified during the compile
step.
\begin{description}
\item[CXX]       The C++ compiler command
\item[CXXFLAGS]  Arguments to the C++ compiler, such as those specifying 
debug symbols or the optimization level.
\item[CC]        The C compiler command
\item[CFLAGS]    Command line arguments to be used for the C compiler.
\item[DOXYGEN]   The doxygen API documentation generation tool.
\end{description}

Most options to the configure script are either of the form 
\begin{center}
\texttt{--with-FEATURE[=ARG]} or \texttt{--enable-FEATURE[=ARG]}.
\end{center}
Some options may accept an additional argument following 
an `=' character.  For each --with-FEATURE option, there is also a corresponding
--without-FEATURE option.  Similarly, there is a --disable-FEATURE option 
corresponding to each --enable-FEATURE option.  The negative forms fo the options 
(--without-FEATURE and --disable-FEATURE) do not accept an additional argument.  
Only the positive form of each option is stated in the description below.  

\label{config_options}
The following general build and debug options may be specified during the configure step:
\begin{description}
\item[\texttt{--}enable-debug]  Select a subset of the following options that
make the most sense for developers of Mesquite, implies: \texttt{--}enable-debug-symbols, \texttt{--}enable-debug-output=1,2, \texttt{--}enable-trap-fpe,
                          \texttt{--}enable-silent-rules

\item[--enable-release]  This is the default behavior unless 
--enable-debug is specified.  It selects a subset of the following options that
typically work best for using Mesquite in a production application.
\item[\texttt{--}enable-compile-optimized] Compile with the available 
optimizations that improve performance without any significant drawbacks 
(the -O2 compiler flag.)
\item[\texttt{--}enable-debug-symbols] Include debugging information in
the compiled Mesquite objects (the -g compiler flag).
\item[\texttt{--}enable-debug-assertions]  Include internal consistancy 
checks that abort when an error is detected.
\item[\texttt{--}enable-debug-output=n,m,...]  Enable the output of
debug and status messages to file descriptor 1 (stdout).  An 
list of integer debug flags for which to enable output may be specified 
as a comma-separated list of values.  The default is to enable debug
flags 1 and 2 if this option is specified without any explicit debug
flag values.
\item[\texttt{--}enable-function-timers]  Enable time-profiling of
some portions of Mesquite.
\item[--enable-trap-fpe]  Enable generation of a floating-point
exception signal for arithmetic errors (e.g. division by zero.)  This is
an option intended for Mesquite developers.  Enabling this will typically cause
the application using Mesquite to abort when such an error is encountered.
\item[\texttt{--}enable-namespace=NAME]  Specify an alternate namespace so as to avoid
symbol conflicts between multiple versions of Mesquite.  See Section \ref{namespace_mangling}.
\item[\texttt{--}disable-option-checking]  Ignore unrecognized \texttt{--}enable\/\texttt{--}with options.
\item[\texttt{--}enable-shared[=PKGS]]  Build shared libraries [default=no]
\item[\texttt{--}enable-static[=PKGS]]  Build static libraries [default=yes] 
\item[\texttt{--}enable-silent-rules]  Less verbose build output (undo: `make V=1')
\item[\texttt{--}disable-silent-rules]  Verbose build output (undo: `make V=0') 
\item[\texttt{--}enable-fast-native]  Compile with fast math options, target build CPU, etc. 
\item[\texttt{--}enable-quiet-make]  Much less verbose output during build. Default is no unless \texttt{--}enable-debug was specified.
\item[\texttt{--}enable-32bit]  Force 32-bit object code.
\item[\texttt{--}enable-64bit]  Force 64-bit object code.
\item[\texttt{--}disable-dependency-tracking] Speeds up one-time build.
\item[\texttt{--}enable-dependency-tracking]  Do not reject slow dependency extractors. 
\item[\texttt{--}disable-libtool-lock]  Avoid locking (might break parallel builds) 
\item[\texttt{--}enable-api-doc=FORMATLIST]  Generate Doxygen docs for the API. Available formats are 
HTML, PDF, PS, ALL. Default is no docs. Multiple values must be separated by commas with no spaces. When the 'make' command is entered after configuring for api docs, the requested documents will be created in the mesquite/doc/user/doxygen directory.
\item[\texttt{--}enable-user-guide=FORMATLIST]   Generate Mesquite Users Guide. Available formats are PDF ,PS, ALL. Default is no docs. Multiple values must be separated by commas with no spaces.  When the 'make' command is entered after configuring for the users guide, the requested documents will be created in the mesquite/doc/user directory.
\end{description}


The following options specify optional Mesquite components and the location 
of the corresponding dependencies.
\begin{description}
\item[\texttt{--}with-cppunit=DIR]  The CppUnit library is required to compile
and run the tests to verify that a particular build of the Mesquite library
is working correctly.  If the CppUnit library is not installed in a default location where the ./configure script can find it, this option may be used to specify
the location.
\item[\texttt{--}with-exodus=DIR]  Enable support for reading and writing
ExodusII files, and optionally specify the location where the ExodusII library
and headers required for this option are installed.
\item[\texttt{--}without-cppunit]  Disable CppUnit tests.
\item[\texttt{--}without-exodus]  Disable exodusII support (default).
\item[\texttt{--}with-netcdf=DIR]  Specify the location of the NetCDF library
required by the ExodusII library.  The default is to look in the ExodusII
directory.
\item[\texttt{--}without-netcdf]  Skip NetCDF check.
\item[\texttt{--}with-mpi=DIR]  Enable parallel support.
\item[\texttt{--}with-pic]  Try to use only PIC/non-PIC objects [default=use both].
\item[\texttt{--}with-gnu-ld]  Assume the C compiler uses GNU ld [default=no]. 
\item[\texttt{--}with-imesh=PATH]  Path to iMesh-Defs.inc (enable iMesh).
\item[\texttt{--}with-imeshp=PATH]  Path to iMeshP-Defs.inc (enable iMeshP).
\end{description}

\subsection{Compiling on Microsoft Windows (CMake build) \label{windows_build} }

The Mesquite source includes the necessary input files to generate Microsoft
Visual Studio project files using the CMake utility.  You will need to 
download and install the CMake utility for Windows if you have not already done so.  It is available at:
\begin{center}
 \url{http://www.cmake.org/cmake/resources/software.html}
\end{center}

Using the graphical version of the CMake utility, select the folder containing the Mesquite source and enter a folder in which you would like the CMake output and compiled code to be stored.  Select the \texttt{Configure} button.  You will be presented with a group of configuration options.  Modify any desired options and click the \texttt{Configure} button again.  Each time you change one or more configuration options, you must click the \texttt{Configure} button to update the list of available options.

 The 'CMAKE\_BUILD\_TYPE' opton controls the build mode that will be used by Visual Studio. Set the option to either 'RELEASE' or 'DEBUG.  The build mode can also be changed from within Visual Studio itself after the generated project file has be loaded.

  When you have finished changing build options, click the \texttt{Generate} button to generate Visual Studio input files and exit the CMake utility.

The build folder you specified in the CMake utility should now contain the necessary input files to build Mesquite using Microsoft Visual C++.  

\subsection{Linking Multiple Versions of Mesquite \label{namespace_mangling} }

Sometimes it is necessary to have multiple different versions of a library 
such as Mesquite linked into the same application.  This situation typically
arises when an application needs both Mesquite and some other library that depends on an older version of Mesquite.  Without taking steps to avoid symbol
name conflicts such a situation will often result in surprising, strange, and
difficult to diagnose runtime errors.  

Mesquite provides the ability to specify an alternate namespace and a standard
namespace alias to assist with addressing such situations.  The ``namespace'' \texttt{Mesquite} is typically an alias to the true internal C++ namespace containing all Mesquite code.  Applications can and should use that alias rather than the internal namespace to avoid the need to modify application code whenever the internal namespace changes.  

The internal namespace can be changed with the configure option \texttt{--enable-namespace=MyNS} or the cmake option \texttt{Mesqutie\_NAMESPACE}, where the value ``MyNS'' can be replaced with any string that is an acceptable C++ namespace label.  The default namespace is \texttt{MesquiteN}, with the Mesquite major version substituted for \texttt{N}.  Specifying an alternate internal namespace results in different mangled symbol names in the compiled library, thus avoiding symbol name conflicts.

If the requested namespace is anything other than ``Mesquite'', then Mesquite will always provide the alias \texttt{namespace Mesquite = MESQUITE\_NS;} so that application code may always use the \texttt{Mesquite} namespace.

\section{Building Trilinos Mesquite from Scratch on a Mac}
\subsection{Installation}
\label{mac_installation}

Trilinos depends on git and cmake.
macports is a tool for downloading and installing software on macs.
At Sandia, downloads to macs are done through portal 80.
in /opt/local/etc/macports/macports.conf set 
\begin{verbatim}
proxy_http        wwwproxy.sandia.gov:80
proxy_https       wwwproxy.sandia.gov:80
proxy_ftp         wwwproxy.sandia.gov:80
\end{verbatim}
However leave proxy\_rsync undefined.


First install macports.  Type {\tt macports} into google, and follow links to download and install.
macports  installs to /opt/local/bin  and /opt/local/lib.
To verify that macports is correctly installed,  first  type {\tt which port},  then go on to step 2.
Also if an install fails for some indiscernible reason, 
first try simply repeating the install command.

\begin{verbatim}
sudo port selfupdate   
sudo port search git-core
sudo port install git-core +bash_completion
sudo port search cmake
sudo port install cmake   
\end{verbatim}
The build of Mesquite with automake and autotools depends on  libtoolize, which can be downloaded similarly.

Check Trilinos (and test that git has been ported successfully) by entering:

\begin{center}
 {\tt git clone software.sandia.gov:/space/git/Trilinos}.
\end{center}

Download clang from {\tt "http://llvm.org/releases/download.html". } Select {\tt "Clang Binaries for MacOS X/x86-64"} and install it (unpack the .tar.gz file).

This usually puts the downloaded tarball into HOME/Downloads, though you can specify a different download directory if you've configured your web browser that way.  Choose a place to put the directory of binaries, such as  HOME/pkg,
\begin{verbatim}
mkdir ~/pkg
mv clang+llvm-3.0-x86_64-apple-darwin11.tar.gz ~/pkg
tar xvzf clang+llvm-3.0-x86_64-apple-darwin11.tar.gz
\end{verbatim}
This creates a {\tt clang+llvm-3.0-x86\_64-apple-darwin11} directory.  
The bin subdirectory has the C and C++ compiler front ends (clang resp. clang++).
\subsection{Building}
\label{building_mac}
Create a build directory for Trilinos.
\begin{verbatim}
cd Trilinos
mkdir Serial
cd Serial
\end{verbatim}
Write a do-configure script for building Trilinos that uses the C and C++ compiler front ends, such as:
\begin{verbatim}
EXTRA_ARGS=$@

CC=$HOME/pkg/clang+llvm-3.0-x86_64-apple-darwin11/bin/clang
CXX=$HOME/pkg/clang+llvm-3.0-x86_64-apple-darwin11/bin/clang++

#rm -f CMakeCache.txt

cmake \
-D CMAKE_BUILD_TYPE:STRING=DEBUG \
-D HAVE_GCC_ABI_DEMANGLE:BOOL=ON \
-D DART_TESTING_TIMEOUT:STRING=600 \
-D Trilinos_ENABLE_Fortran:BOOL=OFF \
-D CMAKE_CXX_COMPILER:FILEPATH="$CXX" \
-D CMAKE_C_COMPILER:FILEPATH="$CC" \
-D Trilinos_ENABLE_DEBUG:BOOL=ON \
-D Trilinos_ENABLE_TESTS:BOOL=ON \
-D Trilinos_ENABLE_ALL_PACKAGES:BOOL=OFF \
-D Trilinos_ENABLE_Mesquite:BOOL=ON \
-D Tpetra_ENABLE_TESTS:BOOL=ON 
$EXTRA_ARGS \
..
\end{verbatim}
Make the script executable, {\tt chmod a+x do-configure}, and then run it to configure Trilinos.

It is also possible to build Mesquite on a Mac using the graphical version of CMake. Just follow the instructions in Section \ref{windows_build} (downloading the Mac version instead of the Windows version of course).

Next build Trilinos with $make$.

It is possible to build OpenMPI (e.g. 1.4.5) with clang and clang++.  It is necessary to to turn off generation of the Fortran MPI bindings.  
OpenMPI is built in a directory completely separate from the OpenMPI source tree.
 Here is a configure line for building OpenMPI with Clang:
 \begin{verbatim}
$ CC=$HOME/pkg/clang+llvm-3.0-x86_64-apple-darwin11/bin/clang 
CXX=$HOME/pkg/clang+llvm-3.0-x86_64-apple-darwin11/bin/clang++
 ../openmpi-1.4.5/configure --prefix=$HOME/pkg/openmpi-1.4.5
  --disable-mpi-f77 --disable-mpi-f90
\end{verbatim}




