2 Building and Using XRTM
This section discusses, first, the process of building (compiling) XRTM including the core library, the language interfaces, the example programs, and the utility programs. Then the compilation details of using the XRTM core library and the appropriate language interface in your programs is outlined.
2.1 Building XRTM
2.1.1 GNU Make
The standard build system uses GNU Make (other versions of UNIX Make may work but are not tested). This should work on Linux, Unix, Mac OS, and on Windows using either Cygwin or MinGW (Minimalist GNU for Windows).
The first step is to configure the build for your environment. This includes setting the compiler commands and the associated options and setting the appropriate paths to external libraries. Settings are contained in the file make.inc in the XRTM base directory.
Compiler and associated options are contained within the section identified as "Compiler and linker settings". The commands for the compilers to use are represented by the variables CC, CXX, F77, and F90, for the C, C++, Fortran 77, and Fortran 90 compilers, respectively, and the associated options are represented by the variables CCFLAGS, CXXFLAGS, F77FLAGS, and F90FLAGS. The default settings are appropriate for GCC (GNU Compiler Collection) versions 4.2 and greater and should not have to be modified unless other compilers are being used. Note that XRTM is entirely C89/90 compliant except for the use of complex types. Therefore, the C compiler must be C99 compliant. As an alternative, all of XRTM's C code may be built with a C++ compiler in which case the complex support is through the C++ standard library's complex class.
The only external libraries that XRTM currently depends on are BLAS (Basic Linear Algebra Subprograms) and LAPACK (Linear Algebra PACKage). Reference version of both libraries may be obtained from http://www.netlib.org/ but it is highly recommend, at least for BLAS, that libraries optimized for your platform are used instead. The performance benefits are usually significant. Optimized versions of BLAS include Intel Math Kernel Library (MKL), AMD Core Math Library (ACML), Automatically Tuned Linear Algebra Software (ATLAS), and GotoBLAS.
For each library the appropriate compiler command line additions required to use them are represented by the variables LIB_BLAS and LIB_LAPACK contained in the section of make.inc identified as "BLAS and LAPACK settings". The values of these variables may contain link flags such as -lblas and -llapack and perhaps flags indicating the location of these libraries such as -L/opt/blas and -L/opt/lapack, respectively. The values may also be set to the libraries themselves such as /opt/blas/libblas.a or /opt/lapack/liblapack.a.
Once the proper settings have been set in make.inc XRTM may be compiled by executing the make command.
2.1.2 Visual Studio
XRTM may also be built on Windows using Visual Studio along with Intel's Visual Fortran Composer XE for Windows. Supported versions of Visual Studio are 2005, 2008, and 2010. Depending on which version is being used the XRTM Visual Studio solution may be loaded from one of the following solution (.sln) files relative to the XRTM base directory:
msvs_2005/xrtm.sln
msvs_2008/xrtm.sln
msvs_2010/xrtm.sln
2.2 Using XRTM in your code
To use XRTM in your own code you have to include/use the appropriate header/module file and link with the appropriate XRTM library files and any required external library files.
2.2.1 C
The C interface is part of the core library in the src/ directory. To use the C interface your code must include the following header file:
src/xrtm_interface.h
and must link with the following libraries:
src/libxrtm.a
misc/libxrtm_misc.a
or when using Visual Studio the following libraries:
$(SolutionDir)/$(ConfigurationName)/libxrtm.lib
$(SolutionDir)/$(ConfigurationName)/libxrtm_f.lib
$(SolutionDir)/$(ConfigurationName)/libxrtm_misc.lib
where the variable $(SolutionDir) is msvs_2005, msvs_2008, or msvs_2010 and the variable $(ConfigurationName) is Debug or Release.
For example, if one has C code in a file named my_code.c, includes the XRTM C interface header file with
#include <xrtm_interface.h>
and uses gcc to compile and link the code the command may look like this
gcc -O2 my_code.c -I$(XRTM_HOME)/src -L$(XRTM_HOME)/src -L$(XRTM_HOME)/misc \
-lxrtm -lxrtm_misc $(BLAS_STUFF) $(LAPACK_STUFF)
where the variable $(XRTM_HOME) is the location of the XRTM base directory and the variables $(BLAS_STUFF) and $(LAPACK_STUFF) represent what is required to link with BLAS and LAPACK, respectively. For more information, take a look at the build details for the C interface example program examples/example_c.c.
2.2.2 C++
To use the C++ interface your code must include the following header file:
interfaces/xrtm_int_cpp.h
and must link with the following libraries:
src/libxrtm.a
misc/libxrtm_misc.a
interfaces/libxrtm_interfaces.a
or when using Visual Studio the following libraries:
$(SolutionDir)/$(ConfigurationName)/libxrtm.lib
$(SolutionDir)/$(ConfigurationName)/libxrtm_f.lib
$(SolutionDir)/$(ConfigurationName)/libxrtm_misc.lib
$(SolutionDir)/$(ConfigurationName)/libxrtm_interfaces.lib
where the variable $(SolutionDir) is msvs_2005, msvs_2008, or msvs_2010 and the variable $(ConfigurationName) is Debug or Release. For more information, take a look at the build details for the C++ interface example program examples/example_cpp.cpp.
2.2.3 Fortran 77
To use the Fortran 77 interface your code must include the following file:
interfaces/xrtm_int_f77.inc
and must link with the following libraries:
src/libxrtm.a
misc/libxrtm_misc.a
interfaces/libxrtm_interfaces.a
or when using Visual Studio the following libraries:
$(SolutionDir)/$(ConfigurationName)/libxrtm.lib
$(SolutionDir)/$(ConfigurationName)/libxrtm_f.lib
$(SolutionDir)/$(ConfigurationName)/libxrtm_misc.lib
$(SolutionDir)/$(ConfigurationName)/libxrtm_interfaces.lib
$(SolutionDir)/$(ConfigurationName)/libxrtm_interfaces_f.lib
where the variable $(SolutionDir) is msvs_2005, msvs_2008, or msvs_2010 and the variable $(ConfigurationName) is Debug or Release. For more information, take a look at the build details for the Fortran 77 interface example program examples/example_f77.f.
2.2.4 Fortran 90
To use the Fortran 90 interface your code must USE the XRTM_INT_F90 module
and must link with the following libraries:
src/libxrtm.a
misc/libxrtm_misc.a
interfaces/libxrtm_interfaces.a
or when using Visual Studio the following libraries:
$(SolutionDir)/$(ConfigurationName)/libxrtm.lib
$(SolutionDir)/$(ConfigurationName)/libxrtm_f.lib
$(SolutionDir)/$(ConfigurationName)/libxrtm_misc.lib
$(SolutionDir)/$(ConfigurationName)/libxrtm_interfaces.lib
$(SolutionDir)/$(ConfigurationName)/libxrtm_interfaces_f.lib
where the variable $(SolutionDir) is msvs_2005, msvs_2008, or msvs_2010 and the variable $(ConfigurationName) is Debug or Release. For more information, take a look at the build details for the Fortran 90 interface example program examples/example_f90.f90.