CheckerMain

java.lang.Object
- org.checkerframework.framework.util.CheckerMain

Direct Known Subclasses:

CheckerDevelMain
```
public class CheckerMain
extends 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 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`
`protected static String`	`CHECKER_BASE_PACKAGE` All "built-in" Checker Framework checkers, except SubtypingChecker, start with this package file path.
`protected File`	`checkerJar` The path to the jar containing CheckerMain.class (i.e.
`protected File`	`checkerQualJar` The path to checker-qual.jar
`protected static String`	`FULLY_QUALIFIED_SUBTYPING_CHECKER`
`protected File`	`javacJar` The path to the jsr308 Langtools Type Annotations Compiler
`protected File`	`jdkJar` The path to the annotated jdk jar to use
`protected static Pattern`	`JVM_OPTS_REGEX` Matches all `-J` arguments
`protected static String`	`SUBTYPING_CHECKER_NAME`

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

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`protected void`	`addMainToArgs(List<String> args)`
`void`	`addToClasspath(List<String> cpOpts)`
`void`	`addToProcessorpath(List<String> ppOpts)`
`void`	`addToRuntimeBootclasspath(List<String> runtimeBootClasspathOpts)`
`protected void`	`assertValidState()`
`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)`
`protected List<String>`	`createCpOpts(List<String> argsList)`
`protected List<String>`	`createPpOpts(List<String> argsList)`
`protected List<String>`	`createRuntimeBootclasspath(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)` Remove the `-cp` and `-classpath` options and their arguments from args.
`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 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(String[] args)` Invoke the JSR 308 Type Annotations Compiler.
`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 processor, 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
  - jdkJar
```
protected final File jdkJar
```
    The path to the annotated jdk jar to use
  - javacJar
```
protected final File javacJar
```
    The path to the jsr308 Langtools Type Annotations Compiler
  - 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
  - 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_PACKAGE
```
protected static final 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 String CHECKER_BASE_DIR_NAME
```
  - FULLY_QUALIFIED_SUBTYPING_CHECKER
```
protected static final String FULLY_QUALIFIED_SUBTYPING_CHECKER
```
  - SUBTYPING_CHECKER_NAME
```
protected static final String SUBTYPING_CHECKER_NAME
```
- 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)
```
    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(List<String> cpOpts)
```
  - addToProcessorpath
```
public void addToProcessorpath(List<String> ppOpts)
```
  - addToRuntimeBootclasspath
```
public void addToRuntimeBootclasspath(List<String> runtimeBootClasspathOpts)
```
  - createRuntimeBootclasspath
```
protected List<String> createRuntimeBootclasspath(List<String> argsList)
```
  - createCompilationBootclasspath
```
protected List<String> createCompilationBootclasspath(List<String> argsList)
```
  - createCpOpts
```
protected List<String> createCpOpts(List<String> argsList)
```
  - createPpOpts
```
protected List<String> createPpOpts(List<String> argsList)
```
  - 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)
```
    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 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 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 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
  - 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 processor,
                                                     List<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"

Class CheckerMain

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

jdkJar

javacJar

checkerJar

checkerQualJar

BOOT_CLASS_PATH_REGEX

JVM_OPTS_REGEX

CHECKER_BASE_PACKAGE

CHECKER_BASE_DIR_NAME

FULLY_QUALIFIED_SUBTYPING_CHECKER

SUBTYPING_CHECKER_NAME

Constructor Detail

CheckerMain

Method Detail

main

assertValidState

addToClasspath

addToProcessorpath

addToRuntimeBootclasspath

createRuntimeBootclasspath

createCompilationBootclasspath

createCpOpts

createPpOpts

collectArgFiles

extractArg

extractFileArg

extractOptWithPattern

extractBootClassPath

extractJvmOpts

extractCpOpts

extractPpOpts

addMainToArgs

getExecArguments

invokeCompiler

expandArgFiles

findPathTo

matchesCheckerOrSubcheckerFromList

replaceShorthandProcessor

unshorthandProcessorNames

matchesFullyQualifiedProcessor