Setting up a Java Program for Analysis

Setting up a Java Program for Analysis

This chapter describes how to setup a Java program for analysis using Chord. Suppose the program has the following directory structure:

example/
    src/
        foo/
            Main.java
            ...
    classes/
        foo/
            Main.class
            ...
    lib/
        src/
            taz/
                ...
        jar/
            taz.jar
    chord.properties

The above structure is typical: the program's Java source files are under src/, its class files are under classes/, and the source and jar files of the libraries used by the program are under lib/src/ and lib/jar/, respectively. The purpose of the chord.properties file is explained below.

The only way to specify inputs to Chord, including the program to be analyzed, is via system properties. Section * describes various ways by which properties can be passed to Chord. Here, we describe the simplest approach, in which all properties of the program to be analyzed that might be needed by Chord are defined in a file named chord.properties that is located in the top-level directory of the program (directory example/ above). Then, Chord can be applied to the program by running the following command:

ant -Dchord.work.dir=<WORK_DIR> run

This command instructs Chord to run in the directory denoted by <WORK_DIR>, where it searches for a file named chord.properties and loads all properties defined in that file, if it exists. Thus, for the above program, <WORK_DIR> must be the absolute or relative path of the example/ directory. A sample chord.properties file for the above program is as follows:

chord.main.class=foo.Main
chord.class.path=classes:lib/jar/taz.jar
chord.src.path=src:lib/src
chord.run.ids=0,1
chord.args.0="-thread 1 -n 10"
chord.args.1="-thread 2 -n 50"

Each relative file/directory name in the value of any property defined in this file (e.g., the lib/src directory name in the value of property chord.src.path above) is treated relative to the directory specified by property chord.work.dir, whose default value is the current directory. Section * presents all program properties that are recognized by Chord. Here, we only describe those that are most commonly used, namely, those defined in the above sample properties file:

• chord.main.class specifies the fully-qualified name of the main class of the program.
• chord.class.path specifies the application classpath of the program (the JDK standard library classpath is implicitly included).
• chord.src.path specifies the Java source path of the program. All analyses in Chord operate on Java bytecode. The only use of this property is to HTMLize the Java source files of the program so that the results of analyses can be reported at the Java source code level.
• chord.run.ids specifies a list of IDs to identify runs of the program. It is used by dynamic analyses to determine how many times the program must be run. An additional use of this property is to allow specifying the command-line arguments to use in the run having ID <id> via property chord.args.<id>, as illustrated by properties chord.args.0 and chord.args.1 above.

The above command does not do much beyond making Chord load the above properties file. For Chord to do something interesting, additional properties must be set that specify the function(s) Chord must perform. All functions are summarized in Section *. The most common function is to run one or more analyses on the input program; it is described in Chapter *.

Setting up a Java Program for Analysis