NOTE: Please visit the following web site for more thorough documentation:
http://www.mcs.anl.gov/research/projects/darshan/documentation

Compile and install example for BG/P:
-------------------------------------

# adjust these paths to suit
export PREFIX=/home/carns/demo/install
export LOGPATH=/home/carns/demo

# configuring, compiling, and installing darshan
./configure --with-mem-align=16 --with-log-path=$LOGPATH --prefix=$PREFIX --with-zlib-for-mpi=/soft/apps/zlib-1.2.3/ --with-jobid-env=COBALT_JOBID CFLAGS="-O2"
make
make install

Explanation of configure arguments:
--------------------

--with-log-path (manditory): specifies the directory where all of the
application log files will be written.  

--prefix (manditory): where compiler scripts and darshan libraries will be
installed.

--with-mem-align (manditory): memory alignment for the architecture you are
building for; 16 is an interesting value on BG/P because that is the optimal
alignment for tree network communication.

--with-jobid-env (manditory): name of environment variable to use for
determining the job id at runtime.  If this environment variable is not set,
then Darshan will use the process pid instead.

--with-zlib-for-mpi (optional): path to a zlib build that is cross compiled
for use with mpi processes


Setting up the log directory
----------------------------

# create the directory that you specified in the --with-log-path argument to
# configure (if it does not already exist)
mkdir $LOGPATH
# run a darshan script (no arguments needed) that will create subdirectories
# for darshan to place output in.  The subdirectories are structured in
# <year>/<month>/<day> format.  The last subdirectories will have the sticky 
# bit set (1777 permissions, like /tmp) so that multiple users can write log
# files to the same directories.
darshan-mk-log-dirs.pl

Generating compiler scripts
---------------------------

Use one of darshan-gen-cc.pl, darshan-gen-fortran.pl, or darshan-gen-cxx.pl
to create new compiler scripts for C, FORTRAN, or C++.  For example:

./darshan-gen-cc.pl `which mpicc` --output $PREFIX/bin/mpicc

The resulting scripts can be placed in your path to be used as the default
compilers (if desired).

Using darshan:
-------
Compile your application using one of the compiler scripts genrated in the
previous step.  If you have a previously compiled application you can simply
relink it using the darshan compilers rather than recompiling from scratch.

Example:

install/bin/mpicc mpi-io-test.c -o mpi-io-test

The log files that darshan generates at run time will be in
a binary format with native gzip compression.  

To get a human readable version of the log file, use the
"$PREFIX/bin/darshan-parser $LOGPATH/<log_file_name>" utility from the
bin directory.

To generate key summary graphs, go to the "utils" directory of the
source tree and run "./darshan-aggregate-stats.pl" on the log file.  This
tool requires pdflatex and a version of gnuplot with pdf support.  It will
generate a pdf file with graphs summarizing the behavior of the application.

You can also compare two different log files by using
$PREFIX/bin/darshan-diff <log1> <log2> to see what fields are different.

compiling libz for the compute nodes
-------------------------------------

NOTE: This is not necessary (there is a libz build already available for
compute nodes). The instructions are included for archival purposes.

cd extern
tar -vxzf zlib-1.2.3.tar.gz
cd zlib-1.2.3
CC=/bgsys/drivers/ppcfloor/gnu-linux/bin/powerpc-bgp-linux-gcc CFLAGS="-O2" ./configure
make
cp libz.a $PREFIX/lib/