Compiling with Blitz++
======================

Header files
------------

Blitz++ follows an X-windows style convention for header files.  All headers are referred to with a prefix of blitz.  For example, to use the Array<T,N> class, one needs to include <blitz/array.h> instead of just <array.h>.  To make this work, the main Blitz++ directory must be in your include path.  For example, if Blitz++ was installed in /software/Blitz++, you will need to compile with -I /software/Blitz++.

If you have root privileges, you may want to put in a symbolic link from the standard include path (e.g. /usr/include/blitz/) to the blitz directory of the distribution.  This will allow you to omit the -I ... option when compiling.

Linking to the Blitz++ library
------------------------------

The Blitz++ library file libblitz.a contains a few pieces of global data.  You should ensure that the lib subdirectory of the Blitz++ distribution is in your library path (e.g. -L/usr/local/blitz-0.5/lib) and include -lblitz on your command line.  If you use math functions, you should also compile with -lm.

An example Makefile
-------------------

Here is a typical skeletal Makefile for compiling with Blitz++ under gcc:

          [file makefile.example not included]

There are more example makefiles in the examples, testsuite, and benchmarks directories of the distribution.

Explicit instantiation
----------------------

It is not possible to do explicit instantiation of Blitz++ arrays.  If you aren't familiar with explicit instantiation of templates, then this fact will never bother you.

The reason is that explicit instantiation results in all members of a class template being instantiated.  This is not the case for implicit instantiation, in which only required members are instantiated.  The Array<T,N> class contains members which are not valid for all types T: for example, the binary AND operation &= is nonsensical if T=float.  If you attempt to explicitly instantiate an array class, e.g.

template class Array<float,3>;

then you will be rewarded with many compile errors, due to methods such as &= which are nonsensical for float.

As some consolation, explicit instantiation would not be much help with Blitz++ arrays.  The typical use for explicit instantiation is to instantiate all the templates you need in one compilation unit, and turn off implicit instantiation in the others -- to avoid duplicate instantiations and reduce compile times.  This is only possible if you can predict ahead of time what needs instantiation.  Easy for simple templates, but impossible for classes like Array.  Almost every line of code you write using Array will cause a different set of things to be implicitly instantiated.