IT++ Logo

IT++ Installation

Table of Contents

IT++ Requirements

IT++ should compile without errors or warnings on most GNU/Linux systems, on UNIX systems like Solaris SunOS, and on POSIX based environments for Microsoft Windows like Cygwin or MinGW with MSYS. It can be also built on Microsoft Windows NT/2000/XP using Microsoft's Visual C++ .NET, but our support for this compiler is limited. For GNU/Linux, SunOS, Cygwin and MinGW we assume that you have at least the following GNU software installed on your computer: To perform tests, two command line programs: sed and diff are required. Optionally, you might need a few additional programs, i.e. Doxygen, LaTeX, Dvips and Ghostscript, to generate the HTML documentation.

We strongly recommend that you use recent stable releases of the GCC, if possible. We do not actively work on supporting older versions of the GCC, and they may therefore (without prior notice) become unsupported in future releases of IT++.

In order to use all functionality provided by the IT++ library, it is recommended that you have some external libraries compiled and installed in your computer. The basic set of them is: BLAS, LAPACK and FFTW (version 3.0.0 or later).

Instead of NetLib's reference BLAS and LAPACK implementations, some optimized platform-specific libraries can be used as well, i.e.:

It is possible to compile and use IT++ without these libraries, but the functionality will be reduced. Therefore, we recommend that you take some time and effort to provide these external libraries in your system. Please note, that some of them (FFTW, BLAS and LAPACK) are usually included in most modern Linux distributions.

Obtaining the IT++ Source Codes

IT++ is released under the GNU General Public License (GPL) and hence the source code of the IT++ library is available for free download. To obtain the IT++ source code, visit the project pages on SourceForge: and download the file named itpp-<VERSION>.tar.gz or itpp-<VERSION>.tar.bz2, where <VERSION> is the latest release number, e.g. 4.0.0.

General IT++ Configuration, Compilation and Installation Instructions

Assuming that you have already downloaded the latest IT++ sources, untar and unpack the sources, and enter the unpacked directory. Depending on the package type you have downloaded, use the following commands:

% gzip -cd itpp-<VERSION>.tar.gz | tar xf -
% cd itpp-<VERSION>

% bzip2 -cd itpp-<VERSION>.tar.bz2 | tar xf -
% cd itpp-<VERSION>

Since version 3.9.0, the IT++ library uses autoconf, automake and libtool for preparing Makefiles and configuration script, so the compilation procedure resembles a standard, well-known GNU method, i.e.

% ./configure
% make

The `configure' command can be invoked with additional switches and options (run `./configure --help' to get a list of them). The most important are:

Plese note that each `--enable-<OPTION>' switch can be replaced with its opposite switch `--disable-<OPTION>'.

Since version 3.99.0, a modularization of the library has been introduced. Therefore, several additional switches have been added to the configure script, which can be used to disable building some of the library components. Here is a list of them:

By default, the `configure' script checks for a few external libraries, which might be used by the IT++ library (cf. IT++ Requirements). BLAS and LAPACK libraries require a Fortran compiler for linking. Therefore, if no Fortran compiler can be found, only FFT libraries are being searched. Otherwise, the detection procedure is as follows:

  1. First, the presence of a BLAS library among MKL, ACML, ATLAS and NetLib's reference BLAS is checked. If one of the above mentioned can be used, HAVE_BLAS is defined.
  2. Next, some LAPACK library is being searched, but only if BLAS is available. Full set of LAPACK routines can be found in the MKL, ACML and NetLib's reference LAPACK libraries. Besides, ATLAS contains a subset of optimised LAPACK routines, which can be used with NetLib's LAPACK library (this is described in the ATLAS documentation). If some LAPACK library can be found, HAVE_LAPACK is defined.
  3. Finally, a set of separate checks for FFT libraries is executed. Currently three different libraries providing FFT/IFFT routines can be used: MKL, ACML and FFTW. If at least one of them is found, HAVE_FFT id defined. Besides, one of the following: HAVE_FFT_MKL, HAVE_FFT_ACML or HAVE_FFTW3 is defined, respectively.

If some external libraries are installed in a non-standard location in your system, e.g. MKL in `/opt/intel/mkl/9.1', the `configure' script will not detect them automatically. In such a case, you should use LDFLAGS and CPPFLAGS environment variables to define additional directories to be searched for libraries (LDFLAGS) and include files (CPPFLAGS). For instance, to configure IT++ to link to the MKL 9.1 external library, which is installed in `/opt/intel/mkl/9.1' directory, you should use the following commands:

% export LDFLAGS="-L/opt/intel/mkl/9.1/lib/32"
% export CPPFLAGS="-I/opt/intel/mkl/9.1/include"
% ./configure

Instead of CPPFLAGS, one can use `--with-fft-include=<PATH>' configure option to set path to header files that provide FFT functionality, i.e. to `fftw3.h', `mkl_dft.h' or `acml.h'.

In the case that external libraries have non-standard names, e.g. `libblas3.a' for BLAS, you might specify them to the configure using `--with-<LIBNAME>' switches, where <LIBNAME> is one of the following: `blas', `lapack' or `fft'. You might use more than one library names by quoting them, e.g.

% ./configure --with-blas="-latlas -lblas"

If there is only one library specified, you can use a simplified notation without the preceding `-l', e.g. `--with-fft=fftw3' instead of `--with-fftw=-lfftw3'.

Although it is not recommended, you can intentionally prevent detection of some external libraries. To do this you should use `--without-<LIBNAME>' or `--with-<LIBNAME>=no', e.g.:

% ./configure --without-blas --without-lapack

It is recommended to set the CXXFLAGS environment variable with some compiler- and platform-specific optimisation flags, before invoking the `configure' command. Additionally, `-DNDEBUG' should be included in the optimised CXXFLAGS, because it turns off all conditional assertion checks. This will improve the computation performance of many IT++ functions. For example, in the case of using the Intel Pentium 4 processor one might employ the following flags:

% CXXFLAGS="-DNDEBUG -O3 -pipe -march=pentium4" ./configure

In the case of Sun's UltraSPARC 64-bit platform and GCC compiler, the flags might be set as follows:

% export CXXFLAGS="-DNDEBUG -O3 -pipe -mcpu=v9 -m64"
% ./confiugre

If CXXFLAGS is not set in the environment, it will be initialised with the default flags, i.e. "-DNDEBUG -O3 -pipe".

When the configuration process is finished, a status message is displayed. For instance, after having invoked the following configuration command on a recent Gentoo Linux system:

% ./configure --with-blas="-lblas"

one can observe something like this:

------------------------------------------------------------------------------
itpp-4.0.0 library configuration:
------------------------------------------------------------------------------

Directories:
  - prefix ......... : /usr/local
  - exec_prefix .... : ${prefix}
  - includedir ..... : ${prefix}/include
  - libdir ......... : ${exec_prefix}/lib
  - datarootdir .... : ${prefix}/share
  - docdir ......... : ${datarootdir}/doc/${PACKAGE_TARNAME}

Switches:
  - debug .......... : no
  - exceptions ..... : no
  - html-doc ....... : yes
  - shared ......... : yes
  - static ......... : no

Documentation tools:
  - doxygen ........ : yes
  - latex .......... : yes
  - dvips .......... : yes
  - ghostscript .... : yes

Testing tools:
  - diff ........... : yes
  - sed ............ : yes

Optional modules:
  - comm ........... : yes
  - fixed .......... : yes
  - optim .......... : yes
  - protocol ....... : yes
  - signal ......... : yes
  - srccode ........ : yes

External libs:
  - BLAS ........... : yes
    * MKL .......... : no
    * ACML ......... : no
    * ATLAS ........ : yes
  - LAPACK ......... : yes
  - FFT ............ : yes
    * MKL .......... : no
    * ACML ......... : no
    * FFTW ......... : yes

Compiler/linker flags/libs/defs:
  - CXX ............ : g++
  - F77 ............ : gfortran
  - CXXFLAGS ....... : -DNDEBUG -O3 -pipe
  - CXXFLAGS_DEBUG . :
  - CPPFLAGS ....... :
  - LDFLAGS ........ :
  - LIBS ........... : -lfftw3 -llapack -lblas

------------------------------------------------------------------------------
Now type 'make && make install' to build and install itpp-4.0.0 library
------------------------------------------------------------------------------

Now, it is time for compiling and linking the IT++ library. To do so, please simply run the following command:

% make

IT++ should compile without any errors or warnings. If this is not the case, please submit a bug-report on the IT++ project page at SourceForge. Please include information about your OS, compiler version, external libraries and their versions, etc.

