README 6.37 KB
Newer Older
František Haas's avatar
František Haas committed
1 2 3
================================================================================
= DiSL SETUP EXAMPLE
================================================================================
4

5
These examples demonstrate fthe basic features of DiSL. In addition, they
6 7 8
provide basic guidelines on how to package the instrumentation classes and how
to run the instrumented application using a simple launcher script that takes
care of starting the necessary Java virtual machines.
František Haas's avatar
František Haas committed
9 10 11 12 13


--------------------------------------------------------------------------------
-- smoke
--------------------------------------------------------------------------------
14

František Haas's avatar
František Haas committed
15 16 17 18 19 20 21 22
The simplest of the examples. The application prints a "hello" message from the
main and exits while DiSL instruments the entry and exit of the main method and
prints more text around the "hello".

The code in the function annotated with "@After" and "@Before" is a snippet.
That's the code that is according to information specified in the annotation
instrumented into the client application class' code.

23

František Haas's avatar
František Haas committed
24 25 26
--------------------------------------------------------------------------------
-- scope
--------------------------------------------------------------------------------
27

František Haas's avatar
František Haas committed
28 29 30 31 32 33 34
This example demonstrates the scoping features. That means the ways how can the
instrumentation application filter application methods based on class-name,
method-name, parameter-types and return-type and instrument just the right
methods. For example those from specified package, class or just those
returning the right types or accepting the right parameters or a combination of
these

35

František Haas's avatar
František Haas committed
36 37 38
--------------------------------------------------------------------------------
-- marker
--------------------------------------------------------------------------------
39

František Haas's avatar
František Haas committed
40 41 42
This example shows how to place instrumentation code on different locations
across methods. That means one can, using scopes, declare methods that should
be processed. But the marker enables to specify where exactly the code should
43
be placed.
František Haas's avatar
František Haas committed
44 45 46 47 48 49

The code might be added at the method body level (BodyMarker), basic block
level (BasicBlockMarker) or even instruction level (e.g.
MethodInvocationMarker). The marker essentially splits the method body into
instrumentation regions. There are some already predefined markers but custom
markers might be created. Creation of custom marker is also shown in the
50
example.
František Haas's avatar
František Haas committed
51 52 53 54 55 56 57 58 59 60

The marker basically goes trough (scoped) method code and whenever it finds a
region between two instruction interesting it marks it. However, the marker
must be cauties to mark all possible entries and exits of such region (goto,
return, throw, ..).

Then there are region specifiers. They specifiy at which entry or exit of the
region the code should be placed. There is (After), (Before), (AfterReturning),
(AfterThrow).

61

František Haas's avatar
František Haas committed
62 63 64
--------------------------------------------------------------------------------
-- guard
--------------------------------------------------------------------------------
65

František Haas's avatar
František Haas committed
66 67 68 69
This is another way to select a region for instrumentation. A snippet
annotation might specify a guard class that has a guard method which decides
whether a snippet will or will not be included.

70

František Haas's avatar
František Haas committed
71 72 73
--------------------------------------------------------------------------------
-- static
--------------------------------------------------------------------------------
74

František Haas's avatar
František Haas committed
75 76 77 78 79 80 81 82 83 84 85 86
This example shows how to use a static context information in snippets or guard
methods. A static context is information derived from the original method's
code. There are multiples classes implementing "StaticContext" interface that
provide various information from static analysis of the code. It's also
demonstrated how to implement and use custom static contexts.

A snippet method might accept unspecified number of static contexts in any
order that can be used in the snippet.

For example static context might tell how many instructions there are in the
method or if it contains a loop.

87

František Haas's avatar
František Haas committed
88 89 90
--------------------------------------------------------------------------------
-- dynamic
--------------------------------------------------------------------------------
91

František Haas's avatar
František Haas committed
92 93 94 95 96
This example shows how snippets can use also runtime information. For example
values of local variables, object instance in member methods, method arguments
or current exceptions.


František Haas's avatar
František Haas committed
97 98 99
--------------------------------------------------------------------------------
-- dispatch
--------------------------------------------------------------------------------
100

František Haas's avatar
František Haas committed
101
This example shows how to evaluate instrumented code on evaluation jvm. For
102
more details try running this example directly using "disl.py" and supplying
František Haas's avatar
František Haas committed
103 104 105
'c_out' and 'e_out' options.


František Haas's avatar
František Haas committed
106
================================================================================
107
= HOW TO RUN THE EXAMPLES
František Haas's avatar
František Haas committed
108
================================================================================
109

110 111 112
If you are using a source DiSL distribution, first compile DiSL by running
"ant" in the top-level directory (see README). You can skip this step if you
are using a binary distribution of DiSL.
František Haas's avatar
František Haas committed
113

114 115
In the "examples" directory, choose an example you want to run, e.g., "smoke",
enter the corresponding directory, and execute "ant run".
František Haas's avatar
František Haas committed
116

117 118 119
This command builds and packages the application and the instrumentation
classes and then, using the laucher script, starts the DiSL instrumentation
server and later on the application VM.
František Haas's avatar
František Haas committed
120

121 122
The output of the application as well as that of the applied instrumentation
should be visible on the console.
František Haas's avatar
František Haas committed
123

124 125 126
When compiled, the example can be also run using the "disl.py" launcher script
found in the "bin" directory, which allows specifying more options. To learn
more about the launcher script, run "disl.py -h" in the "bin" directory.
František Haas's avatar
František Haas committed
127

128

František Haas's avatar
František Haas committed
129 130 131
================================================================================
= NOTE
================================================================================
132 133 134 135

If you want to use "disl.py" to run your application, don't forget to either
set the DISL_HOME variable, or use the "-d" option to pass the DiSL home
directory to the "disl.py" launcher script.
František Haas's avatar
František Haas committed
136 137


František Haas's avatar
František Haas committed
138 139 140
================================================================================
= NOTE
================================================================================
141

František Haas's avatar
František Haas committed
142 143
If you want to include use some library in your instrumentation you should
insert it directly to the instrumentation jar using jarjar.
František Haas's avatar
František Haas committed
144
http://code.google.com/p/jarjar/
145

146 147
Alternatively, you can provide the library's classpath to the "disl.py"
utility.