1 /* 2 * Copyright (c) 2014, 2023, 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 deprecation} <td>use of deprecated items 157 * <tr><th scope="row">{@code dep-ann} <td>items marked as deprecated in a documentation comment but not 158 * using the {@code @Deprecated} annotation 159 * <tr><th scope="row">{@code divzero} <td>division by constant integer {@code 0} 160 * <tr><th scope="row">{@code empty} <td>empty statement after {@code if} 161 * <tr><th scope="row">{@code exports} <td>issues regarding module exports 162 * <tr><th scope="row">{@code fallthrough} <td>falling through from one case of a {@code switch} statement to 163 * the next 164 * <tr><th scope="row">{@code finally} <td>{@code finally} clauses that do not terminate normally 165 * <tr><th scope="row">{@code incubating} <td>use of incubating modules 166 * <tr><th scope="row">{@code lossy-conversions} <td>possible lossy conversions in compound assignment 167 * <tr><th scope="row">{@code missing-explicit-ctor} <td>missing explicit constructors in public and protected classes 168 * in exported packages 169 * <tr><th scope="row">{@code module} <td>module system related issues 170 * <tr><th scope="row">{@code opens} <td>issues regarding module opens 171 * <tr><th scope="row">{@code overloads} <td>issues regarding method overloads 172 * <tr><th scope="row">{@code overrides} <td>issues regarding method overrides 173 * <tr><th scope="row">{@code path} <td>invalid path elements on the command line 174 * <tr><th scope="row">{@code preview} <td>use of preview language features 175 * <tr><th scope="row">{@code rawtypes} <td>use of raw types 176 * <tr><th scope="row">{@code removal} <td>use of API that has been marked for removal 177 * <tr><th scope="row">{@code restricted} <td>use of restricted methods 178 * <tr><th scope="row">{@code requires-automatic} <td>use of automatic modules in the {@code requires} clauses 179 * <tr><th scope="row">{@code requires-transitive-automatic} <td>automatic modules in {@code requires transitive} 180 * <tr><th scope="row">{@code serial} <td>{@link java.base/java.io.Serializable Serializable} classes 181 * that do not have a {@code serialVersionUID} field, or other 182 * suspect declarations in {@code Serializable} and 183 * {@link java.base/java.io.Externalizable Externalizable} classes 184 * and interfaces 185 * <tr><th scope="row">{@code static} <td>accessing a static member using an instance 186 * <tr><th scope="row">{@code strictfp} <td>unnecessary use of the {@code strictfp} modifier 187 * <tr><th scope="row">{@code synchronization} <td>synchronization attempts on instances of value-based classes 188 * <tr><th scope="row">{@code text-blocks} <td>inconsistent white space characters in text block indentation 189 * <tr><th scope="row">{@code this-escape} <td>superclass constructor leaking {@code this} before subclass initialized 190 * <tr><th scope="row">{@code try} <td>issues relating to use of {@code try} blocks 191 * (that is, try-with-resources) 192 * <tr><th scope="row">{@code unchecked} <td>unchecked operations 193 * <tr><th scope="row">{@code varargs} <td>potentially unsafe vararg methods 194 * <tr><th scope="row">{@code doclint:accessibility} <td>accessibility issues found in documentation comments 195 * <tr><th scope="row">{@code doclint:all} <td>all issues found in documentation comments 196 * <tr><th scope="row">{@code doclint:html} <td>HTML issues found in documentation comments 197 * <tr><th scope="row">{@code doclint:missing} <td>missing items in documentation comments 198 * <tr><th scope="row">{@code doclint:reference} <td>reference issues found in documentation comments 199 * <tr><th scope="row">{@code doclint:syntax} <td>syntax issues found in documentation comments 200 * </tbody> 201 * </table> 202 * 203 * @toolGuide javac 204 * 205 * @provides java.util.spi.ToolProvider 206 * Use {@link java.util.spi.ToolProvider#findFirst ToolProvider.findFirst("javac")} 207 * to obtain an instance of a {@code ToolProvider} that provides the equivalent 208 * of command-line access to the {@code javac} tool. 209 * @provides com.sun.tools.javac.platform.PlatformProvider 210 * @provides javax.tools.JavaCompiler 211 * @provides javax.tools.Tool 212 * 213 * @uses javax.annotation.processing.Processor 214 * @uses com.sun.source.util.Plugin 215 * @uses com.sun.tools.javac.platform.PlatformProvider 216 * 217 * @moduleGraph 218 * @since 9 219 */ 220 module jdk.compiler { 221 requires transitive java.compiler; 222 requires jdk.internal.opt; 223 requires jdk.zipfs; 224 225 exports com.sun.source.doctree; 226 exports com.sun.source.tree; 227 exports com.sun.source.util; 228 exports com.sun.tools.javac; 229 230 exports com.sun.tools.doclint to 231 jdk.javadoc; 232 exports com.sun.tools.javac.api to 233 jdk.javadoc, 234 jdk.jshell; 235 exports com.sun.tools.javac.resources to 236 jdk.jshell; 237 exports com.sun.tools.javac.code to 238 jdk.javadoc, 239 jdk.jshell; 240 exports com.sun.tools.javac.comp to 241 jdk.javadoc, 242 jdk.jshell; 243 exports com.sun.tools.javac.file to 244 jdk.jdeps, 245 jdk.javadoc; 246 exports com.sun.tools.javac.jvm to 247 jdk.javadoc; 248 exports com.sun.tools.javac.main to 249 jdk.javadoc, 250 jdk.jshell; 251 exports com.sun.tools.javac.model to 252 jdk.javadoc; 253 exports com.sun.tools.javac.parser to 254 jdk.jshell; 255 exports com.sun.tools.javac.platform to 256 jdk.jdeps, 257 jdk.javadoc; 258 exports com.sun.tools.javac.tree to 259 jdk.javadoc, 260 jdk.jshell; 261 exports com.sun.tools.javac.util to 262 jdk.jdeps, 263 jdk.javadoc, 264 jdk.jshell; 265 exports jdk.internal.shellsupport.doc to 266 jdk.jshell; 267 268 uses javax.annotation.processing.Processor; 269 uses com.sun.source.util.Plugin; 270 uses com.sun.tools.doclint.DocLint; 271 uses com.sun.tools.javac.platform.PlatformProvider; 272 273 provides java.util.spi.ToolProvider with 274 com.sun.tools.javac.main.JavacToolProvider; 275 276 provides com.sun.tools.javac.platform.PlatformProvider with 277 com.sun.tools.javac.platform.JDKPlatformProvider; 278 279 provides javax.tools.JavaCompiler with 280 com.sun.tools.javac.api.JavacTool; 281 282 provides javax.tools.Tool with 283 com.sun.tools.javac.api.JavacTool; 284 } 285