Package 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:
  • 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.

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 Details

    • 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:

    • 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:

    • 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:

    • 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:

  • Constructor Details

    • 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 Details

    • 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.

    • collectArgFiles

      protected List<File> collectArgFiles(List<String> args)
      Returns 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 @Nullable String extractArg(String argumentName, List<String> args)
      Remove the argument given by argumentName and the subsequent value from the list args if present. Return the subsequent value or null if not found.
      Parameters:
      argumentName - a command-line option name whose argument to extract
      args - the current list of arguments
      Returns:
      the string that follows argumentName if argumentName is in args, or null 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

    • 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)
      Returns 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 @Nullable String extractPpOpts(List<String> args)
      Remove all -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

    • getExecArguments

      public List<String> getExecArguments()
      Returns a list of arguments to pass to javac.
      Returns:
      a list of arguments to pass to javac

    • invokeCompiler

      public int invokeCompiler()
      Invoke the compiler with all relevant jars on its classpath and/or bootclasspath.
      Returns:
      error code

    • expandArgFiles

      protected static List<String> expandArgFiles(List<File> files)
      Returns 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(@Nullable 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<@FullyQualifiedName 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<@FullyQualifiedName 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; often just one processor
      fullyQualifiedCheckerNames - a list of fully-qualified checker names to match processorsString against
      allowSubcheckers - if true, 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<@FullyQualifiedName 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 - if true, match against fully qualified checker names ending with "Subchecker"
      Returns:
      true if the shorthand processor name can be expanded to a checker in fullyQualifiedCheckerNames