CheckerMain (checker-framework 3.20.0 API)

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

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`	`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

Class CheckerMain

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

javacJar

checkerJar

checkerQualJar

checkerUtilJar

CHECKER_QUAL_PATH_OPT

CHECKER_UTIL_PATH_OPT

JAVAC_PATH_OPT

JDK_PATH_OPT

BOOT_CLASS_PATH_REGEX

JVM_OPTS_REGEX

CHECKER_BASE_DIR_NAME

COMMON_BASE_DIR_NAME

Constructor Detail

CheckerMain

Method Detail

main

assertValidState

addToClasspath

addToProcessorpath

addToRuntimeClasspath

createRuntimeClasspath

createCompilationBootclasspath

createCpOpts

createPpOpts

collectArgFiles

extractArg

extractFileArg

extractOptWithPattern

extractBootClassPath

extractJvmOpts

extractCpOpts

extractPpOpts

addMainToArgs

getExecArguments

invokeCompiler

expandArgFiles

findPathTo

matchesCheckerOrSubcheckerFromList

replaceShorthandProcessor

unshorthandProcessorNames

matchesFullyQualifiedProcessor