Byteman README
--------------

Byteman supports injection of side effects into Java programs for the
purpose of tracing and testing application behaviour.

Installation
------------

If you have downloaded a binary release then unzip it into a target
install directory. This directory contains everything you need to
use byteman. You should set environment variable BYTEMAN_HOME so
that it points to the target install directory.

If you have downloaded a full release then unzip into a target
release directory. The release includes a subdirectory called install
which contains everything you need to use byteman. You should set
environment variable BYTEMAN_HOME so that it points to the install
subdirectory. If you execute command 'ant install' in the target
release directory then this will rebuild the byteman release from
the sources overwriting the original contents of directory install.

The install directory contains the following subdirectories

  bin -- contains Unix scripts to simplify: using Byteman (bmjava.sh);
      typechecking Byteman rule scripts (bytemancheck.sh);
      communicating with the Byteman agent listener (bmsubmit.sh);
      and installing the agent into a running JVM (bminstall.sh).
      You will need to change the permissions of these files
      in order to execute them directly from the command line.

  docs -- contains the Byteman Programmer's guide and license
      information for Byteman plus the third-party software it uses

  lib -- contains the Byteman agent and rule engine (byteman.jar);
      the subset of this code needed to compile/run the submit
      client (byteman-submit.jar); the subset of this code needed
      to compile/run the install client (byteman-install.jar).

  sample/lib -- contains helper code for the sample scripts

  sample/scripts -- contains example rule scripts showing how to
      use Byteman

   contrib -- contains software contributed by other Byteman users

Using Byteman
-------------
Please consult the Programmer's Guide for details of how Byteman
operates, how to write Byteman rule scripts and how to run a Java
program with the Byteman agent in place.

Take a look at the sample scripts directory to see some examples of
how you can use Byteman to trace application and JVM execution or
to gather and present statistics detailing the operation of JVM
or application code.
(n.b. these examples still need extending to show how to use Byteman
for fault injection based testing).

Copyright
---------
See the copyright file in the docs directory for details of the open
source license under which this code is released. Note that this code
employs the ObjectWeb ASM package to do bytecode manipulation and the
JFlex and JavaCUP tokeniser and parser genereators to generate and
provide runtime support for the rule parser which are also released
under open source licenses.