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, given either as a filesystem path or as a classpath resource name (e.g., an entry inside a JAR)
• 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. As with classFile, a sourceFile location may be either a filesystem path or a classpath resource name.

Location should give the appropriate filesystem path. However, for classFile and sourceFile entries, the location is first resolved as a classpath resource via the ClassLoader passed to AnalysisScopeReader.readJavaScope(), and only falls back to a filesystem path relative to the current working directory (FileProvider.getURLFromClassLoader) if no ClassLoader-resolved resource is found. This behavior means that a class or source file packaged inside a JAR on the analysis classpath can be named directly. For example, Application,Java,classFile,hello/Hello.class resolves even when hello/Hello.class exists only as an entry of some hello.jar on the analysis classpath rather than as a real file. Other entry types (binaryDir, sourceDir, jarFile, stdlib) still require actual filesystem locations. 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.