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=<path to your favorite installation directory> \
--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/qdp_config.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 EXTRA_DIST 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.
---