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