Averroes is Java bytecode generator that enables sound and precise analysis of the application part of a program without analyzing its library dependencies. It achieves that by generating a placeholder/stub library for those dependencies that models the original library code with respect to:
- class instantiations
- callbacks to application methods
- handled exceptions (caught or thrown)
- field and array accesses
Dependencies
The code bas for Averroes is in the form of an Eclipse project. It is setup with the following dependencies:
- Project dependencies (needs to be available in your Eclipse workspace)
- Library dependencies (ships with Averroes)
Build
Averroes uses Gradle as its build system. To build a fat JAR that includes all the dependencies, you need to run ./gradlew fatJar. This command will generate averroes-all-<version>.jar in build/libs, which you can use to run Averroes. If you'd rather generate a JAR file for Averroes itself, simply use ./gradlew jar.
Usage
jar -jar averroes.jar <required parameters> [optional parameters]
where required parameters include:
-a,--application-jars <path> A list of the application JAR
files separated by path separator.
-j,--java-runtime-directory <directory> The directory that contains the
Java runtime environment that
Averroes should model.
-m,--main-class <class> The main class that runs the
application when the program
executes.
-o,--output-directory <directory> The directory to which Averroes
will write any output files/folders.
-r,--application-regex <regex> A list of regular expressions
for application packages or classes
separated by path separator. Use
<package_name>.* to include classes
in a package, <package_name>.** to
include classes in a package and all
its subpackages, ** to include the
default package, <full_class_name> to
include a single class.
and optional parameters include:
-d,--dynamic-classes-file <file> A file that contains a list of
classes that are loaded
dynamically by Averroes (e.g.,
classes instantiated through
reflection).
-h,--help Prints out this help message.
-l,--library-jars <path> A list of the JAR files for
library dependencies separated
by path separator.
-t,--tamiflex-facts-file <file> A file that contains reflection
facts generated for this application
in the TamiFlex format.
Output
After running averroes on some input program, the output directory directory should contain the following:
- averroes-lib-class.jar: the main
averroeslibrary class for the input program. - placeholder-lib.jar: the stubs
averroesgenerates for the library classes of the given input program. - organized-app.jar: the original application code of the input program as is (i.e., not altered by
averroesin any way). - organized-lib.jar: the original library code of the input program as is (i.e., not altered by
averroesin any way). - classes: a directory that contains the class files that
averroesgenerates.
The JAR files averroes-lib-class.jar and placeholder-lib.jar together form the placeholder library generated by averroes. So for example, if you would like to generate the call graph for a that input program using averroes, you need to supply a whole-program analysis tool (e.g., Soot) with 2 JAR files as the library: averroes-lib-class.jar and placeholder-lib.jar, and JAR file as the application: organized-app.jar.
License
Averroes is available as Open Source under the Eclipse Public License.