1 /*
2 * Copyright (c) 2014, 2025, 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
26 import javax.tools.JavaCompiler;
27 import javax.tools.StandardLocation;
28 import com.sun.tools.javac.comp.CodeReflectionTransformer;
29
30 /**
31 * Defines the implementation of the
32 * {@linkplain javax.tools.ToolProvider#getSystemJavaCompiler system Java compiler}
33 * and its command line equivalent, <em>{@index javac javac tool}</em>.
34 *
35 * <p>The {@code com.sun.source.*} packages provide the {@index "Compiler Tree API"}:
36 * an API for accessing the abstract trees (ASTs) representing Java source code
37 * and documentation comments, used by <em>javac</em>, <em>javadoc</em> and related tools.
38 *
39 * <h2 style="font-family:'DejaVu Sans Mono', monospace; font-style:italic">javac</h2>
40 *
41 * <p>
42 * This module provides the equivalent of command-line access to <em>javac</em>
43 * via the {@link java.util.spi.ToolProvider ToolProvider} and
44 * {@link javax.tools.Tool} service provider interfaces (SPIs),
45 * and more flexible access via the {@link javax.tools.JavaCompiler JavaCompiler}
46 * SPI.</p>
47 *
48 * <p> Instances of the tools can be obtained by calling
49 * {@link java.util.spi.ToolProvider#findFirst ToolProvider.findFirst}
50 * or the {@linkplain java.util.ServiceLoader service loader} with the name
51 * {@code "javac"}.
52 *
53 * <p>
54 * In addition, instances of {@link javax.tools.JavaCompiler.CompilationTask}
55 * obtained from {@linkplain javax.tools.JavaCompiler JavaCompiler} can be
56 * downcast to {@link com.sun.source.util.JavacTask JavacTask} for access to
57 * lower level aspects of <em>javac</em>, such as the
58 * {@link com.sun.source.tree Abstract Syntax Tree} (AST).</p>
59 *
60 * <p>This module uses the {@link java.nio.file.spi.FileSystemProvider
61 * FileSystemProvider} API to locate file system providers. In particular,
62 * this means that a jar file system provider, such as that in the
63 * {@code jdk.zipfs} module, must be available if the compiler is to be able
64 * to read JAR files.
65 *
66 * <h3>Options and Environment Variables</h3>
67 *
68 * The full set of options and environment variables supported by <em>javac</em>
69 * is given in the <a href="../../specs/man/javac.html"><em>javac Tool Guide</em></a>.
70 * However, there are some restrictions when the compiler is invoked through
71 * its API.
72 *
73 * <ul>
74 * <li><p>The {@code -J} option is not supported.
75 * Any necessary VM options must be set in the VM used to invoke the API.
76 * {@code IllegalArgumentException} will be thrown if the option
77 * is used when invoking the tool through the {@code JavaCompiler} API;
78 * an error will be reported if the option is used when invoking
79 * <em>javac</em> through the {@link java.util.spi.ToolProvider ToolProvider}
80 * or legacy {@link com.sun.tools.javac.Main Main} API.
81 *
82 * <li><p>The "classpath wildcard" feature is not supported.
83 * The feature is only supported by the native launcher.
84 * When invoking the tool through its API, all necessary jar
85 * files should be included directly in the {@code --class-path}
86 * option, or the {@code CLASSPATH} environment variable.
87 * When invoking the tool through its API, all components of the
88 * class path will be taken literally, and will be ignored if there
89 * is no matching directory or file. The {@code -Xlint:paths}
90 * option can be used to generate warnings about missing components.
91 *
92 * </ul>
93 *
94 * The following restrictions apply when invoking the compiler through
95 * the {@link JavaCompiler} interface.
96 *
97 * <ul>
98 * <li><p>Argument files (so-called @-files) are not supported.
99 * The content of any such files should be included directly
100 * in the list of options provided when invoking the tool
101 * though this API.
102 * {@code IllegalArgumentException} will be thrown if
103 * the option is used when invoking the tool through this API.
104 *
105 * <li><p>The environment variable {@code JDK_JAVAC_OPTIONS} is not supported.
106 * Any options defined in the environment variable should be included
107 * directly in the list of options provided when invoking the
108 * API; any values in the environment variable will be ignored.
109 *
110 * <li><p>Options that are just used to obtain information (such as
111 * {@code --help}, {@code --help-extended}, {@code --version} and
112 * {@code --full-version}) are not supported.
113 * {@link IllegalArgumentException} will be thrown if any of
114 * these options are used when invoking the tool through this API.
115 *
116 * <li>Path-related options depend on the file manager being used
117 * when calling {@link JavaCompiler#getTask}. The "standard"
118 * options, such as {@code --class-path}, {@code --module-path},
119 * and so on are available when using the default file manager,
120 * or one derived from it. These options may not be available
121 * and different options may be available, when using a different
122 * file manager.
123 * {@link IllegalArgumentException} will be thrown if any option
124 * that is unknown to the tool or the file manager is used when
125 * invoking the tool through this API.
126 * </ul>
127 *
128 * Note that the {@code CLASSPATH} environment variable <em>is</em> honored
129 * when invoking the compiler through its API, although such use is discouraged.
130 * An environment variable cannot be unset once a VM has been started,
131 * and so it is recommended to ensure that the environment variable is not set
132 * when starting a VM that will be used to invoke the compiler.
133 * However, if a value has been set, any such value can be overridden by
134 * using the {@code --class-path} option when invoking the compiler,
135 * or setting {@link StandardLocation#CLASS_PATH} in the file manager
136 * when invoking the compiler through the {@link JavaCompiler} interface.
137 *
138 * <h3>SuppressWarnings</h3>
139 *
140 * JLS {@jls 9.6.4.5} specifies a number of strings that can be used to
141 * suppress warnings that may be generated by a Java compiler.
142 *
143 * In addition, <em>javac</em> also supports other strings that can be used
144 * to suppress other kinds of warnings. The following table lists all the
145 * strings that are recognized by <em>javac</em> in {@code @SuppressWarnings}
146 * annotations. Unrecognized strings are ignored.
147 *
148 * <table class="striped">
149 * <caption>Strings supported by {@code SuppressWarnings}</caption>
150 * <thead>
151 * <tr><th>String<th>Suppress Warnings About ...
152 * </thead>
153 * <tbody>
154 * <tr><th scope="row">{@code auxiliaryclass} <td>an auxiliary class that is hidden in a source file, and is used
155 * from other files
156 * <tr><th scope="row">{@code cast} <td>use of unnecessary casts
157 * <tr><th scope="row">{@code dangling-doc-comments} <td>issues related to "dangling" documentation comments,
158 * not attached to a declaration
159 * <tr><th scope="row">{@code deprecation} <td>use of deprecated items
160 * <tr><th scope="row">{@code dep-ann} <td>items marked as deprecated in a documentation comment but not
161 * using the {@code @Deprecated} annotation
162 * <tr><th scope="row">{@code divzero} <td>division by constant integer {@code 0}
163 * <tr><th scope="row">{@code empty} <td>empty statement after {@code if}
164 * <tr><th scope="row">{@code exports} <td>issues regarding module exports
165 * <tr><th scope="row">{@code fallthrough} <td>falling through from one case of a {@code switch} statement to
166 * the next
167 * <tr><th scope="row">{@code finally} <td>{@code finally} clauses that do not terminate normally
168 * <tr><th scope="row">{@code identity} <td>use of a value-based class where an identity class is expected
169 * <tr><th scope="row">{@code lossy-conversions} <td>possible lossy conversions in compound assignments or bit shifts
170 * (more than \u00B131 bits for integers or \u00B163 bits for longs)
171 * <tr><th scope="row">{@code missing-explicit-ctor} <td>missing explicit constructors in public and protected classes
172 * in exported packages
173 * <tr><th scope="row">{@code module} <td>module system related issues
174 * <tr><th scope="row">{@code opens} <td>issues regarding module opens
175 * <tr><th scope="row">{@code overloads} <td>issues regarding method overloads
176 * <tr><th scope="row">{@code overrides} <td>issues regarding method overrides
177 * <tr><th scope="row">{@code preview} <td>use of preview language features
178 * <tr><th scope="row">{@code rawtypes} <td>use of raw types
179 * <tr><th scope="row">{@code removal} <td>use of API that has been marked for removal
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 restricted} <td>use of restricted methods
183 * <tr><th scope="row">{@code serial} <td>{@link java.base/java.io.Serializable Serializable} classes
184 * that do not have a {@code serialVersionUID} field, or other
185 * suspect declarations in {@code Serializable} and
186 * {@link java.base/java.io.Externalizable Externalizable} classes
187 * and interfaces
188 * <tr><th scope="row">{@code static} <td>accessing a static member using an instance
189 * <tr><th scope="row">{@code strictfp} <td>unnecessary use of the {@code strictfp} modifier
190 * <tr><th scope="row">{@code synchronization} <td>deprecated alias for {@code identity} with an identical effect.
191 * Users are encouraged to use {@code identity} instead of
192 * {@code synchronization} for all current and future uses.
193 * <tr><th scope="row">{@code text-blocks} <td>inconsistent white space characters in text block indentation
194 * <tr><th scope="row">{@code this-escape} <td>superclass constructor leaking {@code this} before subclass initialized
195 * <tr><th scope="row">{@code try} <td>issues relating to use of {@code try} blocks
196 * (that is, try-with-resources)
197 * <tr><th scope="row">{@code unchecked} <td>unchecked operations
198 * <tr><th scope="row">{@code varargs} <td>potentially unsafe vararg methods
199 * <tr><th scope="row">{@code doclint:accessibility} <td>accessibility issues found in documentation comments
200 * <tr><th scope="row">{@code doclint:all} <td>all issues found in documentation comments
201 * <tr><th scope="row">{@code doclint:html} <td>HTML issues found in documentation comments
202 * <tr><th scope="row">{@code doclint:missing} <td>missing items in documentation comments
203 * <tr><th scope="row">{@code doclint:reference} <td>reference issues found in documentation comments
204 * <tr><th scope="row">{@code doclint:syntax} <td>syntax issues found in documentation comments
205 * </tbody>
206 * </table>
207 *
208 * All of the non-{@code docllint:} strings listed above may also be used with the {@code -Xlint} command line flag.
209 * The {@code -Xlint} flag also supports these strings not supported by {@code @SuppressWarnings}:
210 *
211 * <table class="striped">
212 * <caption>Strings supported by {@code -Xlint} but not {@code SuppressWarnings}</caption>
213 * <thead>
214 * <tr><th>String<th>Warnings Related To ...
215 * </thead>
216 * <tbody>
217 * <tr><th scope="row">{@code classfile} <td>issues related to classfile contents
218 * <tr><th scope="row">{@code incubating} <td>use of incubating modules
219 * <tr><th scope="row">{@code options} <td>issues relating to use of command line options
220 * <tr><th scope="row">{@code output-file-clash} <td>output files being overwritten due to filename clashes
221 * <tr><th scope="row">{@code path} <td>invalid path elements on the command line
222 * <tr><th scope="row">{@code processing} <td>issues regarding annotation processing
223 * <tr><th scope="row">{@code restricted} <td>use of restricted methods
224 * </tbody>
225 * </table>
226 *
227 * @toolGuide javac
228 *
229 * @provides java.util.spi.ToolProvider
230 * Use {@link java.util.spi.ToolProvider#findFirst ToolProvider.findFirst("javac")}
231 * to obtain an instance of a {@code ToolProvider} that provides the equivalent
232 * of command-line access to the {@code javac} tool.
233 * @provides com.sun.tools.javac.platform.PlatformProvider
234 * @provides javax.tools.JavaCompiler
235 * @provides javax.tools.Tool
236 *
237 * @uses javax.annotation.processing.Processor
238 * @uses com.sun.source.util.Plugin
239 * @uses com.sun.tools.javac.platform.PlatformProvider
240 *
241 * @moduleGraph
242 * @since 9
243 */
244 module jdk.compiler {
245 requires transitive java.compiler;
246 requires jdk.internal.opt;
247 requires jdk.zipfs;
248
249 exports com.sun.source.doctree;
250 exports com.sun.source.tree;
251 exports com.sun.source.util;
252 exports com.sun.tools.javac;
253
254 exports com.sun.tools.doclint to
255 jdk.javadoc;
256 exports com.sun.tools.javac.api to
257 jdk.javadoc,
258 jdk.jshell,
259 jdk.internal.md,
260 jdk.incubator.code;
261 exports com.sun.tools.javac.resources to
262 jdk.jshell, jdk.incubator.code;
263 exports com.sun.tools.javac.code to
264 jdk.javadoc,
265 jdk.jshell,
266 jdk.incubator.code;
267 exports com.sun.tools.javac.comp to
268 jdk.javadoc,
269 jdk.jshell,
270 jdk.incubator.code;
271 exports com.sun.tools.javac.file to
272 jdk.jdeps,
273 jdk.javadoc;
274 exports com.sun.tools.javac.jvm to
275 jdk.javadoc,
276 jdk.incubator.code;
277 exports com.sun.tools.javac.main to
278 jdk.javadoc,
279 jdk.jshell,
280 jdk.incubator.code;
281 exports com.sun.tools.javac.model to
282 jdk.javadoc,
283 jdk.incubator.code;
284 exports com.sun.tools.javac.parser to
285 jdk.jshell,
286 jdk.internal.md;
287 exports com.sun.tools.javac.platform to
288 jdk.jdeps,
289 jdk.javadoc;
290 exports com.sun.tools.javac.tree to
291 jdk.javadoc,
292 jdk.jshell,
293 jdk.internal.md,
294 jdk.incubator.code;
295 exports com.sun.tools.javac.util to
296 jdk.jdeps,
297 jdk.javadoc,
298 jdk.jshell,
299 jdk.internal.md,
300 jdk.incubator.code;
301 exports com.sun.tools.javac.processing to
302 jdk.incubator.code;
303
304 uses javax.annotation.processing.Processor;
305 uses com.sun.source.util.Plugin;
306 uses com.sun.tools.doclint.DocLint;
307 uses com.sun.tools.javac.platform.PlatformProvider;
308 uses com.sun.tools.javac.api.JavacTrees.DocCommentTreeTransformer;
309 uses CodeReflectionTransformer;
310
311 provides java.util.spi.ToolProvider with
312 com.sun.tools.javac.main.JavacToolProvider;
313
314 provides com.sun.tools.javac.platform.PlatformProvider with
315 com.sun.tools.javac.platform.JDKPlatformProvider;
316
317 provides javax.tools.JavaCompiler with
318 com.sun.tools.javac.api.JavacTool;
319
320 provides javax.tools.Tool with
321 com.sun.tools.javac.api.JavacTool;
322 }
323