It is recommended that you check if your library has been compiled and linked properly and works as expected. To do so, you should execute the testing process:

% make check

As a result, you should obtain a similar report:

------------------------------------------------------------------------------
Test `array_test' PASSED.
------------------------------------------------------------------------------
Test `bessel_test' PASSED.
------------------------------------------------------------------------------

[...]

------------------------------------------------------------------------------
Test `window_test' PASSED.
------------------------------------------------------------------------------
Test `histogram_test' PASSED.
------------------------------------------------------------------------------
Test `stat_test' PASSED.
------------------------------------------------------------------------------

Check if all the executed tests PASSED. If not, please contact us by filling a bug-report.

Finally, you should install the compiled and linked library, include files and (optionally) HTML documentation by typing:

% make install

Depending on the PREFIX settings during configuration, you might need the root (administrator) access to perform this step.

Eventually, you might invoke the following command

% make clean

to remove all files created during compilation process, or even

% make distclean

to remove all files generated by the `configure' script.

Instructions for IT++ Configuration on MacOS X

To compile and use IT++ under Mac OS X, you should install the latest version of Apple's developer tools. The tools are delivered with MacOS X, but you may need to unpack them. The configuration procedure is similar to the one described above.

There is one known problem with configuration on MacOS X. Here is the error message that might occur:

