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