1 --- 2 # Copyright (c) 1994, 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. 8 # 9 # This code is distributed in the hope that it will be useful, but WITHOUT 10 # ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 11 # FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 12 # version 2 for more details (a copy is included in the LICENSE file that 13 # accompanied this code). 14 # 15 # You should have received a copy of the GNU General Public License version 16 # 2 along with this work; if not, write to the Free Software Foundation, 17 # Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 18 # 19 # Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 20 # or visit www.oracle.com if you need additional information or have any 21 # questions. 22 # 23 24 title: 'JAVAC(1) JDK @@VERSION_SHORT@@ | JDK Commands' 25 date: @@COPYRIGHT_YEAR@@ 26 lang: en 27 --- 28 29 ## Name 30 31 javac - read Java declarations and compile them into class files 32 33 ## Synopsis 34 35 `javac` \[*options*\] \[*sourcefiles-or-classnames*\] 36 37 *options* 38 : Command-line options. 39 40 *sourcefiles-or-classnames* 41 : Source files to be compiled (for example, `Shape.java`) or 42 the names of previously compiled classes to be processed for annotations 43 (for example, `geometry.MyShape`). 44 45 ## Description 46 47 The `javac` command reads _source files_ that contain module, package and type 48 declarations written in the Java programming language, and compiles them into _class files_ 49 that run on the Java Virtual Machine. 50 51 The `javac` command can also [process annotations](#annotation-processing) 52 in Java source files and classes. 53 54 Source files must have a file name extension of `.java`. 55 Class files have a file name extension of `.class`. 56 Both source and class files normally have file names that identify the contents. 57 For example, a class called `Shape` would be declared in a source file 58 called `Shape.java`, and compiled into a class file called `Shape.class`. 59 60 There are two ways to specify source files to `javac`: 61 62 - For a small number of source files, you can list their file names on 63 the command line. 64 65 - For a large number of source files, you can use the [`@`*filename*](#option-at) 66 option on the command line to specify an _argument file_ that lists 67 their file names. See [Standard Options] for a description of the 68 option and [Command-Line Argument Files] for a description of 69 `javac` argument files. 70 71 The order of source files specified on the command line or in an 72 argument file is not important. `javac` will compile the files together, 73 as a group, and will automatically resolve any dependencies between 74 the declarations in the various source files. 75 76 `javac` expects that source files are arranged in one or more directory 77 hierarchies on the file system, described in [Arrangement of Source 78 Code]. 79 80 To compile a source file, `javac` needs to find the declaration of 81 every class or interface that is used, extended, or implemented by the 82 code in the source file. This lets `javac` check that the code has the 83 right to access those classes and interfaces. Rather than specifying 84 the source files of those classes and interfaces explicitly, you can 85 use command-line options to tell `javac` where to search for their 86 source files. If you have compiled those source files previously, you 87 can use options to tell `javac` where to search for the corresponding 88 class files. The options, which all have names ending in "path", are 89 described in [Standard Options], and further described in 90 [Configuring a Compilation] and [Searching for Module, Package and Type Declarations]. 91 92 By default, `javac` compiles each source file to a class file in the 93 same directory as the source file. However, it is recommended to 94 specify a separate destination directory with the [`-d`](#option-d) option. 95 96 Command-line [options] and [environment variables] also control how 97 `javac` performs various tasks: 98 99 - Compiling code to run on earlier releases of the JDK. 100 - Compiling code to run under a debugger. 101 - Checking for stylistic issues in Java source code. 102 - Checking for problems in `javadoc` comments (`/** ... */`). 103 - Processing annotations in source files and class files. 104 - Upgrading and patching modules in the compile-time environment. 105 106 `javac` supports [Compiling for Earlier Releases Of The Platform] 107 and can also be invoked from Java code using one of a number of [APIs] 108 109 ## Options 110 111 `javac` provides [standard options], and [extra options] that are either 112 non-standard or are for advanced use. 113 114 Some options take one or more arguments. 115 If an argument contains spaces or other whitespace characters, 116 the value should be quoted according to the conventions of the 117 environment being used to invoke javac. 118 If the option begins with a single dash (`-`) the argument should 119 either directly follow the option name, or should be separated with a 120 colon (`:`) or whitespace, depending on the option. If the option begins with 121 a double dash (`--`), the argument may be separated either by whitespace 122 or by an equals (`=`) character with no additional whitespace. 123 For example, 124 125 -Aname="J. Duke" 126 -proc:only 127 -d myDirectory 128 --module-version 3 129 --module-version=3 130 131 In the following lists of options, an argument of *path* represents 132 a search path, composed of a list of file system locations separated 133 by the platform path separator character, (semicolon `;` on Windows, 134 or colon `:` on other systems.) Depending on the option, the 135 file system locations may be directories, JAR files or JMOD files. 136 137 ### Standard Options 138 139 <a id="option-at">`@`*filename*</a> 140 : Reads options and file names from a file. To shorten or simplify the 141 `javac` command, you can specify one or more files that contain arguments 142 to the `javac` command (except [`-J`](#option-J) options). This lets you to create 143 `javac` commands of any length on any operating system. 144 See [Command-Line Argument Files]. 145 146 <a id="option-A">`-A`*key*\[`=`*value*\]</a> 147 : Specifies options to pass to annotation processors. These options are not 148 interpreted by `javac` directly, but are made available for use by 149 individual processors. The *key* value should be one or more identifiers 150 separated by a dot (`.`). 151 152 <a id="option-add-modules">`--add-modules` *module*`,`*module*</a> 153 : Specifies root modules to resolve in addition to the initial modules, or 154 all modules on the module path if *module* is `ALL-MODULE-PATH`. 155 156 <a id="option-boot-class-path">`--boot-class-path` *path* or `-bootclasspath` *path*</a> 157 : Overrides the location of the bootstrap class files. 158 159 **Note:** This can only be used when compiling for releases prior to JDK 9. 160 As applicable, see the descriptions in [`--release`](#option-release), [`-source`](#option-source), or 161 [`-target`](#option-target) for details. For JDK 9 or later, see [`--system`](#option-system). 162 163 <a id="option-class-path">`--class-path` *path*, `-classpath` *path*, or `-cp` *path*</a> 164 : Specifies where to find user class files and annotation processors. This 165 class path overrides the user class path in the `CLASSPATH` environment 166 variable. 167 168 - If `--class-path`, `-classpath`, or `-cp` are not specified, then the 169 user class path is the value of the `CLASSPATH` environment variable, 170 if that is set, or else the current directory. 171 172 - If not compiling code for modules, if the [`--source-path`](#option-source-path) or -sourcepath` 173 option is not specified, then the user class path is also searched for source files. 174 175 - If the [`-processorpath`](#option-processor-path) option is not specified, then the class path is 176 also searched for annotation processors. 177 178 <a id="option-d">`-d` *directory*</a> 179 : Sets the destination directory (or _class output directory_) for class files. 180 If a class is part of a package, then `javac` puts the class file in a 181 subdirectory that reflects the module name (if appropriate) and package name. 182 The directory, and any necessary subdirectories, will be created if they 183 do not already exist. 184 185 If the `-d` option is not specified, then `javac` puts each class file in 186 the same directory as the source file from which it was generated. 187 188 Except when compiling code for multiple modules, the contents of the 189 class output directory will be organized in a package hierarchy. 190 When compiling code for multiple modules, the contents of the output 191 directory will be organized in a module hierarchy, with the contents of each 192 module in a separate subdirectory, each organized as a package 193 hierarchy. 194 195 **Note:** 196 When compiling code for one or more modules, the class output directory will 197 automatically be checked when searching for previously compiled classes. 198 When not compiling for modules, for backwards compatibility, 199 the directory is _not_ automatically checked for previously compiled classes, 200 and so it is recommended to specify the class output directory as one 201 of the locations on the user class path, using the `--class-path` option or one of 202 its alternate forms. 203 204 <a id="option-deprecation">`-deprecation`</a> 205 : Shows a description of each use or override of a deprecated member or 206 class. Without the `-deprecation` option, `javac` shows a summary of the 207 source files that use or override deprecated members or classes. The 208 `-deprecation` option is shorthand for `-Xlint:deprecation`. 209 210 <a id="option-enable-preview">`--enable-preview`</a> 211 : Enables preview language features. Used in conjunction with either 212 [`-source`](#option-source) or [`--release`](#option-release). 213 214 <a id="option-encoding">`-encoding` *encoding*</a> 215 : Specifies character encoding used by source files, such as EUC-JP and 216 UTF-8. If the `-encoding` option is not specified, then the platform default 217 converter is used. 218 219 <a id="option-endorseddirs">`-endorseddirs` *directories*</a> 220 : Overrides the location of the endorsed standards path. 221 222 **Note:** This can only be used when compiling for releases prior to JDK 9. 223 As applicable, see the descriptions in [`--release`](#option-release), [`-source`](#option-source), or 224 [`-target`](#option-target) for details. 225 226 <a id="option-extdirs">`-extdirs` *directories*</a> 227 : Overrides the location of the installed extensions. 228 `directories` is a list of directories, separated by the platform path separator 229 (`;` on Windows, and `:` otherwise). 230 Each JAR file in the specified directories is searched for class files. 231 All JAR files found become part of the class path. 232 233 If you are compiling for a release of the platform that supports the 234 Extension Mechanism, then this option specifies the directories that 235 contain the extension classes. 236 See [Compiling for Other Releases of the Platform]. 237 238 **Note:** This can only be used when compiling for releases prior to JDK 9. 239 As applicable, see the descriptions in [`--release`](#option-release), [`-source`](#option-source), or 240 [`-target`](#option-target) for details. 241 242 <a id="option-g">`-g`</a> 243 : Generates all debugging information, including local variables. By default, 244 only line number and source file information is generated. 245 246 <a id="option-g-custom">`-g:`\[`lines`, `vars`, `source`\]</a> 247 : Generates only the kinds of debugging information specified by the 248 comma-separated list of keywords. Valid keywords are: 249 250 `lines` 251 : Line number debugging information. 252 253 `vars` 254 : Local variable debugging information. 255 256 `source` 257 : Source file debugging information. 258 259 <a id="option-g-none">`-g:none`</a> 260 : Does not generate debugging information. 261 262 <a id="option-h">`-h` *directory*</a> 263 : Specifies where to place generated native header files. 264 265 When you specify this option, a native header file is generated for each 266 class that contains native methods or that has one or more constants 267 annotated with the [`java.lang.annotation.Native`]( 268 ../../api/java.base/java/lang/annotation/Native.html) 269 annotation. If the class is part of a package, then the compiler puts the 270 native header file in a subdirectory that reflects the module name 271 (if appropriate) and package name. 272 The directory, and any necessary subdirectories, will be created if they 273 do not already exist. 274 275 <a id="option-help">`--help`, `-help` or `-?`</a> 276 : Prints a synopsis of the standard options. 277 278 <a id="option-help-extra">`--help-extra` or `-X`</a> 279 : Prints a synopsis of the set of extra options. 280 281 <a id="option-help-lint">`--help-lint`</a> 282 : Prints the supported keys for the `-Xlint` option. 283 284 <a id="option-implicit">`-implicit:`\[`none`, `class`\]</a> 285 : Specifies whether or not to generate class files for implicitly referenced 286 files: 287 288 - `-implicit:class` --- Automatically generates class files. 289 290 - `-implicit:none` --- Suppresses class file generation. 291 292 If this option is not specified, then the default automatically generates 293 class files. In this case, the compiler issues a warning if any class files 294 are generated when also doing annotation processing. The warning is not 295 issued when the `-implicit` option is explicitly set. 296 See [Searching for Module, Package and Type Declarations]. 297 298 <a id="option-J">`-J`*option*</a> 299 : Passes *option* to the runtime system, where *option* is one of the Java 300 options described on [java](java.html) command. For example, `-J-Xms48m` 301 sets the startup memory to 48 MB. 302 303 **Note:** The `CLASSPATH` environment variable, `-classpath` option, `-bootclasspath` 304 option, and `-extdirs` option do not specify the classes used to run 305 `javac`. Trying to customize the compiler implementation with these options 306 and variables is risky and often does not accomplish what you want. If you 307 must customize the compiler implementation, then use the `-J` option to 308 pass options through to the underlying Java launcher. 309 310 <a id="option-limit-modules">`--limit-modules` *module*`,`*module*\*</a> 311 : Limits the universe of observable modules. 312 313 <a id="option-module">`--module` *module-name* (`,`*module-name*)* or `-m` *module-name* (`,`*module-name*)*</a> 314 : Compiles those source files in the named modules that are newer 315 than the corresponding files in the output directory. 316 317 <a id="option-module-path">`--module-path` *path* or `-p` *path*</a> 318 : Specifies where to find application modules. 319 320 <a id="option-module-source-path">`--module-source-path` *module-source-path*</a> 321 : Specifies where to find source files when compiling code 322 in multiple modules. See [The Module Source Path Option]. 323 324 <a id="option-module-version">`--module-version` *version*</a> 325 : Specifies the version of modules that are being compiled. 326 327 <a id="option-nowarn">`-nowarn`</a> 328 : Generate only mandatory warnings. 329 330 <a id="option-parameters">`-parameters`</a> 331 : Generates metadata for reflection on method parameters. Stores formal 332 parameter names of constructors and methods in the generated class file so 333 that the method `java.lang.reflect.Executable.getParameters` from the 334 Reflection API can retrieve them. 335 336 <a id="option-proc">`-proc:`\[`none`, `only`, `full`\]</a> 337 : Controls whether annotation processing and compilation are done. 338 339 - `-proc:none` means that compilation takes place without annotation 340 processing 341 342 - `-proc:only` means that only annotation processing is done, 343 without any subsequent compilation. 344 345 - `-proc:full` means annotation processing and compilation are done. 346 347 If this option is not used, annotation processing and compilation 348 are done if at least one other option is used to explicitly 349 configure annotation processing. 350 351 <a id="option-processor">`-processor` *class1*\[`,`*class2*`,`*class3*...\]</a> 352 : Names of the annotation processors to run. This bypasses the default 353 discovery process. 354 355 <a id="option-processor-module-path">`--processor-module-path` *path*</a> 356 : Specifies the module path used for finding annotation processors. 357 358 <a id="option-processor-path">`--processor-path` *path* or `-processorpath` *path*</a> 359 : Specifies where to find annotation processors. If this option is not used, 360 then the class path is searched for processors. 361 362 <a id="option-profile">`-profile` *profile*</a> 363 : Checks that the API used is available in the specified profile. 364 This option is deprecated and may be removed in a future release. 365 366 **Note:** This can only be used when compiling for releases prior to JDK 9. 367 As applicable, see the descriptions in [`--release`](#option-release), [`-source`](#option-source), 368 or [`-target`](#option-target) for details. 369 370 <a id="option-release">`--release` *release*</a> 371 : Compiles source code according to the rules of the Java programming language 372 for the specified Java SE release, generating class files which target 373 that release. 374 Source code is compiled against the combined Java SE and JDK API for the 375 specified release. 376 377 The supported values of *release* are the current Java SE release and a 378 limited number of previous releases, detailed in the command-line help. 379 380 For the current release, the Java SE API consists of the `java.*`, 381 `javax.*`, and `org.*` packages that are exported by the Java SE modules in 382 the release; the JDK API consists of the `com.*` and `jdk.*` packages that 383 are exported by the JDK modules in the release, plus the `javax.*` packages 384 that are exported by standard, but non-Java SE, modules in the release. 385 386 For previous releases, the Java SE API and the JDK API are as defined in 387 that release. 388 389 **Note:** When using `--release`, you cannot also use the [`--source`](#option-source)/`-source` or 390 [`--target`](#option-target)/`-target` options. 391 392 **Note:** When using `--release` to specify a release that supports the Java 393 Platform Module System, the `--add-exports` option cannot be used to 394 enlarge the set of packages exported by the Java SE, JDK, and standard 395 modules in the specified release. 396 397 <a id="option-s">`-s` *directory*</a> 398 : Specifies the directory used to place the generated source files. If a 399 class is part of a package, then the compiler puts the source file in a 400 subdirectory that reflects the module name (if appropriate) and package name. 401 The directory, and any necessary subdirectories, will be created if they 402 do not already exist. 403 404 Except when compiling code for multiple modules, the contents of the 405 source output directory will be organized in a package hierarchy. 406 When compiling code for multiple modules, the contents of the source output directory will be 407 organized in a module hierarchy, with the contents of each 408 module in a separate subdirectory, each organized as a package 409 hierarchy. 410 411 <a id="option-source">`--source` *release* or `-source` *release*</a> 412 : Compiles source code according to the rules of the Java programming language 413 for the specified Java SE release. 414 The supported values of *release* are the current Java SE release and a 415 limited number of previous releases, detailed in the command-line help. 416 417 If the option is not specified, the default is to compile source code 418 according to the rules of the Java programming language for the current 419 Java SE release. 420 421 <a id="option-source-path">`--source-path` *path* or `-sourcepath` *path*</a> 422 : Specifies where to find source files. 423 Except when compiling multiple modules together, this is the source code path 424 used to search for class or interface definitions. 425 426 **Note:** Classes found through the class path might be recompiled when their source 427 files are also found. See [Searching for Module, Package and Type Declarations]. 428 429 <a id="option-system">`--system` *jdk* \| `none`</a> 430 : Overrides the location of system modules. 431 432 <a id="option-target">`--target` *release* or `-target` *release*</a> 433 : Generates `class` files suitable for the specified Java SE release. 434 The supported values of *release* are the current Java SE release and a 435 limited number of previous releases, detailed in the command-line help. 436 437 **Note:** The target release must be equal to or higher than the source release. 438 (See [`--source`](#option-source).) 439 440 <a id="option-upgrade-module-path">`--upgrade-module-path` *path*</a> 441 : Overrides the location of upgradeable modules. 442 443 <a id="option-verbose">`-verbose`</a> 444 : Outputs messages about what the compiler is doing. Messages include 445 information about each class loaded and each source file compiled. 446 447 <a id="option-version">`--version` or `-version`</a> 448 : Prints version information. 449 450 <a id="option-Werror">`-Werror`</a> 451 : Terminates compilation when warnings occur. 452 453 ### Extra Options 454 455 <a id="option-add-exports">`--add-exports` *module*`/`*package*`=`*other-module*(`,`*other-module*)\*</a> 456 : Specifies a package to be considered as exported from its defining module 457 to additional modules or to all unnamed modules when the value of 458 *other-module* is `ALL-UNNAMED`. 459 460 <a id="option-add-reads">`--add-reads` *module*`=`*other-module*(`,`*other-module*)\*</a> 461 : Specifies additional modules to be considered as required by a given 462 module. 463 464 <a id="option-default-module-for-created-files">`--default-module-for-created-files` *module-name*</a> 465 : Specifies the fallback target module for files created by annotation 466 processors, if none is specified or inferred. 467 468 <a id="option-disable-line-doc-comments">`--disable-line-doc-comments`</a> 469 : Disables support for documentation comments with lines beginning ///. 470 471 <a id="option-Djava.endorsed.dirs">`-Djava.endorsed.dirs=`*dirs*</a> 472 : Overrides the location of the endorsed standards path. 473 474 **Note:** This can only be used when compiling for releases prior to JDK 9. 475 As applicable, see the descriptions in [`--release`](#option-release), [`-source`](#option-source), 476 or [`-target`](#option-target) for details. 477 478 <a id="option-Djava.ext.dirs">`-Djava.ext.dirs=`*dirs*</a> 479 : Overrides the location of installed extensions. 480 481 **Note:** This can only be used when compiling for releases prior to JDK 9. 482 As applicable, see the descriptions in [`--release`](#option-release), [`-source`](#option-source), 483 or [`-target`](#option-target) for details. 484 485 <a id="option-patch-module">`--patch-module` *module*`=`*path*</a> 486 : Overrides or augments a module with classes and resources in JAR files or 487 directories. 488 489 <a id="option-Xbootclasspath">`-Xbootclasspath:`*path*</a> 490 : Overrides the location of the bootstrap class files. 491 492 **Note:** This can only be used when compiling for releases prior to JDK 9. 493 As applicable, see the descriptions in [`--release`](#option-release), [`-source`](#option-source), 494 or [`-target`](#option-target) for details. 495 496 <a id="option-Xbootclasspath-a">`-Xbootclasspath/a:`*path*</a> 497 : Adds a suffix to the bootstrap class path. 498 499 **Note:** This can only be used when compiling for releases prior to JDK 9. 500 As applicable, see the descriptions in [`--release`](#option-release), [`-source`](#option-source), 501 or [`-target`](#option-target) for details. 502 503 <a id="option-Xbootclasspath-p">`-Xbootclasspath/p:`*path*</a> 504 : Adds a prefix to the bootstrap class path. 505 506 **Note:** This can only be used when compiling for releases prior to JDK 9. 507 As applicable, see the descriptions in [`--release`](#option-release), [`-source`](#option-source), 508 or [`-target`](#option-target) for details. 509 510 <a id="option-Xdiags">`-Xdiags:`\[`compact`, `verbose`\]</a> 511 : Selects a diagnostic mode. 512 513 <a id="option-Xdoclint">`-Xdoclint`</a> 514 : Enables recommended checks for problems in documentation comments. 515 516 <a id="option-Xdoclint-custom">`-Xdoclint:`(`all`|`none`|\[`-`\]*group*)\[`/`*access*\]</a> 517 : Enables or disables specific groups of checks in documentation comments. 518 519 *group* can have one of the following values: 520 `accessibility`, `html`, `missing`, `reference`, `syntax`. 521 522 The variable *access* specifies the minimum visibility level of classes and 523 members that the `-Xdoclint` option checks. It can have one of the 524 following values (in order of most to least visible): 525 `public`, `protected`, `package`, `private`. 526 527 The default *access* level is `private`. 528 529 When prefixed by `doclint:`, the *group* names and `all` can be used with `@SuppressWarnings` 530 to suppress warnings about documentation comments in parts of the code being compiled. 531 532 For more information about these groups of checks, see the [DocLint](javadoc.html#doclint) 533 section of the `javadoc` command documentation. 534 The `-Xdoclint` option is disabled by default in the `javac` command. 535 536 For example, the following option checks classes and members (with all 537 groups of checks) that have the access level of protected and higher (which 538 includes protected and public): 539 540 > `-Xdoclint:all/protected` 541 542 The following option enables all groups of checks for all access levels, 543 except it will not check for HTML errors for classes and members that have the 544 access level of package and higher (which includes package, protected and 545 public): 546 547 > `-Xdoclint:all,-html/package` 548 549 <a id="option-Xdoclint-package">`-Xdoclint/package:`\[`-`\]*packages*(`,`\[`-`\]*package*)\*</a> 550 : Enables or disables checks in specific packages. Each *package* is either 551 the qualified name of a package or a package name prefix followed by `.*`, 552 which expands to all sub-packages of the given package. Each *package* can 553 be prefixed with a hyphen (`-`) to disable checks for a specified package 554 or packages. 555 556 For more information, see the [DocLint](javadoc.html#doclint) 557 section of the `javadoc` command documentation. 558 559 <a id="option-Xlint">`-Xlint`</a> 560 : Enables all recommended warnings. In this release, enabling all available 561 warnings is recommended. 562 563 <a id="option-Xlint-custom">`-Xlint:`\[`-`\]*key*(`,`\[`-`\]*key*)\*</a> 564 : Enables and/or disables warning categories using the one or more of the keys described 565 below separated by commas. The keys `all` and `none` enable or disable all categories 566 (respectively); other keys enable the corresponding category, or disable it if preceded 567 by a hyphen (`-`). 568 569 Supported values for *key* are: 570 571 - `all`: Enables all warning categories. 572 573 - `auxiliaryclass`: Warns about an auxiliary class that is hidden in a 574 source file, and is used from other files. 575 576 - `cast`: Warns about the use of unnecessary casts. 577 578 - `classfile`: Warns about the issues related to classfile contents. 579 580 - `dangling-doc-comments`: Warns about extra or misplaced documentation 581 comments near the beginning of a declaration. 582 583 - `deprecation`: Warns about the use of deprecated items. 584 585 - `dep-ann`: Warns about the items marked as deprecated in `javadoc` but 586 without the `@Deprecated` annotation. 587 588 - `divzero`: Warns about the division by the constant integer 0. 589 590 - `empty`: Warns about an empty statement after `if`. 591 592 - `exports`: Warns about the issues regarding module exports. 593 594 - `fallthrough`: Warns about the falling through from one case of a 595 switch statement to the next. 596 597 - `finally`: Warns about `finally` clauses that do not terminate normally. 598 599 - `identity`: Warns about use of a value-based class where an identity 600 class is expected 601 602 - `incubating`: Warns about the use of incubating modules. 603 604 - `initialization`: Warns about code in identity classes that wouldn't be 605 allowed in early construction due to a `this` dependency. 606 607 - `lossy-conversions`: Warns about possible lossy conversions 608 in compound assignment. 609 610 - `missing-explicit-ctor`: Warns about missing explicit constructors in 611 public and protected classes in exported packages. 612 613 - `module`: Warns about the module system-related issues. 614 615 - `opens`: Warns about the issues related to module opens. 616 617 - `options`: Warns about the issues relating to use of command line 618 options. 619 620 - `output-file-clash`: Warns if any output file is overwritten during compilation. 621 This can occur, for example, on case-insensitive filesystems. 622 623 - `overloads`: Warns about the issues related to method overloads. 624 625 - `overrides`: Warns about the issues related to method overrides. 626 627 - `path`: Warns about the invalid path elements on the command line. 628 629 - `preview`: Warns about the use of preview language features. 630 631 - `processing`: Warns about the issues related to annotation processing. 632 633 - `rawtypes`: Warns about the use of raw types. 634 635 - `removal`: Warns about the use of an API that has been marked for 636 removal. 637 638 - `restricted`: Warns about the use of restricted methods. 639 640 - `requires-automatic`: Warns developers about the use of automatic 641 modules in requires clauses. 642 643 - `requires-transitive-automatic`: Warns about automatic modules in 644 requires transitive. 645 646 - `serial`: Warns about the serializable classes that do not provide a 647 serial version ID. Also warns about access to non-public members from a 648 serializable element. 649 650 - `static`: Warns about the accessing a static member using an instance. 651 652 - `strictfp`: Warns about unnecessary use of the `strictfp` modifier. 653 654 - `synchronization`: Warns about synchronization attempts on instances 655 of value-based classes. This key is a deprecated alias for `identity`, 656 which has the same uses and effects. Users are encouraged to use the 657 `identity` category for all future and existing uses of `synchronization`. 658 659 - `text-blocks`: Warns about inconsistent white space characters in text 660 block indentation. 661 662 - `this-escape`: Warns about constructors leaking `this` prior to subclass initialization. 663 664 - `try`: Warns about the issues relating to the use of try blocks (that 665 is, try-with-resources). 666 667 - `unchecked`: Warns about the unchecked operations. 668 669 - `varargs`: Warns about the potentially unsafe `vararg` methods. 670 671 - `none`: Disables all warning categories. 672 673 With the exception of `all` and `none`, the keys can be used with 674 the `@SuppressWarnings` annotation to suppress warnings in a part 675 of the source code being compiled. 676 677 See [Examples of Using -Xlint keys]. 678 679 <a id="option-Xmaxerrs">`-Xmaxerrs` *number*</a> 680 : Sets the maximum number of errors to print. 681 682 <a id="option-Xmaxwarns">`-Xmaxwarns` *number*</a> 683 : Sets the maximum number of warnings to print. 684 685 <a id="option-Xpkginfo">`-Xpkginfo:`\[`always`, `legacy`, `nonempty`\]</a> 686 : Specifies when and how the `javac` command generates `package-info.class` 687 files from `package-info.java` files using one of the following options: 688 689 `always` 690 : Generates a `package-info.class` file for every `package-info.java` 691 file. This option may be useful if you use a build system such as Ant, 692 which checks that each `.java` file has a corresponding `.class` file. 693 694 `legacy` 695 : Generates a `package-info.class` file only if `package-info.java` 696 contains annotations. This option does not generate a 697 `package-info.class` file if `package-info.java` contains only 698 comments. 699 700 **Note:** A `package-info.class` file might be generated but be empty if all the 701 annotations in the `package-info.java` file have 702 `RetentionPolicy.SOURCE`. 703 704 `nonempty` 705 : Generates a `package-info.class` file only if `package-info.java` 706 contains annotations with `RetentionPolicy.CLASS` or 707 `RetentionPolicy.RUNTIME`. 708 709 <a id="option-Xplugin">`-Xplugin:`*name* *args*</a> 710 : Specifies the name and optional arguments for a plug-in to be run. 711 If *args* are provided, *name* and *args* should be quoted or otherwise 712 escape the whitespace characters between the name and all the arguments. 713 For details on the API for a plugin, see the API documentation for 714 [jdk.compiler/com.sun.source.util.Plugin](../../api/jdk.compiler/com/sun/source/util/Plugin.html). 715 716 <a id="option-Xprefer">`-Xprefer:`\[`source`, `newer`\]</a> 717 : Specifies which file to read when both a source file and class file are 718 found for an implicitly compiled class using one of the following options. 719 See [Searching for Module, Package and Type Declarations]. 720 721 - `-Xprefer:newer`: Reads the newer of the source or class files for a 722 type (default). 723 724 - `-Xprefer:source` : Reads the source file. Use `-Xprefer:source` when 725 you want to be sure that any annotation processors can access 726 annotations declared with a retention policy of `SOURCE`. 727 728 <a id="option-Xprint">`-Xprint`</a> 729 : Prints a textual representation of specified types for debugging purposes. 730 This does not perform annotation processing or compilation. The format of 731 the output could change. 732 733 <a id="option-XprintProcessorInfo">`-XprintProcessorInfo`</a> 734 : Prints information about which annotations a processor is asked to process. 735 736 <a id="option-XprintRounds">`-XprintRounds`</a> 737 : Prints information about initial and subsequent annotation processing 738 rounds. 739 740 <a id="option-Xstdout">`-Xstdout` *filename*</a> 741 : Sends compiler messages to the named file. By default, compiler messages go 742 to `System.err`. 743 744 ## Environment Variables 745 746 ### CLASSPATH 747 748 If the [`--class-path`](#option-class-path) option or any of its alternate forms are not specified, 749 the class path will default to the value of the `CLASSPATH` environment 750 variable if it is set. 751 However, it is recommended that this environment variable should _not_ be set, 752 and that the `--class-path` option should be used to provide an explicit 753 value for the class path when one is required. 754 755 ### JDK\_JAVAC\_OPTIONS 756 757 The content of the `JDK_JAVAC_OPTIONS` environment variable, separated by 758 white-spaces ( ) or white-space characters (`\n`, `\t`, `\r`, or `\f`) is 759 prepended to the command line arguments passed to `javac` as a list of 760 arguments. 761 762 The encoding requirement for the environment variable is the same as the 763 `javac` command line on the system. `JDK_JAVAC_OPTIONS` environment variable 764 content is treated in the same manner as that specified in the command line. 765 766 Single quotes (`'`) or double quotes (`"`) can be used to enclose arguments 767 that contain whitespace characters. All content between the open quote and the 768 first matching close quote are preserved by simply removing the pair of quotes. 769 In case a matching quote is not found, the launcher will abort with an error 770 message. `@`*files* are supported as they are specified in the command line. 771 However, as in `@`*files*, use of a wildcard is not supported. 772 773 **Examples of quoting arguments containing white spaces:** 774 775 > `export JDK_JAVAC_OPTIONS='@"C:\white spaces\argfile"'` 776 777 > `export JDK_JAVAC_OPTIONS='"@C:\white spaces\argfile"'` 778 779 > `export JDK_JAVAC_OPTIONS='@C:\"white spaces"\argfile'` 780 781 ## Command-Line Argument Files 782 783 An argument file can include command-line options and source file names in any 784 combination. The arguments within a file can be separated by spaces or new line 785 characters. If a file name contains embedded spaces, then put the whole file 786 name in double quotation marks. 787 788 File names within an argument file are relative to the current directory, not 789 to the location of the argument file. Wildcards (`*`) are not allowed in these 790 lists (such as for specifying `*.java`). Use of the at sign (`@`) to 791 recursively interpret files is not supported. The `-J` options are not supported 792 because they're passed to the launcher, which does not support argument files. 793 794 When executing the `javac` command, pass in the path and name of each argument 795 file with the at sign (`@`) leading character. When the `javac` command 796 encounters an argument beginning with the at sign (`@`), it expands the 797 contents of that file into the argument list. 798 799 800 ### Examples of Using javac @filename 801 802 Single Argument File 803 : You could use a single argument file named `argfile` to hold all `javac` 804 arguments: 805 806 > `javac @argfile` 807 808 This argument file could contain the contents of both files shown in the 809 following **Two Argument Files** example. 810 811 Two Argument Files 812 : You can create two argument files: one for the `javac` options and the 813 other for the source file names. Note that the following lists have no 814 line-continuation characters. 815 816 Create a file named `options` that contains the following: 817 818 **Linux and macOS:** 819 820 ``` 821 -d classes 822 -g 823 -sourcepath /java/pubs/ws/1.3/src/share/classes 824 ``` 825 826 **Windows:** 827 828 ``` 829 -d classes 830 -g 831 -sourcepath C:\java\pubs\ws\1.3\src\share\classes 832 ``` 833 834 Create a file named `sources` that contains the following: 835 836 ``` 837 MyClass1.java 838 MyClass2.java 839 MyClass3.java 840 ``` 841 842 Then, run the `javac` command as follows: 843 844 > `javac @options @sources` 845 846 Argument Files with Paths 847 : The argument files can have paths, but any file names inside the files are 848 relative to the current working directory (not `path1` or `path2`): 849 850 > `javac @path1/options @path2/sources` 851 852 ## Arrangement of Source Code 853 854 In the Java language, classes and interfaces can be organized into 855 packages, and packages can be organized into modules. `javac` expects 856 that the physical arrangement of source files in directories of the 857 file system will mirror the organization of classes into packages, and 858 packages into modules. 859 860 It is a widely adopted convention that module names and package names 861 begin with a lower-case letter, and that class names begin with an 862 upper-case letter. 863 864 ### Arrangement of Source Code for a Package 865 866 When classes and interfaces are organized into a package, the package 867 is represented as a directory, and any subpackages are represented as 868 subdirectories. 869 870 For example: 871 872 - The package `p` is represented as a directory called `p`. 873 874 - The package `p.q` -- that is, the subpackage `q` of package `p` -- 875 is represented as the subdirectory `q` of directory `p`. The 876 directory tree representing package `p.q` is therefore `p\q` 877 on Windows, and `p/q` on other systems. 878 879 - The package `p.q.r` is represented as the directory tree `p\q\r` 880 (on Windows) or `p/q/r` (on other systems). 881 882 Within a directory or subdirectory, `.java` files represent classes 883 and interfaces in the corresponding package or subpackage. 884 885 For example: 886 887 - The class `X` declared in package `p` is represented by the file 888 `X.java` in the `p` directory. 889 890 - The class `Y` declared in package `p.q` is represented by the file 891 `Y.java` in the `q` subdirectory of directory `p`. 892 893 - The class `Z` declared in package `p.q.r` is represented by the file 894 `Z.java` in the `r` subdirectory of `p\q` (on Windows) or `p/q` 895 (on other systems). 896 897 In some situations, it is convenient to split the code into 898 separate directories, each structured as described above, and 899 the aggregate list of directories specified to `javac`. 900 901 ### Arrangement of Source Code for a Module 902 903 In the Java language, a module is a set of packages designed for 904 reuse. In addition to `.java` files for classes and interfaces, each 905 module has a source file called `module-info.java` which: 906 907 1. declares the module's name; 908 909 2. lists the packages exported by the module (to allow reuse by other 910 modules); 911 912 3. lists other modules required by the module (to reuse their exported 913 packages). 914 915 When packages are organized into a module, the module is represented 916 by one or more directories representing the packages in the module, 917 one of which contains the `module-info.java` file. It may be convenient, 918 but it is not required, to use a single directory, named after the module, 919 to contain the `module-info.java` file alongside the directory tree which 920 represents the packages in the module (i.e., the _package hierarchy_ 921 described above). The exact arrangement of source code for a module 922 is typically dictated by the conventions adopted by a development 923 environment (IDE) or build system. 924 925 For example: 926 927 - The module `a.b.c` may be represented by the directory `a.b.c`, on all 928 systems. 929 930 - The module's declaration is represented by the file 931 `module-info.java` in the `a.b.c` directory. 932 933 - If the module contains package `p.q.r`, then the `a.b.c` directory 934 contains the directory tree `p\q\r` (on Windows) or `p/q/r` 935 (on other systems). 936 937 The development environment may prescribe some directory hierarchy 938 between the directory named for the module and the source files to 939 be read by `javac`. 940 941 For example: 942 943 - The module `a.b.c` may be represented by the directory `a.b.c` 944 945 - The module's declaration and the module's packages may be in 946 some subdirectory of `a.b.c`, such as `src\main\java` (on Windows) 947 or `src/main/java` (on other systems). 948 949 950 ## Configuring a Compilation 951 952 This section describes how to configure `javac` to perform a basic compilation. 953 954 See [Configuring the Module System] for additional details for use when compiling 955 for a release of the platform that supports modules. 956 957 ### Source Files 958 959 * Specify the source files to be compiled on the command line. 960 961 If there are no compilation errors, the corresponding class files will 962 be placed in the [output directory]. 963 964 Some systems may limit the amount you can put on a command line; 965 to work around those limits, you can use [argument files](#command-line-argument-files). 966 967 When compiling code for modules, you can also specify source files indirectly, 968 by using the [`--module`](#option-module) or `-m` option. 969 970 ### Output Directory 971 972 * Use the [`-d`](#option-d) option to specify an output directory in which to put the compiled class files. 973 974 This will normally be organized in a [package hierarchy](#package-hierarchy), 975 unless you are compiling source code from multiple modules, in which case it will be 976 organized as a [module hierarchy](#module-hierarchy). 977 978 When the compilation has been completed, if you are compiling one or more modules, 979 you can place the output directory on the module path for the Java [launcher](java.html); 980 otherwise, you can place the place the output directory on the class path 981 for the Java launcher. 982 983 ### Precompiled Code 984 985 The code to be compiled may refer to libraries beyond what is provided by the platform. 986 If so, you must place these libraries on the class path or module path. 987 If the library code is not in a module, place it on the class path; 988 if it is in a module, place it on the module path. 989 990 * Use the [`--class-path`](#option-class-path) option to specify libraries to be placed on the class path. 991 Locations on the class path should be organized in a [package hierarchy](#package-hierarchy). 992 You can also use alternate forms of the option: `-classpath` or `-cp`. 993 994 * Use the [`--module-path`](#option-module-path) option to specify libraries to be placed on the module path. 995 Locations on the module path should either be modules or directories of modules. 996 You can also use an alternate form of the option: `-p`. 997 998 See [Configuring the Module System] for details on how to modify the default 999 configuration of library modules. 1000 1001 **Note**: the options for the class path and module path are not mutually 1002 exclusive, although it is not common to specify the class path when compiling 1003 code for one or more modules. 1004 1005 ### Additional Source Files 1006 1007 The code to be compiled may refer to types in additional source files that are not 1008 specified on the command line. 1009 If so, you must put those source files on either the source path or module path. 1010 You can only specify one of these options: if you are not compiling code for a module, 1011 or if you are only compiling code for a single module, use the source path; 1012 if you are compiling code for multiple modules, use the module source path. 1013 1014 * Use the [`--source-path`](#option-source-path) option to specify the locations of additional source 1015 files that may be read by javac. 1016 Locations on the source path should be organized in a [package hierarchy](#package-hierarchy). 1017 You can also use an alternate form of the option: `-sourcepath`. 1018 1019 * Use the [`--module-source-path`](#option-module-source-path) option one or more times to specify the location 1020 of additional source files in different modules that may be read by javac, 1021 or when compiling source files in multiple modules. 1022 You can either specify the locations for each module [individually](#module-specific-form), 1023 or you can organize the source files so that you can specify the locations all 1024 [together](#module-pattern-form). For more details, see [The Module Source Path Option]. 1025 1026 If you want to be able to refer to types in additional source files but do not 1027 want them to be compiled, use the [`-implicit`](#option-implicit) option. 1028 1029 **Note**: if you are compiling code for multiple modules, you must always specify 1030 a module source path, and all source files specified on the command line must be 1031 in one of the directories on the module source path, or in a subdirectory thereof. 1032 1033 1034 ### Example of Compiling Multiple Source Files 1035 1036 This example compiles the `Aloha.java`, `GutenTag.java`, `Hello.java`, and 1037 `Hi.java` source files in the `greetings` package. 1038 1039 **Linux and macOS:** 1040 1041 ``` 1042 % javac greetings/*.java 1043 % ls greetings 1044 Aloha.class GutenTag.class Hello.class Hi.class 1045 Aloha.java GutenTag.java Hello.java Hi.java 1046 ``` 1047 1048 **Windows:** 1049 1050 ``` 1051 C:\>javac greetings\*.java 1052 C:\>dir greetings 1053 Aloha.class GutenTag.class Hello.class Hi.class 1054 Aloha.java GutenTag.java Hello.java Hi.java 1055 ``` 1056 1057 ### Example of Specifying a User Class Path 1058 1059 After changing one of the source files in the previous example, recompile it: 1060 1061 **Linux and macOS:** 1062 1063 ``` 1064 pwd 1065 /examples 1066 javac greetings/Hi.java 1067 ``` 1068 1069 **Windows:** 1070 1071 ``` 1072 C:\>cd 1073 \examples 1074 C:\>javac greetings\Hi.java 1075 ``` 1076 1077 Because `greetings.Hi` refers to other classes in the `greetings` package, the 1078 compiler needs to find these other classes. The previous example works because 1079 the default user class path is the directory that contains the package 1080 directory. If you want to recompile this file without concern for which 1081 directory you are in, then add the examples directory to the user class path by 1082 setting `CLASSPATH`. This example uses the `-classpath` option. 1083 1084 **Linux and macOS:** 1085 1086 > `javac -classpath /examples /examples/greetings/Hi.java` 1087 1088 **Windows:** 1089 1090 > `C:\>javac -classpath \examples \examples\greetings\Hi.java` 1091 1092 If you change `greetings.Hi` to use a banner utility, then that utility also 1093 needs to be accessible through the user class path. 1094 1095 **Linux and macOS:** 1096 1097 ``` 1098 javac -classpath /examples:/lib/Banners.jar \ 1099 /examples/greetings/Hi.java 1100 ``` 1101 1102 **Windows:** 1103 1104 ``` 1105 C:\>javac -classpath \examples;\lib\Banners.jar ^ 1106 \examples\greetings\Hi.java 1107 ``` 1108 1109 To execute a class in the `greetings` package, the program needs access to the 1110 `greetings` package, and to the classes that the `greetings` classes use. 1111 1112 **Linux and macOS:** 1113 1114 > `java -classpath /examples:/lib/Banners.jar greetings.Hi` 1115 1116 **Windows:** 1117 1118 > `C:\>java -classpath \examples;\lib\Banners.jar greetings.Hi` 1119 1120 ## Configuring the Module System 1121 1122 If you want to include additional modules in your compilation, use the 1123 [`--add-modules`](#option-add-modules) option. 1124 This may be necessary when you are compiling code that is not in a module, 1125 or which is in an automatic module, and the code refers to API in the additional 1126 modules. 1127 1128 If you want to restrict the set of modules in your compilation, use the 1129 [`--limit-modules`](#option-limit-modules) option. 1130 This may be useful if you want to ensure that the code you are compiling 1131 is capable of running on a system with a limited set of modules installed. 1132 1133 If you want to break encapsulation and specify that additional packages 1134 should be considered as exported from a module, use the [`--add-exports`](#option-add-exports) option. 1135 This may be useful when performing white-box testing; relying on access 1136 to internal API in production code is strongly discouraged. 1137 1138 If you want to specify that additional packages 1139 should be considered as required by a module, use the [`--add-reads`](#option-add-reads) option. 1140 This may be useful when performing white-box testing; relying on access 1141 to internal API in production code is strongly discouraged. 1142 1143 You can patch additional content into any module using the 1144 [`--patch-module`](#option-patch-module) option. See [Patching a Module] for more details. 1145 1146 ## Searching for Module, Package and Type Declarations 1147 1148 To compile a source file, the compiler often needs information about a module 1149 or type, but the declaration is not in the source files specified on the command 1150 line. 1151 1152 `javac` needs type information for every class or interface used, 1153 extended, or implemented in the source file. This includes classes and 1154 interfaces not explicitly mentioned in the source file, but that provide 1155 information through inheritance. 1156 1157 For example, when you create a subclass of `java.awt.Window`, you are also 1158 using the ancestor classes of `Window`: `java.awt.Container`, 1159 `java.awt.Component`, and `java.lang.Object`. 1160 1161 When compiling code for a module, the compiler also needs to have available 1162 the declaration of that module. 1163 1164 A successful search may produce a class file, a source file, or both. If 1165 both are found, then you can use the [`-Xprefer`](#option-Xprefer) option to instruct the compiler 1166 which to use. 1167 1168 If a search finds and uses a source file, then by default `javac` 1169 compiles that source file. This behavior can be altered with 1170 [`-implicit`](#option-implicit). 1171 1172 The compiler might not discover the need for some type information until after 1173 annotation processing completes. When the type information is found in a source 1174 file and no [`-implicit`](#option-implicit) option is specified, the compiler gives a warning that 1175 the file is being compiled without being subject to annotation processing. To 1176 disable the warning, either specify the file on the command line (so that it 1177 will be subject to annotation processing) or use the [`-implicit`](#option-implicit) option to 1178 specify whether or not class files should be generated for such source files. 1179 1180 The way that `javac` locates the declarations of those types 1181 depends on whether the reference exists within code for a module or not. 1182 1183 ### Searching Package Oriented Paths 1184 1185 When searching for a source or class file on a path composed of package oriented 1186 locations, `javac` will check each location on the path in turn for the 1187 possible presence of the file. The first occurrence of a particular file 1188 shadows (hides) any subsequent occurrences of like-named files. This shadowing 1189 does not affect any search for any files with a different name. This can be 1190 convenient when searching for source files, which may be grouped in different 1191 locations, such as shared code, platform-specific code and generated code. 1192 It can also be useful when injecting alternate versions of a class file into 1193 a package, to debugging or other instrumentation reasons. But, it can also 1194 be dangerous, such as when putting incompatible different versions of a library 1195 on the class path. 1196 1197 ### Searching Module Oriented Paths 1198 1199 Prior to scanning any module paths for any package or type declarations, 1200 `javac` will lazily scan the following paths and locations to determine 1201 the modules that will be used in the compilation. 1202 1203 * The module source path (see the [`--module-source-path`](#option-module-source-path) option) 1204 * The path for upgradeable modules (see the [`--upgrade-module-path`](#option-upgrade-module-path) option) 1205 * The system modules (see the [`--system`](#option-system) option) 1206 * The user module path ( see the [`--module-path`](#option-module-path) option) 1207 1208 For any module, the first occurrence of the module during the scan completely 1209 shadows (hides) any subsequent appearance of a like-named module. While locating 1210 the modules, `javac` is able to determine the packages exported by the module 1211 and to associate with each module a package oriented path for the contents of 1212 the module. For any previously compiled module, this path will typically be a 1213 single entry for either a directory or a file that provides an internal 1214 directory-like hierarchy, such as a JAR file. Thus, when searching for a type 1215 that is in a package that is known to be exported by a module, `javac` can 1216 locate the declaration directly and efficiently. 1217 1218 ### Searching for the Declaration of a Module 1219 1220 If the module has been previously compiled, the module declaration is 1221 located in a file named `module-info.class` in the root of the package hierarchy 1222 for the content of the module. 1223 1224 If the module is one of those currently being compiled, the module declaration 1225 will be either the file named `module-info.class` in the root of the 1226 package hierarchy for the module in the class output directory, or the 1227 file named `module-info.java` in one of the locations on the source path 1228 or one the module source path for the module. 1229 1230 ### Searching for the Declaration of a Type When the Reference is not in a Module 1231 1232 When searching for a type that is referenced in code that is not in a module, 1233 `javac` will look in the following places: 1234 1235 * The platform classes (or the types in exported packages of the platform modules) 1236 (This is for compiled class files only.) 1237 1238 * Types in exported packages of any modules on the module path, if applicable. 1239 (This is for compiled class files only.) 1240 1241 * Types in packages on the class path and/or source path: 1242 1243 * If both are specified, `javac` looks for compiled class files on the class path 1244 and for source files on the source path. 1245 1246 * If the class path is specified, but not source path, `javac` looks for both 1247 compiled class files and source files on the class path. 1248 1249 * If the class path is not specified, it defaults to the current directory. 1250 1251 When looking for a type on the class path and/or source path, if both a compiled 1252 class file and a source file are found, the most recently modified file will 1253 be used by default. 1254 If the source file is newer, it will be compiled and will may override any 1255 previously compiled version of the file. You can use the [`-Xprefer`](#option-Xprefer) option 1256 to override the default behavior. 1257 1258 ### Searching for the Declaration of a Type When the Reference is in a Module 1259 1260 When searching for a type that is referenced in code in a module, 1261 `javac` will examine the declaration of the enclosing module to determine 1262 if the type is in a package that is exported from another module that is 1263 readable by the enclosing module. 1264 If so, `javac` will simply and directly go to the definition of that module 1265 to find the definition of the required type. 1266 Unless the module is another of the modules being compiled, `javac` will 1267 only look for compiled class files files. In other words, `javac` will 1268 not look for source files in platform modules or modules on the module path. 1269 1270 If the type being referenced is not in some other readable module, 1271 `javac` will examine the module being compiled to try and find the 1272 declaration of the type. 1273 `javac` will look for the declaration of the type as follows: 1274 1275 * Source files specified on the command line or on the source path or 1276 module source path. 1277 1278 * Previously compiled files in the output directory. 1279 1280 1281 ## Directory Hierarchies 1282 1283 `javac` generally assumes that source files and compiled class files will be 1284 organized in a file system directory hierarchy or in a type of file that 1285 supports in an internal directory hierarchy, such as a JAR file. 1286 Three different kinds of hierarchy are supported: a _package hierarchy_, 1287 a _module hierarchy_, and a _module source hierarchy_. 1288 1289 While `javac` is fairly relaxed about the organization of source code, 1290 beyond the expectation that source will be organized in one or package 1291 hierarchies, and can generally accommodate organizations prescribed by 1292 development environments and build tools, Java tools in general, 1293 and `javac` and the Java launcher in particular, are more stringent 1294 regarding the organization of compiled class files, and will be 1295 organized in package hierarchies or module hierarchies, as appropriate. 1296 1297 The location of these hierarchies are specified to `javac` with command-line 1298 options, whose names typically end in "path", like [`--source-path`](#option-source-path) or 1299 [`--class-path`](#option-class-path). Also as a general rule, path options whose name includes the 1300 word `module`, like [`--module-path`](#option-module-path), are used to specify module hierarchies, 1301 although some module-related path options allow a package hierarchy to be 1302 specified on a per-module basis. All other path options are used to specify 1303 package hierarchies. 1304 1305 ### Package Hierarchy 1306 1307 In a package hierarchy, directories and subdirectories are used 1308 to represent the component parts of the package name, with the source 1309 file or compiled class file for a type being stored as a file with an 1310 extension of `.java` or `.class` in the most nested directory. 1311 1312 For example, in a package hierarchy, the source file for a class 1313 `com.example.MyClass` will be stored in the file _com/example/MyClass.java_ 1314 1315 ### Module Hierarchy 1316 1317 In a module hierarchy, the first level of directories are named 1318 for the modules in the hierarchy; within each of those directories 1319 the contents of the module are organized in package hierarchies. 1320 1321 For example, in a module hierarchy, the compiled class file for a type called 1322 `com.example.MyClass` in a module called `my.library` will be stored in 1323 _my.library/com/example/MyClass.class_. 1324 1325 The various output directories used by `javac` (the class output directory, 1326 the source output directory, and native header output directory) 1327 will all be organized in a module hierarchy when multiple modules are being compiled. 1328 1329 ### Module Source Hierarchy 1330 1331 Although the source for each individual module should always be 1332 organized in a package hierarchy, it may be convenient to group 1333 those hierarchies into a module source hierarchy. This is similar 1334 to a module hierarchy, except that there may be intervening directories 1335 between the directory for the module and the directory that is 1336 the root of the package hierarchy for the source code of the module. 1337 1338 For example, in a module source hierarchy, the source file for a type called 1339 `com.example.MyClass` in a module called `my.library` may be stored in a 1340 file such as 1341 _my.library/src/main/java/com/example/MyClass.java_. 1342 1343 ## The Module Source Path Option 1344 1345 The [`--module-source-path`](#option-module-source-path) option has two forms: a _module-specific form_, 1346 in which a package path is given for each module containing code to be compiled, 1347 and a _module-pattern_ form, in which the source path for each module is specified 1348 by a pattern. 1349 The module-specific form is generally simpler to use when only a small number of 1350 modules are involved; the module-pattern form may be more convenient when the 1351 number of modules is large and the modules are organized in a regular manner that 1352 can be described by a pattern. 1353 1354 Multiple instances of the `--module-source-path` option may be given, each one 1355 using either the module-pattern form or the module-specific form, subject to the 1356 following limitations: 1357 1358 * the module-pattern form may be used at most once 1359 * the module-specific form may be used at most once for any given module 1360 1361 If the module-specific form is used for any module, the associated search path 1362 overrides any path that might otherwise have been inferred from the module-pattern form. 1363 1364 ### Module-specific form 1365 1366 The module-specific form allows an explicit search path to be given for any specific module. 1367 This form is: 1368 1369 * `--module-source-path` *module-name*`=`*file-path* (*path-separator* *file-path*)* 1370 1371 The path separator character is `;` on Windows, and `:` otherwise. 1372 1373 **Note:** this is similar to the form used for the [`--patch-module`](#option-patch-module) option. 1374 1375 ### Module-pattern form 1376 1377 The module-pattern form allows a concise specification of the module source path 1378 for any number of modules organized in regular manner. 1379 1380 * `--module-source-path` *pattern* 1381 1382 The pattern is defined by the following rules, which are applied in order: 1383 1384 * The argument is considered to be a series of segments separated by the path 1385 separator character (`;` on Windows, and `:` otherwise). 1386 1387 * Each segment containing curly braces of the form 1388 1389 string1{alt1 ( ,alt2 )* } string2 1390 1391 is considered to be replaced by a series of segments formed by "expanding" the braces: 1392 1393 string1 alt1 string2 1394 string1 alt2 string2 1395 and so on... 1396 1397 The braces may be nested. 1398 1399 This rule is applied for all such usages of braces. 1400 1401 * Each segment must have at most one asterisk (`*`). 1402 If a segment does not contain an asterisk, it is considered to be as though the 1403 file separator character and an asterisk are appended. 1404 1405 For any module _M_, the source path for that module is formed from the series 1406 of segments obtained by substituting the module name _M_ for the asterisk in 1407 each segment. 1408 1409 **Note**: in this context, the asterisk is just used as a special marker, to 1410 denote the position in the path of the module name. It should not be confused 1411 with the use of `*` as a file name wildcard character, as found on most 1412 operating systems. 1413 1414 ## Patching Modules 1415 1416 javac allows any content, whether in source or compiled form, to be patched 1417 into any module using the [`--patch-module`](#option-patch-module) option. 1418 You may want to do this to compile alternative implementations of a class 1419 to be patched at runtime into a JVM, or to inject additional classes into 1420 the module, such as when testing. 1421 1422 The form of the option is: 1423 1424 * `--patch-module` *module-name*`=`*file-path* (*path-separator* *file-path* )* 1425 1426 The path separator character is `;` on Windows, and `:` otherwise. 1427 The paths given for the module must specify the root of a 1428 package hierarchy for the contents of the module 1429 1430 The option may be given at most once for any given module. 1431 Any content on the path will hide any like-named content later in the path 1432 and in the patched module. 1433 1434 When patching source code into more than one module, the [`--module-source-path`](#option-module-source-path) 1435 must also be used, so that the output directory is organized in a module hierarchy, 1436 and capable of holding the compiled class files for the modules being compiled. 1437 1438 ## Annotation Processing 1439 1440 The `javac` command provides direct support for annotation processing. 1441 1442 The API for annotation processors is defined in the 1443 `javax.annotation.processing` and `javax.lang.model` packages and subpackages. 1444 1445 ### How Annotation Processing Works 1446 1447 Annotation processing is requested by using an option to configure 1448 annotation processing, such as [`-processor`](#option-processor), 1449 [`--processor-path`](#option-processor-path), 1450 [`--processor-module-path`](#option-processor-module-path) or by 1451 explicitly enabling processing with the [`-proc:full`](#option-proc) 1452 or [`-proc:only`](#option-proc) options. Annotation processing is 1453 disabled using the [`-proc:none`](#option-proc) option. 1454 1455 If annotation processing is requested, the compiler searches for any 1456 annotation processors that are available. 1457 1458 The search path can be specified with the 1459 [`-processorpath`](#option-processor-path) option. If no path is 1460 specified, then the user class path is used. Processors are located by 1461 means of service provider-configuration files named 1462 `META-INF/services/javax.annotation.processing.Processor` on the 1463 search path. Such files should contain the names of any 1464 annotationation processors to be used, listed one per 1465 line. Alternatively, processors can be specified explicitly, using the 1466 [`-processor`](#option-processor) option. 1467 1468 After scanning the source files and classes on the command line to determine 1469 what annotations are present, the compiler queries the processors to determine 1470 what annotations they process. When a match is found, the processor is called. 1471 A processor can claim the annotations it processes, in which case no further 1472 attempt is made to find any processors for those annotations. After all of the 1473 annotations are claimed, the compiler does not search for additional 1474 processors. 1475 1476 If any processors generate new source files, then another round of annotation 1477 processing occurs: Any newly generated source files are scanned, and the 1478 annotations processed as before. Any processors called on previous rounds are 1479 also called on all subsequent rounds. This continues until no new source files 1480 are generated. 1481 1482 After a round occurs where no new source files are generated, the annotation 1483 processors are called one last time, to give them a chance to complete any 1484 remaining work. Finally, unless the [`-proc:only`](#option-proc) option is used, the compiler 1485 compiles the original and all generated source files. 1486 1487 If you use an annotation processor that generates additional source 1488 files to be included in the compilation, you can specify a default 1489 module to be used for the newly generated files, for use when a 1490 module declaration is not also generated. In this case, use the 1491 [`--default-module-for-created-files`](#option-default-module-for-created-files) option. 1492 1493 ### Compilation Environment and Runtime Environment. 1494 1495 The declarations in source files and previously compiled class files are analyzed 1496 by `javac` in a _compilation environment_ that is distinct from the 1497 _runtime environment_ used to execute `javac` itself. Although there is a 1498 deliberate similarity between many `javac` options and like-named options for the 1499 Java [launcher](java.html), such as `--class-path`, `--module-path` and so 1500 on, it is important to understand that in general the `javac` options just affect 1501 the environment in which the source files are compiled, and do not affect 1502 the operation of `javac` itself. 1503 1504 The distinction between the compilation environment and runtime environment 1505 is significant when it comes to using annotation processors. 1506 Although annotations processors process elements (declarations) that exist 1507 in the compilation environment, the annotation processor itself is executed 1508 in the runtime environment. If an annotation processor has dependencies on 1509 libraries that are not in modules, the libraries can be placed, along with the 1510 annotation processor itself, on the processor path. 1511 (See the [`--processor-path`](#option-processor-path) option.) 1512 If the annotation processor and its dependencies are in modules, you should 1513 use the processor module path instead. 1514 (See the [`--processor-module-path`](#option-processor-module-path) option.) 1515 When those are insufficient, it may be necessary to provide further 1516 configuration of the runtime environment. This can be done in two ways: 1517 1518 1. If `javac` is invoked from the command line, options can be passed to the 1519 underlying runtime by prefixing the option with [`-J`](#option-J). 1520 1521 2. You can start an instance of a Java Virtual Machine directly and use 1522 command line options and API to configure an environment in which 1523 `javac` can be invoked via one of its [APIs]. 1524 1525 ## Compiling for Earlier Releases of the Platform 1526 1527 `javac` can compile code that is to be used on other releases of the platform, 1528 using either the [`--release`](#option-release) option, or the [`--source`](#option-source)/`-source` and 1529 [`--target`](#option-target)/`-target` options, together with additional options to specify the 1530 platform classes. 1531 1532 Depending on the desired platform release, there are some restrictions on some 1533 of the options that can be used. 1534 1535 * When compiling for JDK 8 and earlier releases, you cannot use any option 1536 that is intended for use with the module system. 1537 This includes all of the following options: 1538 1539 * [`--module-source-path`](#option-module-source-path), 1540 [`--upgrade-module-path`](#option-upgrade-module-path), 1541 [`--system`](#option-system), 1542 [`--module-path`](#option-module-path), 1543 [`--add-modules`](#option-add-modules), 1544 [`--add-exports`](#option-add-exports), 1545 `--add-opens`, 1546 [`--add-reads`](#option-add-reads), 1547 [`--limit-modules`](#option-limit-modules), 1548 [`--patch-module`](#option-patch-module) 1549 1550 If you use the `--source`/`-source` or `--target`/`-target` options, 1551 you should also set the appropriate platform classes using the 1552 boot class path family of options. 1553 1554 * When compiling for JDK 9 and later releases, you cannot use any option 1555 that is intended to configure the boot class path. 1556 This includes all of the following options: 1557 1558 * [`-Xbootclasspath/p:`](#option-Xbootclasspath-p), 1559 [`-Xbootclasspath`](#option-Xbootclasspath), 1560 [`-Xbootclasspath/a:`](#option-Xbootclasspath-a), 1561 [`-endorseddirs`](#option-endorseddirs), 1562 [`-Djava.endorsed.dirs`](#option-Djava.endorsed.dirs), 1563 [`-extdirs`](#option-extdirs), 1564 [`-Djava.ext.dirs`](#option-Djava.ext.dirs), 1565 [`-profile`](#option-profile) 1566 1567 If you use the `--source`/`-source` or `--target`/`-target` options, 1568 you should also set the appropriate platform classes using the `--system` 1569 option to give the location of an appropriate installed release of JDK. 1570 1571 When using the `--release` option, only the supported documented API for that 1572 release may be used; you cannot use any options to break encapsulation to 1573 access any internal classes. 1574 1575 ## APIs 1576 1577 The `javac` compiler can be invoked using an API in three different ways: 1578 1579 The [Java Compiler API](../../api/java.compiler/javax/tools/JavaCompiler.html) 1580 : This provides the most flexible way to invoke the compiler, 1581 including the ability to compile source files provided in 1582 memory buffers or other non-standard file systems. 1583 1584 The [ToolProvider API](../../api/java.base/java/util/spi/ToolProvider.html) 1585 : A `ToolProvider` for `javac` can be obtained by calling 1586 `ToolProvider.findFirst("javac")`. This returns an object 1587 with the equivalent functionality of the command-line tool. 1588 1589 **Note**: This API should not be confused with the like-named 1590 API in the [`javax.tools`](../../api/java.compiler/javax/tools/ToolProvider.html) 1591 package. 1592 1593 The `javac` [Legacy API](../../api/jdk.compiler/com/sun/tools/javac/Main.html) 1594 : This API is retained for backward compatibility only. 1595 All new code should use either the Java Compiler API or the ToolProvider API. 1596 1597 **Note:** All other classes and methods found in a package with names that start with 1598 `com.sun.tools.javac` (subpackages of `com.sun.tools.javac`) are strictly 1599 internal and subject to change at any time. 1600 1601 ## Examples of Using -Xlint keys 1602 1603 `cast` 1604 : Warns about unnecessary and redundant casts, for example: 1605 1606 > `String s = (String) "Hello!"` 1607 1608 `classfile` 1609 : Warns about issues related to class file contents. 1610 1611 `deprecation` 1612 : Warns about the use of deprecated items. For example: 1613 1614 ``` 1615 java.util.Date myDate = new java.util.Date(); 1616 int currentDay = myDate.getDay(); 1617 ``` 1618 1619 The method `java.util.Date.getDay` has been deprecated since JDK 1.1. 1620 1621 `dep-ann` 1622 : Warns about items that are documented with the `@deprecated` Javadoc 1623 comment, but do not have the `@Deprecated` annotation, for example: 1624 1625 ``` 1626 /** 1627 * @deprecated As of Java SE 7, replaced by {@link #newMethod()} 1628 */ 1629 public static void deprecatedMethod() { } 1630 public static void newMethod() { } 1631 ``` 1632 1633 `divzero` 1634 : Warns about division by the constant integer 0, for example: 1635 1636 > `int divideByZero = 42 / 0;` 1637 1638 `empty` 1639 : Warns about empty statements after `if`statements, for example: 1640 1641 ``` 1642 class E { 1643 void m() { 1644 if (true) ; 1645 } 1646 } 1647 ``` 1648 1649 `fallthrough` 1650 : Checks the switch blocks for fall-through cases and provides a warning 1651 message for any that are found. Fall-through cases are cases in a switch 1652 block, other than the last case in the block, whose code does not include a 1653 `break` statement, allowing code execution to fall through from that case to 1654 the next case. For example, the code following the case 1 label in this 1655 switch block does not end with a `break` statement: 1656 1657 ``` 1658 switch (x) { 1659 case 1: 1660 System.out.println("1"); 1661 // No break statement here. 1662 case 2: 1663 System.out.println("2"); 1664 } 1665 ``` 1666 1667 If the `-Xlint:fallthrough` option was used when compiling this code, then 1668 the compiler emits a warning about possible fall-through into case, with 1669 the line number of the case in question. 1670 1671 `finally` 1672 : Warns about `finally` clauses that cannot be completed normally, for 1673 example: 1674 1675 ``` 1676 public static int m() { 1677 try { 1678 throw new NullPointerException(); 1679 } catch (NullPointerException e) { 1680 System.err.println("Caught NullPointerException."); 1681 return 1; 1682 } finally { 1683 return 0; 1684 } 1685 } 1686 ``` 1687 1688 The compiler generates a warning for the `finally` block in this example. 1689 When the `int` method is called, it returns a value of 0. A `finally` block 1690 executes when the `try` block exits. In this example, when control is 1691 transferred to the `catch` block, the `int` method exits. However, the 1692 `finally` block must execute, so it's executed, even though control was 1693 transferred outside the method. 1694 1695 `options` 1696 : Warns about issues that related to the use of command-line options. See 1697 [Compiling for Earlier Releases of the Platform]. 1698 1699 `overrides` 1700 : Warns about issues related to method overrides. For example, consider the 1701 following two classes: 1702 1703 ``` 1704 public class ClassWithVarargsMethod { 1705 void varargsMethod(String... s) { } 1706 } 1707 1708 public class ClassWithOverridingMethod extends ClassWithVarargsMethod { 1709 @Override 1710 void varargsMethod(String[] s) { } 1711 } 1712 ``` 1713 1714 The compiler generates a warning similar to the following:. 1715 1716 ``` 1717 warning: [override] varargsMethod(String[]) in ClassWithOverridingMethod 1718 overrides varargsMethod(String...) in ClassWithVarargsMethod; overriding 1719 method is missing '...' 1720 ``` 1721 1722 When the compiler encounters a `varargs` method, it translates the 1723 `varargs` formal parameter into an array. In the method 1724 `ClassWithVarargsMethod.varargsMethod`, the compiler translates the 1725 `varargs` formal parameter `String... s` to the formal parameter 1726 `String[] s`, an array that matches the formal parameter of the method 1727 `ClassWithOverridingMethod.varargsMethod`. Consequently, this example 1728 compiles. 1729 1730 `path` 1731 : Warns about invalid path elements and nonexistent path directories on the 1732 command line (with regard to the class path, the source path, and other 1733 paths). Such warnings cannot be suppressed with the `@SuppressWarnings` 1734 annotation. For example: 1735 1736 - **Linux and macOS:** 1737 `javac -Xlint:path -classpath /nonexistentpath Example.java` 1738 1739 - **Windows:** 1740 `javac -Xlint:path -classpath C:\nonexistentpath Example.java` 1741 1742 `processing` 1743 : Warns about issues related to annotation processing. The compiler generates 1744 this warning when you have a class that has an annotation, and you use an 1745 annotation processor that cannot handle that type of annotation. For example, 1746 the following is a simple annotation processor: 1747 1748 **Source file AnnoProc.java**: 1749 1750 ``` 1751 import java.util.*; 1752 import javax.annotation.processing.*; 1753 import javax.lang.model.*; 1754 import javax.lang.model.element.*; 1755 1756 @SupportedAnnotationTypes("NotAnno") 1757 public class AnnoProc extends AbstractProcessor { 1758 public boolean process(Set<? extends TypeElement> elems, RoundEnvironment renv){ 1759 return true; 1760 } 1761 1762 public SourceVersion getSupportedSourceVersion() { 1763 return SourceVersion.latest(); 1764 } 1765 } 1766 ``` 1767 1768 **Source file AnnosWithoutProcessors.java**: 1769 1770 ``` 1771 @interface Anno { } 1772 1773 @Anno 1774 class AnnosWithoutProcessors { } 1775 ``` 1776 1777 The following commands compile the annotation processor `AnnoProc`, then 1778 run this annotation processor against the source file 1779 `AnnosWithoutProcessors.java`: 1780 1781 ``` 1782 javac AnnoProc.java 1783 javac -cp . -Xlint:processing -processor AnnoProc -proc:only AnnosWithoutProcessors.java 1784 ``` 1785 1786 When the compiler runs the annotation processor against the source file 1787 `AnnosWithoutProcessors.java`, it generates the following warning: 1788 1789 ``` 1790 warning: [processing] No processor claimed any of these annotations: Anno 1791 ``` 1792 1793 To resolve this issue, you can rename the annotation defined and used in 1794 the class `AnnosWithoutProcessors` from `Anno` to `NotAnno`. 1795 1796 `rawtypes` 1797 : Warns about unchecked operations on raw types. The following statement 1798 generates a `rawtypes` warning: 1799 1800 > `void countElements(List l) { ... }` 1801 1802 The following example does not generate a `rawtypes` warning: 1803 1804 > `void countElements(List<?> l) { ... }` 1805 1806 `List` is a raw type. However, `List<?>` is an unbounded wildcard 1807 parameterized type. Because `List` is a parameterized interface, always 1808 specify its type argument. In this example, the `List` formal argument is 1809 specified with an unbounded wildcard (`?`) as its formal type parameter, 1810 which means that the `countElements` method can accept any instantiation of 1811 the `List` interface. 1812 1813 `serial` 1814 : Warns about missing `serialVersionUID` definitions on serializable classes. 1815 For example: 1816 1817 ``` 1818 public class PersistentTime implements Serializable 1819 { 1820 private Date time; 1821 1822 public PersistentTime() { 1823 time = Calendar.getInstance().getTime(); 1824 } 1825 1826 public Date getTime() { 1827 return time; 1828 } 1829 } 1830 ``` 1831 1832 The compiler generates the following warning: 1833 1834 ``` 1835 warning: [serial] serializable class PersistentTime has no definition of 1836 serialVersionUID 1837 ``` 1838 1839 If a serializable class does not explicitly declare a field named 1840 `serialVersionUID`, then the serialization runtime environment calculates a 1841 default `serialVersionUID` value for that class based on various aspects of 1842 the class, as described in the Java Object Serialization Specification. 1843 However, it's strongly recommended that all serializable classes explicitly 1844 declare `serialVersionUID` values because the default process of computing 1845 `serialVersionUID` values is highly sensitive to class details that can 1846 vary depending on compiler implementations. As a result, this might cause 1847 an unexpected `InvalidClassExceptions` during deserialization. To guarantee 1848 a consistent `serialVersionUID` value across different Java compiler 1849 implementations, a serializable class must declare an explicit 1850 `serialVersionUID` value. 1851 1852 `static` 1853 : Warns about issues relating to the use of static variables, for example: 1854 1855 ``` 1856 class XLintStatic { 1857 static void m1() { } 1858 void m2() { this.m1(); } 1859 } 1860 ``` 1861 1862 The compiler generates the following warning: 1863 1864 ``` 1865 warning: [static] static method should be qualified by type name, 1866 XLintStatic, instead of by an expression 1867 ``` 1868 1869 To resolve this issue, you can call the `static` method `m1` as follows: 1870 1871 > `XLintStatic.m1();` 1872 1873 Alternately, you can remove the `static` keyword from the declaration of 1874 the method `m1`. 1875 1876 `this-escape` 1877 : Warns about constructors leaking 1878 `this` prior to subclass initialization. 1879 For example, this class: 1880 1881 ``` 1882 public class MyClass { 1883 public MyClass() { 1884 System.out.println(this.hashCode()); 1885 } 1886 } 1887 ``` 1888 1889 generates the following warning: 1890 1891 ``` 1892 MyClass.java:3: warning: [this-escape] possible 'this' escape 1893 before subclass is fully initialized 1894 System.out.println(this.hashCode()); 1895 ^ 1896 ``` 1897 1898 A 'this' escape warning is generated when a constructor does something 1899 that might result in a subclass method being invoked before the 1900 constructor returns. 1901 In such cases the subclass method would be operating on an incompletely 1902 initialized instance. 1903 In the above example, a subclass of `MyClass` that overrides 1904 `hashCode()` to incorporate its own fields would likely produce 1905 an incorrect result when invoked as shown. 1906 1907 Warnings are only generated if a subclass could exist that is outside 1908 of the current module (or package, if no module) being compiled. 1909 So, for example, constructors in final and non-public classes do not 1910 generate warnings. 1911 1912 `try` 1913 : Warns about issues relating to the use of `try` blocks, including 1914 try-with-resources statements. For example, a warning is generated for the 1915 following statement because the resource `ac` declared in the `try` block 1916 is not used: 1917 1918 ``` 1919 try ( AutoCloseable ac = getResource() ) { // do nothing} 1920 ``` 1921 1922 `unchecked` 1923 : Gives more detail for unchecked conversion warnings that are mandated by 1924 the Java Language Specification, for example: 1925 1926 ``` 1927 List l = new ArrayList<Number>(); 1928 List<String> ls = l; // unchecked warning 1929 ``` 1930 1931 During type erasure, the types `ArrayList<Number>` and `List<String>` 1932 become `ArrayList` and `List`, respectively. 1933 1934 The `ls` command has the parameterized type `List<String>`. When the `List` 1935 referenced by `l` is assigned to `ls`, the compiler generates an unchecked 1936 warning. At compile time, the compiler and JVM cannot determine whether `l` 1937 refers to a `List<String>` type. In this case, `l` does not refer to a 1938 `List<String>` type. As a result, heap pollution occurs. 1939 1940 A heap pollution situation occurs when the `List` object `l`, whose static 1941 type is `List<Number>`, is assigned to another `List` object, `ls`, that 1942 has a different static type, `List<String>`. However, the compiler still 1943 allows this assignment. It must allow this assignment to preserve backward 1944 compatibility with releases of Java SE that do not support generics. Because 1945 of type erasure, `List<Number>` and `List<String>` both become `List`. 1946 Consequently, the compiler allows the assignment of the object `l`, which 1947 has a raw type of `List`, to the object `ls`. 1948 1949 `varargs` 1950 : Warns about unsafe use of variable arguments (`varargs`) methods, in 1951 particular, those that contain non-reifiable arguments, for example: 1952 1953 ``` 1954 public class ArrayBuilder { 1955 public static <T> void addToList (List<T> listArg, T... elements) { 1956 for (T x : elements) { 1957 listArg.add(x); 1958 } 1959 } 1960 } 1961 ``` 1962 1963 A non-reifiable type is a type whose type information is not fully available 1964 at runtime. 1965 1966 The compiler generates the following warning for the definition of the 1967 method `ArrayBuilder.addToList`: 1968 1969 ``` 1970 warning: [varargs] Possible heap pollution from parameterized vararg type T 1971 ``` 1972 1973 When the compiler encounters a varargs method, it translates the `varargs` 1974 formal parameter into an array. However, the Java programming language 1975 does not permit the creation of arrays of parameterized types. In the method 1976 `ArrayBuilder.addToList`, the compiler translates the `varargs` formal 1977 parameter `T...` elements to the formal parameter `T[]` elements, an array. 1978 However, because of type erasure, the compiler converts the `varargs` 1979 formal parameter to `Object[]` elements. Consequently, there's a 1980 possibility of heap pollution.