187 lines
5.6 KiB
Text
187 lines
5.6 KiB
Text
/*! \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.
|
|
|
|
|
|
*/
|