Running an Analysis

Running an Analysis

This chapter describes how to run an analysis in Chord. Broadly, there are two kinds of analyses in Chord: those written imperatively in Java and those written declaratively in Datalog. They are summarized in the following table:

In its most general form, the command for running an analysis is as follows:

ant -Dchord.work.dir=<WORK_DIR> -Dchord.run.analyses=<ANALYSIS_NAME> \
    -Dchord.dlog.analysis.path=<DLOG_ANALYSIS_PATH> \
    -Dchord.java.analysis.path=<JAVA_ANALYSIS_PATH> run

where:

• <WORK_DIR> is a directory containing a file named chord.properties that defines various properties of the Java program to be analyzed that might be needed by the analysis being run, such as the program's main class, the program's application classpath, etc. (see Chapter *).
• <ANALYSIS_NAME> is the name of the analysis to run. More generally, it can be a comma-separated list of names of analyses to run in order.
• <JAVA_ANALYSIS_PATH> is a path specifying all imperative analyses written in Java that might be needed to run the desired analysis.
• <DLOG_ANALYSIS_PATH> is a path specifying all declarative analyses written in Datalog that might be needed to run the desired analysis.

Each analysis in Chord is written modularly, independent of other analyses, along with lightweight annotations specifying the inputs and outputs of the analysis. Chord's runtime automatically computes dependencies between analyses (e.g., determines which analysis produces as output a result that is needed as input by another analysis). Before running the desired analysis named <ANALYSIS_NAME>, Chord recursively runs other analyses until the inputs to the desired analysis have been computed; it finally runs the desired analysis to produce the outputs of that analysis. Chapter * explains this process in detail. Each of these analyses must occur in the path denoted by <JAVA_ANALYSIS_PATH> or <DLOG_ANALYSIS_PATH>, depending upon whether the analysis is written imperatively in Java or declaratively in Datalog, respectively.

Chord provides shorthand ways for specifying analysis paths by means of the following six properties:

The paths specified by the chord.std.*.analysis.path properties conventionally include all "standard" analyses: analyses that are predefined in Chord. The default value of each of these properties is the absolute path of file chord.jar. Normally, users must not change the value of these properties.

The paths specified by the chord.ext.*.analysis.path properties conventionally include all "external" analyses: analyses that are written by users. The default value of each of these properties is the empty path.

The paths specified by the chord.*.analysis.path properties include all analyses: both standard and external ones. The default value of each of these properties is simply the concatenation of the values of the corresponding two properties above that specify the paths of standard and external analyses. Normally, users must not change the value of these properties.

Running the above command can cause Chord to report a runtime error in the following scenarios:

• Either no included analysis or multiple included analyses are named <ANALYSIS_NAME>.
• A result declared as consumed by the analysis named <ANALYSIS_NAME> (or by some analysis on which the specified analysis is dependent directly or transitively) is either not declared as produced by any included analysis or is declared as produced by multiple included analyses.

To fix the error resulting from the "missing analysis" case in both the above scenarios, simply include the missing analysis in the path specified by properties chord.*.analysis.path.

To fix the error resulting from the "ambiguous analysis" case in both the above scenarios, the names A1, ..., An of all analyses that were involved in the ambiguity are provided in the error report. Suppose Ai is the desired analysis from this set. Then, one way to fix the error is to exclude all analyses in that set except analysis Ai from the path specified by properties chord.*.analysis.path. A better way is to specify the names of multiple analyses in the value of property chord.run.analyses (recall that this property allows a comma-separated list of names of analyses to be run in order). Specifically, the value of this property must specify the name of the desired analysis Ai before the name of the analysis that caused the ambiguity error.

The above command is for users who have defined their own analyses and wish to run them. The following simpler command that uses the default values for properties chord.*.analysis.path suffices for users who only wish to run analyses predefined in Chord:

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

Section * illustrates this command using an example predefined analysis in Chord.

Running an Analysis