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