| | | Getting Started |
This chapter describes how to download, install, and run Chord. Section * describes how to obtain pre-built binaries of Chord. Section * describes how to obtain the source code of Chord and Section * explains how to build it. Finally, Section * describes how to run Chord.
To obtain Chord's pre-built binaries, download and uncompress file chord-bin-2.0.tar.gz. It includes the following files:
Novice users can ignore items (2) and (3) until they become more familiar with Chord. The binaries mentioned in items (2) and (3) might not be compatible with your machine, in which case you can either forgo using them (with hardly any noticeable difference in functionality), or you can download the sources (see Section *) and build them yourself (see Section *).
To obtain Chord's source code, download and uncompress the following files:
Alternatively, you can obtain the latest development snapshot from the SVN repository by running the following command:
svn checkout http://jchord.googlecode.com/svn/trunk/ chord |
Instead of checking out the entire trunk/, which contains several sub-directories, you can check out specific sub-directories:
Files chord-2.0-src.tar.gz and chord-2.0-libsrc.tar.gz mentioned above are essentially stable releases of the main/ and libsrc/ directories, respectively.
Compiling Chord's source code requires the following software:
Chord's main directory contains a file named build.xml which is interpreted by Apache Ant. To see the various possible targets, simply run command "ant" in that directory.
To compile Chord, run command "ant compile" in the same directory. This will compile Chord's Java sources from src/ to class files in classes/, as well as build a jar file chord.jar that contains these class files as well as those in the jars of libraries that are used by Chord and are provided under lib/ (e.g., joeq.jar, javassist.jar, bddbddb.jar, etc.). Additionally:
If system property chord.use.buddy is set to true, then the C source code of BDD library BuDDy from directory bdd/ will be compiled to a shared library named (libbuddy.so on Linux, buddy.dll on Windows, and libbuddy.dylib on MacOS; this library is used by BDD-based Datalog solver bddbddb in Chord for running analyses written in Datalog.
If system property chord.use.jvmti is set to true, then the C++ source code of the JVMTI-based bytecode instrumentation agent from directory agent/ will be compiled to a shared library named libchord_instr_agent.so on all architectures; this agent is used in Chord for computing analysis scope dynamically and for running dynamic analyses.
Properties chord.use.buddy and chord.use.jvmti are defined in a file named chord.properties in Chord's main directory. The default value of both these properties is false. If you set either of them to true, then you will also need a utility like GNU Make (to run the Makefile's in directories bdd/ and agent/) and a C++ compiler (to build the above shared libraries).
Running Chord requires a JVM supporting Java 5 or higher. There are two equivalent commands to run Chord.
One command, which is available in the source and binary installations of Chord, is:
java -cp <CHORD_MAIN_DIR>/chord.jar -D<key1>=<val1> ... -D<keyN>=<valN> chord.project.Boot |
where <CHORD_MAIN_DIR> denotes the directory containing file chord.jar; that directory is also expected to contain any shared libraries in Chord's installation (e.g., libbuddy.so and libchord_instr_agent.so).
The alternate command, which is available only in the source installation of Chord, is:
ant -f <CHORD_MAIN_DIR>/build.xml -D<key1>=<val1> ... -D<keyN>=<valN> run |
This command requires Apache Ant (a Java build tool) to be installed on your machine. This command is used throughout this guide. Also, the "-f <CHORD_MAIN_DIR>/build.xml" argument in the command is omitted for brevity.
Each "-D<key>=<val>" argument in either of the above commands sets the system property named <key> to the value denoted by <val>. The only way to specify inputs to Chord is via system properties; there is no command-line argument processing. Chapter * describes all system properties recognized by Chord.
| | | Getting Started |