README
mwalk version 0.2.0
Robert Chalmers (robertc@cs.ucsb.edu)
$Id: README,v 1.9 2001/01/22 18:50:54 robertc Exp $


INTRODUCTION

Mwalk is a collection of java applications and perl scripts which
re-create a global view of a multicast session from mtrace and RTCP
logs.  Once the session "tree" is constructed, a number of plug-in
classes, "visitors", can be employed to gather statistics while the
tree is traversed or "walked".  New visitors can easily be created by
extending existing classes, and visitors can be combined to setup
state within the tree that is later collected and analyzed.

This distribution was built using the follwing packages:

	JDK v1.2.2 from Sun (Blackdown)
	perl v.5.6.0
	gmake v3.79.1
	autoconf v2.13
	automake v1.4


DOWNLOAD

Mwalk can be downloaded from http://www.nmsl.cs.ucsb.edu/mwalk/ as a
self-configuring package.
 
Copyright (c) 2000, Robert Chalmers. All rights reserved.  This
program is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the
Free Software Foundation; either version 2 of the License, or (at your
option) any later version.
 
This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
General Public License for more details.


UNPACKING

Mwalk is distributed as a gzipped tar archive.  To unpack the
distribution you will need access to a current version of `tar' and
`gzip'.  Assuming the file is ./mwalk-0.1.0.tgz, you can extract the
distribution tree by typing:

	$ gunzip mwalk-0.1.0.tgz
	$ tar xf mwalk-0.1.0.tar

or, if you have GNU tar:

	$ tar xzf mwalk-0.1.0.tgz


INSTALLATION

Mwalk comes with a configuration script that automatically detects
many pecularaities of your system and creates make files accordingly.
Details of the configure script are explained in `INSTALL' which
should be included in this package.  In short, the process consists of
running the configure script then running make to build and possibly
install the package.

In the package directory type (using GNU make):

	$ ./configure
	$ make

and if you want to install the package, type:

	$ make install

During configuration, the script will attempt to find the path to java
binaries.  If it cannot find them automatically or if you would like
to indicate a different path, pass the --with-jdk or --with-java
options.  The former assumes that the standard jdk directory exists at
the indicated path, including bin and lib sub-directories.  The
latter, indicates an explicit directory which contains just the java
binaries.  Another option, --enable-jdk-home, allows the user to
circumvent the normal search order by supplying a path to the jdk
through $JDK_HOME.

By default, the package does not create API documentation.  This can
take some time to compile and requires javadoc.  To enable this
feature include the --enable-api option.  To view the entire set of
available options, type:

	$ ./configure --help


PACKAGE CONTENTS

The distribution tree consists of seven directories:

  config  autoconf/automake particulars
  src     java source tree, perl scripts and perl module tree
  bin     main application script
  etc     base config file and java policy file
  lib     destination for .jar files
  doc     general documentation and javadoc api
  class   destination for .class (created by configure)

Mwalk consists primarily of two java application (Builder and
Animator) and three perl scripts (generate.pl, parse.pl and upath.pl).
However, a single shell script, mwalk, is supplied which runs the
correct "application" within the appropriate environment.  See the
next section (RUNNING MWALK) for more details.

The java application depend on a number of support classes.  Five java
packages are defined in src:

  mwalk.core     core classes
  mwalk.util     utility classes
  mwalk.eval     activity evaluators
  mwalk.visitor  standard visitors
  mwalk.app      application classes

When building mwalk, these classes are combined into two jar files,
mwalk-core.jar and mwalk-app.jar.  The jar files are installed and the
`mwalk' script automatically places them in your classpath.  If you do
not follow the basic installation procedures then you will need to
ensure that these archives are available.

The perl scripts depend on a number of custom modules which are
located in src/Mwalk and will be installed in the project library
path.  The path prior to the `Mwalk' directory must be passed to perl
via the -I option when running the scripts.  By default, the scripts
themselves are not executable.  Instead you should use the main
`mwalk' script which will include the search path automatically.

When the package is installed, the installation path is burned into
the `mwalk' script.  If you move the package after installation, this
path will be incorrect.  The script does attempt to handle this
situation to some degree by inspecting the script's execution path as
well as trying the $MWALK_HOME environment variable.


RUNNING MWALK

All of the mwalk applications can be run through a single script,
aptly named mwalk.  The script takes an action as its first parameter
which indicates which application to run.  The script itself has a few
options (shown below) and each action has its own set of command-line
arguments.

  Usage: mwalk <action> [-h | --help | -?] [-c CFG | --config=CFG]
                        [-cp CLASSPATH | --classpath=CLASSPATH]
                        [-ja JARGS | --java-args=JARGS]
                        [-dev | --developer] [--version]
  Actions:
    generate  generate mtrace and rtcp logs from a receiver list
    parse     parse mtrace and rtcp logs to prepare for tree building
    build     build an activity graph representing the entire session
    animate   animate the activity graph with visitors
    upath     gather unicast path lengths for multicast receivers
  Global Options:
    -h --help -?      display action-specific help message
    -cp --classpath   CLASSPATH is prepended to the current classpath
    -ja --java-args   JARGS are extra arguments to pass to the java vm
    -dev --developer  indicate that action is running within development tree
    --version         display version info

Further detailed instructions about each action can be found in the
README files in the doc directory.


ACKNOWLEDGMENTS

The author would like to thank Josep M. Blanquer for his help in
debugging mwalk, as well as contributing to its overall design.

