jdk
289 строк · 14.7 Кб
1/*
2* Copyright (c) 2014, 2024, Oracle and/or its affiliates. All rights reserved.
3* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4*
5* This code is free software; you can redistribute it and/or modify it
6* under the terms of the GNU General Public License version 2 only, as
7* published by the Free Software Foundation. Oracle designates this
8* particular file as subject to the "Classpath" exception as provided
9* by Oracle in the LICENSE file that accompanied this code.
10*
11* This code is distributed in the hope that it will be useful, but WITHOUT
12* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14* version 2 for more details (a copy is included in the LICENSE file that
15* accompanied this code).
16*
17* You should have received a copy of the GNU General Public License version
18* 2 along with this work; if not, write to the Free Software Foundation,
19* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20*
21* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22* or visit www.oracle.com if you need additional information or have any
23* questions.
24*/
25
26import javax.tools.JavaCompiler;
27import javax.tools.StandardLocation;
28
29/**
30* Defines the implementation of the
31* {@linkplain javax.tools.ToolProvider#getSystemJavaCompiler system Java compiler}
32* and its command line equivalent, <em>{@index javac javac tool}</em>.
33*
34* <p>The {@code com.sun.source.*} packages provide the {@index "Compiler Tree API"}:
35* an API for accessing the abstract trees (ASTs) representing Java source code
36* and documentation comments, used by <em>javac</em>, <em>javadoc</em> and related tools.
37*
38* <h2 style="font-family:'DejaVu Sans Mono', monospace; font-style:italic">javac</h2>
39*
40* <p>
41* This module provides the equivalent of command-line access to <em>javac</em>
42* via the {@link java.util.spi.ToolProvider ToolProvider} and
43* {@link javax.tools.Tool} service provider interfaces (SPIs),
44* and more flexible access via the {@link javax.tools.JavaCompiler JavaCompiler}
45* SPI.</p>
46*
47* <p> Instances of the tools can be obtained by calling
48* {@link java.util.spi.ToolProvider#findFirst ToolProvider.findFirst}
49* or the {@linkplain java.util.ServiceLoader service loader} with the name
50* {@code "javac"}.
51*
52* <p>
53* In addition, instances of {@link javax.tools.JavaCompiler.CompilationTask}
54* obtained from {@linkplain javax.tools.JavaCompiler JavaCompiler} can be
55* downcast to {@link com.sun.source.util.JavacTask JavacTask} for access to
56* lower level aspects of <em>javac</em>, such as the
57* {@link com.sun.source.tree Abstract Syntax Tree} (AST).</p>
58*
59* <p>This module uses the {@link java.nio.file.spi.FileSystemProvider
60* FileSystemProvider} API to locate file system providers. In particular,
61* this means that a jar file system provider, such as that in the
62* {@code jdk.zipfs} module, must be available if the compiler is to be able
63* to read JAR files.
64*
65* <h3>Options and Environment Variables</h3>
66*
67* The full set of options and environment variables supported by <em>javac</em>
68* is given in the <a href="../../specs/man/javac.html"><em>javac Tool Guide</em></a>.
69* However, there are some restrictions when the compiler is invoked through
70* its API.
71*
72* <ul>
73* <li><p>The {@code -J} option is not supported.
74* Any necessary VM options must be set in the VM used to invoke the API.
75* {@code IllegalArgumentException} will be thrown if the option
76* is used when invoking the tool through the {@code JavaCompiler} API;
77* an error will be reported if the option is used when invoking
78* <em>javac</em> through the {@link java.util.spi.ToolProvider ToolProvider}
79* or legacy {@link com.sun.tools.javac.Main Main} API.
80*
81* <li><p>The "classpath wildcard" feature is not supported.
82* The feature is only supported by the native launcher.
83* When invoking the tool through its API, all necessary jar
84* files should be included directly in the {@code --class-path}
85* option, or the {@code CLASSPATH} environment variable.
86* When invoking the tool through its API, all components of the
87* class path will be taken literally, and will be ignored if there
88* is no matching directory or file. The {@code -Xlint:paths}
89* option can be used to generate warnings about missing components.
90*
91* </ul>
92*
93* The following restrictions apply when invoking the compiler through
94* the {@link JavaCompiler} interface.
95*
96* <ul>
97* <li><p>Argument files (so-called @-files) are not supported.
98* The content of any such files should be included directly
99* in the list of options provided when invoking the tool
100* though this API.
101* {@code IllegalArgumentException} will be thrown if
102* the option is used when invoking the tool through this API.
103*
104* <li><p>The environment variable {@code JDK_JAVAC_OPTIONS} is not supported.
105* Any options defined in the environment variable should be included
106* directly in the list of options provided when invoking the
107* API; any values in the environment variable will be ignored.
108*
109* <li><p>Options that are just used to obtain information (such as
110* {@code --help}, {@code --help-extended}, {@code --version} and
111* {@code --full-version}) are not supported.
112* {@link IllegalArgumentException} will be thrown if any of
113* these options are used when invoking the tool through this API.
114*
115* <li>Path-related options depend on the file manager being used
116* when calling {@link JavaCompiler#getTask}. The "standard"
117* options, such as {@code --class-path}, {@code --module-path},
118* and so on are available when using the default file manager,
119* or one derived from it. These options may not be available
120* and different options may be available, when using a different
121* file manager.
122* {@link IllegalArgumentException} will be thrown if any option
123* that is unknown to the tool or the file manager is used when
124* invoking the tool through this API.
125* </ul>
126*
127* Note that the {@code CLASSPATH} environment variable <em>is</em> honored
128* when invoking the compiler through its API, although such use is discouraged.
129* An environment variable cannot be unset once a VM has been started,
130* and so it is recommended to ensure that the environment variable is not set
131* when starting a VM that will be used to invoke the compiler.
132* However, if a value has been set, any such value can be overridden by
133* using the {@code --class-path} option when invoking the compiler,
134* or setting {@link StandardLocation#CLASS_PATH} in the file manager
135* when invoking the compiler through the {@link JavaCompiler} interface.
136*
137* <h3>SuppressWarnings</h3>
138*
139* JLS {@jls 9.6.4.5} specifies a number of strings that can be used to
140* suppress warnings that may be generated by a Java compiler.
141*
142* In addition, <em>javac</em> also supports other strings that can be used
143* to suppress other kinds of warnings. The following table lists all the
144* strings that can be used with {@code @SuppressWarnings}.
145*
146* <table class="striped">
147* <caption>Strings supported by {@code SuppressWarnings}</caption>
148* <thead>
149* <tr><th>String<th>Suppress Warnings About ...
150* </thead>
151* <tbody>
152* <tr><th scope="row">{@code auxiliaryclass} <td>an auxiliary class that is hidden in a source file, and is used
153* from other files
154* <tr><th scope="row">{@code cast} <td>use of unnecessary casts
155* <tr><th scope="row">{@code classfile} <td>issues related to classfile contents
156* <tr><th scope="row">{@code dangling-doc-comments} <td>issues related to "dangling" documentation comments,
157* not attached to a declaration
158* <tr><th scope="row">{@code deprecation} <td>use of deprecated items
159* <tr><th scope="row">{@code dep-ann} <td>items marked as deprecated in a documentation comment but not
160* using the {@code @Deprecated} annotation
161* <tr><th scope="row">{@code divzero} <td>division by constant integer {@code 0}
162* <tr><th scope="row">{@code empty} <td>empty statement after {@code if}
163* <tr><th scope="row">{@code exports} <td>issues regarding module exports
164* <tr><th scope="row">{@code fallthrough} <td>falling through from one case of a {@code switch} statement to
165* the next
166* <tr><th scope="row">{@code finally} <td>{@code finally} clauses that do not terminate normally
167* <tr><th scope="row">{@code incubating} <td>use of incubating modules
168* <tr><th scope="row">{@code lossy-conversions} <td>possible lossy conversions in compound assignment
169* <tr><th scope="row">{@code missing-explicit-ctor} <td>missing explicit constructors in public and protected classes
170* in exported packages
171* <tr><th scope="row">{@code module} <td>module system related issues
172* <tr><th scope="row">{@code opens} <td>issues regarding module opens
173* <tr><th scope="row">{@code overloads} <td>issues regarding method overloads
174* <tr><th scope="row">{@code overrides} <td>issues regarding method overrides
175* <tr><th scope="row">{@code path} <td>invalid path elements on the command line
176* <tr><th scope="row">{@code preview} <td>use of preview language features
177* <tr><th scope="row">{@code rawtypes} <td>use of raw types
178* <tr><th scope="row">{@code removal} <td>use of API that has been marked for removal
179* <tr><th scope="row">{@code restricted} <td>use of restricted methods
180* <tr><th scope="row">{@code requires-automatic} <td>use of automatic modules in the {@code requires} clauses
181* <tr><th scope="row">{@code requires-transitive-automatic} <td>automatic modules in {@code requires transitive}
182* <tr><th scope="row">{@code serial} <td>{@link java.base/java.io.Serializable Serializable} classes
183* that do not have a {@code serialVersionUID} field, or other
184* suspect declarations in {@code Serializable} and
185* {@link java.base/java.io.Externalizable Externalizable} classes
186* and interfaces
187* <tr><th scope="row">{@code static} <td>accessing a static member using an instance
188* <tr><th scope="row">{@code strictfp} <td>unnecessary use of the {@code strictfp} modifier
189* <tr><th scope="row">{@code synchronization} <td>synchronization attempts on instances of value-based classes
190* <tr><th scope="row">{@code text-blocks} <td>inconsistent white space characters in text block indentation
191* <tr><th scope="row">{@code this-escape} <td>superclass constructor leaking {@code this} before subclass initialized
192* <tr><th scope="row">{@code try} <td>issues relating to use of {@code try} blocks
193* (that is, try-with-resources)
194* <tr><th scope="row">{@code unchecked} <td>unchecked operations
195* <tr><th scope="row">{@code varargs} <td>potentially unsafe vararg methods
196* <tr><th scope="row">{@code doclint:accessibility} <td>accessibility issues found in documentation comments
197* <tr><th scope="row">{@code doclint:all} <td>all issues found in documentation comments
198* <tr><th scope="row">{@code doclint:html} <td>HTML issues found in documentation comments
199* <tr><th scope="row">{@code doclint:missing} <td>missing items in documentation comments
200* <tr><th scope="row">{@code doclint:reference} <td>reference issues found in documentation comments
201* <tr><th scope="row">{@code doclint:syntax} <td>syntax issues found in documentation comments
202* </tbody>
203* </table>
204*
205* @toolGuide javac
206*
207* @provides java.util.spi.ToolProvider
208* Use {@link java.util.spi.ToolProvider#findFirst ToolProvider.findFirst("javac")}
209* to obtain an instance of a {@code ToolProvider} that provides the equivalent
210* of command-line access to the {@code javac} tool.
211* @provides com.sun.tools.javac.platform.PlatformProvider
212* @provides javax.tools.JavaCompiler
213* @provides javax.tools.Tool
214*
215* @uses javax.annotation.processing.Processor
216* @uses com.sun.source.util.Plugin
217* @uses com.sun.tools.javac.platform.PlatformProvider
218*
219* @moduleGraph
220* @since 9
221*/
222module jdk.compiler {
223requires transitive java.compiler;
224requires jdk.internal.opt;
225requires jdk.zipfs;
226
227exports com.sun.source.doctree;
228exports com.sun.source.tree;
229exports com.sun.source.util;
230exports com.sun.tools.javac;
231
232exports com.sun.tools.doclint to
233jdk.javadoc;
234exports com.sun.tools.javac.api to
235jdk.javadoc,
236jdk.jshell,
237jdk.internal.md;
238exports com.sun.tools.javac.resources to
239jdk.jshell;
240exports com.sun.tools.javac.code to
241jdk.javadoc,
242jdk.jshell;
243exports com.sun.tools.javac.comp to
244jdk.javadoc,
245jdk.jshell;
246exports com.sun.tools.javac.file to
247jdk.jdeps,
248jdk.javadoc;
249exports com.sun.tools.javac.jvm to
250jdk.javadoc;
251exports com.sun.tools.javac.main to
252jdk.javadoc,
253jdk.jshell;
254exports com.sun.tools.javac.model to
255jdk.javadoc;
256exports com.sun.tools.javac.parser to
257jdk.jshell,
258jdk.internal.md;
259exports com.sun.tools.javac.platform to
260jdk.jdeps,
261jdk.javadoc;
262exports com.sun.tools.javac.tree to
263jdk.javadoc,
264jdk.jshell,
265jdk.internal.md;
266exports com.sun.tools.javac.util to
267jdk.jdeps,
268jdk.javadoc,
269jdk.jshell,
270jdk.internal.md;
271
272uses javax.annotation.processing.Processor;
273uses com.sun.source.util.Plugin;
274uses com.sun.tools.doclint.DocLint;
275uses com.sun.tools.javac.platform.PlatformProvider;
276uses com.sun.tools.javac.api.JavacTrees.DocCommentTreeTransformer;
277
278provides java.util.spi.ToolProvider with
279com.sun.tools.javac.main.JavacToolProvider;
280
281provides com.sun.tools.javac.platform.PlatformProvider with
282com.sun.tools.javac.platform.JDKPlatformProvider;
283
284provides javax.tools.JavaCompiler with
285com.sun.tools.javac.api.JavacTool;
286
287provides javax.tools.Tool with
288com.sun.tools.javac.api.JavacTool;
289}
290
291