| | | Chord Properties |
The only way to specify inputs to Chord is by means of system properties. There is no command-line argument processing in Chord and any command-line arguments are ignored. Section * explains how to set properties and Section * explains the meaning of properties recognized by Chord. Notation [<...>] is used in this chapter to denote the value of the property named <...>.
A property can be passed to Chord in any of several ways. The reason for providing multiple ways is to provide users with shorthand ways for defining properties once and for all for a particular Java program under analysis, or even once and for all across all Chord runs. The following are the different ways by which a property can be passed to Chord in decreasing order of precedence:
How: On the command-line via the "-D<key>=<val>" format.
When: Use this option to specify properties specific to the current run of Chord.
Typical usage of this option is by running the following command:
ant -D<key1>=<val1> ... -D<keyN>=<valN> run |
How: Via a user-defined properties file whose location is specified by property chord.props.file.
When: Use this option to specify once and for all properties of the Java program to be analyzed (e.g., property chord.main.class specifying the name of that program's main class). Chapter * presents an example properties file that defines the program properties that are most commonly used. Section * presents all program properties that are recognized by Chord.
The default value of property chord.props.file is [chord.work.dir]/chord.properties. Property chord.work.dir specifies the directory in which Chord must run; its default value is the current directory.
There are three ways to use this option of setting properties:
The first way is to override the default value of property chord.work.dir on the command-line. This requires naming the above properties file as chord.properties, placing it in the directory in which Chord will run, denoted <WORK_DIR> (e.g., this could be the top-level directory of the program to be analyzed), and running the following command:
ant -Dchord.work.dir=<WORK_DIR> run |
The second way is to override the default value of property chord.props.file on the command-line. In this case, the properties file can be in any user-desired location, denoted <PROPS_FILE>, and Chord will run in the current directory:
ant -Dchord.props.file=<PROPS_FILE> run |
The third (and most flexible) way is to override the default values of both properties chord.work.dir and chord.props.file on the command-line.
How: Via the properties file named chord.properties that is already provided in Chord's main directory.
When: Use this option to specify once and for all properties you would like to hold in every run of Chord (e.g., property chord.max.heap specifying the maximum heap memory size to be used by the JVM running Chord).
The following properties are recognized by Chord. The separator for list-valued properties can be either a blank space, a comma, a colon, or a semi-colon.
This section describes properties of the Java program to be analyzed, such as its main class, the location(s) of its class files and Java source files, and command-line arguments to be used when running the program.
chord.work.dir
Type: location
Description: Working directory during Chord's execution. This is
usually the top-level directory of the input Java program.
Default value: current working directory
chord.props.file
Type: location
Description: Properties file loaded by Chord at the
beginning before doing anything else. Any of the below properties may
be defined in this file to avoid defining them on the command line
(using the "-D<key>=<val>" format) every time Chord is run.
Each relative file/directory name in the value of any property defined
in this file is treated relative to Chord's working directory (which
is specified by property chord.work.dir).
Default value: [chord.work.dir]/chord.properties
chord.main.class
Type: class
Description: Fully-qualified name of the main class of the input Java program (e.g., com.example.Main).
chord.class.path
Type: path
Description: Classpath of the input Java program. It does not need to include
boot classes (i.e., classes in [sun.boot.class.path]) or
standard extensions (i.e., classes in jar files in directory [java.home]/lib/ext/).
Default value: ""
chord.src.path
Type: path
Description: Source path of the input Java program.
Default value: ""
Note: Chord analyzes only Java bytecode, not Java source code. This property is used only by the task of converting Java source files into HTML files by analyses that need to present their results at the Java source code level (by calling method chord.program.Program.g().HTMLizeJavaSrcFiles()).
chord.run.ids
Type: string list
Description: List of IDs to identify runs of the input Java program.
Default value: 0
Note: This property is used only when Chord runs the input Java program, namely, when it is asked to compute the analysis scope dynamically (i.e., when [chord.scope.kind]=dynamic) or when it is asked to run a dynamic analysis.
chord.args.<id>
Type: string
Description: Command-line arguments string to be used for the input Java program in the run having ID <id>.
Default value: ""
Note: This property is used only when Chord runs the input Java program, namely, when it is asked to compute the analysis scope dynamically (i.e., when [chord.scope.kind]=dynamic) or when it is asked to run a dynamic analysis.
chord.runtime.jvmargs
Type: string
Description: Arguments to JVM which runs the input Java program.
Default value: "-ea -Xmx1024m"
Note: This property is used only when Chord runs the input Java program, namely, when it is asked to compute the analysis scope dynamically (i.e., when [chord.scope.kind]=dynamic) or when it is asked to run a dynamic analysis.
This section describes properties that specify how the analysis scope of the input Java program is computed. See Chapter * for more details.
chord.scope.kind
Type: [dynamic|rta|cha]
Description: Algorithm to compute analysis scope. The choices are dynamic (dynamic analysis), rta (Rapid Type Analysis), and cha (Class Hierarchy Analysis).
Default value: rta
Note: This property is ignored if property chord.reuse.scope is set to true and the files specified by properties chord.methods.file and chord.reflect.file exist.
chord.reflect.kind
Type: [none|dynamic|static|static_cast]
Description: Algorithm to resolve reflection. The choices are none (do not resolve any reflection),
dynamic (run the program and observe how reflection is resolved),
static (resolve reflection statically but without analyzing casts), and
static_cast (resolve reflection statically by analyzing casts).
Default value: none
chord.ch.kind
Type: [static|dynamic]
Description: Algorithm to build the class hierarchy. If it is dynamic, then the input Java program is executed
and classes not loaded by the JVM while running the program are excluded while building the class hierarchy.
Default value: static
Note: This property is relevant only if chord.scope.kind is cha since only this
scope computing algorithm queries the class hierarchy.
chord.ssa
Type: bool
Description: Do SSA (Static Single Assignment) transformation of the bodies of all methods deemed reachable by the algorithm used to compute analysis scope.
Default value: true
chord.std.scope.exclude
Type: string list
Description: Partial list of prefixes of names of classes, typically inside the JDK standard library, whose methods must be treated as no-ops.
Default value: ""
chord.ext.scope.exclude
Type: string list
Description: Partial list of prefixes of names of classes, typically outside the JDK standard library, whose methods must be treated as no-ops.
Default value: ""
chord.scope.exclude
Type: string list
Description: Complete list of prefixes of names of classes whose methods must be treated as no-ops.
Default value: "[chord.std.scope.exclude],[chord.ext.scope.exclude]"
chord.std.check.exclude
Type: string list
Description: Partial list of prefixes of names of classes, typically inside the JDK standard library, to be excluded by analyses. Interpretation of this property is analysis-specific.
Default value: "java.,javax.,sun.,com.sun.,com.ibm., org.apache.harmony."
chord.ext.check.exclude
Type: string list
Description: Partial list of prefixes of names of classes, typically outside the JDK standard library, to be excluded by analyses. Interpretation of this property is analysis-specific.
Default value: ""
chord.check.exclude
Type: string list
Description: Complete list of prefixes of names of classes to be excluded by analyses. Interpretation of this property is analysis-specific.
Default value: "[chord.std.check.exclude],[chord.ext.check.exclude]"
This section describes properties that dictate what task(s) Chord must perform.
chord.build.scope
Type: bool
Description: Compute the analysis scope of the input Java program.
Default value: false
Note: The analysis scope is computed regardless of the value of this property if another task (e.g., an analysis specified via property chord.run.analyses) demands it.
chord.run.analyses
Type: string list
Description: List of names of analyses to be run in order.
Default value: ""
Note: If the analysis is written in Java, its name is specified via
a statement name="..." in the @Chord annotation of the class defining
the analysis. If the analysis is written in Datalog, its name is specified via
a line "# name=..." in the .dlog file defining the analysis.
chord.print.methods
Type: string list
Description: List of methods whose intermediate representation to print to standard output.
Default value: ""
Note: Specify each method in format mname:mdesc@cname where mname is the method's name, mdesc is the method's descriptor, and cname is the name of the method's declaring class. In cname, use `.' instead of `/', and use `#' instead of `$'.
chord.print.classes
Type: string list
Description: List of classes whose intermediate representation to print to standard output.
Default value: ""
Note: In class names, use `.' instead of `/', and use # instead of the dollar character.
chord.print.all.classes
Type: bool
Description: Print intermediate representation of all classes in scope to standard output.
Default value: false
chord.print.rels
Type: string list
Description: List of names of program relations whose contents must be printed to files [chord.out.dir]/<RELNAME>.txt where
<RELNAME> denotes the relation name.
Default value: ""
Note: This functionality must be used with caution as certain program relations, albeit represented compactly as BDDs, may contain
a large number (e.g., millions) of tuples, resulting in voluminous output when printed in explicit form to a text file. See Section
* for a more efficient way to query the contents of program relations (namely, by using the debug
target provided in file build.xml in Chord's main directory).
chord.print.project
Type: bool
Description: Create files targets_sortby_name.html, targets_sortby_kind.html, and targets_sortby_producers.html
in directory [chord.out.dir], publishing all tasks and targets defined by analyses in paths [chord.java.analysis.path] and
[chord.dlog.analysis.path].
Default value: false
chord.print.results
Type: bool
Description: Print the results of analyses in HTML. Interpretation of this property is analysis-specific.
Default value: true
chord.verbose
Type: int in the range [0..5]
Description: Control the verbosity of messages during Chord's execution.
Default value: 1
This section describes properties regarding analyses executed by Chord.
chord.classic
Type: bool
Description: Whether to use the classic project (as opposed to the modern
project). See Chapter* for the difference
between the two kinds of projects.
Default value: true
chord.std.java.analysis.path
Type: path
Description: Partial classpath of analyses written in Java (i.e., @Chord-annotated classes).
Conventionally, it includes all Java analyses that are predefined in Chord.
Default value: The absolute path of file chord.jar.
chord.ext.java.analysis.path
Type: path
Description: Partial classpath of analyses written in Java (i.e., @Chord-annotated classes).
Conventionally, it includes all user-defined analyses.
Default value: ""
chord.java.analysis.path
Type: path
Description: Complete classpath of analyses written in Java (i.e., @Chord-annotated classes).
Default value: [chord.std.java.analysis.path]:[chord.ext.java.analysis.path]
chord.std.dlog.analysis.path
Type: path
Description: Partial path of analyses written in Datalog (i.e., files with suffix .dlog).
Conventionally, it includes all Datalog analyses that are predefined in Chord.
Default value: The absolute path of file chord.jar.
chord.ext.dlog.analysis.path
Type: path
Description: Partial path of analyses written in Datalog (i.e., files with suffix .dlog).
Conventionally, it includes all user-defined Datalog analyses.
Default value: ""
chord.dlog.analysis.path
Type: path
Description: Complete path of analyses written in Datalog (i.e., files with suffix .dlog).
Default value: [chord.std.dlog.analysis.path]:[chord.ext.dlog.analysis.path]
This section describes properties regarding bytecode instrumentation and dynamic analysis.
chord.use.jvmti
Type: bool
Description: Whether the JVMTI-based bytecode instrumentation agent from main/agent/ must be used for running dynamic analyses.
Default value: false
chord.instr.kind
Type: [offline|online]
Description: The kind of bytecode instrumentation. The choices are offline and online (load-time).
Default value: offline
chord.trace.kind
Type: [full|pipe]
Description: The medium by which an event-generating JVM and an event-handling JVM communicate in a dynamic analysis. The choices are regular file and POSIX pipe.
Default value: full
chord.trace.block.size
Type: int
Description: Number of bytes to read/write in a single operation from/to the event trace file in a multi-JVM dynamic analysis.
Default value: 4096
chord.dynamic.haltonerr
Type: bool
Description: Whether to terminate Chord if the input Java program terminates abnormally during dynamic analysis.
Default value: true
chord.dynamic.timeout
Type: int
Description: The amount of time, in milliseconds, after which to kill the process running the given program during dynamic analysis, or -1 if the process must never be killed.
Default value: -1
chord.max.cons.size
Type: int
Description: Maximum number of bytes over which events generated during the execution of any constructor in the given program may span.
Default value: 50000000
Note: This property is relevant only for dynamic analyses which want events of the form BEF_NEW h t o to be generated (see Section *). The problem with generating such events at run-time is that the ID o of the object freshly created by thread t at object allocation site h cannot be instrumented until the object is fully initialized (i.e., its constructor has finished executing). Hence, Chord first generates a "crude dynamic trace", which has events of the form BEF_NEW h t and AFT_NEW h t o generated before and after the execution of the constructor, respectively. A subsequent pass generates a "final dynamic trace", which replaces each BEF_NEW h t event by BEF_NEW h t o. For this purpose, however, Chord must buffer all events generated between the BEF_NEW and AFT_NEW events, and this property specifies the number of bytes over which these events may span. If the actual number of bytes exceeds the value specified by this property (e.g., if the constructor throws an exception and the AFT_NEW event is not generated at all), then Chord simply generates event BEF_NEW h i 0 (i.e., it treats the created object as having ID 0, which is the ID also used for null).
This section describes properties that specify what must be reused by Chord, if available, from previous runs instead of recomputing.
chord.reuse.scope
Type: bool
Description: Compute analysis scope using the information in files specified by properties chord.methods.file and chord.reflect.file, if both of those files exist.
Default value: false
Note: Property chord.scope.kind is ignored if this property is set to true and the two files exist.
chord.reuse.rels
Type: bool
Description: Load each desired program relation named <name> from the BDD stored in file [chord.bddbddb.work.dir]/<name>.bdd, if the file exists.
Default value: false
chord.reuse.traces
Type: bool
Description: Reuse event traces stored in file(s) chord.trace.file]_full_ver0_runM.txt for dynamic analysis, if those files exist,
where M ranges over run IDs specified by property chord.run.ids.
Property chord.trace.kind must be set to full if this property is set to true.
Default value: false
This section describes properties regarding the JVM that runs Chord.
chord.max.heap
Type: string
Description: Maximum heap memory size of the JVM running Chord.
Default value: 1024m
chord.max.stack
Type: string
Description: Maximum thread stack size of the JVM running Chord.
Default value: 32m
chord.jvmargs
Type: string
Description: Arguments to the JVM running Chord.
Default value: "-showversion -ea -Xmx[chord.max.heap] -Xss[chord.max.stack]"
This section describes properties concerning BDD-based Datalog solver bddbddb that is used by Chord to run analyses written in Datalog.
chord.use.buddy
Type: bool
Description: Whether BDD library BuDDy from main/bdd/ must be used by bddbddb.
Default value: false
chord.bddbddb.max.heap
Type: string
Description: Maximum heap memory size of JVM running bddbddb.
Default value: 1024m
Note: bddbddb is invoked in a separate JVM for each analysis written in Datalog that is executed.
This is primarily because multiple Datalog analyses may be executed in a single run of Chord,
resulting in multiple invocations of bddbddb, and it is difficult to reset the state of bddbddb on each invocation.
This section describes properties specifying the names of files and directories output by Chord. Most users will not need to alter the default values of these properties.
chord.out.file
Type: location
Description: Absolute location of the file to which the standard output stream is redirected during Chord's execution.
Default value: null
chord.err.file
Type: location
Description: Absolute location of the file to which the standard error stream is redirected during Chord's execution.
Default value: null
chord.out.dir
Type: location
Description: Absolute location of the directory to which Chord dumps all files.
Default value: [chord.work.dir]/chord_output/
chord.reflect.file
Type: location
Description: Absolute location of the file from/to which resolved reflection information is read/written.
Default value: [chord.out.dir]/reflect.txt
chord.methods.file
Type: location
Description: Absolute location of the file from/to which list of methods deemed reachable is read/written.
Default value: [chord.out.dir]/methods.txt
chord.classes.file
Type: location
Description: Absolute location of the file from/to which list of classes deemed reachable is read/written.
Default value: [chord.out.dir]/classes.txt
chord.bddbddb.work.dir
Type: location
Description: Absolute location of the directory used by BDD-based Datalog solver bddbddb as its input/output directory (namely, for program domain files *.dom and *.map, and program relation files *.bdd).
Default value: [chord.out.dir]/bddbddb/
chord.boot.classes.dir
Type: location
Description: Absolute location of the directory from/to which instrumented classes of the input Java program inside the JDK standard library are read/written by dynamic analyses.
Default value: [chord.out.dir]/boot_classes/
chord.user.classes.dir
Type: location
Description: Absolute location of the directory from/to which instrumented classes of the input Java program outside the JDK standard library are read/written by dynamic analyses.
Default value: [chord.out.dir]/user_classes/
chord.instr.scheme.file
Type: location
Description: Absolute location of the file specifying the kind and format of events in trace files used by dynamic analyses.
Default value: [chord.out.dir]/scheme.ser
chord.trace.file
Type: location
Description: Absolute location of trace files used by dynamic analyses.
Default value: [chord.out.dir]/trace
Note: Suffix _full_verN.txt or _pipe_verN.txt is appended to the name of the file, depending upon whether it is a regular file or a POSIX pipe, respectively, where N is the version of the file (multiple versions are maintained if the trace is transformed by filters defined by the dynamic analysis; 0 is the final version). If chord.reuse.traces is set to true, then _full_verN_runM.txt is appended to the name of the file, where M is the run ID.
| | | Chord Properties |