org.checkerframework.framework.util

Class CheckerMain

java.lang.Object

org.checkerframework.framework.util.CheckerMain

public class CheckerMain
extends Object

This class behaves similarly to javac. CheckerMain does the following:

• add the javac.jar to the runtime classpath of the process that runs the Checker Framework.
• parse and implement any special options used by the Checker Framework, e.g., using "shortnames" for annotation processors
• pass all remaining command-line arguments to the real javac

To debug this class, use the -AoutputArgsToFile=FILENAME command-line argument or -AoutputArgsToFile=- to output to standard out.

"To run the Checker Framework" really means to run java, where the program being run is javac and javac is passed a -processor command-line argument that mentions a Checker Framework checker. There are 5 relevant classpaths: The classpath and bootclasspath when running java, and the classpath, bootclasspath, and processorpath used by javac. The latter three are the only important ones.

Note for developers: Try to limit the work done (and options interpreted) by CheckerMain, because its functionality is not available to users who choose not to use the Checker Framework javac script.

Field Summary

Fields

Modifier and Type	Field and Description
protected static Pattern	BOOT_CLASS_PATH_REGEX A pattern to match bootclasspath prepend entries, used to construct one -Xbootclasspath/p: command-line argument.
protected static String	CHECKER_BASE_DIR_NAME Processor shorthand is enabled for processors in this directory in checker.jar.
static String	CHECKER_QUAL_PATH_OPT Option name for specifying an alternative checker-qual.jar location.
static String	CHECKER_UTIL_PATH_OPT Option name for specifying an alternative checker-util.jar location.
protected File	checkerJar The path to the jar containing CheckerMain.class (i.e.
protected File	checkerQualJar The path to checker-qual.jar.
protected File	checkerUtilJar The path to checker-util.jar.
protected static String	COMMON_BASE_DIR_NAME Processor shorthand is enabled for processors in this directory in checker.jar.
static String	JAVAC_PATH_OPT Option name for specifying an alternative javac.jar location.
protected File	javacJar The path to the javacJar to use.
static String	JDK_PATH_OPT Option name for specifying an alternative jdk.jar location.
protected static Pattern	JVM_OPTS_REGEX Matches all -J arguments.

Constructor Summary

Constructors

Constructor and Description
CheckerMain(File checkerJar, List<String> args) Construct all the relevant file locations and Java version given the path to this jar and a set of directories in which to search for jars.

Method Summary

Modifier and Type	Method and Description
protected void	addMainToArgs(List<String> args)
void	addToClasspath(List<String> cpOpts)
void	addToProcessorpath(List<String> ppOpts)
void	addToRuntimeClasspath(List<String> runtimeClasspathOpts)
protected void	assertValidState() Assert that required jars exist.
protected List<File>	collectArgFiles(List<String> args) Return the arguments that start with @ and therefore are files that contain javac arguments.
protected List<String>	createCompilationBootclasspath(List<String> argsList) Returns the compilation bootclasspath from argsList.
protected List<String>	createCpOpts(List<String> argsList)
protected List<String>	createPpOpts(List<String> argsList) Returns processor path options.
protected List<String>	createRuntimeClasspath(List<String> argsList)
protected static List<String>	expandArgFiles(List<File> files) Return all the lines in all the files.
protected static String	extractArg(String argumentName, String alternative, List<String> args) Remove the argument given by argumentName and the subsequent value from the list args if present.
protected static List<String>	extractBootClassPath(List<String> args) Remove all -Xbootclasspath/p: or -J-Xbootclasspath/p: arguments from args and add them to the returned list.
protected static List<String>	extractCpOpts(List<String> args) Return the last -cp or -classpath option.
protected static File	extractFileArg(String argumentName, File alternative, List<String> args) Remove the argument given by argumentName and the subsequent value from the list args if present.
protected static List<String>	extractJvmOpts(List<String> args) Remove all -J arguments from args and add them to the returned list (without the -J prefix).
protected static List<String>	extractOptWithPattern(Pattern pattern, boolean allowEmpties, List<String> args) Find all args that match the given pattern and extract their index 1 group.
protected static List<String>	extractPpOpts(List<String> args) Remove the -processorpath options and their arguments from args.
static String	findPathTo(Class<?> cls, boolean errIfFromDirectory) Find the jar file or directory containing the .class file from which cls was loaded.
List<String>	getExecArguments() Invoke the compiler with all relevant jars on its classpath and/or bootclasspath.
int	invokeCompiler() Invoke the compiler with all relevant jars on its classpath and/or bootclasspath.
static void	main(String[] args) Any exception thrown by the Checker Framework escapes to the command line.
static boolean	matchesCheckerOrSubcheckerFromList(String processorString, List<String> fullyQualifiedCheckerNames) Returns true if processorString, once transformed into fully-qualified form, is present in fullyQualifiedCheckerNames.
static boolean	matchesFullyQualifiedProcessor(String processorName, List<String> fullyQualifiedCheckerNames, boolean allowSubcheckers) Given a shorthand processor name, returns true if it can be expanded to a checker in the fullyQualifiedCheckerNames list.
protected void	replaceShorthandProcessor(List<String> args) For every "-processor" argument in args, replace its immediate successor argument using unabbreviateProcessorNames.
protected static String	unshorthandProcessorNames(String processorsString, List<String> fullyQualifiedCheckerNames, boolean allowSubcheckers) Takes a string of comma-separated processor names, and expands any shorthands to fully-qualified names from the fullyQualifiedCheckerNames list.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

javacJar

protected final File javacJar

The path to the javacJar to use.

checkerJar

protected final File checkerJar

The path to the jar containing CheckerMain.class (i.e. checker.jar).

checkerQualJar

protected final File checkerQualJar

The path to checker-qual.jar.

checkerUtilJar

protected final File checkerUtilJar

The path to checker-util.jar.

CHECKER_QUAL_PATH_OPT

public static final String CHECKER_QUAL_PATH_OPT

Option name for specifying an alternative checker-qual.jar location. The accompanying value MUST be the path to the jar file (NOT the path to its encompassing directory)

See Also:

Constant Field Values

CHECKER_UTIL_PATH_OPT

public static final String CHECKER_UTIL_PATH_OPT

Option name for specifying an alternative checker-util.jar location. The accompanying value MUST be the path to the jar file (NOT the path to its encompassing directory)

See Also:

Constant Field Values

JAVAC_PATH_OPT

public static final String JAVAC_PATH_OPT

Option name for specifying an alternative javac.jar location. The accompanying value MUST be the path to the jar file (NOT the path to its encompassing directory)

See Also:

Constant Field Values

JDK_PATH_OPT

public static final String JDK_PATH_OPT

Option name for specifying an alternative jdk.jar location. The accompanying value MUST be the path to the jar file (NOT the path to its encompassing directory)

See Also:

Constant Field Values

BOOT_CLASS_PATH_REGEX

protected static final Pattern BOOT_CLASS_PATH_REGEX

A pattern to match bootclasspath prepend entries, used to construct one -Xbootclasspath/p: command-line argument.

JVM_OPTS_REGEX

protected static final Pattern JVM_OPTS_REGEX

Matches all -J arguments.

CHECKER_BASE_DIR_NAME

protected static final String CHECKER_BASE_DIR_NAME

Processor shorthand is enabled for processors in this directory in checker.jar.

See Also:

Constant Field Values

COMMON_BASE_DIR_NAME

protected static final String COMMON_BASE_DIR_NAME

Processor shorthand is enabled for processors in this directory in checker.jar.

See Also:

Constant Field Values

Constructor Detail

CheckerMain

public CheckerMain(File checkerJar,
                   List<String> args)

Construct all the relevant file locations and Java version given the path to this jar and a set of directories in which to search for jars.

Method Detail

main

public static void main(String[] args)

Any exception thrown by the Checker Framework escapes to the command line.

Parameters:

args - command-line arguments

assertValidState

protected void assertValidState()

Assert that required jars exist.

addToClasspath

public void addToClasspath(List<String> cpOpts)

addToProcessorpath

public void addToProcessorpath(List<String> ppOpts)

addToRuntimeClasspath

public void addToRuntimeClasspath(List<String> runtimeClasspathOpts)

createRuntimeClasspath

protected List<String> createRuntimeClasspath(List<String> argsList)

createCompilationBootclasspath

protected List<String> createCompilationBootclasspath(List<String> argsList)

Returns the compilation bootclasspath from argsList.

Parameters:

argsList - args to add

Returns:

the compilation bootclasspath from argsList

createCpOpts

protected List<String> createCpOpts(List<String> argsList)

createPpOpts

protected List<String> createPpOpts(List<String> argsList)

Returns processor path options.

This method assumes that createCpOpts has already been run.

Parameters:

argsList - arguments

Returns:

processor path options

collectArgFiles

protected List<File> collectArgFiles(List<String> args)

Return the arguments that start with @ and therefore are files that contain javac arguments.

Parameters:

args - a list of command-line arguments; is not modified

Returns:

a List of files representing all arguments that started with @

extractArg

protected static String extractArg(String argumentName,
                                   String alternative,
                                   List<String> args)

Remove the argument given by argumentName and the subsequent value from the list args if present. Return the subsequent value.

Parameters:

argumentName - a command-line option name whose argument to extract

alternative - default value to return if argumentName does not appear in args

args - the current list of arguments

Returns:

the string that follows argumentName if argumentName is in args, or alternative if argumentName is not present in args

extractFileArg

protected static File extractFileArg(String argumentName,
                                     File alternative,
                                     List<String> args)

Remove the argument given by argumentName and the subsequent value from the list args if present. Return the subsequent value wrapped as a File.

Parameters:

argumentName - argument to extract

alternative - file to return if argumentName is not found in args

args - the current list of arguments

Returns:

the string that follows argumentName wrapped as a File if argumentName is in args or alternative if argumentName is not present in args

extractOptWithPattern

protected static List<String> extractOptWithPattern(Pattern pattern,
                                                    boolean allowEmpties,
                                                    List<String> args)

Find all args that match the given pattern and extract their index 1 group. Add all the index 1 groups to the returned list. Remove all matching args from the input args list.

Parameters:

pattern - a pattern with at least one matching group

allowEmpties - whether or not to add empty group(1) matches to the returned list

args - the arguments to extract from

Returns:

a list of arguments from the first group that matched the pattern for each input args or the empty list if there were none

extractBootClassPath

protected static List<String> extractBootClassPath(List<String> args)

Remove all -Xbootclasspath/p: or -J-Xbootclasspath/p: arguments from args and add them to the returned list.

Parameters:

args - the arguments to extract from

Returns:

all non-empty arguments matching BOOT_CLASS_PATH_REGEX or an empty list if there were none

extractJvmOpts

protected static List<String> extractJvmOpts(List<String> args)

Remove all -J arguments from args and add them to the returned list (without the -J prefix).

Parameters:

args - the arguments to extract from

Returns:

all -J arguments (without the -J prefix) or an empty list if there were none

extractCpOpts

protected static List<String> extractCpOpts(List<String> args)

Return the last -cp or -classpath option. If no -cp or -classpath arguments were present, then return the CLASSPATH environment variable (if set) followed by the current directory.

Also removes all -cp and -classpath options from args.

Parameters:

args - a list of arguments to extract from; is side-effected by this

Returns:

collection of classpaths to concatenate to use when calling javac.jar

extractPpOpts

protected static List<String> extractPpOpts(List<String> args)

Remove the -processorpath options and their arguments from args. Return the last argument.

Parameters:

args - a list of arguments to extract from

Returns:

the arguments that should be put on the processorpath when calling javac.jar

addMainToArgs

protected void addMainToArgs(List<String> args)

getExecArguments

public List<String> getExecArguments()

Invoke the compiler with all relevant jars on its classpath and/or bootclasspath.

invokeCompiler

public int invokeCompiler()

Invoke the compiler with all relevant jars on its classpath and/or bootclasspath.

expandArgFiles

protected static List<String> expandArgFiles(List<File> files)

Return all the lines in all the files.

Parameters:

files - a list of files

Returns:

a list of all the lines in all the files

findPathTo

public static String findPathTo(Class<?> cls,
                                boolean errIfFromDirectory)
                         throws IllegalStateException

Find the jar file or directory containing the .class file from which cls was loaded.

Parameters:

cls - the class whose .class file we wish to locate; if null, CheckerMain.class

errIfFromDirectory - if false, throw an exception if the file was loaded from a directory

Throws:

IllegalStateException

matchesCheckerOrSubcheckerFromList

public static boolean matchesCheckerOrSubcheckerFromList(String processorString,
                                                         List<String> fullyQualifiedCheckerNames)

Returns true if processorString, once transformed into fully-qualified form, is present in fullyQualifiedCheckerNames. Used by SourceChecker to determine whether a class is annotated for any processor that is being run.

Parameters:

processorString - the name of a single processor, not a comma-separated list of processors

fullyQualifiedCheckerNames - a list of fully-qualified checker names

Returns:

true if the fully-qualified version of processorString is in fullyQualifiedCheckerNames

replaceShorthandProcessor

protected void replaceShorthandProcessor(List<String> args)

For every "-processor" argument in args, replace its immediate successor argument using unabbreviateProcessorNames.

unshorthandProcessorNames

protected static String unshorthandProcessorNames(String processorsString,
                                                  List<String> fullyQualifiedCheckerNames,
                                                  boolean allowSubcheckers)

Takes a string of comma-separated processor names, and expands any shorthands to fully-qualified names from the fullyQualifiedCheckerNames list. For example:

 NullnessChecker → org.checkerframework.checker.nullness.NullnessChecker
 nullness → org.checkerframework.checker.nullness.NullnessChecker
 NullnessChecker,RegexChecker → org.checkerframework.checker.nullness.NullnessChecker,org.checkerframework.checker.regex.RegexChecker
 

Note, a processor entry only gets replaced if it contains NO "." (i.e., it is not qualified by a package name) and can be found under the package org.checkerframework.checker in checker.jar.

Parameters:

processorsString - a comma-separated string identifying processors

fullyQualifiedCheckerNames - a list of fully-qualified checker names to match processorsString against

allowSubcheckers - whether to match against fully qualified checker names ending with "Subchecker"

Returns:

processorsString where all shorthand references to Checker Framework built-in checkers are replaced with fully-qualified references

matchesFullyQualifiedProcessor

public static boolean matchesFullyQualifiedProcessor(String processorName,
                                                     List<String> fullyQualifiedCheckerNames,
                                                     boolean allowSubcheckers)

Given a shorthand processor name, returns true if it can be expanded to a checker in the fullyQualifiedCheckerNames list.

Parameters:

processorName - a string identifying one processor

fullyQualifiedCheckerNames - a list of fully-qualified checker names to match processorName against

allowSubcheckers - whether to match against fully qualified checker names ending with "Subchecker"

Returns:

true if the shorthand processor name can be expanded to a checker in fullyQualifiedCheckerNames