org.checkerframework.framework.util

Class CheckerMain

java.lang.Object

org.checkerframework.framework.util.CheckerMain

Direct Known Subclasses:

CheckerDevelMain

public class CheckerMain
extends java.lang.Object

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

• add the jsr308-langtools javac.jar to the runtime bootclasspath of the process that runs the Checker Framework. This specifies which classes are used to run javac
• add jdk7.jar or jdk8.jar to the compile time bootclasspath of the javac argument list passed to javac
• 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 a special version of 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 java.util.regex.Pattern	BOOT_CLASS_PATH_REGEX A pattern to match bootclasspath prepend entries, used to construct one -Xbootclasspath/p: command-line argument
protected static java.lang.String	CHECKER_BASE_DIR_NAME
protected static java.lang.String	CHECKER_BASE_PACKAGE All "built-in" Checker Framework checkers, except SubtypingChecker, start with this package file path.
protected java.io.File	checkerJar The path to the jar containing CheckerMain.class (i.e.
protected java.io.File	checkerQualJar The path to checker-qual.jar
protected static java.lang.String	FULLY_QUALIFIED_SUBTYPING_CHECKER
protected java.io.File	javacJar The path to the jsr308 Langtools Type Annotations Compiler
protected java.io.File	jdkJar The path to the annotated jdk jar to use
protected static java.util.regex.Pattern	JVM_OPTS_REGEX Matches all -J arguments
protected static java.lang.String	SUBTYPING_CHECKER_NAME

Constructor Summary

Constructors

Constructor and Description
CheckerMain(java.io.File checkerJar, java.util.List<java.lang.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(java.util.List<java.lang.String> args)
void	addToClasspath(java.util.List<java.lang.String> cpOpts)
void	addToProcessorpath(java.util.List<java.lang.String> ppOpts)
void	addToRuntimeClasspath(java.util.List<java.lang.String> runtimeClasspathOpts)
protected void	assertValidState()
protected java.util.List<java.io.File>	collectArgFiles(java.util.List<java.lang.String> args) Return the arguments that start with @ and therefore are files that contain javac arguments.
protected java.util.List<java.lang.String>	createCompilationBootclasspath(java.util.List<java.lang.String> argsList)
protected java.util.List<java.lang.String>	createCpOpts(java.util.List<java.lang.String> argsList)
protected java.util.List<java.lang.String>	createPpOpts(java.util.List<java.lang.String> argsList)
protected java.util.List<java.lang.String>	createRuntimeClasspath(java.util.List<java.lang.String> argsList)
protected static java.util.List<java.lang.String>	expandArgFiles(java.util.List<java.io.File> files) Return all the lines in all the files.
protected static java.lang.String	extractArg(java.lang.String argumentName, java.lang.String alternative, java.util.List<java.lang.String> args) Remove the argument given by argumentName and the subsequent value from the list args if present.
protected static java.util.List<java.lang.String>	extractBootClassPath(java.util.List<java.lang.String> args) Remove all -Xbootclasspath/p: or -J-Xbootclasspath/p: arguments from args and add them to the returned list.
protected static java.util.List<java.lang.String>	extractCpOpts(java.util.List<java.lang.String> args) Remove the -cp and -classpath options and their arguments from args.
protected static java.io.File	extractFileArg(java.lang.String argumentName, java.io.File alternative, java.util.List<java.lang.String> args) Remove the argument given by argumentName and the subsequent value from the list args if present.
protected static java.util.List<java.lang.String>	extractJvmOpts(java.util.List<java.lang.String> args) Remove all -J arguments from args and add them to the returned list (without the -J prefix)
protected static java.util.List<java.lang.String>	extractOptWithPattern(java.util.regex.Pattern pattern, boolean allowEmpties, java.util.List<java.lang.String> args) Find all args that match the given pattern and extract their index 1 group.
protected static java.util.List<java.lang.String>	extractPpOpts(java.util.List<java.lang.String> args) Remove the -processorpath options and their arguments from args.
static java.lang.String	findPathTo(java.lang.Class<?> cls, boolean errIfFromDirectory) Find the jar file or directory containing the .class file from which cls was loaded
java.util.List<java.lang.String>	getExecArguments() Invoke the JSR308 Type Annotations Compiler with all relevant jars on its classpath or boot classpath
int	invokeCompiler() Invoke the JSR308 Type Annotations Compiler with all relevant jars on its classpath or boot classpath
static void	main(java.lang.String[] args) Invoke the JSR 308 Type Annotations Compiler.
static boolean	matchesCheckerOrSubcheckerFromList(java.lang.String processorString, java.util.List<java.lang.String> fullyQualifiedCheckerNames) Returns true if processorString, once transformed into fully-qualified form, is present in fullyQualifiedCheckerNames.
static boolean	matchesFullyQualifiedProcessor(java.lang.String processor, java.util.List<java.lang.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(java.util.List<java.lang.String> args) For every "-processor" argument in args, replace its immediate successor argument using unabbreviateProcessorNames
protected static java.lang.String	unshorthandProcessorNames(java.lang.String processorsString, java.util.List<java.lang.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

jdkJar

protected final java.io.File jdkJar

The path to the annotated jdk jar to use

javacJar

protected final java.io.File javacJar

The path to the jsr308 Langtools Type Annotations Compiler

checkerJar

protected final java.io.File checkerJar

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

checkerQualJar

protected final java.io.File checkerQualJar

The path to checker-qual.jar

BOOT_CLASS_PATH_REGEX

protected static final java.util.regex.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 java.util.regex.Pattern JVM_OPTS_REGEX

Matches all -J arguments

CHECKER_BASE_PACKAGE

protected static final java.lang.String CHECKER_BASE_PACKAGE

All "built-in" Checker Framework checkers, except SubtypingChecker, start with this package file path. Framework Checkers, except for SubtypingChecker, are excluded from processor shorthand.

See Also:

Constant Field Values

CHECKER_BASE_DIR_NAME

protected static final java.lang.String CHECKER_BASE_DIR_NAME

FULLY_QUALIFIED_SUBTYPING_CHECKER

protected static final java.lang.String FULLY_QUALIFIED_SUBTYPING_CHECKER

SUBTYPING_CHECKER_NAME

protected static final java.lang.String SUBTYPING_CHECKER_NAME

Constructor Detail

CheckerMain

public CheckerMain(java.io.File checkerJar,
                   java.util.List<java.lang.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(java.lang.String[] args)

Invoke the JSR 308 Type Annotations Compiler. Any exception thrown by the Checker Framework escapes to the command line.

assertValidState

protected void assertValidState()

addToClasspath

public void addToClasspath(java.util.List<java.lang.String> cpOpts)

addToProcessorpath

public void addToProcessorpath(java.util.List<java.lang.String> ppOpts)

addToRuntimeClasspath

public void addToRuntimeClasspath(java.util.List<java.lang.String> runtimeClasspathOpts)

createRuntimeClasspath

protected java.util.List<java.lang.String> createRuntimeClasspath(java.util.List<java.lang.String> argsList)

createCompilationBootclasspath

protected java.util.List<java.lang.String> createCompilationBootclasspath(java.util.List<java.lang.String> argsList)

createCpOpts

protected java.util.List<java.lang.String> createCpOpts(java.util.List<java.lang.String> argsList)

createPpOpts

protected java.util.List<java.lang.String> createPpOpts(java.util.List<java.lang.String> argsList)

collectArgFiles

protected java.util.List<java.io.File> collectArgFiles(java.util.List<java.lang.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 java.lang.String extractArg(java.lang.String argumentName,
                                             java.lang.String alternative,
                                             java.util.List<java.lang.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 java.io.File extractFileArg(java.lang.String argumentName,
                                             java.io.File alternative,
                                             java.util.List<java.lang.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 java.util.List<java.lang.String> extractOptWithPattern(java.util.regex.Pattern pattern,
                                                                        boolean allowEmpties,
                                                                        java.util.List<java.lang.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 java.util.List<java.lang.String> extractBootClassPath(java.util.List<java.lang.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 java.util.List<java.lang.String> extractJvmOpts(java.util.List<java.lang.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 java.util.List<java.lang.String> extractCpOpts(java.util.List<java.lang.String> args)

Remove the -cp and -classpath options and their arguments from args. Return the last argument. If no -cp or -classpath arguments were present then return the CLASSPATH environment variable followed by the current directory.

Parameters:

args - a list of arguments to extract from

Returns:

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

extractPpOpts

protected static java.util.List<java.lang.String> extractPpOpts(java.util.List<java.lang.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(java.util.List<java.lang.String> args)

getExecArguments

public java.util.List<java.lang.String> getExecArguments()

Invoke the JSR308 Type Annotations Compiler with all relevant jars on its classpath or boot classpath

invokeCompiler

public int invokeCompiler()

Invoke the JSR308 Type Annotations Compiler with all relevant jars on its classpath or boot classpath

expandArgFiles

protected static java.util.List<java.lang.String> expandArgFiles(java.util.List<java.io.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 java.lang.String findPathTo(java.lang.Class<?> cls,
                                          boolean errIfFromDirectory)
                                   throws java.lang.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:

java.lang.IllegalStateException

matchesCheckerOrSubcheckerFromList

public static boolean matchesCheckerOrSubcheckerFromList(java.lang.String processorString,
                                                         java.util.List<java.lang.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

replaceShorthandProcessor

protected void replaceShorthandProcessor(java.util.List<java.lang.String> args)

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

unshorthandProcessorNames

protected static java.lang.String unshorthandProcessorNames(java.lang.String processorsString,
                                                            java.util.List<java.lang.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(java.lang.String processor,
                                                     java.util.List<java.lang.String> fullyQualifiedCheckerNames,
                                                     boolean allowSubcheckers)

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

Parameters:

processor - a string identifying one processor

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

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