1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/test/tools/javac/diags/README.examples.txt Wed Apr 27 01:34:52 2016 +0800
1.3 @@ -0,0 +1,134 @@
1.4 +Diagnostics Examples.
1.5 +
1.6 +The "examples/ directory contains a collection of examples of Java code, each of
1.7 +which is designed to illustrate one or more diagnostics that can be generated by
1.8 +the JDK Java compiler, javac. These examples are represented by files or
1.9 +directories of files, each of which is designed to illustrate a specific
1.10 +diagnostic. Sometimes it is unavoidable that creating one issue will lead to
1.11 +downstream issues: this is especially true for lex errors, where the error
1.12 +recovery is fragile at best. Each example declares the diagnostics that it is
1.13 +expected to generate -- this allows the examples to be verified and facilitates
1.14 +searching for examples for specific messages.
1.15 +
1.16 +Normally, tests for javac errors avoid checking the actual error messages that
1.17 +get generated. Older tests simply verify that one or more warnings or errors
1.18 +are generated; more recent tests verify that specific messages are generated,
1.19 +but these tests typically avoid checking the localized text by using the
1.20 +-XDrawDiagnostics mechanism. In addition, the focus of such tests is often on
1.21 +completeness instead of simplicity.
1.22 +
1.23 +By contrast, the intent of these examples is to provide simple and easy to
1.24 +understand examples of the situations in which a diagnostic can arise, and the
1.25 +messages that may be displayed. This will aid in reviewing the output generated
1.26 +by javac and in localizing the resource bundle to other locales. In addition,
1.27 +the examples include simple meta-information so that the collection as a whole
1.28 +can be audited for coverage, thus encouraging new examples to be added when new
1.29 +diagnostics are added to javac.
1.30 +
1.31 +There are two utilities for processing these examples.
1.32 +
1.33 +The first utility is "CheckExamples" which checks various conditions for the
1.34 +examples:
1.35 +-- each example must generate exactly the set of keys that it is declared to
1.36 + generate
1.37 +-- together, the examples must generate all the resource keys coming from javac
1.38 + (except for resource keys that are registered in a "not yet" list)
1.39 +-- the "not yet" list should only contain those resource keys from javac that
1.40 + are not covered by any example
1.41 +
1.42 +CheckExamples can be run standalone, and as a jtreg test, and will fail if any
1.43 +anomalous conditions are found.
1.44 +
1.45 +The second utility is "RunExamples" which runs selected examples or all of them.
1.46 +The examples can be run with -XDrawDiagnostics or without. Examples can be
1.47 +selected by name or by resource key. Most examples are simple to run directly
1.48 +anyway, but some use annotation processors or sourcepath or other options, and
1.49 +the framework handles all these requirements.
1.50 +
1.51 +RunExamples can be run standalone and as a jtreg test, in which case it
1.52 +generates a simple plain text report. In addition, the langtools/make/build.xml
1.53 +file has a target "diags-examples" that uses RunExamples to create an HTML
1.54 +report containing the output from all the examples.
1.55 +
1.56 +
1.57 +Adding examples.
1.58 +
1.59 +When new diagnostics are added to javac, CheckExamples will probably initially
1.60 +fail because the diagnostic will not have a corresponding example, nor will the
1.61 +resource key be registered in the "not yet" list. Avoid the temptation to
1.62 +simply add the resource key to the "not yet" list, except as a last resort.
1.63 +
1.64 +Examples should be as simple as possible to illustrate a diagnostic. An example
1.65 +that is a single file is to be preferred over multiple files. An example that
1.66 +generates just the one intended diagnostic is to be preferred over one that
1.67 +generates multiple diagnostics. Examples should be a simple illustration of the
1.68 +conditions that give rise to the diagnostic and should be easy to understand by
1.69 +the reviewer and, potentially, by the localization folk, who have to understand
1.70 +the context in which these new messages can appear.
1.71 +
1.72 +
1.73 +Specification for writing examples.
1.74 +
1.75 +An example may a single file or a directory of files directly in the "examples"
1.76 +directory. One file within an example must contain meta-information such as the
1.77 +keys that it generates, any javac options that may be required, and additional
1.78 +info about how to run the test, if needed.
1.79 +
1.80 +If an example is represented by a directory of files, by default all files
1.81 +within that directory will be compiled together, putting all the files on the
1.82 +command line. However, some subdirectories are special:
1.83 +-- processors/
1.84 + Files within this directory will be treated as annotation processors and
1.85 + compiled ahead of time. Currently, annotation processors are made available
1.86 + to javac using the -classpath option (not -processorpath). This is to avoid
1.87 + explicit use of annotation processing options on the javac command line.
1.88 + Any annotation processors found will be registered for access by the JDK
1.89 + service loaded. Currently, annotation processors are assumed to be in the
1.90 + unnamed package.
1.91 +-- sourcepath/
1.92 + If present, this directory will be put passed to javac using the -sourcepath
1.93 + option.
1.94 +-- classpath/
1.95 + This name is reserved for future use. It is expected that this directory
1.96 + will be used to provide classes to be compiled and passes to javac via the
1.97 + -classpath option.
1.98 +-- support/
1.99 + This name is reserved for future use. It is expected that this directory
1.100 + will be used to provide classes that setup non-standard conditions for a
1.101 + test, such as very large source files, or illegal class files.
1.102 +
1.103 +Meta-information is represented by simple comment lines in exactly one of the
1.104 +source files of the example. The file must not be in one of the special
1.105 +subdirectories (processors/, sourcepath/, classpath/ or support/). Three
1.106 +different types of information may be given:
1.107 +// key: <resource-key>
1.108 + One or more such lines must be provided, declaring the full resource keys
1.109 + that will be used by javac when this example is run.
1.110 +// options: <javac-options>
1.111 + This line may be given at most once, providing one or more options to be
1.112 + passed to javac. It is not possible to use this to specify options that
1.113 + require filenames or directories.
1.114 +// run: <mode> <optional-args>
1.115 + This line may be given at most once, providing infomation about how to
1.116 + run the example. Three different kinds are supported:
1.117 + jsr199 -- The example will be run using the JSR 199 Compiler API.
1.118 + This is the default if the tag is omitted. Messages generated
1.119 + by the "rich diagnostic formatter" can not be accessed in this
1.120 + way. However, this mode does provide additional options for
1.121 + simulating errors in the filesystem. (See the options below.)
1.122 + simple -- The example will be run using the simple com.sun.tools.javac.Main
1.123 + API. This mode is most like the normal command line invocation.
1.124 + backdoor -- The example will be run using an internal "backdoor" API, that
1.125 + interposes access to the main compiler message bundle. This mode
1.126 + is required to detect and track messages that bypass the normal
1.127 + diagnostic mechanisms, such as output generated by the -verbose
1.128 + option.
1.129 +
1.130 +The "jsr199" run mode accepts the following options:
1.131 + -cantRead:pattern
1.132 + -cantWrite:pattern
1.133 +In both cases, the pattern is a standard Java regular expression (See the
1.134 +javadoc for java.util.regex.Pattern for a complete specification.) Attempts to
1.135 +read or write from files matching the corresponding pattern will cause an
1.136 +IOException to occur within javac.
1.137 +
