Linking with IT++

Introduction

Since version 3.9.0, there are two convenient methods of linking your programs with the IT++ library. The first one employs the `pkg-config' command (see http://pkg-config.freedesktop.org/), wheres the second one uses the `itpp-config' script. These methods are shortly described below.

Using the pkg-config command

`pkg-config' is a helper tool used when compiling and linking programs or libraries. It provides correct compiler and linker options (flags). The syntax of the `pkg-config' command is as follows:

% pkg-config <options> <library_name>

For instance, assuming that you need to compile an IT++ based program `my_prog.cpp', you might use the following command:

% g++ `pkg-config --cflags itpp` -o my_prog my_prog.cpp `pkg-config --libs itpp`

If you have installed a debugging version of the IT++ library in parallel, you can ask the `pkg-config' command to provide flags for it as well. Just use `itpp_debug' name instead of `itpp' in the arguments:

% export CXXFLAGS_DEBUG=`pkg-config --cflags itpp_debug`
% export LIBS_DEBUG=`pkg-config --libs itpp_debug`
% g++ $CXXFLAGS_DEBUG -o my_prog my_prog.cpp $LIBS_DEBUG

Alternatively, when you have to use static linking only (e.g. in Cygwin or MinGW/MSYS), you might need to add the `--static' switch to your command:

% export CXXFLAGS=`pkg-config --cflags itpp`
% export LIBS=`pkg-config --static --libs`
% g++ $CXXFLAGS -o my_prog my_prog.cpp $LIBS

If `pkg-config' can not find the itpp library information, you might need to set the PKG_CONFIG_PATH environment variable with the directory where the `itpp.pc' file is installed (`$prefix/lib/pkgconfig' by default). Alternatively you can use the full path to the `itpp.pc' or `itpp_debug.pc' file, e.g.:

% pkg-config --libs /usr/local/lib/pkgconfig/itpp.pc

For more information please refer to the `pkg-config' documentation.

Using the itpp-config script

IT++ also provides a shell script called `itpp-config`, which is installed in a `$prefix/bin' (`/usr/local/bin') directory by default. It can be used to simplify the compilation and linking of IT++ based programs. The usage of this script is quite similar to the usage of the `pkg-config' command.

Assuming that you need to compile the program `my_prog.cpp', you can do that with the following command:

% g++ `itpp-config --cflags` -o my_prog my_prog.cpp `itpp-config --libs`

The above command will result in an optimised binary `my_prog', and optimisation flags (CXXFLAGS) will be the same as those used when compiling the IT++ library.

When you need to use static linking, you might need to prepend the `--libs' switch with `--static', e.g.:

% export CXXFLAGS=`itpp-config --cflags`
% export LIBS=`itpp-config --static --libs`
% g++ $CXXFLAGS -o my_prog my_prog.cpp $LIBS

Moreover, if you compiled and installed the debugging IT++ library (`libitpp_debug.*') by using `--enable-debug' swich to configure, you can compile and link your program with debugging options using the following command instead:

% g++ `itpp-config --debug --cflags` -o my_prog_debug my_prog.cpp `itpp-config --debug --libs`

Full list of `itpp-config' options can be obtained by typing:

% itpp-config --help

If the `itpp-config' command is not found by your shell, you should add its location `$prefix/bin' to the PATH environment variable, e.g.:

% export PATH=/usr/local/bin:$PATH

Using IT++ with dynamic linking

When using static linking some of the IT++ library routines are copied into your executable program. This can lead to unnecessary large executables. To avoid this you may use dynamic linking instead. Dynamic linking means that the actual linking is performed when the program is executed. This requires that the system is able to locate the shared IT++ library file (`libitpp.so' or `libittp_debug.so) during the program execution. If you have to install the IT++ library using non-standard prefix, the `LD_LIBRARY_PATH' environment variable might be used to inform the linker about the location of the shared library object (`$prefix/lib'), e.g.:

% export LD_LIBRARY_PATH="/usr/local/lib:$LD_LIBRARY_PATH"

This environment variable can be also used to set dynamic linking library paths for external libraries which are used by IT++, e.g. ATLAS, MKL, ACML and others.

Linking your own programs with IT++ using MSVC++

It is assumed here that the IT++ library is already compiled and linked with either ACML or MKL, using Microsoft Visual C++ .NET (or Express) compiler (see IT++ Compilation and Installation using Microsoft Visual C++).

To link your own programs with IT++ and ACML or MKL, several things need to be correctly set up in your MSVC++ project:

The IT++ include directory must be defined. Settings for this can be found in the "Tools -> Options -> Projects and Solutions -> VC++ Directories -> Include files" menu. Add path to "<IT++ source directory>", e.g. "C:\itpp-4.0.1".

The IT++ library directory must be defined. Settings for this can be found in the "Tools -> Options -> Projects and Solutions -> VC++ Directories -> Library files" menu. Add path to "<IT++ source directory>\win32\lib", e.g. "C:\itpp-4.0.1\win32\lib".

The ACML or MKL library directory must be defined. If you properly set up the LIB environment variable after the installation of ACML or MKL (see IT++ Compilation and Installation using Microsoft Visual C++), you can just add $(LIB) as an another library path.

Linking with IT++ and ACML or MKL must be set up. Do this by marking your project and go to the "Project -> Properties -> Configuration Properties -> Linker -> Input -> Additional Dependencies" menu. There you need to add itpp_debug.lib or itpp.lib depending on whether the Debug or Release mode are being used. Furthermore, you need to add libacml_dll.lib or mkl_c_dll.lib, respectively.

Two additional definitions: _CRT_SECURE_NO_DEPRECATE and _CRT_NONSTDC_NO_DEPRECATE, which disable warnings on Standard C Library and POSIX-compilant function names, might be also added in "Project -> Properties -> Configuration Properties -> C/C++ -> Preprocessor -> Preprocessor Definitions". Moreover, HAVE_ACML or HAVE_MKL definitions should be set up, depending on the installed library.

Please note that similar project settings for your program must be made for both the Debug and Release modes.

Using IT++ file format in Matlab/Octave

IT++ provides two m-files `itload.m' and `itsave.m', which can be used for reading and writing IT++ data files in Matlab or GNU Octave. To ensure that Matlab/Octave finds these two files you should add the following directory `$prefix/share/itpp' to the default path in Matlab/Octave, e.g.:

p = path; path(p, "/usr/local/share/itpp");