Commit 6a1e826a authored by Lukáš Marek's avatar Lukáš Marek

3b) remoteval moved as new trunk

parents 51dac9e0 b0549b78
<?xml version="1.0" encoding="UTF-8"?>
<classpath>
<classpathentry kind="src" path="src"/>
<classpathentry kind="src" path="src-re-disp"/>
<classpathentry kind="src" path="src-re-server"/>
<classpathentry kind="src" path="src-agent-java"/>
<classpathentry kind="src" path="src-test"/>
<classpathentry kind="con" path="org.eclipse.jdt.launching.JRE_CONTAINER"/>
<classpathentry kind="lib" path="lib/asm-debug-all-4.0.jar"/>
<classpathentry kind="lib" path="build/eclipse-dynamicbypass.jar"/>
<classpathentry kind="lib" path="lib/asm-debug-all-4.1.jar"/>
<classpathentry kind="output" path="bin"/>
</classpath>
<?xml version="1.0" encoding="UTF-8"?>
<projectDescription>
<name>DiSL</name>
<name>DiSL-RE</name>
<comment></comment>
<projects>
</projects>
......
The DiSL language is hosted in Java using annotations, therefore, no special compiler is required.
A convenient way to specify an instrumentation and to pass it to the DiSL framework is to pack the instrumentation classes with a manifest file into one jar.
The DiSL framework will load the jar, parse the instrumentation specification, and instrument all classes used by an application at load-time.
The examples of simple instrumentation are in src-test directory.
The test can be invoked using runTest.sh script in the root directory.
For user defined instrumentation, it is recommended to mimic the start and build script as they are provided for test.
We are working on better setup scripts to ease the setup effort for developer.
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
Makefile.local.tmpl file to Makefile.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 root directory.
You can create javadoc documentation by running "ant javadoc".
EXAMPLES
========
For the basic instrumentation example, please look in the example directory.
Also the src-test directory contains simple examples of DiSL features.
DOCUMENTATION
=============
Please look at http://disl.projects.ow2.org/xwiki/bin/view/Main/Doc.
USER ERRORS
===========
If you get a Java error during instrumentation or running your application,
please look at USERERRORS document describing most common problems.
Exception in thread "main" java.lang.VerifyError: (class: ..., method: ... signature: ... Expecting to find object/array on stack
- CAUSE: The instrumentation attempts to access an uninitialized object.
- HOW TO FIX: Fix the instrumentation or disable the Java verifier (-noverify
commmand line option).
Java process ends with SEGFAULT
- CAUSE: The instrumentation instruments one of the java.lang.* classes and
disturbs the java initialization
- HOW TO FIX: Fix the instrumentation or exclude the class causing the problem
in the exclusion list (-Ddisl.exclusionList=exclusion.lst command line
option of DiSL server).
Build failure: java.lang.UnsupportedClassVersionError: ch/usi/dag/disl/utilinstr/tlvinserter/ExtendThread : Unsupported major.minor version 51.0
- CAUSE: A version 1.7.x JRE is used; this version is not yet supported
- HOW TO FIX: Use a version 1.6.x JRE instead.
asm.lib=asm-debug-all-4.0.jar
asm.lib=asm-debug-all-4.1.jar
asm.path=lib/${asm.lib}
src.disl=src
src.dynbypass=src-dynbypass
src.dynbypass.act=src-dynbypass-act
src.agent.java=src-agent-java
src.agent.c=src-agent-c
src.reserver=src-re-server
src.redispatch=src-re-disp
src.reagent=src-re-agent
src.test=src-test
bin=bin
......@@ -14,4 +18,4 @@ build.afterbootstrap=build-abs
extendedthread.path=${build}/extendedthread.jar
instr.jar.name=dislinstr.jar
instr.jar.name=disl-instr.jar
......@@ -47,22 +47,43 @@
</javac>
</target>
<target name="compile-test" depends="compile-disl">
<target name="compile-agent-c">
<exec executable="make" dir="${src.agent.c}" />
</target>
<target name="compile-reserver">
<javac srcdir="${src.reserver}" destdir="${bin}" debug="true" includeAntRuntime="false">
<classpath refid="buildpath" />
</javac>
</target>
<target name="compile-redispatch">
<javac srcdir="${src.redispatch}" destdir="${bin}" debug="true" includeAntRuntime="false">
<classpath refid="buildpath" />
</javac>
</target>
<target name="compile-reagent">
<exec executable="make" dir="${src.reagent}" />
</target>
<target name="compile-test" depends="compile-disl,compile-reserver,compile-redispatch">
<javac srcdir="${src.test}" destdir="bin" debug="true" includeAntRuntime="false">
<classpath refid="buildpath" />
</javac>
</target>
<target name="compile" depends="compile-disl,compile-agent-java,compile-test" />
<target name="compile" depends="compile-disl,compile-agent-java,compile-agent-c,compile-test,compile-reserver,compile-redispatch" />
<target name="package-dislserver" depends="compile-disl">
<jar basedir="${bin}" destfile="${build}/dislserver-${disl.version}.jar"
<jar basedir="${bin}" destfile="${build}/disl-server.jar"
includes="ch/usi/dag/disl/**,ch/usi/dag/dislserver/**"
excludes="ch/usi/dag/disl/test/**,ch/usi/dag/disl/testtools/**">
<manifest>
<attribute name="Class-Path" value="${asm.lib} ${instr.jar.name}" />
<attribute name="Class-Path" value="${asm.lib}" />
<attribute name="Main-Class" value="ch.usi.dag.dislserver.DiSLServer" />
<attribute name="DiSL-Version" value="${disl.version}" />
</manifest>
</jar>
</target>
......@@ -79,14 +100,14 @@
<!-- rename after bootstrap class -->
<move file="${build.afterbootstrap}/ch/usi/dag/disl/dynamicbypass/DynamicBypassCheck.class"
tofile="${build.afterbootstrap}/DynamicBypassCheck-AfterBootstrap.class" />
<jar basedir="${bin}" destfile="${build}/dislagent-${disl.version}.jar"
<jar basedir="${bin}" destfile="${build}/disl-agent.jar"
includes="ch/usi/dag/dislagent/**,ch/usi/dag/disl/dynamicbypass/**">
<manifest>
<attribute name="Class-Path" value="${instr.jar.name}" />
<attribute name="Premain-Class" value="ch.usi.dag.dislagent.DiSLAgent" />
<attribute name="Can-Redefine-Classes" value="true" />
<attribute name="DiSL-Version" value="${disl.version}" />
</manifest>
<!-- include after bootstrap class -->
......@@ -97,7 +118,24 @@
<delete dir="${build.afterbootstrap}" />
</target>
<target name="package" depends="package-dislserver,package-dislagent-java" />
<target name="package-reserver" depends="compile-reserver">
<jar basedir="${bin}" destfile="${build}/dislre-server.jar"
includes="ch/usi/dag/dislreserver/**">
<manifest>
<attribute name="Class-Path" value="${asm.lib}" />
<attribute name="Main-Class" value="ch.usi.dag.dislreserver.DiSLREServer" />
<attribute name="DiSL-Version" value="${disl.version}" />
</manifest>
</jar>
</target>
<target name="package-redispatch" depends="compile-redispatch">
<jar basedir="${bin}" destfile="${build}/dislre-dispatch.jar"
includes="ch/usi/dag/dislre/**">
</jar>
</target>
<target name="package" depends="package-dislserver,package-dislagent-java,package-reserver,package-redispatch,compile-agent-c,compile-reagent" />
<target name="eclipse-agent" description="creates simple agent jar file for eclipse">
<mkdir dir="build" />
......@@ -110,7 +148,7 @@
<target name="eclipse-dynamicbypass" depends="compile-dynamicbypass"
description="creates support library for DiSL development under eclipse">
<jar basedir="${bin}" destfile="${build}/eclipse-dynamicbypass.jar"
includes="ch/usi/dag/disl/dynamicbypass/" />
</target>
......@@ -128,8 +166,20 @@
<delete dir="${build}" />
<delete dir="${build.thread}" />
<delete dir="${build.afterbootstrap}" />
<exec executable="make" dir="${src.agent.c}">
<arg value="clean" />
</exec>
<exec executable="make" dir="${src.reagent}">
<arg value="clean" />
</exec>
</target>
<target name="javadoc" depends="package,eclipse">
<javadoc access="public" author="true" overview="doc/overview.html" classpath="build/eclipse-dynamicbypass.jar:${asm.path}" destdir="doc" nodeprecated="false" nodeprecatedlist="false" noindex="false" nonavbar="false" notree="false" packagenames="ch.usi.dag.disl.guardcontext,ch.usi.dag.disl.staticcontext,ch.usi.dag.disl.dynamiccontext,ch.usi.dag.disl.classcontext,ch.usi.dag.disl.marker,ch.usi.dag.disl.transformer,ch.usi.dag.disl.processorcontext,ch.usi.dag.disl.annotation" source="1.7" sourcefiles="src/ch/usi/dag/disl/scope/Scope.java,src/ch/usi/dag/disl/scope/ScopeImpl.java,src/ch/usi/dag/disl/DiSL.java,src/ch/usi/dag/disl/snippet/Shadow.java" sourcepath="src-test:src-agent-java:src" splitindex="true" use="true" version="true"/>
</target>
<!-- *** test instrumentaion package *** -->
<target name="check-test-property">
......
disl.version=unspec
\ No newline at end of file
disl.version=unspec
This diff is collapsed.
This source diff could not be displayed because it is too large. You can view the blob instead.
This source diff could not be displayed because it is too large. You can view the blob instead.
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html;charset=utf-8">
<title>Overview</title>
</head>
<body>
<div>This documentation serves only as a developer documentation of DiSL API. For the installation notes, please look at the README file in the DiSL distribution. For learning of DiSL, please look at the basic examples and the tutorial papers.</div>
</body>
</html>
DiSL SETUP EXAMPLE
==================
This simple example illustrates a basic instrumentation setup. It shows, how
the instrumentation should be packaged and contains a scripts that should ease
running DiSL together with your program.
The example contains simple user application that prints hello string on
command line and instrumentation printing strings before and after application
main.
HOW TO RUN THE EXAMPLE
======================
First be sure that you compiled DiSL (see README in the root directory). Then
follow the steps:
1) compile application calling "ant" in the app directory
2) compile instrumentation calling "ant" in the instrumentation directory
3) run "./runApp.sh instr/build/disl-instr.jar -jar app/build/example-app.jar"
The last command starts the application together with DiSL. The output of the
application and the applied instrumentation should be visible on command line.
NOTE: If you want to use "runApp.sh" to run your application, don't forget to set
"DISL_LIB_P" variable correctly. Also, you can modify DiSL setting in
"runServer.sh".
NOTE: If you want to include use some library in your instrumentation you shlould
insert it directly to the instrumentation jar using jarjar.
http://code.google.com/p/jarjar/
DIRECTORIES (FILES)
===================
app - contains sources of simple application
instr - contains sources of simple instrumentation
runApp.sh - bash script starting the application together with
DiSL (+ instrumentation)
runServer.sh - starts instrumentation server
runClient.sh - starts application vm with necessary agents
<project name="example-app" default="package" basedir=".">
<path id="buildpath">
<pathelement location="${bin}" />
</path>
<target name="compile">
<mkdir dir="bin" />
<javac srcdir="src" destdir="bin" debug="true" includeAntRuntime="false">
<classpath refid="buildpath" />
</javac>
</target>
<target name="package" depends="compile">
<mkdir dir="build" />
<jar basedir="bin" destfile="build/example-app.jar">
<manifest>
<attribute name="Main-Class" value="Main" />
</manifest>
</jar>
</target>
<target name="clean">
<delete dir="bin" />
<delete dir="build" />
</target>
</project>
public class Main {
public static void main(String[] args) {
System.out.println("Hi -- this is application main");
}
}
lib.path=../../build
dislserver.path=${lib.path}/disl-server.jar
asm.lib=asm-debug-all-4.0.jar
asm.path=${lib.path}/${asm.lib}
instr.jar.name=disl-instr.jar
<project name="example-disl" default="package" basedir=".">
<property file="build.properties" />
<path id="buildpath">
<pathelement location="${asm.path}" />
<pathelement location="${dislserver.path}" />
<pathelement location="${bin}" />
</path>
<target name="compile">
<mkdir dir="bin" />
<javac srcdir="src" destdir="bin" debug="true" includeAntRuntime="false">
<classpath refid="buildpath" />
</javac>
</target>
<target name="package" depends="compile" description="create instrumentation package">
<mkdir dir="build"/>
<jar jarfile="build/${instr.jar.name}"
basedir="bin"
excludes="MANIFEST.MF"
manifest="src/MANIFEST.MF">
</jar>
</target>
<target name="clean">
<delete dir="bin" />
<delete dir="build" />
</target>
</project>
import ch.usi.dag.disl.annotation.After;
import ch.usi.dag.disl.annotation.AfterReturning;
import ch.usi.dag.disl.annotation.Before;
import ch.usi.dag.disl.marker.BodyMarker;
public class DiSLClass {
@Before(marker = BodyMarker.class, scope = "Main.main")
public static void beforemain() {
System.out.println("Before main()");
}
@After(marker = BodyMarker.class, scope = "Main.main")
public static void aftermain() {
System.out.println("After main()");
}
}
Manifest-Version: 1.0
DiSL-Classes: DiSLClass
\ No newline at end of file
# /bin/sh
# default DiSL lib path
if [ -z "${DISL_LIB_P}" ]; then
DISL_LIB_P=../build
fi
# test number of arguments
EXPECTED_ARGS=2
if [ $# -lt $EXPECTED_ARGS ]
then
echo "Usage: `basename $0` instr-lib java-params"
exit
fi
# set server file
SERVER_FILE=.server.pid
export SERVER_FILE
# kill running server
if [ -e ${SERVER_FILE} ]
then
kill -KILL `cat ${SERVER_FILE}`
rm ${SERVER_FILE}
fi
export DISL_LIB_P
# start server (with instrumentation library) and take pid
./runServer.sh $1
# wait for server startup
sleep 3
# run client
./runClient.sh $*
# wait for server shutdown
sleep 1
# kill server
kill -KILL `cat ${SERVER_FILE}` 2> /dev/null
rm ${SERVER_FILE}
#!/bin/bash
# set default lib path
if [ -z "${DISL_LIB_P}" ]; then
DISL_LIB_P=./build
fi
# test number of arguments
EXPECTED_ARGS=2
if [ $# -lt $EXPECTED_ARGS ]
then
echo "Usage: `basename $0` instr-lib java-params"
exit
fi
# set proper lib depending on OS
OS=`uname`
if [ "${OS}" = "Darwin" ]; then
C_AGENT="${DISL_LIB_P}/libdislagent.jnilib"
else
C_AGENT="${DISL_LIB_P}/libdislagent.so"
fi
# get instrumentation library and shift parameters
INSTR_LIB=$1
shift
# start client
java -agentpath:${C_AGENT} \
-javaagent:${DISL_LIB_P}/disl-agent.jar \
-Xbootclasspath/a:${DISL_LIB_P}/disl-agent.jar:${INSTR_LIB} \
$*
#!/bin/sh
# set default lib path
if [ -z "${DISL_LIB_P}" ]; then
DISL_LIB_P=./build
fi
# available options
# -Ddebug=true \
# -Ddisl.classes="list of disl classes (: - separator)"
# -Ddisl.noexcepthandler=true \
# -Ddisl.exclusionList="path" \
# -Ddislserver.instrumented="path" \
# -Ddislserver.uninstrumented="path" \
# -Ddislserver.port="portNum" \
# -Ddislserver.timestat=true \
# -Ddislserver.continuous=true \
# get instrumentation library and shift parameters
INSTR_LIB=$1
shift
# start server
java $* \
-cp ${INSTR_LIB}:${DISL_LIB_P}/disl-server.jar \
ch.usi.dag.dislserver.DiSLServer \
&
# print pid to the server file
if [ -n "${SERVER_FILE}" ]; then
echo $! > ${SERVER_FILE}
fi
#!/bin/bash
OS=`uname`
# set default lib path
if [ -z "${DISL_LIB_P}" ]; then
DISL_LIB_P=./build
fi
# test number of arguments
if [ $# -lt 2 ]; then
echo "Usage: `basename $0` instr-lib java-params"
exit 1
fi
# determine libs depending on the OS
OS=`uname`
if [ "${OS}" = "Darwin" ]; then
C_AGENT="src-agent-c/libdislagent.jnilib"
C_AGENT="${DISL_LIB_P}/libdislagent.jnilib"
RE_AGENT="${DISL_LIB_P}/libdislreagent.jnilib"
else
C_AGENT="src-agent-c/libdislagent.so"
C_AGENT="${DISL_LIB_P}/libdislagent.so"
RE_AGENT="${DISL_LIB_P}/libdislreagent.so"
fi
java -agentpath:${C_AGENT} \
-javaagent:build/dislagent-unspec.jar \
-Xbootclasspath/a:build/dislagent-unspec.jar:build/dislinstr.jar \
-cp bin/ \
$*
# get instrumentation library and shift parameters
INSTR_LIB=$1
shift
# start the client
${JAVA_HOME:+$JAVA_HOME/jre/bin/}java \
-agentpath:${C_AGENT} -agentpath:${RE_AGENT} \
-javaagent:${DISL_LIB_P}/disl-agent.jar \
-Xbootclasspath/a:${DISL_LIB_P}/disl-agent.jar:${INSTR_LIB}:${DISL_LIB_P}/dislre-dispatch.jar \
"$@"
#!/bin/sh
# set default lib path
if [ -z "${DISL_LIB_P}" ]; then
DISL_LIB_P=./build
fi
# test number of arguments
if [ $# -lt 1 ]; then
echo "Usage: `basename $0` instr-lib [java-params]"
exit 1
fi
# get instrumentation library and shift parameters
INSTR_LIB=$1
shift
# start the remote execution server
# options available:
# -Ddebug=true \
# -Ddislreserver.port="portNum" \
${JAVA_HOME:+$JAVA_HOME/jre/bin/}java \
-Xms1G -Xmx2G \
-cp ${INSTR_LIB}:${DISL_LIB_P}/dislre-server.jar \
ch.usi.dag.dislreserver.DiSLREServer \
"$@" &
# print pid to the server file
if [ -n "${RE_SERVER_FILE}" ]; then
echo $! > ${RE_SERVER_FILE}
fi
#!/bin/sh
# available options
# -Ddebug=true \
# -Ddisl.classes="list of disl classes (: - separator)"
# -Ddisl.noexcepthandler=true \
# -Ddisl.exclusionList="path" \
# -Ddislserver.instrumented="path" \
# -Ddislserver.uninstrumented="path" \
# -Ddislserver.port="portNum" \
# -Ddislserver.timestat=true \
# -Ddislserver.continuous=true \
# set default lib path
if [ -z "${DISL_LIB_P}" ]; then
DISL_LIB_P=./build
fi
# test number of arguments
if [ $# -lt 1 ]; then
echo "Usage: `basename $0` instr-lib [java-params]"
exit 1
fi
java $* \
-jar build/dislserver-unspec.jar \
&
# get instrumentation library and shift parameters
INSTR_LIB=$1
shift
echo $! > ${SERVER_FILE}
# start the instrumentation server
# options available:
# -Ddebug=true \
# -Ddisl.classes="list of disl classes (: - separator)"
# -Ddisl.noexcepthandler=true \
# -Ddisl.exclusionList="path" \
# -Ddislserver.instrumented="path" \
# -Ddislserver.uninstrumented="path" \
# -Ddislserver.port="portNum" \
# -Ddislserver.timestat=true \
# -Ddislserver.continuous=true \
# -Ddislserver.disablebypass=true \
${JAVA_HOME:+$JAVA_HOME/jre/bin/}java \
-cp ${INSTR_LIB}:${DISL_LIB_P}/disl-server.jar \
ch.usi.dag.dislserver.DiSLServer \
"$@" &
# print pid to the server file
if [ -n "${SERVER_FILE}" ]; then
echo $! > ${SERVER_FILE}
fi
# /bin/sh
#!/bin/bash
TARGET_BASE="ch.usi.dag.disl.test"
TARGET_MAIN="TargetClass"
if [ $# -lt 1 ]; then
echo "Usage: `basename $0` <test-name>"
echo "<test-name> is a package under $TARGET_BASE containing $TARGET_MAIN"
exit 1
fi
EXPECTED_ARGS=1
if [ $# -lt $EXPECTED_ARGS ]
then
echo "Usage: `basename $0` test-case"
exit
fi
kill_server () {
if [ -f "$1" ]; then