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
=======

If you have downloaded a binary distribution of DiSL, this step is not
necessary. Simply extract the archive to a preferred location and update your
project to use it.

If you have downloaded a source distribution of DiSL, you need to compile it
first by running the "ant" command in the top-level directory.

While most of the DiSL is written in Java, it requires a JVM enhanced with a
native agent written in C. Compiling the agent requires JNI header files for
your platform. For commonly used platforms, these are part of the DiSL source
distribution. Should the compilation fail on your machine, you may need to
modify Makefile.local files in the src-disl-agent and src-shvm-agent
directories to override the default value of the INCLUDE_DIR variable.

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, and there is experimental support for cross-
compiling the DiSL agent for the Win32/Win64 platforms using MinGW. However,
these targets were not extensively tested.


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

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

After building DiSL, you will find the API documentation in the output/jdoc
directory, and document containing an introduction to instrumenting
applications with DiSL in the output/build/intro directory. However, to build
the document, you will need a working LaTeX installation with "pdflatex".


EXAMPLES ========

For a set of simple examples showcasing basic DiSL features, please check
the "examples" directory.

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 the most common problems.