jdk

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

26
import javax.tools.JavaCompiler;
27
import 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
 */
222
module jdk.compiler {
223
    requires transitive java.compiler;
224
    requires jdk.internal.opt;
225
    requires jdk.zipfs;
226

227
    exports com.sun.source.doctree;
228
    exports com.sun.source.tree;
229
    exports com.sun.source.util;
230
    exports com.sun.tools.javac;
231

232
    exports com.sun.tools.doclint to
233
        jdk.javadoc;
234
    exports com.sun.tools.javac.api to
235
        jdk.javadoc,
236
        jdk.jshell,
237
        jdk.internal.md;
238
    exports com.sun.tools.javac.resources to
239
        jdk.jshell;
240
    exports com.sun.tools.javac.code to
241
        jdk.javadoc,
242
        jdk.jshell;
243
    exports com.sun.tools.javac.comp to
244
        jdk.javadoc,
245
        jdk.jshell;
246
    exports com.sun.tools.javac.file to
247
        jdk.jdeps,
248
        jdk.javadoc;
249
    exports com.sun.tools.javac.jvm to
250
        jdk.javadoc;
251
    exports com.sun.tools.javac.main to
252
        jdk.javadoc,
253
        jdk.jshell;
254
    exports com.sun.tools.javac.model to
255
        jdk.javadoc;
256
    exports com.sun.tools.javac.parser to
257
        jdk.jshell,
258
        jdk.internal.md;
259
    exports com.sun.tools.javac.platform to
260
        jdk.jdeps,
261
        jdk.javadoc;
262
    exports com.sun.tools.javac.tree to
263
        jdk.javadoc,
264
        jdk.jshell,
265
        jdk.internal.md;
266
    exports com.sun.tools.javac.util to
267
        jdk.jdeps,
268
        jdk.javadoc,
269
        jdk.jshell,
270
        jdk.internal.md;
271

272
    uses javax.annotation.processing.Processor;
273
    uses com.sun.source.util.Plugin;
274
    uses com.sun.tools.doclint.DocLint;
275
    uses com.sun.tools.javac.platform.PlatformProvider;
276
    uses com.sun.tools.javac.api.JavacTrees.DocCommentTreeTransformer;
277

278
    provides java.util.spi.ToolProvider with
279
        com.sun.tools.javac.main.JavacToolProvider;
280

281
    provides com.sun.tools.javac.platform.PlatformProvider with
282
        com.sun.tools.javac.platform.JDKPlatformProvider;
283

284
    provides javax.tools.JavaCompiler with
285
        com.sun.tools.javac.api.JavacTool;
286

287
    provides javax.tools.Tool with
288
        com.sun.tools.javac.api.JavacTool;
289
}
290

291