Using TAU with Dyninst 4.x.
---------------------------
Part I) Configuring and installing Dyninst 2.x 

% tar xzvf  binDist4.x.tar.gz
(Agree to Dyninst licensing terms)
% cd <dir>/dyninstAPI-4.x

Add to .cshrc file: 

setenv DYNINST_ROOT <dyninst-dir>/dyninstAPI-4.x/
setenv PLATFORM    i386-unknown-linux2.4
setenv DYNINSTAPI_RT_LIB $DYNINST_ROOT/$PLATFORM/lib/libdyninstAPI_RT.so.1
setenv LD_LIBRARY_PATH <tau-root>/i386_linux/lib\:$DYNINST_ROOT/lib/$PLATFORM

% source ~/.cshrc

Compiling Dyninst (optional, you may download the binary release).

% cd $DYNINST_ROOT/core/
% make 
% cd $DYNINST_ROOT/core/dyninstAPI/tests/$PLATFORM
% make 
% ./test1
% ./test2
% ./test3

if it passes all tests then :

Part 2: Configuring TAU with Dyninst
------------------------------------

% tar zxvf tau-2.x.tar.gz
% cd <tau-root>
% configure -dyninst=$DYNINST_ROOT
% make install
% set path=(<tau-root>/i386_linux/bin $path)
% cd examples/dyninst
% make
% tau_run klargest
% pprof

If you're using DyninstAPI with an MPI application (works under Linux with 
MPICH), you need to follow these steps:

1) normally you'd invoke an mpi application using :
% mpirun -np <np> a.out <args>
2) With TAU and DyninstAPI, you'll need to invoke it as:
% mpirun -np <np> tau.shell <args>

where tau.shell is a shell script that you write as follows:
#!/bin/tcsh
<tauroot>/<arch>/bin/taurun -XrunTAUsh[-options] <full path to exec>/a.out $*

Note, by default taurun doesn't need the specification of the TAU library to
use (in the second -XrunTAUsh[-options] argument) but you can specify it when
more than one version of TAU is configured. For e.g.,

% mpirun -np 4 tau.papiwallclock.sh <args>
% cat tau.papiwallclock.sh 
#!/bin/tcsh
/home/users/sameer/tau2/i386_linux/bin/tau_run -XrunTAUsh-papiwallclock-papi /home/users/sameer/tau2/examples/mpi-ek/ek $*


To use tau_run to re-write a binary file, use the -o <outputfile> option. 
For e.g., 
% f90 app.f90
creates a.out
% tau_run a.out
does runtime pre-execution instrumentation by spawning a.out.
% tau_run -o a.out.rewritten a.out
reads a.out, instruments it and rewrites the binary image as a.out.rewritten
(typically in _dyninstsaved<n> directory where n = 0, 1, 2...)
NOTE: The binary rewriting feature has been tested under Sparc Solaris 2.8+
with the application binary files created with the Sun F90 compiler. 

SELECTIVE INSTRUMENTATION FEATURES:
-----------------------------------
tau_run takes a -f <selective> instrumentation specification file option. This
allows the user to specify which routines and/or files should be included or
excluded. If a user wishes to only instrument routines main and foo in the 
binary, a file with
BEGIN_INCLUDE_LIST
main
foo
END_INCLUDE_LIST
can be made and specified with the -f option. Other tags (like 
BEGIN_INCLUDE_LIST) include BEGIN_EXCLUDE_LIST/END_EXCLUDE_LIST (the routines
specified between these are excluded from instrumentation, and 
BEGIN_FILE_INCLUDE_LIST/END_FILE_INCLUDE_LIST for specifying a list of files
for including (only these files are instrumented). e.g., 
BEGIN_FILE_INCLUDE_LIST
app_main.cpp
f*.cpp
END_FILE_INCLUDE_LIST
Note that you can specify the file name with wildcard characters (* and ?). 
Also, BEGIN_FILE_EXCLUDE_LIST/END_FILE_EXCLUDE_LIST can be used to exclude 
the list of files (*.so for instance). You may specify either include or excludelists but not both. The selective instrumentation file specification is common 
to DyninstAPI based tau_run and PDT based tau_instrumentor.  

Please direct any questions to tau-bugs@cs.uoregon.edu.
