Deam Usage

How to use Deam

Study with random changes

To evaluate the target dynamic impact analysis using random changes, the first and foremost step is to generate a massive number of changed program versions. Deam does this efficiently via dynamic generation of those versions of a same base program version, which involves byte-code instrumentation.

In order for Deam to instrument the bytecode of the target subject, adding certain statements in the subject source code is needed. In this regard however, Deam 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 deam Instrumentation
	static void __link() { 
		mut.Modify.__link(); 
	}
	......

Then, follow the steps below:

(1) Compile the subject with the above extra code added.

• similar to how you compile the original (uninstrumented) subject program, just add extra class paths for Deam and its library dependencies.

(2) Instrument state-modification probes for runtime generation of changed versions.

• An actual example script is given below; you just need to accommodate the variables to your own environment.

  ver=$1
  seed=$2
  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/workspace/DUAForensics/bin:$ROOT/workspace/LocalsBox/bin:$ROOT/workspace/InstrReporters/bin:$ROOT/workspace/Deam/bin:$ROOT/workspace/mcia/bin:$ROOT/workspace/Sensa/bin:$ROOT/tools/java_cup.jar:$ROOT/workspace/ProbSli/bin"
  
  SOOTCP=".:/etc/alternatives/java_sdk/jre/lib/rt.jar:/etc/alternatives/java_sdk/jre/lib/jce.jar:$ROOT/workspace/DUAForensics/bin:$ROOT/workspace/LocalsBox/bin:$ROOT/workspace/InstrReporters/bin:$ROOT/workspace/mcia/bin:$ROOT/workspace/Deam/bin:$ROOT/workspace/Sensa/bin:$ROOT/workspace/ProbSli/bin:$subjectloc/lib:$subjectloc/bin/${ver}${seed}"
  
  suffix=${ver}${seed}
  
  LOGDIR=out-MutEHInstr
  mkdir -p $LOGDIR
  logout=$LOGDIR/instr-$suffix.out
  logerr=$LOGDIR/instr-$suffix.err
  
  OUTDIR=$subjectloc/Step1MutEHInstrumented-$suffix 
  mkdir -p $OUTDIR 
  
  java -Xmx6600m -ea -cp ${MAINCP} mut.MutInst \
  	-w -cp $SOOTCP -p cg verbose:false,implicit-entry:false \
  	-p cg.spark verbose:false,on-fly-cg:true,rta:true -f c \
  	-d $OUTDIR \
  	-brinstr:off -duainstr:off \
  	-allApplicablePoints \
  	-allowphantom \
  	-slicectxinsens \
  	-main-class $DRIVERCLASS \
  	-entry:$DRIVERCLASS \
  	-process-dir $subjectloc/bin/${ver}${seed} \
  	1> $logout 2> $logerr
  
  SOOTCP=".:/etc/alternatives/java_sdk/jre/lib/rt.jar:/etc/alternatives/java_sdk/jre/lib/jce.jar:$ROOT/workspace/DUAForensics/bin:$ROOT/workspace/LocalsBox/bin:$ROOT/workspace/InstrReporters/bin:$ROOT/workspace/mcia/bin:$ROOT/workspace/Deam/bin:$ROOT/workspace/Sensa/bin:$ROOT/workspace/ProbSli/bin:$subjectloc/lib:$OUTDIR"
  
  OUTDIR1=$OUTDIR
  OUTDIR=$subjectloc/MutEHInstrumented-$suffix
  
  change="-2147483648" # leave this value, for instrumenting execution history collection everywhere in the program
  java -Xmx6600m -ea -cp ${MAINCP} deam.DeamInst \
  	-w -cp $SOOTCP -p cg verbose:false,implicit-entry:false \
  	-p cg.spark verbose:false,on-fly-cg:true,rta:true -f c \
  	-d $OUTDIR \
  	-brinstr:off -duainstr:off \
  	-allowphantom \
  	-slicectxinsens \
  	-start:$change \
  	-main-class $DRIVERCLASS \
  	-entry:$DRIVERCLASS \
  	-process-dir $OUTDIR1 \
  	1>> $logout 2>> $logerr
  
  mv $OUTDIR1/MutPoints.out $OUTDIR/
  rm -rf $OUTDIR1
  

(3) Run the above instrumented code to produce the execution history of the unchanged program.

• Similar to how you run the original (uninstrumented) subject program, just add extra class paths for Deam and its library dependencies.
• The reason why we don't directly run the uninstrumented code to get this original execution history is that we need execution history alignment between this unchanged version and many changed versions produced later on, to facilitate the execution history differencing.

(4) Prepare the binary executable as the input to the dynamic impact analysis you want to evaluate.