checking for Fortran libraries of g77... -lcrt2.o -L/sw/lib/gcc/powerpc-apple-da
rwin8.4.0/3.4.3 -L/sw/lib/gcc/powerpc-apple-darwin8.4.0/3.4.3/../../.. -lm -lfrt
begin -lg2c -lSystemStubs -lSystem -lmx /usr/lib/gcc/powerpc-apple-darwin8/4.0.1
/libgcc.a
checking for dummy main to link with Fortran libraries... unknown
configure: error: linking to Fortran libraries from C fails
See `config.log' for more details.

We have found out that this error is caused by a possible bug in an autoconf macro, which is responsible for setting FLIBS used for linking with fortran libraries. The problem is with "-lcrt2.o", which shouldn't be there.

The known solution is to set FLIBS by hand, e.g.:

% FLIBS="-L/sw/lib -lg2c" ./configure

or if it does not work, use the FLIBS detected by the autoconf omitting "-lcrt2.o":

% FLIBS="-L/sw/lib/gcc/powerpc-apple-darwin8.4.0/3.4.3 -L/sw/lib -lm -lfrtbegin
-lg2c -lSystemStubs -lSystem -lmx /usr/lib/gcc/powerpc-apple-darwin8/4.0.1/libg
cc.a"
% ./configure

BLAS and LAPACK support can be obtained with the vecLib framework, but you must then use Apple's GCC compiler. Hence, only FFTW is then needed to be installed externally.

How To Set Up a Local, Dual-config IT++ Installation without Being Root

This section presents a walkthrough of how to easily set up an IT++ environment without being root (all files are installed locally). The installation results in two parallel versions of the IT++ library, one version with debugging features enabled (this is slow in general but can be valuable during the development phase) and one version which is complied with maximum optimization. When compiling executables, one can then easily generate two versions of a program: one for debugging and one for maximum runtime efficiency. See the Makefile below for an example.

The philosophy behind this installation is:

The source code will reside in the directories itpp-external-3.0.0 and itpp-4.0.0. The libraries will be created in the directories it++external-3.0.0 and it++4.0.0.

The installation procedure goes as follows ($HOME can be replaced by any directory where you have write access):

  1. Download itpp-external-3.0.0.tar.bz2 and itpp-4.0.0.tar.bz2. Save them in your $HOME directory, and unpack them:
    % cd $HOME
    % tar jzf itpp-external-3.0.0.tar.bz2
    % tar jzf itpp-4.0.0.tar.bz2
    

  2. Compile and install the external libs
    % cd $HOME/itpp-external-3.0.0
    % make distclean
    % ./configure --prefix=$HOME/it++external-3.0.0 --disable-shared --enable-static
    % make && make install
    

  3. Compile and install the optimized and debugging IT++ libraries:
    % export LDFLAGS=-L$HOME/it++external-3.0.0/lib
    % export CPPFLAGS=-I$HOME/it++external-3.0.0/include
    % cd $HOME/itpp-4.0.0
    % make distclean
    % ./configure --disable-shared --enable-static --enable-debug --prefix=$HOME/it++4.0.0
    % make && make check && make install
    

  4. Go to a temporary directory, and create the following program example.cpp:
    #include <itpp/itbase.h>
    using namespace itpp;
    using namespace std;
    
    int main()
    {
      for (int i = 0; i < 10; i++) {
        mat X = randn(500, 500);
        mat Z = chol(X * X.transpose());
        cout << Z(0, 0) << endl;
      }
    
      for (int i = 0; i < 10; i++) {
        cvec a = fft(randn_c(10000));
        cout << a(5) << endl;
      }
    
      it_assert_debug(1 == 0, "Debugging is on!");
    }
    

    Also, in the same directory, create the following Makefile:

    FLAGS_DEBUG = `$(HOME)/it++4.0.0/bin/itpp-config --debug --cflags`
    FLAGS_OPT   = `$(HOME)/it++4.0.0/bin/itpp-config --cflags`
    
    LIBS_DEBUG  = `$(HOME)/it++4.0.0/bin/itpp-config --debug --static --libs`
    LIBS_OPT    = `$(HOME)/it++4.0.0/bin/itpp-config --static --libs`
    
    example: example.cpp
    	g++ $(FLAGS_DEBUG) example.cpp -o example_debug  $(LIBS_DEBUG)
    	g++ $(FLAGS_OPT) example.cpp -o example_opt  $(LIBS_OPT)
    

    This Makefile produces two programs: example_opt and example_debug. The former is optimized for performance but offers no debugging or assertions. The latter includes debugging info and is compiled with all assertions enabled (this generally gives "safe" but slow code).

    Run make and try the programs example_opt and example_debug. If this works the library is ready to use. (The program example_debug should exit with an assertion error.)

  5. If you want to conserve disk space, clean up all temporary files:
    % cd $HOME/itpp-external-3.0.0
    % make distclean
    % cd $HOME/itpp-4.0.0
    % make distclean
    

    To conserve even more diskspace (remove all sources) then do

    % rm -rf $HOME/itpp-external-3.0.0
    % rm -rf $HOME/itpp-4.0.0
    

Note: the make distclean commands in some steps may result in an error message; just ignore this. But the command is recommended because it guarantees that you start with a clean directory, in the event you would repeat the installation procedure.

IT++ Compilation and Installation using Microsoft Visual C++

It is possible to compile and link the IT++ library using the Microsoft Visual C++ .NET (or Express) compiler and either Intel Math Kernel Library (MKL) or AMD Core Math Library (ACML).

First, you need to install ACML or MKL in your system. If you decided to use ACML, please download the library built with PGI compiler for Windows, e.g. acml3.6.0-32-pgi.exe file for 32-bit systems. Please follow the default installation steps of the ACML or MKL installer, except for the installation directories. For MKL, use the following directory: "C:\Program Files\Intel\MKL" (without version number). For ACML: "C:\Program Files\AMD\acml". After waiting a few dozens of seconds you should have the chosen external libraries installed on your computer. Finally, you should add the directory with dll files to the PATH environment variable, e.g. "C:\Program Files\Intel\MKL\ia32\bin" or "C:\Program Files\AMD\acml\pgi32\lib".

The next step is to compile and link the IT++ library. Assuming that you have already downloaded and unpacked the IT++ package, you should find the itpp_acml.vcproj and itpp_mkl.vcproj MSVC++ project files in the win32 directory. Depending on the installed external library (ACML or MKL), open one of these project files in the MSVC++ IDE environment. There are two default targets prepared for compilation and linking: Debug and Release. The former can be used to compile a non-optimised version of the library for debugging purposes, named itpp_debug.lib, whereas the latter one should produce an optimised library named itpp.lib, which is also used by test programs. Both libraries are static ones and they should be created in win32\lib directory. IT++ should compile and link without any warnings or errors.

Last but not least, test programs can be compiled and linked to IT++ with MKL or ACML by using the project files included in win32\itpp_mkl_tests or win32\itpp_acml_tests respectively. The resulting executable test files should be created in win32\bin directory. Currently there is no automated method for comparing the output of these test programs with the reference files (*.ref) located in tests directory.

To learn how to set up your own project for linking with the IT++ library and ACML or MKL, please read the following manual: Linking your own programs with IT++ using MSVC++.

SourceForge Logo

Generated on Sun Sep 14 18:52:37 2008 for IT++ by Doxygen 1.5.6