README.md 3.25 KB
Newer Older
1 2
DiSL
====
3

4 5 6 7
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
8 9 10
monitoring, or other tasks not bent on altering program execution.

DiSL is inspired by AOP, but in contrast to mainstream AOP languages, it
11 12
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
13 14 15 16 17 18 19 20 21 22 23 24 25
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

28 29 30
INSTALL
=======

Lubomir Bulej's avatar
Lubomir Bulej committed
31 32 33
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.
34

Lubomir Bulej's avatar
Lubomir Bulej committed
35
If you have downloaded a source distribution of DiSL, you need to compile it
36
first by running the `ant` command in the top-level directory.
37

Lubomir Bulej's avatar
Lubomir Bulej committed
38 39 40 41
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
42 43
modify `Makefile.local` files in the `src-disl-agent` and `src-shvm-agent`
directories to override the default value of the `INCLUDE_DIR` variable.
44

Lubomir Bulej's avatar
Lubomir Bulej committed
45 46 47 48 49
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.
50

51

52 53
DOCUMENTATION
=============
54

55
After building DiSL, you will find the API documentation in the `output/jdoc`
Lubomir Bulej's avatar
Lubomir Bulej committed
56
directory, and document containing an introduction to instrumenting applications
57 58
with DiSL in the `output/build/intro` directory. However, to build the
document, you will need a working LaTeX installation with `pdflatex`.
59

60

61 62
EXAMPLES
========
63

Lubomir Bulej's avatar
Lubomir Bulej committed
64
For a set of simple examples showcasing basic DiSL features, please check
65
the `examples` directory.
66

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

70

71 72
USER ERRORS
===========
73

74
If you get a Java error during instrumentation or running your application,
75
please consult the `USER_ERRORS` document describing some of the most common
Lubomir Bulej's avatar
Lubomir Bulej committed
76
problems.