Before you use NIONKA-Java

  1. Obtain the Soot framework.

    Visit http://www.sable.mcgill.ca/soot/soot_download.html and download the Jars containing the class files for:
    - Soot (sootclasses-<version>.jar)
    - Jasmin (jasminclasses-<version>.jar)
    - Polyglot (polyglotclasses-<version>.jar)

    Add the three Jars to your Java classpath.

  2. Add nionka-java.jar to your Java classpath.

Test your NIONKA-Java setup

Assuming $NIONKA is the directory where you extracted the Nionka tarball.

  1. Enter the test directory

    $ cd $NIONKA/test

  2. Compile Test.java

    $ javac Test.java

    This will create a Test.class file.

  3. Instrument the Test program using NIONKA

    $ java nionka.instrumenter.RunInstrumenter -keep-line-number -input <full path to Test.branches> Test

    This will create a sootOutput directory that contains the instrumented Test.class file.

  4. Test the non-instrumented program

    Running the non-instrumented program should give the following output:
    $ java Test true true
    Conditions: true, true
    Condition 1's true branch
    Condition 2's true branch

  5. Test the instrumented program

    Running the instrumented program should give the following output:
    $ java Test true true
    Conditions: true, true
    Condition 1's false branch
    Condition 2's true branch

If the outputs in Step 4 and Step 5 are correct then you have a successfully installed NIONKA.

How to use NIONKA

$ java nionka.instrumenter.RunInstrumenter -keep-line-number
-input <full path to branch table file> <java program>

It is mandatory to include the -keep-line-number flag. This will ask Soot to include line number information which is used by Nionka to identify the predicates' locations.

The branch table file needs to follow this format:

<line number> <0 or 1>

Each line indicates the line number of a predicate and whether the predicate's outcome will be flipped or not. 1 indicates to flip the predicate's outcome.

* Current limitation of NIONKA is that it can only be used on Java programs composed out of one java file.