Analysis Scope

An AnalysisScope specifies the application and library code to be analyzed. AnalysisScopeReader.makeJavaBinaryAnalysisScope() constructs an AnalysisScope given a Java classpath String and an exclusions file (discussed further below). For more control, use the AnalysisScopeReader.readJavaScope() method, whose first parameter is the name of a text scope file specifying the analysis scope. A scope file has lines of the following format:

Classloader,Language,Type,Location

For Java, Classloader is one of Primordial, Extension, or Application (see Naming Java Entities). Primordial is reserved for the Java standard libraries. If you want to analyze the same standard library as the JVM WALA runs on for analysis, the following two lines for Primordial should do the right thing:

Primordial,Java,stdlib,none
Primordial,Java,jarFile,primordial.jar.model

The above lines will include all modules from the running VM's standard library. To include only the java.base module, use the base option for stdlib as follows:

Primordial,Java,stdlib,base
Primordial,Java,jarFile,primordial.jar.model

If you would like to add modules beyond java.base you can add jdkModule lines with the module names, e.g.:

Primordial,Java,stdlib,base
Primordial,Java,jdkModule,java.desktop
Primordial,Java,jarFile,primordial.jar.model

NOTE: for WALA to analyze the running VM's standard library, you must be using a JDK that provides .jmod files. Of note, recent Eclipse Temurin JDKs do not provide these files; see this issue. We recommend using another OpenJDK build instead, like from Zulu.

If you would like to analyze some other version of the Java standard library (not from the running JVM), instead of the Primordial,Java,stdlib,none line, add lines of the form Primordial,Java,stdlib,/path/to/lib.jar for each standard library jar or jmod file you would like to analyze (e.g., an rt.jar file). Retain the Primordial,Java,jarFile,primordial.jar.model line so that appropriate library models are used.

Extension entries should be used for other libraries used by the application, while Application entries should be used for the application code itself. Some valid values of Type are:

• classFile for a single .class file
• binaryDir for a directory containing class files (with the standard package-to-sub-directory correspondence)
• jarFile for a .jar file
• sourceFile and sourceDir for source files. This is for use with a Java source front end, or to provide source file locations for class files in the scope. For the latter use case, make sure the class files / directories appear in the scope file before the corresponding sourceFile or sourceDir.

Location should give the appropriate filesystem path. Here's a full example:

Primordial,Java,stdlib,none
Primordial,Java,jarFile,primordial.jar.model
Extension,Java,jarFile,/workspace/myapp/lib/someLib.jar
Application,Java,binaryDir,/workspace/myApp/bin

As an alternative to scope files, there are APIs in the AnalysisScope class to programmatically build up a scope with different types of entries (see the add*ToScope methods).

Exclusions files

An exclusions file is a text file giving patterns of class names that should be excluded from an AnalysisScope. Using an exclusions file can help with the scalability of analyses like call graph construction, in the case where certain classes are present but known to be irrelevant (or likely irrelevant) to the analysis. Note that excluding relevant classes could be a source of analysis unsoundness.

Each line in an exclusions file excludes classes in a package or set of packages, e.g.:

java\/awt\/.*
javax\/swing\/.*
sun\/awt\/.*

A full example is here.