[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1 Introduction


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.1 About this document

To use the Blitz++ library, you will need a compiler with near-ISO/ANSI C++ syntax support (see the following section for possible compilers). Information on what platforms are supported is available from http://oonumerics.org/blitz/platforms/. To download Blitz++, please go to the download page at http://oonumerics.org/blitz/download/.

If you need to do something that Blitz++ doesn’t support, see a possible improvement, or notice an error in the documentation, please send a note to one of the Blitz++ mailing lists (described later).


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.2 Platform/compiler notes

For up-to-date information on supported platforms, please consult the platforms area on the Blitz++ home page:

http://oonumerics.org/blitz/platforms/

The information in this document may be out of date.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.2.1 KAI C++ for Linux/Unix

Blitz++ was developed and tested using KAI C++ under AIX. It should (in theory) port to other KAI C++ platforms (Cray, SGI, HP, Sun, Linux, Compaq) without difficulty. Since KAI C++ uses an EDG front end, other EDG front-ended compilers (e.g. Comeau) should be able to compile Blitz++.

Recommended compile flags are:

+K3 -O2 --restrict --abstract_pointer --abstract_float -tused

Note that you cannot compile with -tall (this will generate lots of errors).

Under Linux, you may need the flag -D__signed__=. You should omit -tused since this template instantiation model is not supported by gcc, which is used as the back-end compiler.

Please note that since the purchase of KAI by Intel several years ago, the use of this compiler has been gradually phased out, with most of the KAI compiler technology being transferred into the Intel C/C++ compiler. Thus, Blitz++ is no longer being routinely tested under KCC.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.2.2 Intel C++ for x86

Blitz++ compiles under fairly recent versions of the Intel C++ compiler (version 7.1, 8.x or 9.0) for Linux platforms, as well as the comparable plug-in compiler for Windows that can be used within the Microsoft Visual Studio IDE. We recommend use of the -ansi flag for compiler adherence to the ANSI C++ standard. The -strict_ansi flag is not used, as this can lead to many compiler error messages originating from code in the GNU C++ standard library header files.

More information:

http://www.intel.com/software/products/compilers/clin

http://www.intel.com/software/products/compilers/cwin


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.2.3 Microsoft VS.NET 2003 for Windows

Blitz++ has been ported to the C++ compiler within the Microsoft VS.NET 2003 compiler and IDE package. We provide a zip archive containing an appropriate configuration header file and project files for building the Blitz library and all of the testsuite codes. Previous versions of the Microsoft C++ compiler within Visual Studio do not have the required C++ features needed by Blitz++ and are not supported. Blitz can be compiled under Visual Studio by using the Intel plug-in C++ compiler for Windows.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.2.4 gcc for Linux/Unix/Darwin

GCC (g++) is a free GNU C++ compiler. It compiles Blitz++ reliably on almost any platform running Linux or another Unix variant (including the Darwin OS). In fact, most Blitz++ development work is done with g++.

Work has been done in the latest Blitz++ release to ensure compatibility with the gcc-4.x release, which contains some key changes in enforcement of the C++ ANSI standard related to the use of anonymous enums.

gcc may be downloaded from http://www.gnu.org/software/gcc/gcc.html.

If you are using gcc under Solaris, SunOS, or OSF/1, please see the ‘README.binutils’ file included in the distribution.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.2.5 PathScale for x86_64

We have just added support for the PathScale pathCC compiler in blitz-0.9. This compiler is being provided on many of the newer Opteron x86_64 systems. We welcome feedback on support for this compiler.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.2.6 PGI for Linux x86

The Portland Group PGI compiler is supported on Linux x86 platforms, and more recent versions of pgCC such as 5.x are capable of compiling blitz. However, performance is not particularly good and PGI support is not being actively tested or maintained.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.2.7 Absoft for Mac OS X

Absoft markets a variant of the IBM xlC compiler called xlc++ that has been ported to the Darwin operating system (Mac OS X). We are providing support for compiling blitz using this compiler. Although we have noted and reported some bugs with this compiler, it is capable of producing fairly high quality optimized code for the Darwin platform.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.2.8 Metrowerks for Mac

Metrowerks is sort-of supported; see the platforms web page and the mailing lists for more information. Support for Metrowerks is no longer being actively maintained.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.2.9 Compaq Alpha

The Compaq C++ compiler version 6.x is supported, and we recommend use of the -model ansi flag in order to obtain standard C++ compiler behavior and proper name mangling. We have inserted a workaround for the lack of standard ostream support for the long double type. At this point, performance of blitz code under the cxx compiler is somewhat disappointing.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.2.10 IBM RS6000/IBM PowerPC

The IBM Visual Age C++ compiler is supported as of version 6.x. However, you may run into a variety of annoying compiler bugs that prevent certain portions of the Blitz++ library code from compiling. Therefore, it is strongly recommended that you obtain xlC version 7.0.0.3 or later, in order to get all the necessary patches that IBM has produced in response to our bug reports. Also note that compile times can be fairly long with full optimization enabled.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.2.11 SGI MIPSpro

The SGI MIPSpro-7.x version CC compiler is supported, although active testing is no longer being done.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.2.12 Sun SPARC

As of version Sun Studio 10.x, the Sun CC compiler should be capable of compiling blitz. However, no active support is being provided.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.2.13 Cray T3E/Cray T90/Cray C90/Cray J90

As of Version 0.2-alpha-02 of Blitz++, Version 3.0.0.0 of the Cray C++ compiler is supported (well, tolerated anyway). It seems to be based on an older version of the EDG front end, so some kludges are required. It doesn’t support partial ordering of member templates, so slicing arrays requires the workaround described in Section Slicing. Portions of the standard library are missing, such as <limits>, <complex>, and <set>. This means you won’t be able to use complex numbers (well, not the ISO/ANSI C++ versions anyway), numeric inquiry functions, or fast traversal orders.

These compilation flags are recommended:

-h instantiate=used

For optimization, you’ll want:

-O3 -h aggress

The ability of the Cray C++ compiler to optimize away temporary objects is disappointing. It’s not able to optimize away expression templates overhead or comma-delimited array initializers. Please note that support for compiling Blitz++ under the Cray C++ compiler is no longer being actively maintained.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.2.14 Fujitsu

This platform and compiler are no longer being actively supported.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.3 How to download Blitz++

The Blitz++ project is now being served via SourceForge. To download the Blitz++ library, go to the blitz project web page, at http://sourceforge.net/projects/blitz.

More information about supported platforms and C++ compilers is available in this document or on the official Blitz++ home page, at http://oonumerics.org/blitz.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.4 Installation and porting


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.4.1 Installation

Blitz++ uses GNU Autoconf, which handles rewriting Makefiles for various platforms and compilers. It has greatly simplified installation and porting. Many thanks to John W. Eaton and Brendan Kehoe for their help with this.

To install blitz, unpack the ‘blitz-VERSION.tar.gz’ file (it will install into a subdirectory ‘blitz-VERSION’). For example:

[tveldhui@n2001:~] 32: ls -l blitz*.gz
-rw-r--r--   1 tveldhui users      480953 Jun 23 15:20 blitz-0.5.tar.gz
[tveldhui@n2001:~] 33: gunzip blitz-0.5.tar.gz 
[tveldhui@n2001:~] 34: tar xvf blitz-0.5.tar
blitz-0.5/CHANGELOG
blitz-0.5/COPYING
blitz-0.5/INSTALL
blitz-0.5/Makefile.in
blitz-0.5/README
blitz-0.5/THANKS
  .
  .

Then go into the ‘blitz-VERSION’ directory, and type:

./configure CXX=[compiler]

where [compiler] is one of xlc++, icpc, pathCC, xlC, cxx, aCC, CC, g++, KCC, pgCC or FCC. (If you do not choose a C++ compiler, the configure script will attempt to find an appropriate compiler for the current platform.)

By default, the configure script will use a particular set of options with each C++ compiler. You can disable these default settings and then substitute your own preferred compiler options with the CXXFLAGS variable, using this syntax:

./configure CXX=g++ --disable-cxx-flags-preset CXXFLAGS="-ftemplate-depth-50"

If you are interested in benchmarking, you may want to use the option --with-blas=... to specify the path where the blas library is found. Run the configure script with the option --help to see all the available options.

Once the configure script is done, you can do any of these things:

make lib

Check the compiler and create ‘libblitz.a’.

make check-testsuite

Make the blitz library plus build and run the testsuite.

make check-examples

Make the blitz library plus build and run the examples.

make check-benchmarks

Make the blitz library plus build and run the benchmarks.

make all

Do all of the above. This may take a long time.

make install

Build the blitz library and documentation and install, along with the blitz header files, in prefix directory.

Building the benchmark programs requires both a Fortran 77 and Fortran 90 compiler.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.4.2 The Blitz++ directory tree

The main Blitz++ directory contains these subdirectories:

blitz

Blitz++ headers and source code files

random

Random number generators

src

Source code for ‘libblitz.a

lib

Location of ‘libblitz.a

doc

Documentation in HTML and PostScript

testsuite

Testsuite programs

examples

Example programs

benchmarks

Benchmark programs


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.4.3 Porting Blitz++

If you want to try porting Blitz++ to a new compiler or platform, I suggest the following approach:


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.5 Compiling with Blitz++


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.5.1 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.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.5.2 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.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.5.3 An example Makefile

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

# Path where Blitz++ is installed
BZDIR = /usr/local/blitz

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.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.5.4 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.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.6 Licensing terms

The Blitz++ library is licensed under both the GPL and the more permissive “Blitz++ Artistic License”. Take your pick. They are detailed in GPL and LICENSE, respectively. The artistic license is more appropriate for commercial use, since it lacks the “viral” properties of the GPL.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

Copyright © 1996–2003 Free Software Foundation, Inc.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.7 Mailing lists and support


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.7.1 How to get help

The starting point for all bug reports, feature requests and support questions is the SourceForge Blitz++ project web page, at http://sourceforge.net/projects/blitz. From this page, you can click on the Support link to browse previous Blitz++ support requests or make your own request.

There is also a Lists link that provides access to and lets you search the blitz mailing list archives. This will often turn up answers to your question if it has been asked before. Finally, if you continue to experience a problem with using Blitz++, there is a Bugs link that allows you to file a bug report and check the status of existing bug reports.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.7.2 How to subscribe to a mailing list

The main mailing list for Blitz++ support questions and information is blitz-support@lists.sourceforge.net. Anyone is free to post a question to this list, although the list is moderated. You can subscribe to the list via the Lists link on the SourceForge Blitz++ project page, http://sourceforge.net/projects/blitz. Besides the main support list, there is also a blitz-devel list for comments or questions about future development of Blitz++ and a blitz-cvs list that sends notification of changes to the Blitz++ cvs repository. These lists generally have far less traffic than the blitz-support list.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.7.3 blitz-devel

Blitz++ is in open development: anyone can contribute features and code to the library. If you are interested in helping out with coding or porting, you should start by subscribing to the blitz-devel mailing list.

This list is also an appropriate place to send suggestions for features; just send email to blitz-devel@lists.sourceforge.net. We can’t implement it if you don’t suggest it.

Archives of this list are available from the Blitz++ web site.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.7.4 blitz-support

This mailing list is for posting and answering questions about using the Blitz++ library. Anyone can post questions; anyone can answer.


[ << ] [ >> ]           [Top] [Contents] [Index] [ ? ]

This document was generated on April 9, 2013 using texi2html 5.0.