
How to install and configure VampirTrace
========================================

  Basics
  ------

    Building VampirTrace is typically a combination of running "configure"
    and "make".  Execute the following commands to install VampirTrace from
    within the directory at the top of the tree:

         $ ./configure --prefix=/where/to/install
         [...lots of output...]
         $ make all install

    If you need special access to install, then you can execute "make
    all" as a user with write permissions in the build tree, and a
    separate "make install" as a user with write permissions to the
    install tree.

    However, for more details, read also the following instructions. Sometimes
    it might be necessary to provide ./configure with options, e.g.
    specifications of paths or compilers.

    VampirTrace comes with example programs written in C, C++, and Fortran.
    They can be used to test different instrumentation types of the
    VampirTrace installation.
    You can find them in the directory examples of the VampirTrace package.


  Configure Options
  -----------------

    * Compilers and Options

      Some systems require unusual options for compilation or linking that
      the `configure' script does not know about.  Run `./configure --help'
      for details on some of the pertinent environment variables.

      You can give `configure' initial values for configuration parameters
      by setting variables in the command line or in the environment.  Here
      is an example:

           ./configure CC=c89 CFLAGS=-O2 LIBS=-lposix


    * Installation Names

      By default, `make install' will install the package's files in
      `/usr/local/bin', /usr/local/include', etc.  You can specify an
      installation prefix other than `/usr/local' by giving `configure' the
      option `--prefix=PATH'.


    * Optional Features

      --enable-compinst=LIST
                              enable support for compiler instrumentation,
                              (gnu,intel,pathscale,pgi,sun,xl,ftrace,openuh)
                              A VampirTrace installation can handle different
                              compilers. The first item in the list is the
                              run-time default.
                              default: automatically by configure

      --enable-dyninst
                              enable support for Dyninst instrumentation,
                              default: enable if found by configure
                              Note: Requires Dyninst version 5.1 or higher!

      --enable-dyninst-attlib
                              build shared library which attaches Dyninst to 
                              the running application, default: enable if
                              Dyninst found by configure and system supports
                              shared libraries

      --enable-iotrace
                              enable LIBC's I/O tracing support, default: enable
                              if libdl found by configure

      --enable-libctrace
                              enable tracing support for several LIBC functions,
                              default: enable if libdl found by configure

      --enable-memtrace
                              enable memory tracing support, default: enable if
                              found by configure

      --enable-cpuidtrace
                              enable CPU ID tracing support, default: enable if
                              found by configure

      --enable-rutrace
                              enable resource usage tracing support, default:
                              enable if found by configure


      --enable-metrics=TYPE
                              enable support for hardware performance counter
                              (papi,cpc,necsx), default: automatically by
                              configure

      --enable-zlib
                              enable ZLIB trace compression support, default:
                              enable if found by configure

      --enable-mpi
                              enable MPI support, default: enable if
                              MPI found by configure

      --enable-fmpi-lib
                              build the MPI Fortran support library, in case your 
                              system does not have a MPI Fortran library.
                              default: enable if no MPI Fortran library 
                              found by configure

      --enable-fmpi-handle-convert
                              do convert MPI handles, default: enable if MPI
                              conversion functions found by configure

      --enable-mpi2-thread
                              enable MPI-2 Thread support, default: enable if
                              found by configure

      --enable-mpi2-1sided
                              enable MPI-2 One-Sided Communication support,
                              default: enable if found by configure

      --enable-mpi2-extcoll
                              enable MPI-2 Extended Collective Operation support,
                              default: enable if found by configure

      --enable-mpi2-io
                              enable MPI-2 I/O support, default: enable if found
                              by configure

      --enable-mpicheck
                              enable support for Universal MPI Correctness
                              Interface (UniMCI), default: enable if
                              unimci-config found by configure

      --enable-etimesync
                              enable enhanced timer synchronization support,
                              default: enable if C-LAPACK found by configure

      --enable-threads=LIST
                              enable support for threads (pthread, omp), default:
                              automatically by configure

      --enable-java
                              enable Java support, default: enable if JVMTI
                              found by configure


    * Important Optional Packages

      This a summary of the most important optional features. For a full list
      of all available features run `./configure --help'.

      --with-platform=PLATFORM
                              configure for given platform
                              (altix,bgl,bgp,crayt3e,crayx1,crayxt,ibm,linux,
                               macos,necsx,origin,sicortex,sun,generic),
                              default: automatically by configure

      --with-bitmode=<32|64>
                              specify bit mode

      --with-options=FILE
                              load options from FILE, default: configure
                              searches for a config file in config/defaults
                              based on given platform and bitmode

      --with-local-tmp-dir=DIR
                              give the path for node-local temporary directory,
                              default: /tmp

        Specify name of (SMP) node-local directory that can be used to store
        temporary trace files.

      If you would like to use an external version of OTF library, set
      --with-extern-otf
                              use external OTF library, default: not seta

      --with-extern-otf-dir=OTFDIR
                              give the path for OTF, default: /usr

      --with-otf-flags=FLAGS
                              pass FLAGS to the OTF distribution configuration
                              (only for internal OTF version)

      --with-otf-lib=OTFLIB
                              use given otf lib, default: -lotf -lz

        If used OTF library was built without zlib support, then it will do
        to set OTFLIB to '-lotf'.

      --with-dyninst-dir=DYNIDIR
                              give the path for DYNINST, default: /usr

      --with-dyninst-inc-dir=DYNIINCDIR
                              give the path for Dyninst-include files,
                              default: DYNIDIR/include

      --with-dyninst-lib-dir=DYNILIBDIR
                              give the path for Dyninst-libraries,
                              default: DYNIDIR/lib

      --with-dyninst-lib=DYNILIB
                              use given Dyninst lib, default: -ldyninstAPI

      --with-tau-instrumentor=TAUINSTUMENTOR
                              give the command for the TAU instrumentor,
                              default: tau_instrumentor

      --with-pdt-cparse=PDTCPARSE
                              give the command for PDT C source code parser,
                              default: cparse

      --with-pdt-cxxparse=PDTCXXPARSE
                              give the command for PDT C++ source code parser,
                              default: cxxparse

      --with-pdt-fparse=PDTFPARSE
                              give the command for PDT Fortran source code parser,
                              default: f95parse, f90parse, or gfparse

      --with-papi-dir=PAPIDIR
                              give the path for PAPI, default: /usr

      --with-cpc-dir=CPCDIR
                              give the path for CPC, default: /usr

      If you don't have specified the environment variable MPICC
      (MPI compiler command), use following options to set location
      of your MPI installation:

      --with-mpi-dir=MPIDIR
                              give the path for MPI, default: /usr

      --with-mpi-inc-dir=MPIINCDIR
                              give the path for MPI-include-files, default:
                              MPIDIR/include

      --with-mpi-lib-dir=MPILIBDIR
                              give the path for MPI-libraries, default:
                              MPIDIR/lib

      --with-mpi-lib
                              use given mpi lib

      --with-pmpi-lib
                              use given pmpi lib

      If your system does not have a MPI Fortran library,
      set '--enable-fmpi-lib' (see above), otherwise set

      --with-fmpi-lib
                              use given fmpi lib

      Use the following options to specify your MPI-implementation

      --with-hpmpi            set MPI-libs for HP MPI

      --with-intelmpi         set MPI-libs for Intel MPI

      --with-intelmpi2        set MPI-libs for Intel MPI2

      --with-lam              set MPI-libs for LAM/MPI
       
      --with-mpibgl           set MPI-libs for IBM BG/L

      --with-mpibgp           set MPI-libs for IBM BG/P 

      --with-mpich            set MPI-libs for MPICH

      --with-mpich2           set MPI-libs for MPICH2

      --with-mvapich          set MPI-libs for MVAPICH

      --with-mvapich2         set MPI-libs for MVAPICH2

      --with-mpisx            set MPI-libs for NEC MPI/SX

      --with-mpisx-ew         set MPI-libs for NEC MPI/SX with 
                              8 Byte Fortran Integer 

      --with-openmpi          set MPI-libs for Open MPI

      --with-sgimpt           set MPI-libs for SGI MPT

      --with-sunmpi           set MPI-libs for SUN MPI

      --with-sunmpi-mt        set MPI-libs for SUN MPI-MT 

      To enable enhanced timer synchronization a LAPACK library with C wrapper
      support is needed:

      --with-clapack-dir=LAPACKDIR
                              set the path for CLAPACK,
                              default: /usr

      --with-clapack-lib
                              set CLAPACK-libs, default: 
                              -lclapack -lcblas -lf2c

      --with-clapack-acml     set CLAPACK-libs for ACML

      --with-clapack-essl     set CLAPACK-libs for ESSL

      --with-clapack-mkl      set CLAPACK-libs for MKL

      --with-clapack-sunperf  set CLAPACK-libs for SUN Performance Library 

      To enable Java support the JVM Tool Interface (JVMTI) version 1.0 or
      higher is needed:

      --with-jvmti-dir=JVMTIDIR
                              give the path for JVMTI, default: JAVA_HOME

      --with-jvmti-inc-dir=JVMTIINCDIR
                              give the path for JVMTI-include files, default:
                              JVMTI/include


  Cross Compilation
  -----------------

    Building VampirTrace on cross compilation platforms needs some special attention.
    The compiler wrappers, OPARI, and the Library Wrapper Generator are built for the
    front-end (build system) whereas  the VampirTrace libraries, vtdyn, vtunify, and
    vtfilter are built for the back-end (host system). Some configure options which are
    of interest for cross compilation are shown below:

      * Set CC, CXX, F77, and FC to the cross compilers installed on the front-end.

      * Set CC_FOR_BUILD and CXX_FOR_BUILD to the native compilers of the front-end.

      * Set --host= to the output of config.guess on the back-end.

      * Set --with-cross-prefix= to a prefix which will be prepended to the executables
        of the compiler wrappers and OPARI (default: cross-)

      * Maybe you also need to set additional commands and flags for the back-end
        (e.g. RANLIB, AR, MPICC, CXXFLAGS).

    Examples:
      BlueGene/P:
        % ./configure --host=powerpc64-ibm-linux-gnu

      Cray XK6:
        % ./configure --host=x86_64-cray-linux-gnu
                      CC_FOR_BUILD=craycc
                      CXX_FOR_BUILD=crayc++

      NEC SX6:
        % ./configure --host=sx6-nec-superux14.1


  Set up the Environment
  ----------------------

    Add the bin subdirectory of the installation directory to your PATH
    environment variable. To use VampirTrace with Dyninst, you will also need
    to add the lib subdirectory to your LD_LIBRARY_PATH environment variable:

    for csh and tcsh:

         > setenv PATH <vampirtrace-install>/bin:$PATH
         > setenv LD_LIBRARY_PATH <vampirtrace-install>/lib:$LD_LIBRARY_PATH

    for bash and sh:

         $ export PATH=<vampirtrace-install>/bin:$PATH
         $ export LD_LIBRARY_PATH=<vampirtrace-install>/lib:$LD_LIBRARY_PATH


  Notes for Developers
  --------------------

    * Build from CVS
    
      If you have checked out a DEVELOPER'S COPY of VampirTrace (i.e. you
      checked out from CVS), you should first run:

           $ ./bootstrap [--otf-package <package>] [--version <version>]

      Note that GNU Autoconf >= 2.60 and GNU Automake >= 1.9.6 is required.
      You can download them from http://www.gnu.org/software/autoconf and
      http://www.gnu.org/software/automake.

