Mercurial > jdk8-mips64-public > langtools / annotate
test/tools/javac/diags/README.examples.txt@7873d37f5b37 (annotated)
test/tools/javac/diags/README.examples.txt
Mon, 21 Jan 2013 20:13:56 +0000
- author
- mcimadamore
- date
- Mon, 21 Jan 2013 20:13:56 +0000
- changeset 1510
- 7873d37f5b37
- parent 0
- 959103a6100f
- permissions
- -rw-r--r--
8005244: Implement overload resolution as per latest spec EDR
Summary: Add support for stuck expressions and provisional applicability
Reviewed-by: jjg
| aoqi@0 | 1 | Diagnostics Examples. |
| aoqi@0 | 2 | |
| aoqi@0 | 3 | The "examples/ directory contains a collection of examples of Java code, each of |
| aoqi@0 | 4 | which is designed to illustrate one or more diagnostics that can be generated by |
| aoqi@0 | 5 | the JDK Java compiler, javac. These examples are represented by files or |
| aoqi@0 | 6 | directories of files, each of which is designed to illustrate a specific |
| aoqi@0 | 7 | diagnostic. Sometimes it is unavoidable that creating one issue will lead to |
| aoqi@0 | 8 | downstream issues: this is especially true for lex errors, where the error |
| aoqi@0 | 9 | recovery is fragile at best. Each example declares the diagnostics that it is |
| aoqi@0 | 10 | expected to generate -- this allows the examples to be verified and facilitates |
| aoqi@0 | 11 | searching for examples for specific messages. |
| aoqi@0 | 12 | |
| aoqi@0 | 13 | Normally, tests for javac errors avoid checking the actual error messages that |
| aoqi@0 | 14 | get generated. Older tests simply verify that one or more warnings or errors |
| aoqi@0 | 15 | are generated; more recent tests verify that specific messages are generated, |
| aoqi@0 | 16 | but these tests typically avoid checking the localized text by using the |
| aoqi@0 | 17 | -XDrawDiagnostics mechanism. In addition, the focus of such tests is often on |
| aoqi@0 | 18 | completeness instead of simplicity. |
| aoqi@0 | 19 | |
| aoqi@0 | 20 | By contrast, the intent of these examples is to provide simple and easy to |
| aoqi@0 | 21 | understand examples of the situations in which a diagnostic can arise, and the |
| aoqi@0 | 22 | messages that may be displayed. This will aid in reviewing the output generated |
| aoqi@0 | 23 | by javac and in localizing the resource bundle to other locales. In addition, |
| aoqi@0 | 24 | the examples include simple meta-information so that the collection as a whole |
| aoqi@0 | 25 | can be audited for coverage, thus encouraging new examples to be added when new |
| aoqi@0 | 26 | diagnostics are added to javac. |
| aoqi@0 | 27 | |
| aoqi@0 | 28 | There are two utilities for processing these examples. |
| aoqi@0 | 29 | |
| aoqi@0 | 30 | The first utility is "CheckExamples" which checks various conditions for the |
| aoqi@0 | 31 | examples: |
| aoqi@0 | 32 | -- each example must generate exactly the set of keys that it is declared to |
| aoqi@0 | 33 | generate |
| aoqi@0 | 34 | -- together, the examples must generate all the resource keys coming from javac |
| aoqi@0 | 35 | (except for resource keys that are registered in a "not yet" list) |
| aoqi@0 | 36 | -- the "not yet" list should only contain those resource keys from javac that |
| aoqi@0 | 37 | are not covered by any example |
| aoqi@0 | 38 | |
| aoqi@0 | 39 | CheckExamples can be run standalone, and as a jtreg test, and will fail if any |
| aoqi@0 | 40 | anomalous conditions are found. |
| aoqi@0 | 41 | |
| aoqi@0 | 42 | The second utility is "RunExamples" which runs selected examples or all of them. |
| aoqi@0 | 43 | The examples can be run with -XDrawDiagnostics or without. Examples can be |
| aoqi@0 | 44 | selected by name or by resource key. Most examples are simple to run directly |
| aoqi@0 | 45 | anyway, but some use annotation processors or sourcepath or other options, and |
| aoqi@0 | 46 | the framework handles all these requirements. |
| aoqi@0 | 47 | |
| aoqi@0 | 48 | RunExamples can be run standalone and as a jtreg test, in which case it |
| aoqi@0 | 49 | generates a simple plain text report. In addition, the langtools/make/build.xml |
| aoqi@0 | 50 | file has a target "diags-examples" that uses RunExamples to create an HTML |
| aoqi@0 | 51 | report containing the output from all the examples. |
| aoqi@0 | 52 | |
| aoqi@0 | 53 | |
| aoqi@0 | 54 | Adding examples. |
| aoqi@0 | 55 | |
| aoqi@0 | 56 | When new diagnostics are added to javac, CheckExamples will probably initially |
| aoqi@0 | 57 | fail because the diagnostic will not have a corresponding example, nor will the |
| aoqi@0 | 58 | resource key be registered in the "not yet" list. Avoid the temptation to |
| aoqi@0 | 59 | simply add the resource key to the "not yet" list, except as a last resort. |
| aoqi@0 | 60 | |
| aoqi@0 | 61 | Examples should be as simple as possible to illustrate a diagnostic. An example |
| aoqi@0 | 62 | that is a single file is to be preferred over multiple files. An example that |
| aoqi@0 | 63 | generates just the one intended diagnostic is to be preferred over one that |
| aoqi@0 | 64 | generates multiple diagnostics. Examples should be a simple illustration of the |
| aoqi@0 | 65 | conditions that give rise to the diagnostic and should be easy to understand by |
| aoqi@0 | 66 | the reviewer and, potentially, by the localization folk, who have to understand |
| aoqi@0 | 67 | the context in which these new messages can appear. |
| aoqi@0 | 68 | |
| aoqi@0 | 69 | |
| aoqi@0 | 70 | Specification for writing examples. |
| aoqi@0 | 71 | |
| aoqi@0 | 72 | An example may a single file or a directory of files directly in the "examples" |
| aoqi@0 | 73 | directory. One file within an example must contain meta-information such as the |
| aoqi@0 | 74 | keys that it generates, any javac options that may be required, and additional |
| aoqi@0 | 75 | info about how to run the test, if needed. |
| aoqi@0 | 76 | |
| aoqi@0 | 77 | If an example is represented by a directory of files, by default all files |
| aoqi@0 | 78 | within that directory will be compiled together, putting all the files on the |
| aoqi@0 | 79 | command line. However, some subdirectories are special: |
| aoqi@0 | 80 | -- processors/ |
| aoqi@0 | 81 | Files within this directory will be treated as annotation processors and |
| aoqi@0 | 82 | compiled ahead of time. Currently, annotation processors are made available |
| aoqi@0 | 83 | to javac using the -classpath option (not -processorpath). This is to avoid |
| aoqi@0 | 84 | explicit use of annotation processing options on the javac command line. |
| aoqi@0 | 85 | Any annotation processors found will be registered for access by the JDK |
| aoqi@0 | 86 | service loaded. Currently, annotation processors are assumed to be in the |
| aoqi@0 | 87 | unnamed package. |
| aoqi@0 | 88 | -- sourcepath/ |
| aoqi@0 | 89 | If present, this directory will be put passed to javac using the -sourcepath |
| aoqi@0 | 90 | option. |
| aoqi@0 | 91 | -- classpath/ |
| aoqi@0 | 92 | This name is reserved for future use. It is expected that this directory |
| aoqi@0 | 93 | will be used to provide classes to be compiled and passes to javac via the |
| aoqi@0 | 94 | -classpath option. |
| aoqi@0 | 95 | -- support/ |
| aoqi@0 | 96 | This name is reserved for future use. It is expected that this directory |
| aoqi@0 | 97 | will be used to provide classes that setup non-standard conditions for a |
| aoqi@0 | 98 | test, such as very large source files, or illegal class files. |
| aoqi@0 | 99 | |
| aoqi@0 | 100 | Meta-information is represented by simple comment lines in exactly one of the |
| aoqi@0 | 101 | source files of the example. The file must not be in one of the special |
| aoqi@0 | 102 | subdirectories (processors/, sourcepath/, classpath/ or support/). Three |
| aoqi@0 | 103 | different types of information may be given: |
| aoqi@0 | 104 | // key: <resource-key> |
| aoqi@0 | 105 | One or more such lines must be provided, declaring the full resource keys |
| aoqi@0 | 106 | that will be used by javac when this example is run. |
| aoqi@0 | 107 | // options: <javac-options> |
| aoqi@0 | 108 | This line may be given at most once, providing one or more options to be |
| aoqi@0 | 109 | passed to javac. It is not possible to use this to specify options that |
| aoqi@0 | 110 | require filenames or directories. |
| aoqi@0 | 111 | // run: <mode> <optional-args> |
| aoqi@0 | 112 | This line may be given at most once, providing infomation about how to |
| aoqi@0 | 113 | run the example. Three different kinds are supported: |
| aoqi@0 | 114 | jsr199 -- The example will be run using the JSR 199 Compiler API. |
| aoqi@0 | 115 | This is the default if the tag is omitted. Messages generated |
| aoqi@0 | 116 | by the "rich diagnostic formatter" can not be accessed in this |
| aoqi@0 | 117 | way. However, this mode does provide additional options for |
| aoqi@0 | 118 | simulating errors in the filesystem. (See the options below.) |
| aoqi@0 | 119 | simple -- The example will be run using the simple com.sun.tools.javac.Main |
| aoqi@0 | 120 | API. This mode is most like the normal command line invocation. |
| aoqi@0 | 121 | backdoor -- The example will be run using an internal "backdoor" API, that |
| aoqi@0 | 122 | interposes access to the main compiler message bundle. This mode |
| aoqi@0 | 123 | is required to detect and track messages that bypass the normal |
| aoqi@0 | 124 | diagnostic mechanisms, such as output generated by the -verbose |
| aoqi@0 | 125 | option. |
| aoqi@0 | 126 | |
| aoqi@0 | 127 | The "jsr199" run mode accepts the following options: |
| aoqi@0 | 128 | -cantRead:pattern |
| aoqi@0 | 129 | -cantWrite:pattern |
| aoqi@0 | 130 | In both cases, the pattern is a standard Java regular expression (See the |
| aoqi@0 | 131 | javadoc for java.util.regex.Pattern for a complete specification.) Attempts to |
| aoqi@0 | 132 | read or write from files matching the corresponding pattern will cause an |
| aoqi@0 | 133 | IOException to occur within javac. |
| aoqi@0 | 134 |
