README 2.83 KB
Newer Older
1 2
DiSL
====
3

4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25
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.
26

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

29

30 31 32
INSTALL
=======

33 34 35 36 37 38 39 40 41 42 43
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
František Haas's avatar
František Haas committed
44 45 46
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.
47 48 49 50

Finally, to compile DiSL, run the "ant" command in the root directory.

You can create javadoc documentation by running "ant javadoc".
51 52


František Haas's avatar
František Haas committed
53
EXAMPLES ========
54 55 56 57

For the basic instrumentation example, please look in the example directory.
Also the src-test directory contains simple examples of DiSL features.

58

František Haas's avatar
František Haas committed
59
DOCUMENTATION =============
60 61 62

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

63

František Haas's avatar
František Haas committed
64
USER ERRORS ===========
65

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