All the libs listed below should be in your Java classpath:
Libraries required:
These libraries are required to compile SensA source package and, more other libraries may be needed to add to either the JVM class path or Soot class path, depending on which part of Sensa is to be used. Those more libraries are clarified in the sections where they are involved as follows.
Simply put, the input to SensA should be the Java bytecodes, in which there is a change location of which you wish to see the impacts. The bytecodes, in the form of classfiles, are to be presented to the SensA instrumenter as the source input of the whole SensA dynamic analysis pipeline as well, which includes three phases:
(1) instrumenting subject, which instruments modification interface into the subject bytecode for later dynamic analysis;
(2) running instrumented subject, by which SensA modifies target variable in the instrumented statement in the runtime;
(3) post-processing the outputs from phase (2), through which SensA calculates change impact rankings as so to tell which points (statements) in the input subject is impacted and, especially, how much each point is impacted in terms of the rank of possibility that each is impacted compared to other impacted points.
As these phases being listed, the input for phase (2) is the instrumented subject classfiles, and that for the phase (3) is the outputs from running the subject instrumented. Here the running outputs are not merely the output of the original subject before instrumentation, but those in which the execution history, that SensA has instrumented by the way the modification interface was instrumented in phase (1), is mixed.
Another input for phase (2) is what the original subject should be fed with. In particular, SensA presumes that there is a "standard" sub-directory named "inputs" located in the "Basepath", as indicated as the second parameter of SensaRun. See the following section on "How to use SensA Run" for more details.
In order for SensA to instrument the bytecode of the target subject, adding certain statements in the subject source code is needed. In this regard however, SensA requires the addition of statements into the main/entry class of the holistic subject project only.
Precisely, the following statements should be added to the entry class, which is essentially an extra static method and thus would not mess the original source code up:
public class TheEntryClass {
......
// added for Sensa Instrumentation
static void __link() {
BranchReporter.__link();
DUAReporter.__link();
DynSliceReporter.__link();
ExecHistReporter.__link();
Sensa.Modify.__link();
}
......
In order to compile this piece of code, the corresponding names should be imported as well:
import profile.ExecHistReporter; import change.DynSliceReporter; import profile.BranchReporter; import profile.DUAReporter;
As long as the libraries required as described above are in the class paths, the compiler will be able to find the packages and names in there. For the "Sensa.Modify" to be resolved, however, the path where the SensA classfiles are located should also be added into the class path setting for compiler.
Now the source code of target subject with the foregoing additions can be compiled, an exemplary class path setting is given below as it is in a complete compilation script (in Linux B-shell):
ROOT=/home/user1/
MAINCP=".:$ROOT/tools/DUAForensics-bins-code/DUAForensics:$ROOT/tools/DUAForensics-bins-code/InstrReporters:$ROOT/tools/Sensa/bin/:$ROOT/subject/src/"
javac -g:source -source 1.4 -cp ${MAINCP} -d $ROOT/subject/bin subjectFile1.java
Other paths needed for the subject's class dependences and libraries ought also to be in "MAINCP". Note that the "-g:source -source:1.4" option for javac is strongly recommended for compiling subject in order to ensure correct functionalities of SensA.
Once the compilation succeeds, it is ready to start the instrumentation for dynamic analysis as instructed as follows. First, you need to indicate the instrumentation point for SensA to instrument modifications in the enclosing class. This instrumentation point is also referred as "change location" since you will almost always want to instrument at the change location when using SensA to predict how the change you have known about will impact other points in your whole subject project.
Since the primary input of SensA is the byte-code of the target subject, change location as it is indicated to SensA is referred to based on the intermediate representation of the subject rather than its plain source code. SensA is now built and works on top of the Soot framework and, in particular, substantially uses Soot's Jimple representation along with the corresponding parser to implement basic Java byte-code resolution and analysis. Therefore, the change location is specified according to where the statement in which the change is involved is located in the Jimple code derived from the original subject's source code.
Once we have chosen the change location, instrumentation is ready to run. As shown in the following example, "change" is the statement id giving the change location and, the class path for JVM and Soot are given by "MAINCP" and "SOOTCP" respectively. To run the instrumenter using command line on Windows, the shell below script can be converted into batch script accordingly. When running it in IDEs such as Eclipse, a Run/Debug configuration can be created by picking class paths as exemplified in the script below and indicating corresponding parameters.
The primary parameters for SensA instrumenter are explained as follows.
change=$1
ver=$2
seed=$3
ROOT=/home/hcai/
subjectloc=/home/hcai/SVNRepos/star-lab/trunk/Subjects/Schedule1/
MAINCP=".:/etc/alternatives/java_sdk/jre/lib/rt.jar:$ROOT/tools/polyglot-1.3.5/lib/polyglot.jar:$ROOT/tools/soot-2.3.0/lib/sootclasses-2.3.0.jar:$ROOT/tools/jasmin-2.3.0/lib/jasminclasses-2.3.0.jar:$ROOT/tools/DUAForensics-bins-code/DUAForensics:$ROOT/tools/DUAForensics-bins-code/LocalsBox:$ROOT/tools/DUAForensics-bins-code/InstrReporters:$ROOT/workspace/Sensa/bin:$ROOT/tools/java_cup.jar:$ROOT/workspace/ProbSli/bin"
mkdir -p out-instr
SOOTCP=".:$ROOT/software/j2re1.4.2_18/lib/rt.jar:$ROOT/tools/DUAForensics-bins-code/DUAForensics:$ROOT/tools/DUAForensics-bins-code/LocalsBox:$ROOT/tools/DUAForensics-bins-code/InstrReporters:$ROOT/workspace/Sensa/bin:$ROOT/workspace/ProbSli/bin:$subjectloc/bin/${ver}${seed}:$subjectloc/lib"
OUTDIR=$subjectloc/instrumented-$ver-$seed-$change
mkdir -p $OUTDIR
java -Xmx1600m -ea -cp ${MAINCP} Sensa.SensaInst \
-w -cp ${SOOTCP} \
-p cg verbose:true,implicit-entry:false -p cg.spark verbose:true,on-fly-cg:true,rta:true \
-f c -d "$OUTDIR" -brinstr:off -duainstr:off \
-duaverbose -start:$change \
-slicectxinsens \
-allowphantom \
-exechist \
-main-class ScheduleClass -entry:ScheduleClass \
-process-dir $subjectloc/bin/${ver}${seed} \
1>out-instr/instr-$change-${ver}${seed}.out 2>out-instr/instr-$change-${ver}${seed}.err
After successful instrumentation, the instrumented subject, the instrumented class needs to be run using SensA runner as follows.
An actual example of the runtime phase usage of SensA is shown below.
change=$1
ver=$2
seed=$3
ROOT=/home/hcai/
subjectloc=/home/hcai/SVNRepos/star-lab/trunk/Subjects/Schedule1/
INDIR=$subjectloc/instrumented-$ver-$seed-$change
MAINCP=".:/etc/alternatives/java_sdk/jre/lib/rt.jar:$ROOT/tools/polyglot-1.3.5/lib/polyglot.jar:$ROOT/tools/soot-2.3.0/lib/sootclasses-2.3.0.jar:$ROOT/tools/jasmin-2.3.0/lib/jasminclasses-2.3.0.jar:$ROOT/workspace/Sensa/bin:$ROOT/workspace/ProbSli/bin:$ROOT/tools/java_cup.jar:$ROOT/tools/DUAForensics-bins-code/DUAForensics:$ROOT/tools/DUAForensics-bins-code/LocalsBox:$ROOT/tools/DUAForensics-bins-code/InstrReporters:$ROOT/workspace/Sensa/bin:$subjectloc/lib:$ROOT/workspace/TestAdequacy/bin:$INDIR"
OUTDIR=$subjectloc/outdyn-${ver}${seed}-$change
mkdir -p $OUTDIR
java -Xmx2800m -ea -cp ${MAINCP} -DnotRunWithNotHit=true Sensa.SensaRun \
ScheduleClass \
"$subjectloc" \
"$INDIR" \
$change \
$OUTDIR
(1) the expected outputs of SensA instrumenter are:
(2) the expected outputs for the run phase of SensA are:
1.6.1