Summary

Specify differences in the different ways to invoke javac

Problem

javac can be invoked in different ways, all involving options and some environment variables. The man page lists everything for the command-line tool, but the ToolProvider and JavaCompiler API have some limitations. These should be documented.

Solution

Document the differences to the main launcher when using the ToolProvider and JavaCompiler API. Because ToolProvider and JavaCompiler are both general service-provider interfaces for potentially different implementations, it is not appropriate to document the javac functionality in the API for those interfaces; instead, the documentation must be provided in the module that provides the implementation of those interfaces ... i.e. jdk.compiler.

Specification

The following text is added to the jdk.compiler module declaration.
It is inserted before big <h3>SuppressWarnings</h3> table.

 * <h3>Options and Environment Variables</h3>
 *
 * The full set of options and environment variables supported by <em>javac</em>
 * is given in the <a href="../specs/man/javac.html"><em>javac Tool Guide</em></a>.
 * However, there are some restrictions when the compiler is invoked through
 * its API.
 *
 * <ul>
 *     <li><p>The {@code -J} option is not supported.
 *          Any necessary VM options must be set in the VM used to invoke the API.
 *          {@code IllegalArgumentException} will be thrown if the option
 *          is used when invoking the tool through the {@code JavaCompiler} API;
 *          an error will be reported if the option is used when invoking
 *          <em>javac</em> through the {@link java.util.spi.ToolProvider ToolProvider}
 *          or legacy {@link com.sun.tools.javac.Main Main} API.
 *
 *     <li><p>The "classpath wildcard" feature is not supported.
 *          The feature is only supported by the native launcher.
 *          When invoking the tool through its API, all necessary jar
 *          files should be included directly in the {@code --class-path}
 *          option, or the {@code CLASSPATH} environment variable.
 *          When invoking the tool through its API, all components of the
 *          class path will be taken literally, and will be ignored if there
 *          is no matching directory or file. The {@code -Xlint:paths}
 *          option can be used to generate warnings about missing components.
 *
 * </ul>
 *
 * The following restrictions apply when invoking the compiler through
 * the {@link JavaCompiler} interface.
 *
 * <ul>
 *     <li><p>Argument files (so-called @-files) are not supported.
 *          The content of any such files should be included directly
 *          in the list of options provided when invoking the tool
 *          though this API.
 *          {@code IllegalArgumentException} will be thrown if
 *          the option is used when invoking the tool through this API.
 *
 *     <li><p>The environment variable {@code JDK_JAVAC_OPTIONS} is not supported.
 *          Any options defined in the environment variable should be included
 *          directly in the list of options provided when invoking the
 *          API; any values in the environment variable will be ignored.
 *
 *     <li><p>Options that are just used to obtain information (such as
 *          {@code --help}, {@code --help-extended}, {@code --version} and
 *          {@code --full-version}) are not supported.
 *          {@link IllegalArgumentException} will be thrown if any of
 *          these options are used when invoking the tool through this API.
 *
 *      <li>Path-related options depend on the file manager being used
 *          when calling {@link JavaCompiler#getTask}. The "standard"
 *          options, such as {@code --class-path}, {@code --module-path},
 *          and so on are available when using the default file manager,
 *          or one derived from it. These options may not be available
 *          and different options may be available, when using a different
 *          file manager.
 *          {@link IllegalArgumentException} will be thrown if any option
 *          that is unknown to the tool or the file manager is used when
 *          invoking the tool through this API.
 * </ul>
 *
 * Note that the {@code CLASSPATH} environment variable <em>is</em> honored
 * when invoking the compiler through its API, although such use is discouraged.
 * An environment variable cannot be unset once a VM has been started,
 * and so it is recommended to ensure that the environment variable is not set
 * when starting a VM that will be used to invoke the compiler.
 * However, if a value has been set, any such value can be overridden by
 * using the {@code --class-path} option when invoking the compiler,
 * or setting {@link StandardLocation#CLASS_PATH} in the file manager
 * when invoking the compiler through the {@link JavaCompiler} interface.
 *