/*! \page install Installation/Linkage

libMASA uses the GNU autotools suite (autoconf, automake, and libtool)
for its development build system.  This system is popular among the
Linux development community and provides a familiar build environment
for end users.  

To build libMASA starting from a release distribution, untar the distribution and
enter the top-level directory.

<div class="fragment"><pre class="fragment">
 > tar xvfz masa-$(VERSION).tar.gz
 > cd masa-$(VERSION)/            
</pre></div>

<h2>Configuration Requirements</h2>

Since libMASA provides a Fortran interface, a valid Fortran90 compiler is
also required.  To date, libMASA has been successfully tested with \e
gfortran and the Intel \e ifort compilers.  The configuration step
will look for available compilers in the user environment but as with
any \e autoconf based configuration, these can be overridden with
command line arguments (by setting \c CXX, \c FC, and \c F77
appropriately).

<b>Installation Directory</b>: Use the <tt>--prefix</tt> option to
specify your desired top-level installation directory for MASA.  The
examples below all configure libMASA to be installed in the user's ~/bin/masa
directory.

Once configured, issue a <tt>make</tt> to build the software. If successful, this
will build the libMASA library (static and dynamic versions) and several
examples.

\code > make \endcode

<b> Verifying the build:</b> To verify that the software is working
properly, a test option is provided to run a short suite of
functionality tests against the local build.  To run, issue a <tt>make
check</tt> to run the tests.  If successful, output similar to the
following will be generated.

\code
 > make check

-------------------------------------------------------
Initializing MASA Tests
-------------------------------------------------------
PASS: init.sh
PASS: misc
PASS: fail_cond
PASS: catch_exception
PASS: register
PASS: poly
PASS: uninit
PASS: pass_func
PASS: purge
PASS: heat_const_steady
PASS: heat_var_steady
PASS: heat_const_unsteady
PASS: heat_var_unsteady
PASS: euler1d
PASS: euler2d
PASS: euler3d
PASS: euler_transient_1d
PASS: euler_chem_1d
PASS: ns2d
PASS: ns3d
PASS: ns3d_phys
PASS: n2d3d
PASS: axi_euler
PASS: axi_cns
PASS: rans_sa
PASS: sod
 
-------------------------------------------------------
Initializing CMASA Tests
-------------------------------------------------------
PASS: c_init.sh
PASS: c_misc
PASS: c_purge
PASS: c_heat1dsc
PASS: c_heat2dsc
PASS: c_heat3dsc
PASS: c_euler1d
PASS: c_euler2d
PASS: c_euler3d
PASS: c_euler_chem_1d
PASS: c_navierstokes2d
PASS: c_navierstokes3d
 
-------------------------------------------------------
Initializing FortMASA Tests
-------------------------------------------------------
PASS: f_init.sh
MASA :: selected mytest
PASS: f_misc
PASS: f_purge
PASS: f_heat
PASS: f_euler1d
PASS: f_euler2d
PASS: f_euler3d
PASS: f_euler_chem_1d
PASS: f_cns2d
PASS: f_cns3d
 
-------------------------------------------------------
Initializing MASA Examples Tests
-------------------------------------------------------
PASS: example_test.sh

-------------------------------------------------------
Finalizing MASA Tests, have a well verified day
-------------------------------------------------------
PASS: finalize.sh
===================
All 50 tests passed
===================

\endcode

<h2> Installation </h2>

After the build is complete, issue a <tt>make install</tt> to install
the library.  The installation will consist of three top-level
directories housing the library, include files, and
example files.  An example of the top-level directories after
installation is shown below:

\code > make install \endcode

Top-level libMASA installation directory:

\code
 > ls $HOME/bin/masa/
 examples/  include/  lib/
\endcode

<h2>Library Linkage</h2>

To link an external C/C++ or Fortran application with the library, the
\c include directory must be added to the compilers include search
path in order to access the masa.h header file (or for Fortran, the \c
lib directory should be added to access the pre-compiled
masa F90 module).  The \c lib directory should also be added
to the linker search path along with a request to link against the
libMASA library.  Several example link steps are provided below.  These
examples assume that the libMASA library has been successfully built and
installed previously in the users's ~/bin/masa directory:

<h3>C/C++ Example</h3>

\code > $(CC) -I$HOME/bin/masa/include app.c -L$HOME/bin/masa/lib -lmasa \endcode

If you set your <tt>PKG_CONFIG_PATH</tt> environment variable to contain
<tt>$HOME/lib/pkgconfig</tt> you can use <ahref="http://pkg-config.freedesktop.org/wiki/"><tt>pkg-config</tt></a> to
lookup the relevant linking information automatically:

\code > $(CC) `pkg-config --cflags masa` app.c `pkg-config --libs masa` \endcode

<h3>Fortran Example</h3>

Fortran applications also require linking against the fmasa library:

\code > $(FC) -I$HOME/bin/masa/lib app.f90 -L$HOME/bin/masa/lib -lfmasa -lmasa \endcode

As with C/C++, users can use make use of pkg-config:

\code > $(FC) `pkg-config --variable=fflags masa` app.f90 `pkg-config --variable=flibs masa` \endcode

To embed the dynamic library search path for the libMASA library
directly into the application executable, use an additional linker
option as follows:

<h3>C/C++ Example</h3>

\code > $(CC) -I$HOME/bin/masa/include app.c -L$HOME/bin/masa/lib \
         -Wl,-rpath,$HOME/bin/masa/lib -lmasa \endcode


<b>Important Note:</b> F90 module file formats are not consistent
across multiple compilers. Therefore, a Fortran application and the libMASA
F90 interface \em must be built with the same Fortran compiler family to ensure
compatibility.


*/