aoqi@0: Diagnostics Examples. aoqi@0: aoqi@0: The "examples/ directory contains a collection of examples of Java code, each of aoqi@0: which is designed to illustrate one or more diagnostics that can be generated by aoqi@0: the JDK Java compiler, javac. These examples are represented by files or aoqi@0: directories of files, each of which is designed to illustrate a specific aoqi@0: diagnostic. Sometimes it is unavoidable that creating one issue will lead to aoqi@0: downstream issues: this is especially true for lex errors, where the error aoqi@0: recovery is fragile at best. Each example declares the diagnostics that it is aoqi@0: expected to generate -- this allows the examples to be verified and facilitates aoqi@0: searching for examples for specific messages. aoqi@0: aoqi@0: Normally, tests for javac errors avoid checking the actual error messages that aoqi@0: get generated. Older tests simply verify that one or more warnings or errors aoqi@0: are generated; more recent tests verify that specific messages are generated, aoqi@0: but these tests typically avoid checking the localized text by using the aoqi@0: -XDrawDiagnostics mechanism. In addition, the focus of such tests is often on aoqi@0: completeness instead of simplicity. aoqi@0: aoqi@0: By contrast, the intent of these examples is to provide simple and easy to aoqi@0: understand examples of the situations in which a diagnostic can arise, and the aoqi@0: messages that may be displayed. This will aid in reviewing the output generated aoqi@0: by javac and in localizing the resource bundle to other locales. In addition, aoqi@0: the examples include simple meta-information so that the collection as a whole aoqi@0: can be audited for coverage, thus encouraging new examples to be added when new aoqi@0: diagnostics are added to javac. aoqi@0: aoqi@0: There are two utilities for processing these examples. aoqi@0: aoqi@0: The first utility is "CheckExamples" which checks various conditions for the aoqi@0: examples: aoqi@0: -- each example must generate exactly the set of keys that it is declared to aoqi@0: generate aoqi@0: -- together, the examples must generate all the resource keys coming from javac aoqi@0: (except for resource keys that are registered in a "not yet" list) aoqi@0: -- the "not yet" list should only contain those resource keys from javac that aoqi@0: are not covered by any example aoqi@0: aoqi@0: CheckExamples can be run standalone, and as a jtreg test, and will fail if any aoqi@0: anomalous conditions are found. aoqi@0: aoqi@0: The second utility is "RunExamples" which runs selected examples or all of them. aoqi@0: The examples can be run with -XDrawDiagnostics or without. Examples can be aoqi@0: selected by name or by resource key. Most examples are simple to run directly aoqi@0: anyway, but some use annotation processors or sourcepath or other options, and aoqi@0: the framework handles all these requirements. aoqi@0: aoqi@0: RunExamples can be run standalone and as a jtreg test, in which case it aoqi@0: generates a simple plain text report. In addition, the langtools/make/build.xml aoqi@0: file has a target "diags-examples" that uses RunExamples to create an HTML aoqi@0: report containing the output from all the examples. aoqi@0: aoqi@0: aoqi@0: Adding examples. aoqi@0: aoqi@0: When new diagnostics are added to javac, CheckExamples will probably initially aoqi@0: fail because the diagnostic will not have a corresponding example, nor will the aoqi@0: resource key be registered in the "not yet" list. Avoid the temptation to aoqi@0: simply add the resource key to the "not yet" list, except as a last resort. aoqi@0: aoqi@0: Examples should be as simple as possible to illustrate a diagnostic. An example aoqi@0: that is a single file is to be preferred over multiple files. An example that aoqi@0: generates just the one intended diagnostic is to be preferred over one that aoqi@0: generates multiple diagnostics. Examples should be a simple illustration of the aoqi@0: conditions that give rise to the diagnostic and should be easy to understand by aoqi@0: the reviewer and, potentially, by the localization folk, who have to understand aoqi@0: the context in which these new messages can appear. aoqi@0: aoqi@0: aoqi@0: Specification for writing examples. aoqi@0: aoqi@0: An example may a single file or a directory of files directly in the "examples" aoqi@0: directory. One file within an example must contain meta-information such as the aoqi@0: keys that it generates, any javac options that may be required, and additional aoqi@0: info about how to run the test, if needed. aoqi@0: aoqi@0: If an example is represented by a directory of files, by default all files aoqi@0: within that directory will be compiled together, putting all the files on the aoqi@0: command line. However, some subdirectories are special: aoqi@0: -- processors/ aoqi@0: Files within this directory will be treated as annotation processors and aoqi@0: compiled ahead of time. Currently, annotation processors are made available aoqi@0: to javac using the -classpath option (not -processorpath). This is to avoid aoqi@0: explicit use of annotation processing options on the javac command line. aoqi@0: Any annotation processors found will be registered for access by the JDK aoqi@0: service loaded. Currently, annotation processors are assumed to be in the aoqi@0: unnamed package. aoqi@0: -- sourcepath/ aoqi@0: If present, this directory will be put passed to javac using the -sourcepath aoqi@0: option. aoqi@0: -- classpath/ aoqi@0: This name is reserved for future use. It is expected that this directory aoqi@0: will be used to provide classes to be compiled and passes to javac via the aoqi@0: -classpath option. aoqi@0: -- support/ aoqi@0: This name is reserved for future use. It is expected that this directory aoqi@0: will be used to provide classes that setup non-standard conditions for a aoqi@0: test, such as very large source files, or illegal class files. aoqi@0: aoqi@0: Meta-information is represented by simple comment lines in exactly one of the aoqi@0: source files of the example. The file must not be in one of the special aoqi@0: subdirectories (processors/, sourcepath/, classpath/ or support/). Three aoqi@0: different types of information may be given: aoqi@0: // key: aoqi@0: One or more such lines must be provided, declaring the full resource keys aoqi@0: that will be used by javac when this example is run. aoqi@0: // options: aoqi@0: This line may be given at most once, providing one or more options to be aoqi@0: passed to javac. It is not possible to use this to specify options that aoqi@0: require filenames or directories. aoqi@0: // run: aoqi@0: This line may be given at most once, providing infomation about how to aoqi@0: run the example. Three different kinds are supported: aoqi@0: jsr199 -- The example will be run using the JSR 199 Compiler API. aoqi@0: This is the default if the tag is omitted. Messages generated aoqi@0: by the "rich diagnostic formatter" can not be accessed in this aoqi@0: way. However, this mode does provide additional options for aoqi@0: simulating errors in the filesystem. (See the options below.) aoqi@0: simple -- The example will be run using the simple com.sun.tools.javac.Main aoqi@0: API. This mode is most like the normal command line invocation. aoqi@0: backdoor -- The example will be run using an internal "backdoor" API, that aoqi@0: interposes access to the main compiler message bundle. This mode aoqi@0: is required to detect and track messages that bypass the normal aoqi@0: diagnostic mechanisms, such as output generated by the -verbose aoqi@0: option. aoqi@0: aoqi@0: The "jsr199" run mode accepts the following options: aoqi@0: -cantRead:pattern aoqi@0: -cantWrite:pattern aoqi@0: In both cases, the pattern is a standard Java regular expression (See the aoqi@0: javadoc for java.util.regex.Pattern for a complete specification.) Attempts to aoqi@0: read or write from files matching the corresponding pattern will cause an aoqi@0: IOException to occur within javac. aoqi@0: