|
GRVY-0.38.0
|
libGRVY 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. The three basic steps of the autotools process are:
These installation steps are discussed in more detail below followed by information on how to link against the library once installed. To initiate the build process starting from a release distribution, you should first untar the distribution and enter the top-level directory:
> tar xvfz grvy-0.38.0.tar.gz > cd grvy-0.38.0/
External Software Dependencies:
The minimum software required to build libGRVY is a local copy of the Boost library. Note that you can choose to build libGRVY against a header-only version of Boost or a full library installation. A build using the header-only version will disable some miscellaneous libGRVY functionality which leverages Boost libraries (grvy_copy_dir(), in particular). Additional library functionality can be enabled via linkage to optional HDF and MPI libraries.
If Boost is installed and available within your default login environment, then libGRVY should automatically configure against the available installation. If, however, your Boost installation is in a non-standard location, use the "--with-boost" option to specify the location.
Since libGRVY provides a Fortran interface, a valid Fortran90 compiler is also required. To date, libGRVY has been successfully tested with gfortran and the Intel ifort compilers. The configuration step will look for available compilers in the user environment but as with any autoconf based configuration, these can be overridden with command line arguments (by setting CXX, CC, and FC appropriately). For full documentation on available configuration options, run "configure --help". The examples below highlight common configuration examples:
Configure with Boost from default login environment (and request installation in user's ~/bin/grvy directory):
Or, configure with Boost from a specific directory:
Or, configure with specific Intel compilers:
Or, configure for Boost header-only compilation:
Or, enable optional functionality requiring MPI:
Or, enable optional functionality requiring HDF5:
Once configured, issue a "make" to build the software. If successful, this will build the libGRVY library (static and dynamic versions) along with relevant binaries and several examples.
Verifying the build: 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 "make
check" to initiate the tests. If successful, output similar to the following will be generated (the exact number of tests will vary depending on version and configuration options):
After the build is complete, issue a "make install" to install the library. The installation will consist of four top-level directories housing the library, binaries, include files, and example files. An example of the top-level directories after installation is shown below:
Top-level libGRVY installation directory:
To link an external C/C++ or Fortran application with an installed version of the library, the include directory must be added to the compilers include search path in order to access the grvy.h header file (or for Fortran, the lib directory should be added to access the pre-compiled grvy F90 module). The lib directory should also be added to the linker search path along with a request to link against the libGRVY library (and the Fortran interface for F90 applications). Several example link steps are provided below. These examples assume that the libGRVY library has been successfully built and installed previously in the users's ~/bin/grvy directory:
To embed the dynamic library search path for the libGRVY library directly into the application executable, use an additional linker option as follows:
Important Note: F90 module file formats are not consistent across multiple compilers. Therefore, a Fortran application and the libGRVY F90 interface must be built with the same Fortran compiler family to ensure compatibility.