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 jdk.incubator.code; 275 exports com.sun.tools.javac.jvm to 276 jdk.javadoc, 277 jdk.incubator.code; 278 exports com.sun.tools.javac.main to 279 jdk.javadoc, 280 jdk.jshell, 281 jdk.incubator.code; 282 exports com.sun.tools.javac.model to 283 jdk.javadoc, 284 jdk.incubator.code; 285 exports com.sun.tools.javac.parser to 286 jdk.jshell, 287 jdk.internal.md; 288 exports com.sun.tools.javac.platform to 289 jdk.jdeps, 290 jdk.javadoc; 291 exports com.sun.tools.javac.tree to 292 jdk.javadoc, 293 jdk.jshell, 294 jdk.internal.md, 295 jdk.incubator.code; 296 exports com.sun.tools.javac.util to 297 jdk.jdeps, 298 jdk.javadoc, 299 jdk.jshell, 300 jdk.internal.md, 301 jdk.incubator.code; 302 exports com.sun.tools.javac.processing to 303 jdk.incubator.code; 304 305 uses javax.annotation.processing.Processor; 306 uses com.sun.source.util.Plugin; 307 uses com.sun.tools.doclint.DocLint; 308 uses com.sun.tools.javac.platform.PlatformProvider; 309 uses com.sun.tools.javac.api.JavacTrees.DocCommentTreeTransformer; 310 uses CodeReflectionTransformer; 311 312 provides java.util.spi.ToolProvider with 313 com.sun.tools.javac.main.JavacToolProvider; 314 315 provides com.sun.tools.javac.platform.PlatformProvider with 316 com.sun.tools.javac.platform.JDKPlatformProvider; 317 318 provides javax.tools.JavaCompiler with 319 com.sun.tools.javac.api.JavacTool; 320 321 provides javax.tools.Tool with 322 com.sun.tools.javac.api.JavacTool; 323 } 324 --- EOF ---