bzsubsect(Header files)

bzindex(header files, convention)
bzindex(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 tt(Array<T,N>) class, one needs to include
tt(<blitz/array.h>) instead of just tt(<array.h>).
To make this work, the main Blitz++ directory must be in
your include path.  For example, if Blitz++ was installed
in tt(/software/Blitz++), you will need to compile with
tt(-I /software/Blitz++).

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

bzsubsect(Linking to the Blitz++ library)

bzindex(libblitz.a)
bzindex(library (libblitz.a))

The Blitz++ library file tt(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. tt(-L/usr/local/blitz-0.5/lib)) and include
tt(-lblitz) on your command line.  If you use math functions,
you should also compile with tt(-lm).

bzsubsect(An example Makefile)

bzindex(makefile, example)

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

bzverb(\
# Path where Blitz++ is installed
BZDIR = /usr/local/blitz-0.5

CXX = g++

# Flags for optimized executables
# CXXFLAGS = -O2 -I$(BZDIR) -ftemplate-depth-30

# Flags for debugging
CXXFLAGS = -ftemplate-depth-30 -g -DBZ_DEBUG -I$(BZDIR)

LDFLAGS =
LIBS = -L$(BZDIR)/lib -lblitz -lm

TARGETS = myprogram1 myprogram2

.SUFFIXES: .o .cpp

.cpp.o:
        $(CXX) $(CXXFLAGS) -c $*.cpp

$(TARGETS):
        $(CXX) $(LDFLAGS) $@.o -o $@ $(LIBS)

all:
        $(TARGETS)

myprogram1:      myprogram1.o
myprogram2:      myprogram2.o

clean:
        rm -f *.o $(TARGETS)
)

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

bzsubsect(Explicit instantiation)

bzindex(explicit instantiation)
bzindex(Array!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 bf(not) the case
for implicit instantiation, in which only required members are
instantiated.  The tt(Array<T,N>) class contains members which
are not valid for all types tt(T): for example, the
binary AND operation tt(&=) is nonsensical if tt(T=float).
If you attempt to explicitly instantiate an array class, e.g.

bzverb(\
template class Array<float,3>;
)

then you will be rewarded with many compile errors, due to methods
such as tt(&=) which are nonsensical for tt(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 tt(Array).  Almost every line of code 
you write using tt(Array) will cause a different set of things to be 
implicitly instantiated.