• By default, if EAS is the analysis under study, the following example illustrates how to prepare that input.
• EAS implementation has been included in the Deam package that can be found in the list of downloadables.

  ver=$1
  seed=$2
  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/workspace/DUAForensics/bin:$ROOT/workspace/LocalsBox/bin:$ROOT/workspace/InstrReporters/bin:$ROOT/workspace/Deam/bin:$ROOT/workspace/mcia/bin:$ROOT/workspace/Sensa/bin:$ROOT/tools/java_cup.jar:$ROOT/workspace/ProbSli/bin"
  
  SOOTCP=".:/etc/alternatives/java_sdk/jre/lib/rt.jar:/etc/alternatives/java_sdk/jre/lib/jce.jar:$ROOT/workspace/DUAForensics/bin:$ROOT/workspace/LocalsBox/bin:$ROOT/workspace/InstrReporters/bin:$ROOT/workspace/mcia/bin:$ROOT/workspace/Deam/bin:$ROOT/workspace/Sensa/bin:$subjectloc/bin/${ver}${seed}:$subjectloc/lib"
  
  suffix=${ver}${seed}
  
  LOGDIR=out-MutEAInstr
  mkdir -p $LOGDIR
  logout=$LOGDIR/instr-$suffix.out
  logerr=$LOGDIR/instr-$suffix.err
  
  OUTDIR=$subjectloc/MutEAInstrumented-$suffix
  mkdir -p $OUTDIR
  
  java -Xmx6600m -ea -cp ${MAINCP} mut.MutInst \
  	-w -cp $SOOTCP -p cg verbose:false,implicit-entry:false \
  	-p cg.spark verbose:false,on-fly-cg:true,rta:true -f c \
  	-d $OUTDIR \
  	-brinstr:off -duainstr:off \
  	-allowphantom \
  	-wrapTryCatch \
  	-allApplicablePoints \
  	-dumpJimple \
  	-instrEAS \
  	-dumpFunctionList \
  	-slicectxinsens \
  	-main-class $DRIVERCLASS \
  	-entry:$DRIVERCLASS \
  	-process-dir $subjectloc/bin/${ver}${seed} \
  	1> $logout 2> $logerr
  

(5) Run the study.

• The following script illustrates how to evaluate the target analysis for the given list of queries and list of modification points.
• The third parameter gives the list of queried methods.
• The fourth parameter gives the list of modification points (statements), each in order corresponding to a query in the list of queries given by the third parameter above.
• The last parameter indicates how many tests to run for this study.

ver=$1
seed=$2
query=${3:-"main"}
change=$4
NT=${5:-2650}

ROOT=/home/hcai/
subjectloc=/home/hcai/SVNRepos/star-lab/trunk/Subjects/Schedule1/

suffix=${ver}${seed}

INDIREA=$subjectloc/MutEAInstrumented-$suffix
INDIREH=$subjectloc/MutEHInstrumented-$suffix

MAINCP=".:/etc/alternatives/java_sdk/jre/lib/rt.jar:$ROOT/tools/j2sdk1.4.2_18/lib/tools.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/java_cup.jar:$ROOT/workspace/DUAForensics/bin:$ROOT/workspace/LocalsBox/bin:$ROOT/workspace/InstrReporters/bin:$ROOT/workspace/Deam/bin:$ROOT/workspace/mcia/bin:$ROOT/workspace/Sensa/bin:$ROOT/workspace/ProbSli/bin:$ROOT/workspace/TestAdequacy/bin:$subjectloc/lib"

suffix=${ver}${seed}

java -Xmx1600m -ea -cp ${MAINCP} mut.MutRunAnalysis \
	"$subjectloc" \
	${ver}${seed} \
	$DRIVERCLASS \
	"$query" \
	$change \
	$INDIREA/traceLengths.txt \
	$INDIREH/stmtids.out \
	$NT \
	10 \
	1

• To run the entire study for single-method changes (i.e., evaluate with all possible queries, with a single query each time), you may write a wrapper script where you repeat this step, each time assigning a query and modification point, to traverse all methods in the subject (you can find the list of all methods in the file 'functionList') using corresponding modification point list per method (you can find the list of all modifiable points in the file 'MutPoints.out'). (Both files are located in the output directory of step (2).)
• To run the entire study for multiple-method changes (i.e., evaluate with all possible queries, with multiple queries each time), the procedure is similar to above. The main difference is the extra step of random grouping multiple methods.
• To illustrate, refer to the pytho scripts enclosed: 'calculateEASAccuracy.py' for single-method change study, and 'MMC_calculateEASAccuracy.py' for multiple-method change study.

(6) Obtain the results.

• Running Step (5) will print the accuracy measure and related statistics for each query (or query group) to the stdout.