README

DiSL
====

DiSL is a Java bytecode instrumentation framework intended for observation of
programs executing in the Java Virtual Machine. It has been mainly used for
development of dynamic program analysis instrumentations, but it can be used
equally well to develop instrumentations for, e.g. runtime performance
monitoring, or other tasks not bent on altering program execution.

DiSL is inspired by AOP, but in contrast to mainstream AOP languages, it
features an open join point model where any region of bytecodes can serve as a
join point (i.e., code location to be instrumented). DiSL also reconciles
high-level language concepts, such as the pointcut/advice programming model
found in AOP, with high expressiveness, and efficiency of bytecode
manipulation performed using low-level libraries such as ASM. As a result,
instrumentations written using DiSL almost as compact as aspects written in
AspectJ, but perform about as fast as those written using ASM.

However, in contrast to AspectJ, DiSL does not restrict the code locations
that can be instrumented, and the code generated by DiSL avoids expensive
operations (such as object allocations that are not visible to the
programmer). Furthermore, DiSL supports instrumentations with complete
bytecode coverage out-of-the-box and avoids structural modifications of
classes that would be visible through reflection and could break the
instrumented code.

link: http://forge.ow2.org/projects/disl/


INSTALL
=======

DiSL currently fully supports "Linux" and "OS X" platforms with Java, ant, GCC
and make installed and found on the executable path. DiSL has been used on the
Windows/Cygwin platform as well, but it was not extensively tested there.

While most of the DiSL is written in Java, it requires a JVM enhanced with a
native agent written in C, which must be compiled first. For that, the simple
build system needs to know where your JDK is installed to be able to find JNI
header files for your platform. On many systems, the JAVA_HOME environment
variable points to the root of the JDK installation and you should be fine.

If this is not the case, please enter the src-agent-c directory, copy the
javahome/var.local.tmp file to javahome/var.local and modify it to set the
JAVA_HOME variable to point to the root of the JDK installation you want to
use.

Finally, to compile DiSL, run the "ant" command in the top-level directory.


DOCUMENTATION =============

Please look at http://disl.projects.ow2.org/xwiki/bin/view/Main/Doc.

After building DiSL, you will find the API documentation and an introduction
to instrumenting applications with DiSL in the output/dist/doc directory.


EXAMPLES ========

For a set of simple examples showcasing basic DiSL features, please look in
the "examples" directory. Note that the "examples" are meant to be used with
DiSL a distribution directory layout, which will be created in the
"output/dist" directory after buildig DiSL.

In addition, the "src-test" directory contains additional examples used for
testing other DiSL features -- these can be run using Ant.


USER ERRORS ===========

If you get a Java error during instrumentation or running your application,
please look at the USER_ERRORS document describing most common problems.