mwalk - Instructions

Instructions

This page attempts to explain most of what you need to know in order to install, run and extend mwalk. Much of this content is also available in the distribution as README files.

We have included a link to the API documentation, but at this point it is woefully incomplete. If you have any suggestions on how to improve this page, the package documentation or the applications, please contact us at robertc@cs.ucsb.edu.

Handling the distribution
Running mwalk
Extending the package
- create your own visitors (soon to come)
- check out the API documentation

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 with the 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:

$ ./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 and perl source 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 files (created by configure)

Mwalk consists primarily of two java applications (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 applications 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 lib/Mwalk. The path prior to the `Mwalk' directory must be passed to perl via the -I option when running the scripts. 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 following sub-sections.

updated 05.01.01