Quick installations instructions for QDP

To build QDP, it is recommended you make a subdirectory for the build and keep the build tree separate from the source tree. E.g., say to build the "scalar" version (single node workstation) of QDP++:

% cd qdp++ % mkdir scalar-build % cd scalar-build % ../configure --prefix= --enable-parallel-arch=scalar % make

The include files, libraries and docs are installed in the path specified by ``prefix''.

============================================================================ Extended examples of installation

See INSTALL_EXAMPLES

============================================================================

STATUS

Scalar and Parscalar library compiles, examples compile and link and run.

SOFTWARE PREREQUISITES

This implementation has been developed under gcc-3.2, and Intel C++ (32bit) V7.0. To compile this code you will need a compiler that supports the C++ 3.0 standard - e.g., gcc-3.x. Also needed: gmake and libxml2. To be able to play with the build system you'll also need autoconf-2.5x and automake-1.7.x and gm4.

INSTALLATION

See the ./INSTALL file.

COMPILE TIME PARAMETERS

The macros NC, ND and NS are defined in params.h, but in qdp_config.h. params.h includes qdp_config.h and sets Nc=NC, ND=Nd and NS=Ns from the defined values NC, ND and NS which are defined in qdp_config.h

The file qdp_config.h is created by the configure script from the template qdp_config.h.in and the resulting file is placed in the build directory include/qdpconfig.h . Apart from defining NC, ND and NS it also defines the relevant ARCH[PAR]SCALAR which defines the type of parallel architecture. Hence qdp.h also includes qdp_config.h.

USAGE

The installation creates and installs a library - depending on the environment it is called libqdp.a . In the installation directory there is an include and a lib subdirectory where the relevant files are found. The user uses compiles their code with the appropriate include and link flags pointing to the installation directories. E.g., assuming configuration with --prefix=/usr/local/qdp++/scalar

% g++ -I/usr/local/qdp++/scalar/include -L/usr/local/qdp++/scalar/lib myfile.cc -lqdp

If QMP is used there also needs to be links to its installation directories as well.

AUTOCONF & AUTOMAKE

The build system has been converted to work with autoconf/automake. If you just want to build/install QDP++ you shouldn't need to care about this.

If you are intending to develop the system you need to know how autoconf/automake work.

Short summary:

Autoconf is a programming language based on shell (sh) script and m4 macros that allow you to write configure scripts. You edit the configure.ac script with your editor and run autotoconf to turn it into a configure script.

The configure script allows configuration in several ways. It can substitute values in files, it can define compiler

define-s amongst other things. Generally it maps template

Makefile.in files to Makefile files (that get used by your build)

Automake is a system to allow you to write Makefile.in files for autoconf. Generally Automake takes a set of Makefile.am files and produces Makefile.in files from it. These then get turned into Makefile files by the configure script.

If you add a file to say a directory (say a foo.cc in lib/ ) and you want it to be compiled into the library, you must do the following:

i) drop the foo.cc file into lib/
   ii) Edit lib/Makefile.am and add the source file at the 
   end of the right SOURCES or LIBADD primary

  iii) Go to the toplevel directory and type autoreconf

You should find that if things went well, that when you next type ./configure everything should be taken care of.

If things go badly and autoreconf doesn't work, because say there is a version mismatch with automake then remove the aclocal file from the toplevel directory.

then type:

$ aclocal $ autoconf $ automake --add-missing --copy

aclocal creates an aclocal.m4 file containing macros for automake autoconf and automake need to be run. Automake needs a few files present (like COPYING, NEWS, AUTHORS, ChangeLog etc etc etc). If you don't have these the --add-missing --copy should get them for you.

$ autoreconf should work thereafter.

More pointers:

if you add a header file to include/ also add it to Makefile.am to the include_HEADERS primary (so that it gets installed when you type make install)

in lib/ you can make files depend on headers by adding them to the HDRS macro. Note that HDRS in lib/Makefile.am is a part of nodist_libqdp_a_SOURCE as those headers are also put into the distro by the Makefile.am

If you just drop a file that you don't want to use yet, but want the file there for later use, add it to the EXTRA_DIST line in to the Makefile.am in the top source directory.

Rolling Distribution Tarballs

Once you have configured QDP++, you should be able to create a distribution tarball (qdp-ver.tar.gz - where ver is version number specified in the first line of configure.ac) by typing You can then put this distro on a web page or mail it to friends.

make dist

The rules of what goes into a distribution are fairly poorly specified. More or less anything in a _SOURCES or _HEADERS will be put in, as well as all the Makefile.in-s and Makefile.am-s and the configure.ac etc etc etc.

For things that are not in these (say QDPClasses.in) you have to add extra instructins for the file to be included in a distribution tarball (see the EXTRADIST Automake variable -- for things that need to be added in as extra, and the nodist primary prefix -- for things that are sources but shouldn't be added (eg qdp_config.h shouldn't be added because it should always be recreated at configure time)

Further Information

The Autoconf Manual: http://www.gnu.org/manual/autoconf-2.53/autoconf.html

The Automake Manual: http://www.gnu.org/manual/automake-1.6.1/automake.html

GNU Autoconf, Automake and Libtool: http://sources.redhat.com/autobook

Learning Autoconf and Automake: http://www.amath.washington.edu/~lf/tutorials/autoconf

Software versions used in building the build system:

autoconf-2.56 automake-1.7.1

You will also probably want a version of gm4 installed (the above use it) and gmake too for its VPATH support.

GPU support

0) Get CUDA 4.0 (or higher, RC2 is known to work!) and a device with sm_20 or higher! 1) see configure --help for details how to configure the QDP++ 2) set QDP_INSTALL to the install path of QDP++ 3) set QDP_TEMP to a directoy (where you have write permissions) This directory will be used for the compiled CUDA kernels. Upon Chroma startup the kernels found in this directory are loaded in this way no CUDA compilation is carried out multiple times. 4) get Chroma from: git://qcdsfware.ur.de/chroma.git (git branch: gpu)