1JAVAC(1) JDK Commands JAVAC(1)
2
6 javac - read Java declarations and compile them into class files
7
9 javac [options] [sourcefiles-or-classnames]
10 options
12 Command-line options.
13 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 The javac command can also process annotations in Java source files and
25 classes.
26 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 There are two ways to specify source files to javac:
34 • For a small number of source files, you can list their file names on
36 the command line.
37 • 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 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 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 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 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 Command-line options and environment variables also control how javac
69 performs various tasks:
70 • Compiling code to run on earlier releases of the JDK.
72 • Compiling code to run under a debugger.
74 • Checking for stylistic issues in Java source code.
76 • Checking for problems in javadoc comments (/** ... */).
78 • Processing annotations in source files and class files.
80 • Upgrading and patching modules in the compile-time environment.
82 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 non-
88 standard or are for advanced use.
89 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 -Aname="J. Duke"
101 -proc:only
102 -d myDirectory
103 --module-version 3
104 --module-version=3
105 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
110 locations may be directories, JAR files or JMOD files.
111 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 -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 --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 --boot-class-path path or -bootclasspath path
132 Overrides the location of the bootstrap class files.
133 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 --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 • 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 • 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 • If the -processorpath option is not specified, then the class
153 path is also searched for annotation processors.
154 -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 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 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 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 -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 --enable-preview
191 Enables preview language features. Used in conjunction with ei‐
192 ther -source or --release.
193 -encoding encoding
195 Specifies character encoding used by source files, such as EUC-
196 JP and UTF-8. If the -encoding option is not specified, then
197 the platform default converter is used.
198 -endorseddirs directories
200 Overrides the location of the endorsed standards path.
201 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 -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 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 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 -g Generates all debugging information, including local variables.
223 By default, only line number and source file information is gen‐
224 erated.
225 -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 lines Line number debugging information.
231 vars Local variable debugging information.
233 source Source file debugging information.
235 -g:none
237 Does not generate debugging information.
238 -h directory
240 Specifies where to place generated native header files.
241 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 --help, -help or -?
252 Prints a synopsis of the standard options.
253 --help-extra or -X
255 Prints a synopsis of the set of extra options.
256 --help-lint
258 Prints the supported keys for the -Xlint option.
259 -implicit:[none, class]
261 Specifies whether or not to generate class files for implicitly
262 referenced files:
263 • -implicit:class --- Automatically generates class files.
265 • -implicit:none --- Suppresses class file generation.
267 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 -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 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 --limit-modules module,module*
289 Limits the universe of observable modules.
290 --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 --module-path path or -p path
296 Specifies where to find application modules.
297 --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 --module-version version
304 Specifies the version of modules that are being compiled.
305 -nowarn
307 Disables warning messages. This option operates the same as the
308 -Xlint:none option.
309 -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 -proc:[none, only, full]
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. If this option is not
321 used, or -proc:full is specified, annotation processing and com‐
322 pilation are done.
323 -processor class1[,class2,class3...]
325 Names of the annotation processors to run. This bypasses the
326 default discovery process.
327 --processor-module-path path
329 Specifies the module path used for finding annotation proces‐
330 sors.
331 --processor-path path or -processorpath path
333 Specifies where to find annotation processors. If this option
334 is not used, then the class path is searched for processors.
335 -profile profile
337 Checks that the API used is available in the specified profile.
338 This option is deprecated and may be removed in a future re‐
339 lease.
340 Note: This can only be used when compiling for releases prior to
342 JDK 9. As applicable, see the descriptions in --release,
343 -source, or -target for details.
344 --release release
346 Compiles source code according to the rules of the Java program‐
347 ming language for the specified Java SE release, generating
348 class files which target that release. Source code is compiled
349 against the combined Java SE and JDK API for the specified re‐
350 lease.
351 The supported values of release are the current Java SE release
353 and a limited number of previous releases, detailed in the com‐
354 mand-line help.
355 For the current release, the Java SE API consists of the java.*,
357 javax.*, and org.* packages that are exported by the Java SE
358 modules in the release; the JDK API consists of the com.* and
359 jdk.* packages that are exported by the JDK modules in the re‐
360 lease, plus the javax.* packages that are exported by standard,
361 but non-Java SE, modules in the release.
362 For previous releases, the Java SE API and the JDK API are as
364 defined in that release.
365 Note: When using --release, you cannot also use the
367 --source/-source or --target/-target options.
368 Note: When using --release to specify a release that supports
370 the Java Platform Module System, the --add-exports option cannot
371 be used to enlarge the set of packages exported by the Java SE,
372 JDK, and standard modules in the specified release.
373 -s directory
375 Specifies the directory used to place the generated source
376 files. If a class is part of a package, then the compiler puts
377 the source file in a subdirectory that reflects the module name
378 (if appropriate) and package name. The directory, and any nec‐
379 essary subdirectories, will be created if they do not already
380 exist.
381 Except when compiling code for multiple modules, the contents of
383 the source output directory will be organized in a package hier‐
384 archy. When compiling code for multiple modules, the contents
385 of the source output directory will be organized in a module hi‐
386 erarchy, with the contents of each module in a separate subdi‐
387 rectory, each organized as a package hierarchy.
388 --source release or -source release
390 Compiles source code according to the rules of the Java program‐
391 ming language for the specified Java SE release. The supported
392 values of release are the current Java SE release and a limited
393 number of previous releases, detailed in the command-line help.
394 If the option is not specified, the default is to compile source
396 code according to the rules of the Java programming language for
397 the current Java SE release.
398 --source-path path or -sourcepath path
400 Specifies where to find source files. Except when compiling
401 multiple modules together, this is the source code path used to
402 search for class or interface definitions.
403 Note: Classes found through the class path might be recompiled
405 when their source files are also found. See Searching for Mod‐
406 ule, Package and Type Declarations.
407 --system jdk | none
409 Overrides the location of system modules.
410 --target release or -target release
412 Generates class files suitable for the specified Java SE re‐
413 lease. The supported values of release are the current Java SE
414 release and a limited number of previous releases, detailed in
415 the command-line help.
416 Note: The target release must be equal to or higher than the
418 source release. (See --source.)
419 --upgrade-module-path path
421 Overrides the location of upgradeable modules.
422 -verbose
424 Outputs messages about what the compiler is doing. Messages in‐
425 clude information about each class loaded and each source file
426 compiled.
427 --version or -version
429 Prints version information.
430 -Werror
432 Terminates compilation when warnings occur.
433 Extra Options
435 --add-exports module/package=other-module(,other-module)*
436 Specifies a package to be considered as exported from its defin‐
437 ing module to additional modules or to all unnamed modules when
438 the value of other-module is ALL-UNNAMED.
439 --add-reads module=other-module(,other-module)*
441 Specifies additional modules to be considered as required by a
442 given module.
443 --default-module-for-created-files module-name
445 Specifies the fallback target module for files created by anno‐
446 tation processors, if none is specified or inferred.
447 -Djava.endorsed.dirs=dirs
449 Overrides the location of the endorsed standards path.
450 Note: This can only be used when compiling for releases prior to
452 JDK 9. As applicable, see the descriptions in --release,
453 -source, or -target for details.
454 -Djava.ext.dirs=dirs
456 Overrides the location of installed extensions.
457 Note: This can only be used when compiling for releases prior to
459 JDK 9. As applicable, see the descriptions in --release,
460 -source, or -target for details.
461 --patch-module module=path
463 Overrides or augments a module with classes and resources in JAR
464 files or directories.
465 -Xbootclasspath:path
467 Overrides the location of the bootstrap class files.
468 Note: This can only be used when compiling for releases prior to
470 JDK 9. As applicable, see the descriptions in --release,
471 -source, or -target for details.
472 -Xbootclasspath/a:path
474 Adds a suffix to the bootstrap class path.
475 Note: This can only be used when compiling for releases prior to
477 JDK 9. As applicable, see the descriptions in --release,
478 -source, or -target for details.
479 -Xbootclasspath/p:path
481 Adds a prefix to the bootstrap class path.
482 Note: This can only be used when compiling for releases prior to
484 JDK 9. As applicable, see the descriptions in --release,
485 -source, or -target for details.
486 -Xdiags:[compact, verbose]
488 Selects a diagnostic mode.
489 -Xdoclint
491 Enables recommended checks for problems in documentation com‐
492 ments.
493 -Xdoclint:(all|none|[-]group)[/access]
495 Enables or disables specific groups of checks in documentation
496 comments.
497 group can have one of the following values: accessibility, html,
499 missing, reference, syntax.
500 The variable access specifies the minimum visibility level of
502 classes and members that the -Xdoclint option checks. It can
503 have one of the following values (in order of most to least vis‐
504 ible): public, protected, package, private.
505 The default access level is private.
507 When prefixed by doclint:, the group names and all can be used
509 with @SuppressWarnings to suppress warnings about documentation
510 comments in parts of the code being compiled.
511 For more information about these groups of checks, see the Do‐
513 cLint section of the javadoc command documentation. The -Xdo‐
514 clint option is disabled by default in the javac command.
515 For example, the following option checks classes and members
517 (with all groups of checks) that have the access level of pro‐
518 tected and higher (which includes protected and public):
519 -Xdoclint:all/protected
521 The following option enables all groups of checks for all access
523 levels, except it will not check for HTML errors for classes and
524 members that have the access level of package and higher (which
525 includes package, protected and public):
526 -Xdoclint:all,-html/package
528 -Xdoclint/package:[-]packages(,[-]package)*
530 Enables or disables checks in specific packages. Each package
531 is either the qualified name of a package or a package name pre‐
532 fix followed by .*, which expands to all sub-packages of the
533 given package. Each package can be prefixed with a hyphen (-)
534 to disable checks for a specified package or packages.
535 For more information, see the DocLint section of the javadoc
537 command documentation.
538 -Xlint Enables all recommended warnings. In this release, enabling all
540 available warnings is recommended.
541 -Xlint:[-]key(,[-]key)*
543 Supplies warnings to enable or disable, separated by comma.
544 Precede a key by a hyphen (-) to disable the specified warning.
545 Supported values for key are:
547 • all: Enables all warnings.
549 • auxiliaryclass: Warns about an auxiliary class that is hidden
551 in a source file, and is used from other files.
552 • cast: Warns about the use of unnecessary casts.
554 • classfile: Warns about the issues related to classfile con‐
556 tents.
557 • deprecation: Warns about the use of deprecated items.
559 • dep-ann: Warns about the items marked as deprecated in javadoc
561 but without the @Deprecated annotation.
562 • divzero: Warns about the division by the constant integer 0.
564 • empty: Warns about an empty statement after if.
566 • exports: Warns about the issues regarding module exports.
568 • fallthrough: Warns about the falling through from one case of
570 a switch statement to the next.
571 • finally: Warns about finally clauses that do not terminate
573 normally.
574 • lossy-conversions: Warns about possible lossy conversions in
576 compound assignment.
577 • missing-explicit-ctor: Warns about missing explicit construc‐
579 tors in public and protected classes in exported packages.
580 • module: Warns about the module system-related issues.
582 • opens: Warns about the issues related to module opens.
584 • options: Warns about the issues relating to use of command
586 line options.
587 • output-file-clash: Warns if any output file is overwritten
589 during compilation. This can occur, for example, on case-in‐
590 sensitive filesystems.
591 • overloads: Warns about the issues related to method overloads.
593 • overrides: Warns about the issues related to method overrides.
595 • path: Warns about the invalid path elements on the command
597 line.
598 • preview: Warns about the use of preview language features.
600 • processing: Warns about the issues related to annotation pro‐
602 cessing.
603 • rawtypes: Warns about the use of raw types.
605 • removal: Warns about the use of an API that has been marked
607 for removal.
608 • requires-automatic: Warns developers about the use of automat‐
610 ic modules in requires clauses.
611 • requires-transitive-automatic: Warns about automatic modules
613 in requires transitive.
614 • serial: Warns about the serializable classes that do not pro‐
616 vide a serial version ID. Also warns about access to non-pub‐
617 lic members from a serializable element.
618 • static: Warns about the accessing a static member using an in‐
620 stance.
621 • strictfp: Warns about unnecessary use of the strictfp modifi‐
623 er.
624 • synchronization: Warns about synchronization attempts on in‐
626 stances of value-based classes.
627 • text-blocks: Warns about inconsistent white space characters
629 in text block indentation.
630 • this-escape: Warns about constructors leaking this prior to
632 subclass initialization.
633 • try: Warns about the issues relating to the use of try blocks
635 (that is, try-with-resources).
636 • unchecked: Warns about the unchecked operations.
638 • varargs: Warns about the potentially unsafe vararg methods.
640 • none: Disables all warnings.
642 With the exception of all and none, the keys can be used with
644 the @SuppressWarnings annotation to suppress warnings in a part
645 of the source code being compiled.
646 See Examples of Using -Xlint keys.
648 -Xmaxerrs number
650 Sets the maximum number of errors to print.
651 -Xmaxwarns number
653 Sets the maximum number of warnings to print.
654 -Xpkginfo:[always, legacy, nonempty]
656 Specifies when and how the javac command generates package-in‐
657 fo.class files from package-info.java files using one of the
658 following options:
659 always Generates a package-info.class file for every package-in‐
661 fo.java file. This option may be useful if you use a
662 build system such as Ant, which checks that each .java
663 file has a corresponding .class file.
664 legacy Generates a package-info.class file only if package-in‐
666 fo.java contains annotations. This option does not gen‐
667 erate a package-info.class file if package-info.java con‐
668 tains only comments.
669 Note: A package-info.class file might be generated but be
671 empty if all the annotations in the package-info.java
672 file have RetentionPolicy.SOURCE.
673 nonempty
675 Generates a package-info.class file only if package-in‐
676 fo.java contains annotations with RetentionPolicy.CLASS
677 or RetentionPolicy.RUNTIME.
678 -Xplugin:name args
680 Specifies the name and optional arguments for a plug-in to be
681 run. If args are provided, name and args should be quoted or
682 otherwise escape the whitespace characters between the name and
683 all the arguments. For details on the API for a plugin, see the
684 API documentation for jdk.compiler/com.sun.source.util.Plugin.
685 -Xprefer:[source, newer]
687 Specifies which file to read when both a source file and class
688 file are found for an implicitly compiled class using one of the
689 following options. See Searching for Module, Package and Type
690 Declarations.
691 • -Xprefer:newer: Reads the newer of the source or class files
693 for a type (default).
694 • -Xprefer:source : Reads the source file. Use -Xprefer:source
696 when you want to be sure that any annotation processors can
697 access annotations declared with a retention policy of SOURCE.
698 -Xprint
700 Prints a textual representation of specified types for debugging
701 purposes. This does not perform annotation processing or compi‐
702 lation. The format of the output could change.
703 -XprintProcessorInfo
705 Prints information about which annotations a processor is asked
706 to process.
707 -XprintRounds
709 Prints information about initial and subsequent annotation pro‐
710 cessing rounds.
711 -Xstdout filename
713 Sends compiler messages to the named file. By default, compiler
714 messages go to System.err.
715
717 CLASSPATH
718 If the --class-path option or any of its alternate forms are not speci‐
719 fied, the class path will default to the value of the CLASSPATH envi‐
720 ronment variable if it is set. However, it is recommended that this
721 environment variable should not be set, and that the --class-path op‐
722 tion should be used to provide an explicit value for the class path
723 when one is required.
724 JDK_JAVAC_OPTIONS
726 The content of the JDK_JAVAC_OPTIONS environment variable, separated by
727 white-spaces ( ) or white-space characters (\n, \t, \r, or \f) is
728 prepended to the command line arguments passed to javac as a list of
729 arguments.
730 The encoding requirement for the environment variable is the same as
732 the javac command line on the system. JDK_JAVAC_OPTIONS environment
733 variable content is treated in the same manner as that specified in the
734 command line.
735 Single quotes (') or double quotes (") can be used to enclose arguments
737 that contain whitespace characters. All content between the open quote
738 and the first matching close quote are preserved by simply removing the
739 pair of quotes. In case a matching quote is not found, the launcher
740 will abort with an error message. @files are supported as they are
741 specified in the command line. However, as in @files, use of a wild‐
742 card is not supported.
743 Examples of quoting arguments containing white spaces:
745 export JDK_JAVAC_OPTIONS='@"C:\white spaces\argfile"'
747 export JDK_JAVAC_OPTIONS='"@C:\white spaces\argfile"'
749 export JDK_JAVAC_OPTIONS='@C:\"white spaces"\argfile'
751
753 An argument file can include command-line options and source file names
754 in any combination. The arguments within a file can be separated by
755 spaces or new line characters. If a file name contains embedded spa‐
756 ces, then put the whole file name in double quotation marks.
757 File names within an argument file are relative to the current directo‐
759 ry, not to the location of the argument file. Wildcards (*) are not
760 allowed in these lists (such as for specifying *.java). Use of the at
761 sign (@) to recursively interpret files is not supported. The -J op‐
762 tions are not supported because they're passed to the launcher, which
763 does not support argument files.
764 When executing the javac command, pass in the path and name of each ar‐
766 gument file with the at sign (@) leading character. When the javac
767 command encounters an argument beginning with the at sign (@), it ex‐
768 pands the contents of that file into the argument list.
769 Examples of Using javac @filename
771 Single Argument File
772 You could use a single argument file named argfile to hold all
773 javac arguments:
774 javac @argfile
776 This argument file could contain the contents of both files
778 shown in the following Two Argument Files example.
779 Two Argument Files
781 You can create two argument files: one for the javac options and
782 the other for the source file names. Note that the following
783 lists have no line-continuation characters.
784 Create a file named options that contains the following:
786 Linux and macOS:
788 -d classes
790 -g
791 -sourcepath /java/pubs/ws/1.3/src/share/classes
792 Windows:
794 -d classes
796 -g
797 -sourcepath C:\java\pubs\ws\1.3\src\share\classes
798 Create a file named sources that contains the following:
800 MyClass1.java
802 MyClass2.java
803 MyClass3.java
804 Then, run the javac command as follows:
806 javac @options @sources
808 Argument Files with Paths
810 The argument files can have paths, but any file names inside the
811 files are relative to the current working directory (not path1
812 or path2):
813 javac @path1/options @path2/sources
815
817 In the Java language, classes and interfaces can be organized into
818 packages, and packages can be organized into modules. javac expects
819 that the physical arrangement of source files in directories of the
820 file system will mirror the organization of classes into packages, and
821 packages into modules.
822 It is a widely adopted convention that module names and package names
824 begin with a lower-case letter, and that class names begin with an up‐
825 per-case letter.
826 Arrangement of Source Code for a Package
828 When classes and interfaces are organized into a package, the package
829 is represented as a directory, and any subpackages are represented as
830 subdirectories.
831 For example:
833 • The package p is represented as a directory called p.
835 • The package p.q -- that is, the subpackage q of package p -- is rep‐
837 resented as the subdirectory q of directory p. The directory tree
838 representing package p.q is therefore p\q on Windows, and p/q on oth‐
839 er systems.
840 • The package p.q.r is represented as the directory tree p\q\r (on Win‐
842 dows) or p/q/r (on other systems).
843 Within a directory or subdirectory, .java files represent classes and
845 interfaces in the corresponding package or subpackage.
846 For example:
848 • The class X declared in package p is represented by the file X.java
850 in the p directory.
851 • The class Y declared in package p.q is represented by the file Y.java
853 in the q subdirectory of directory p.
854 • The class Z declared in package p.q.r is represented by the file
856 Z.java in the r subdirectory of p\q (on Windows) or p/q (on other
857 systems).
858 In some situations, it is convenient to split the code into separate
860 directories, each structured as described above, and the aggregate list
861 of directories specified to javac.
862 Arrangement of Source Code for a Module
864 In the Java language, a module is a set of packages designed for reuse.
865 In addition to .java files for classes and interfaces, each module has
866 a source file called module-info.java which:
867 1. declares the module's name;
869 2. lists the packages exported by the module (to allow reuse by other
871 modules);
872 3. lists other modules required by the module (to reuse their exported
874 packages).
875 When packages are organized into a module, the module is represented by
877 one or more directories representing the packages in the module, one of
878 which contains the module-info.java file. It may be convenient, but it
879 is not required, to use a single directory, named after the module, to
880 contain the module-info.java file alongside the directory tree which
881 represents the packages in the module (i.e., the package hierarchy de‐
882 scribed above). The exact arrangement of source code for a module is
883 typically dictated by the conventions adopted by a development environ‐
884 ment (IDE) or build system.
885 For example:
887 • The module a.b.c may be represented by the directory a.b.c, on all
889 systems.
890 • The module's declaration is represented by the file module-info.java
892 in the a.b.c directory.
893 • If the module contains package p.q.r, then the a.b.c directory con‐
895 tains the directory tree p\q\r (on Windows) or p/q/r (on other sys‐
896 tems).
897 The development environment may prescribe some directory hierarchy be‐
899 tween the directory named for the module and the source files to be
900 read by javac.
901 For example:
903 • The module a.b.c may be represented by the directory a.b.c
905 • The module's declaration and the module's packages may be in some
907 subdirectory of a.b.c, such as src\main\java (on Windows) or
908 src/main/java (on other systems).
909
911 This section describes how to configure javac to perform a basic compi‐
912 lation.
913 See Configuring the Module System for additional details for use when
915 compiling for a release of the platform that supports modules.
916 Source Files
918 • Specify the source files to be compiled on the command line.
919 If there are no compilation errors, the corresponding class files will
921 be placed in the output directory.
922 Some systems may limit the amount you can put on a command line; to
924 work around those limits, you can use argument files.
925 When compiling code for modules, you can also specify source files in‐
927 directly, by using the --module or -m option.
928 Output Directory
930 • Use the -d option to specify an output directory in which to put the
931 compiled class files.
932 This will normally be organized in a package hierarchy, unless you are
934 compiling source code from multiple modules, in which case it will be
935 organized as a module hierarchy.
936 When the compilation has been completed, if you are compiling one or
938 more modules, you can place the output directory on the module path for
939 the Java launcher; otherwise, you can place the place the output direc‐
940 tory on the class path for the Java launcher.
941 Precompiled Code
943 The code to be compiled may refer to libraries beyond what is provided
944 by the platform. If so, you must place these libraries on the class
945 path or module path. If the library code is not in a module, place it
946 on the class path; if it is in a module, place it on the module path.
947 • Use the --class-path option to specify libraries to be placed on the
949 class path. Locations on the class path should be organized in a
950 package hierarchy. You can also use alternate forms of the option:
951 -classpath or -cp.
952 • Use the --module-path option to specify libraries to be placed on the
954 module path. Locations on the module path should either be modules
955 or directories of modules. You can also use an alternate form of the
956 option: -p.
957 See Configuring the Module System for details on how to modify the
959 default configuration of library modules.
960 Note: the options for the class path and module path are not mutually
962 exclusive, although it is not common to specify the class path when
963 compiling code for one or more modules.
964 Additional Source Files
966 The code to be compiled may refer to types in additional source files
967 that are not specified on the command line. If so, you must put those
968 source files on either the source path or module path. You can only
969 specify one of these options: if you are not compiling code for a mod‐
970 ule, or if you are only compiling code for a single module, use the
971 source path; if you are compiling code for multiple modules, use the
972 module source path.
973 • Use the --source-path option to specify the locations of additional
975 source files that may be read by javac. Locations on the source path
976 should be organized in a package hierarchy. You can also use an al‐
977 ternate form of the option: -sourcepath.
978 • Use the --module-source-path option one or more times to specify the
980 location of additional source files in different modules that may be
981 read by javac, or when compiling source files in multiple modules.
982 You can either specify the locations for each module individually, or
983 you can organize the source files so that you can specify the loca‐
984 tions all together. For more details, see The Module Source Path Op‐
985 tion.
986 If you want to be able to refer to types in additional source files but
988 do not want them to be compiled, use the -implicit option.
989 Note: if you are compiling code for multiple modules, you must always
991 specify a module source path, and all source files specified on the
992 command line must be in one of the directories on the module source
993 path, or in a subdirectory thereof.
994 Example of Compiling Multiple Source Files
996 This example compiles the Aloha.java, GutenTag.java, Hello.java, and
997 Hi.java source files in the greetings package.
998 Linux and macOS:
1000 % javac greetings/*.java
1002 % ls greetings
1003 Aloha.class GutenTag.class Hello.class Hi.class
1004 Aloha.java GutenTag.java Hello.java Hi.java
1005 Windows:
1007 C:\>javac greetings\*.java
1009 C:\>dir greetings
1010 Aloha.class GutenTag.class Hello.class Hi.class
1011 Aloha.java GutenTag.java Hello.java Hi.java
1012 Example of Specifying a User Class Path
1014 After changing one of the source files in the previous example, recom‐
1015 pile it:
1016 Linux and macOS:
1018 pwd
1020 /examples
1021 javac greetings/Hi.java
1022 Windows:
1024 C:\>cd
1026 \examples
1027 C:\>javac greetings\Hi.java
1028 Because greetings.Hi refers to other classes in the greetings package,
1030 the compiler needs to find these other classes. The previous example
1031 works because the default user class path is the directory that con‐
1032 tains the package directory. If you want to recompile this file with‐
1033 out concern for which directory you are in, then add the examples di‐
1034 rectory to the user class path by setting CLASSPATH. This example uses
1035 the -classpath option.
1036 Linux and macOS:
1038 javac -classpath /examples /examples/greetings/Hi.java
1040 Windows:
1042 C:\>javac -classpath \examples \examples\greetings\Hi.java
1044 If you change greetings.Hi to use a banner utility, then that utility
1046 also needs to be accessible through the user class path.
1047 Linux and macOS:
1049 javac -classpath /examples:/lib/Banners.jar \
1051 /examples/greetings/Hi.java
1052 Windows:
1054 C:\>javac -classpath \examples;\lib\Banners.jar ^
1056 \examples\greetings\Hi.java
1057 To execute a class in the greetings package, the program needs access
1059 to the greetings package, and to the classes that the greetings classes
1060 use.
1061 Linux and macOS:
1063 java -classpath /examples:/lib/Banners.jar greetings.Hi
1065 Windows:
1067 C:\>java -classpath \examples;\lib\Banners.jar greetings.Hi
1069
1071 If you want to include additional modules in your compilation, use the
1072 --add-modules option. This may be necessary when you are compiling
1073 code that is not in a module, or which is in an automatic module, and
1074 the code refers to API in the additional modules.
1075 If you want to restrict the set of modules in your compilation, use the
1077 --limit-modules option. This may be useful if you want to ensure that
1078 the code you are compiling is capable of running on a system with a
1079 limited set of modules installed.
1080 If you want to break encapsulation and specify that additional packages
1082 should be considered as exported from a module, use the --add-exports
1083 option. This may be useful when performing white-box testing; relying
1084 on access to internal API in production code is strongly discouraged.
1085 If you want to specify that additional packages should be considered as
1087 required by a module, use the --add-reads option. This may be useful
1088 when performing white-box testing; relying on access to internal API in
1089 production code is strongly discouraged.
1090 You can patch additional content into any module using the --patch-mod‐
1092 ule option. See [Patching a Module] for more details.
1093
1095 To compile a source file, the compiler often needs information about a
1096 module or type, but the declaration is not in the source files speci‐
1097 fied on the command line.
1098 javac needs type information for every class or interface used, extend‐
1100 ed, or implemented in the source file. This includes classes and in‐
1101 terfaces not explicitly mentioned in the source file, but that provide
1102 information through inheritance.
1103 For example, when you create a subclass of java.awt.Window, you are al‐
1105 so using the ancestor classes of Window: java.awt.Container, ja‐
1106 va.awt.Component, and java.lang.Object.
1107 When compiling code for a module, the compiler also needs to have
1109 available the declaration of that module.
1110 A successful search may produce a class file, a source file, or both.
1112 If both are found, then you can use the -Xprefer option to instruct the
1113 compiler which to use.
1114 If a search finds and uses a source file, then by default javac com‐
1116 piles that source file. This behavior can be altered with -implicit.
1117 The compiler might not discover the need for some type information un‐
1119 til after annotation processing completes. When the type information
1120 is found in a source file and no -implicit option is specified, the
1121 compiler gives a warning that the file is being compiled without being
1122 subject to annotation processing. To disable the warning, either spec‐
1123 ify the file on the command line (so that it will be subject to annota‐
1124 tion processing) or use the -implicit option to specify whether or not
1125 class files should be generated for such source files.
1126 The way that javac locates the declarations of those types depends on
1128 whether the reference exists within code for a module or not.
1129 Searching Package Oriented Paths
1131 When searching for a source or class file on a path composed of package
1132 oriented locations, javac will check each location on the path in turn
1133 for the possible presence of the file. The first occurrence of a par‐
1134 ticular file shadows (hides) any subsequent occurrences of like-named
1135 files. This shadowing does not affect any search for any files with a
1136 different name. This can be convenient when searching for source
1137 files, which may be grouped in different locations, such as shared
1138 code, platform-specific code and generated code. It can also be useful
1139 when injecting alternate versions of a class file into a package, to
1140 debugging or other instrumentation reasons. But, it can also be dan‐
1141 gerous, such as when putting incompatible different versions of a li‐
1142 brary on the class path.
1143 Searching Module Oriented Paths
1145 Prior to scanning any module paths for any package or type declara‐
1146 tions, javac will lazily scan the following paths and locations to de‐
1147 termine the modules that will be used in the compilation.
1148 • The module source path (see the --module-source-path option)
1150 • The path for upgradeable modules (see the --upgrade-module-path op‐
1152 tion)
1153 • The system modules (see the --system option)
1155 • The user module path ( see the --module-path option)
1157 For any module, the first occurrence of the module during the scan com‐
1159 pletely shadows (hides) any subsequent appearance of a like-named mod‐
1160 ule. While locating the modules, javac is able to determine the pack‐
1161 ages exported by the module and to associate with each module a package
1162 oriented path for the contents of the module. For any previously com‐
1163 piled module, this path will typically be a single entry for either a
1164 directory or a file that provides an internal directory-like hierarchy,
1165 such as a JAR file. Thus, when searching for a type that is in a pack‐
1166 age that is known to be exported by a module, javac can locate the dec‐
1167 laration directly and efficiently.
1168 Searching for the Declaration of a Module
1170 If the module has been previously compiled, the module declaration is
1171 located in a file named module-info.class in the root of the package
1172 hierarchy for the content of the module.
1173 If the module is one of those currently being compiled, the module dec‐
1175 laration will be either the file named module-info.class in the root of
1176 the package hierarchy for the module in the class output directory, or
1177 the file named module-info.java in one of the locations on the source
1178 path or one the module source path for the module.
1179 Searching for the Declaration of a Type When the Reference is not in a Mod‐
1181 ule
1182 When searching for a type that is referenced in code that is not in a
1183 module, javac will look in the following places:
1184 • The platform classes (or the types in exported packages of the plat‐
1186 form modules) (This is for compiled class files only.)
1187 • Types in exported packages of any modules on the module path, if ap‐
1189 plicable. (This is for compiled class files only.)
1190 • Types in packages on the class path and/or source path:
1192 • If both are specified, javac looks for compiled class files on the
1194 class path and for source files on the source path.
1195 • If the class path is specified, but not source path, javac looks
1197 for both compiled class files and source files on the class path.
1198 • If the class path is not specified, it defaults to the current di‐
1200 rectory.
1201 When looking for a type on the class path and/or source path, if both a
1203 compiled class file and a source file are found, the most recently mod‐
1204 ified file will be used by default. If the source file is newer, it
1205 will be compiled and will may override any previously compiled version
1206 of the file. You can use the -Xprefer option to override the default
1207 behavior.
1208 Searching for the Declaration of a Type When the Reference is in a Module
1210 When searching for a type that is referenced in code in a module, javac
1211 will examine the declaration of the enclosing module to determine if
1212 the type is in a package that is exported from another module that is
1213 readable by the enclosing module. If so, javac will simply and direct‐
1214 ly go to the definition of that module to find the definition of the
1215 required type. Unless the module is another of the modules being com‐
1216 piled, javac will only look for compiled class files files. In other
1217 words, javac will not look for source files in platform modules or mod‐
1218 ules on the module path.
1219 If the type being referenced is not in some other readable module,
1221 javac will examine the module being compiled to try and find the decla‐
1222 ration of the type. javac will look for the declaration of the type as
1223 follows:
1224 • Source files specified on the command line or on the source path or
1226 module source path.
1227 • Previously compiled files in the output directory.
1229
1231 javac generally assumes that source files and compiled class files will
1232 be organized in a file system directory hierarchy or in a type of file
1233 that supports in an internal directory hierarchy, such as a JAR file.
1234 Three different kinds of hierarchy are supported: a package hierarchy,
1235 a module hierarchy, and a module source hierarchy.
1236 While javac is fairly relaxed about the organization of source code,
1238 beyond the expectation that source will be organized in one or package
1239 hierarchies, and can generally accommodate organizations prescribed by
1240 development environments and build tools, Java tools in general, and
1241 javac and the Java launcher in particular, are more stringent regarding
1242 the organization of compiled class files, and will be organized in
1243 package hierarchies or module hierarchies, as appropriate.
1244 The location of these hierarchies are specified to javac with command-
1246 line options, whose names typically end in "path", like --source-path
1247 or --class-path. Also as a general rule, path options whose name in‐
1248 cludes the word module, like --module-path, are used to specify module
1249 hierarchies, although some module-related path options allow a package
1250 hierarchy to be specified on a per-module basis. All other path op‐
1251 tions are used to specify package hierarchies.
1252 Package Hierarchy
1254 In a package hierarchy, directories and subdirectories are used to rep‐
1255 resent the component parts of the package name, with the source file or
1256 compiled class file for a type being stored as a file with an extension
1257 of .java or .class in the most nested directory.
1258 For example, in a package hierarchy, the source file for a class
1260 com.example.MyClass will be stored in the file com/example/MyClass.java
1261 Module Hierarchy
1263 In a module hierarchy, the first level of directories are named for the
1264 modules in the hierarchy; within each of those directories the contents
1265 of the module are organized in package hierarchies.
1266 For example, in a module hierarchy, the compiled class file for a type
1268 called com.example.MyClass in a module called my.library will be stored
1269 in my.library/com/example/MyClass.class.
1270 The various output directories used by javac (the class output directo‐
1272 ry, the source output directory, and native header output directory)
1273 will all be organized in a module hierarchy when multiple modules are
1274 being compiled.
1275 Module Source Hierarchy
1277 Although the source for each individual module should always be orga‐
1278 nized in a package hierarchy, it may be convenient to group those hier‐
1279 archies into a module source hierarchy. This is similar to a module
1280 hierarchy, except that there may be intervening directories between the
1281 directory for the module and the directory that is the root of the
1282 package hierarchy for the source code of the module.
1283 For example, in a module source hierarchy, the source file for a type
1285 called com.example.MyClass in a module called my.library may be stored
1286 in a file such as my.library/src/main/java/com/example/MyClass.java.
1287
1289 The --module-source-path option has two forms: a module-specific form,
1290 in which a package path is given for each module containing code to be
1291 compiled, and a module-pattern form, in which the source path for each
1292 module is specified by a pattern. The module-specific form is general‐
1293 ly simpler to use when only a small number of modules are involved; the
1294 module-pattern form may be more convenient when the number of modules
1295 is large and the modules are organized in a regular manner that can be
1296 described by a pattern.
1297 Multiple instances of the --module-source-path option may be given,
1299 each one using either the module-pattern form or the module-specific
1300 form, subject to the following limitations:
1301 • the module-pattern form may be used at most once
1303 • the module-specific form may be used at most once for any given mod‐
1305 ule
1306 If the module-specific form is used for any module, the associated
1308 search path overrides any path that might otherwise have been inferred
1309 from the module-pattern form.
1310 Module-specific form
1312 The module-specific form allows an explicit search path to be given for
1313 any specific module. This form is:
1314 • --module-source-path module-name=file-path (path-separator file-
1316 path)*
1317 The path separator character is ; on Windows, and : otherwise.
1319 Note: this is similar to the form used for the --patch-module option.
1321 Module-pattern form
1323 The module-pattern form allows a concise specification of the module
1324 source path for any number of modules organized in regular manner.
1325 • --module-source-path pattern
1327 The pattern is defined by the following rules, which are applied in or‐
1329 der:
1330 • The argument is considered to be a series of segments separated by
1332 the path separator character (; on Windows, and : otherwise).
1333 • Each segment containing curly braces of the form
1335 string1{alt1 ( ,alt2 )* } string2
1337 is considered to be replaced by a series of segments formed by "ex‐
1339 panding" the braces:
1340 string1 alt1 string2
1342 string1 alt2 string2
1343 and so on...
1344 The braces may be nested.
1346 This rule is applied for all such usages of braces.
1348 • Each segment must have at most one asterisk (*). If a segment does
1350 not contain an asterisk, it is considered to be as though the file
1351 separator character and an asterisk are appended.
1352 For any module M, the source path for that module is formed from the
1354 series of segments obtained by substituting the module name M for the
1355 asterisk in each segment.
1356 Note: in this context, the asterisk is just used as a special marker,
1358 to denote the position in the path of the module name. It should not
1359 be confused with the use of * as a file name wildcard character, as
1360 found on most operating systems.
1361
1363 javac allows any content, whether in source or compiled form, to be
1364 patched into any module using the --patch-module option. You may want
1365 to do this to compile alternative implementations of a class to be
1366 patched at runtime into a JVM, or to inject additional classes into the
1367 module, such as when testing.
1368 The form of the option is:
1370 • --patch-module module-name=file-path (path-separator file-path )*
1372 The path separator character is ; on Windows, and : otherwise. The
1374 paths given for the module must specify the root of a package hierarchy
1375 for the contents of the module
1376 The option may be given at most once for any given module. Any content
1378 on the path will hide any like-named content later in the path and in
1379 the patched module.
1380 When patching source code into more than one module, the --module-
1382 source-path must also be used, so that the output directory is orga‐
1383 nized in a module hierarchy, and capable of holding the compiled class
1384 files for the modules being compiled.
1385
1387 The javac command provides direct support for annotation processing.
1388 The API for annotation processors is defined in the javax.annota‐
1390 tion.processing and javax.lang.model packages and subpackages.
1391 How Annotation Processing Works
1393 Unless annotation processing is disabled with the -proc:none option,
1394 the compiler searches for any annotation processors that are available.
1395 The search path can be specified with the -processorpath option. If no
1396 path is specified, then the user class path is used. Processors are
1397 located by means of service provider-configuration files named META-
1398 INF/services/javax.annotation.processing.Processor on the search path.
1399 Such files should contain the names of any annotation processors to be
1400 used, listed one per line. Alternatively, processors can be specified
1401 explicitly, using the -processor option.
1402 After scanning the source files and classes on the command line to de‐
1404 termine what annotations are present, the compiler queries the proces‐
1405 sors to determine what annotations they process. When a match is
1406 found, the processor is called. A processor can claim the annotations
1407 it processes, in which case no further attempt is made to find any pro‐
1408 cessors for those annotations. After all of the annotations are
1409 claimed, the compiler does not search for additional processors.
1410 If any processors generate new source files, then another round of an‐
1412 notation processing occurs: Any newly generated source files are
1413 scanned, and the annotations processed as before. Any processors
1414 called on previous rounds are also called on all subsequent rounds.
1415 This continues until no new source files are generated.
1416 After a round occurs where no new source files are generated, the anno‐
1418 tation processors are called one last time, to give them a chance to
1419 complete any remaining work. Finally, unless the -proc:only option is
1420 used, the compiler compiles the original and all generated source
1421 files.
1422 If you use an annotation processor that generates additional source
1424 files to be included in the compilation, you can specify a default mod‐
1425 ule to be used for the newly generated files, for use when a module
1426 declaration is not also generated. In this case, use the --default-
1427 module-for-created-files option.
1428 Compilation Environment and Runtime Environment.
1430 The declarations in source files and previously compiled class files
1431 are analyzed by javac in a compilation environment that is distinct
1432 from the runtime environment used to execute javac itself. Although
1433 there is a deliberate similarity between many javac options and like-
1434 named options for the Java launcher, such as --class-path, --module-
1435 path and so on, it is important to understand that in general the javac
1436 options just affect the environment in which the source files are com‐
1437 piled, and do not affect the operation of javac itself.
1438 The distinction between the compilation environment and runtime envi‐
1440 ronment is significant when it comes to using annotation processors.
1441 Although annotations processors process elements (declarations) that
1442 exist in the compilation environment, the annotation processor itself
1443 is executed in the runtime environment. If an annotation processor has
1444 dependencies on libraries that are not in modules, the libraries can be
1445 placed, along with the annotation processor itself, on the processor
1446 path. (See the --processor-path option.) If the annotation processor
1447 and its dependencies are in modules, you should use the processor mod‐
1448 ule path instead. (See the --processor-module-path option.) When
1449 those are insufficient, it may be necessary to provide further configu‐
1450 ration of the runtime environment. This can be done in two ways:
1451 1. If javac is invoked from the command line, options can be passed to
1453 the underlying runtime by prefixing the option with -J.
1454 2. You can start an instance of a Java Virtual Machine directly and use
1456 command line options and API to configure an environment in which
1457 javac can be invoked via one of its APIs.
1458
1460 javac can compile code that is to be used on other releases of the
1461 platform, using either the --release option, or the --source/-source
1462 and --target/-target options, together with additional options to spec‐
1463 ify the platform classes.
1464 Depending on the desired platform release, there are some restrictions
1466 on some of the options that can be used.
1467 • When compiling for JDK 8 and earlier releases, you cannot use any op‐
1469 tion that is intended for use with the module system. This includes
1470 all of the following options:
1471 • --module-source-path, --upgrade-module-path, --system, --module-
1473 path, --add-modules, --add-exports, --add-opens, --add-reads,
1474 --limit-modules, --patch-module
1475 If you use the --source/-source or --target/-target options, you
1477 should also set the appropriate platform classes using the boot class
1478 path family of options.
1479 • When compiling for JDK 9 and later releases, you cannot use any op‐
1481 tion that is intended to configure the boot class path. This in‐
1482 cludes all of the following options:
1483 • -Xbootclasspath/p:, -Xbootclasspath, -Xbootclasspath/a:, -endorsed‐
1485 dirs, -Djava.endorsed.dirs, -extdirs, -Djava.ext.dirs, -profile
1486 If you use the --source/-source or --target/-target options, you
1488 should also set the appropriate platform classes using the --system
1489 option to give the location of an appropriate installed release of
1490 JDK.
1491 When using the --release option, only the supported documented API for
1493 that release may be used; you cannot use any options to break encapsu‐
1494 lation to access any internal classes.
1495
1497 The javac compiler can be invoked using an API in three different ways:
1498 The Java Compiler API
1500 This provides the most flexible way to invoke the compiler, in‐
1501 cluding the ability to compile source files provided in memory
1502 buffers or other non-standard file systems.
1503 The ToolProvider API
1505 A ToolProvider for javac can be obtained by calling Tool‐
1506 Provider.findFirst("javac"). This returns an object with the
1507 equivalent functionality of the command-line tool.
1508 Note: This API should not be confused with the like-named API in
1510 the javax.tools package.
1511 The javac Legacy API
1513 This API is retained for backward compatibility only. All new
1514 code should use either the Java Compiler API or the ToolProvider
1515 API.
1516 Note: All other classes and methods found in a package with names that
1518 start with com.sun.tools.javac (subpackages of com.sun.tools.javac) are
1519 strictly internal and subject to change at any time.
1520
1522 cast Warns about unnecessary and redundant casts, for example:
1523 String s = (String) "Hello!"
1525 classfile
1527 Warns about issues related to class file contents.
1528 deprecation
1530 Warns about the use of deprecated items. For example:
1531 java.util.Date myDate = new java.util.Date();
1533 int currentDay = myDate.getDay();
1534 The method java.util.Date.getDay has been deprecated since JDK
1536 1.1.
1537 dep-ann
1539 Warns about items that are documented with the @deprecated
1540 Javadoc comment, but do not have the @Deprecated annotation, for
1541 example:
1542 /**
1544 * @deprecated As of Java SE 7, replaced by {@link #newMethod()}
1545 */
1546 public static void deprecatedMethod() { }
1547 public static void newMethod() { }
1548 divzero
1550 Warns about division by the constant integer 0, for example:
1551 int divideByZero = 42 / 0;
1553 empty Warns about empty statements after ifstatements, for example:
1555 class E {
1557 void m() {
1558 if (true) ;
1559 }
1560 }
1561 fallthrough
1563 Checks the switch blocks for fall-through cases and provides a
1564 warning message for any that are found. Fall-through cases are
1565 cases in a switch block, other than the last case in the block,
1566 whose code does not include a break statement, allowing code ex‐
1567 ecution to fall through from that case to the next case. For
1568 example, the code following the case 1 label in this switch
1569 block does not end with a break statement:
1570 switch (x) {
1572 case 1:
1573 System.out.println("1");
1574 // No break statement here.
1575 case 2:
1576 System.out.println("2");
1577 }
1578 If the -Xlint:fallthrough option was used when compiling this
1580 code, then the compiler emits a warning about possible fall-
1581 through into case, with the line number of the case in question.
1582 finally
1584 Warns about finally clauses that cannot be completed normally,
1585 for example:
1586 public static int m() {
1588 try {
1589 throw new NullPointerException();
1590 } catch (NullPointerException(); {
1591 System.err.println("Caught NullPointerException.");
1592 return 1;
1593 } finally {
1594 return 0;
1595 }
1596 }
1597 The compiler generates a warning for the finally block in this
1599 example. When the int method is called, it returns a value of
1600 0. A finally block executes when the try block exits. In this
1601 example, when control is transferred to the catch block, the int
1602 method exits. However, the finally block must execute, so it's
1603 executed, even though control was transferred outside the meth‐
1604 od.
1605 options
1607 Warns about issues that related to the use of command-line op‐
1608 tions. See Compiling for Earlier Releases of the Platform.
1609 overrides
1611 Warns about issues related to method overrides. For example,
1612 consider the following two classes:
1613 public class ClassWithVarargsMethod {
1615 void varargsMethod(String... s) { }
1616 }
1617 public class ClassWithOverridingMethod extends ClassWithVarargsMethod {
1619 @Override
1620 void varargsMethod(String[] s) { }
1621 }
1622 The compiler generates a warning similar to the following:.
1624 warning: [override] varargsMethod(String[]) in ClassWithOverridingMethod
1626 overrides varargsMethod(String...) in ClassWithVarargsMethod; overriding
1627 method is missing '...'
1628 When the compiler encounters a varargs method, it translates the
1630 varargs formal parameter into an array. In the method Class‐
1631 WithVarargsMethod.varargsMethod, the compiler translates the
1632 varargs formal parameter String... s to the formal parameter
1633 String[] s, an array that matches the formal parameter of the
1634 method ClassWithOverridingMethod.varargsMethod. Consequently,
1635 this example compiles.
1636 path Warns about invalid path elements and nonexistent path directo‐
1638 ries on the command line (with regard to the class path, the
1639 source path, and other paths). Such warnings cannot be sup‐
1640 pressed with the @SuppressWarnings annotation. For example:
1641 • Linux and macOS: javac -Xlint:path -classpath /nonexistentpath
1643 Example.java
1644 • Windows: javac -Xlint:path -classpath C:\nonexistentpath Exam‐
1646 ple.java
1647 processing
1649 Warns about issues related to annotation processing. The com‐
1650 piler generates this warning when you have a class that has an
1651 annotation, and you use an annotation processor that cannot han‐
1652 dle that type of annotation. For example, the following is a
1653 simple annotation processor:
1654 Source file AnnoProc.java:
1656 import java.util.*;
1658 import javax.annotation.processing.*;
1659 import javax.lang.model.*;
1660 import javax.lang.model.element.*;
1661 @SupportedAnnotationTypes("NotAnno")
1663 public class AnnoProc extends AbstractProcessor {
1664 public boolean process(Set<? extends TypeElement> elems, RoundEnvironment renv){
1665 return true;
1666 }
1667 public SourceVersion getSupportedSourceVersion() {
1669 return SourceVersion.latest();
1670 }
1671 }
1672 Source file AnnosWithoutProcessors.java:
1674 @interface Anno { }
1676 @Anno
1678 class AnnosWithoutProcessors { }
1679 The following commands compile the annotation processor Anno‐
1681 Proc, then run this annotation processor against the source file
1682 AnnosWithoutProcessors.java:
1683 javac AnnoProc.java
1685 javac -cp . -Xlint:processing -processor AnnoProc -proc:only AnnosWithoutProcessors.java
1686 When the compiler runs the annotation processor against the
1688 source file AnnosWithoutProcessors.java, it generates the fol‐
1689 lowing warning:
1690 warning: [processing] No processor claimed any of these annotations: Anno
1692 To resolve this issue, you can rename the annotation defined and
1694 used in the class AnnosWithoutProcessors from Anno to NotAnno.
1695 rawtypes
1697 Warns about unchecked operations on raw types. The following
1698 statement generates a rawtypes warning:
1699 void countElements(List l) { ... }
1701 The following example does not generate a rawtypes warning:
1703 void countElements(List<?> l) { ... }
1705 List is a raw type. However, List<?> is an unbounded wildcard
1707 parameterized type. Because List is a parameterized interface,
1708 always specify its type argument. In this example, the List
1709 formal argument is specified with an unbounded wildcard (?) as
1710 its formal type parameter, which means that the countElements
1711 method can accept any instantiation of the List interface.
1712 serial Warns about missing serialVersionUID definitions on serializable
1714 classes. For example:
1715 public class PersistentTime implements Serializable
1717 {
1718 private Date time;
1719 public PersistentTime() {
1721 time = Calendar.getInstance().getTime();
1722 }
1723 public Date getTime() {
1725 return time;
1726 }
1727 }
1728 The compiler generates the following warning:
1730 warning: [serial] serializable class PersistentTime has no definition of
1732 serialVersionUID
1733 If a serializable class does not explicitly declare a field
1735 named serialVersionUID, then the serialization runtime environ‐
1736 ment calculates a default serialVersionUID value for that class
1737 based on various aspects of the class, as described in the Java
1738 Object Serialization Specification. However, it's strongly rec‐
1739 ommended that all serializable classes explicitly declare seri‐
1740 alVersionUID values because the default process of computing se‐
1741 rialVersionUID values is highly sensitive to class details that
1742 can vary depending on compiler implementations. As a result,
1743 this might cause an unexpected InvalidClassExceptions during de‐
1744 serialization. To guarantee a consistent serialVersionUID value
1745 across different Java compiler implementations, a serializable
1746 class must declare an explicit serialVersionUID value.
1747 static Warns about issues relating to the use of static variables, for
1749 example:
1750 class XLintStatic {
1752 static void m1() { }
1753 void m2() { this.m1(); }
1754 }
1755 The compiler generates the following warning:
1757 warning: [static] static method should be qualified by type name,
1759 XLintStatic, instead of by an expression
1760 To resolve this issue, you can call the static method m1 as fol‐
1762 lows:
1763 XLintStatic.m1();
1765 Alternately, you can remove the static keyword from the declara‐
1767 tion of the method m1.
1768 this-escape
1770 Warns about constructors leaking this prior to subclass initial‐
1771 ization. For example, this class:
1772 public class MyClass {
1774 public MyClass() {
1775 System.out.println(this.hashCode());
1776 }
1777 }
1778 generates the following warning:
1780 MyClass.java:3: warning: [this-escape] possible 'this' escape
1782 before subclass is fully initialized
1783 System.out.println(this.hashCode());
1784 ^
1785 A 'this' escape warning is generated when a constructor does
1787 something that might result in a subclass method being invoked
1788 before the constructor returns. In such cases the subclass
1789 method would be operating on an incompletely initialized in‐
1790 stance. In the above example, a subclass of MyClass that over‐
1791 rides hashCode() to incorporate its own fields would likely pro‐
1792 duce an incorrect result when invoked as shown.
1793 Warnings are only generated if a subclass could exist that is
1795 outside of the current module (or package, if no module) being
1796 compiled. So, for example, constructors in final and non-public
1797 classes do not generate warnings.
1798 try Warns about issues relating to the use of try blocks, including
1800 try-with-resources statements. For example, a warning is gener‐
1801 ated for the following statement because the resource ac de‐
1802 clared in the try block is not used:
1803 try ( AutoCloseable ac = getResource() ) { // do nothing}
1805 unchecked
1807 Gives more detail for unchecked conversion warnings that are
1808 mandated by the Java Language Specification, for example:
1809 List l = new ArrayList<Number>();
1811 List<String> ls = l; // unchecked warning
1812 During type erasure, the types ArrayList<Number> and
1814 List<String> become ArrayList and List, respectively.
1815 The ls command has the parameterized type List<String>. When
1817 the List referenced by l is assigned to ls, the compiler gener‐
1818 ates an unchecked warning. At compile time, the compiler and
1819 JVM cannot determine whether l refers to a List<String> type.
1820 In this case, l does not refer to a List<String> type. As a re‐
1821 sult, heap pollution occurs.
1822 A heap pollution situation occurs when the List object l, whose
1824 static type is List<Number>, is assigned to another List object,
1825 ls, that has a different static type, List<String>. However,
1826 the compiler still allows this assignment. It must allow this
1827 assignment to preserve backward compatibility with releases of
1828 Java SE that do not support generics. Because of type erasure,
1829 List<Number> and List<String> both become List. Consequently,
1830 the compiler allows the assignment of the object l, which has a
1831 raw type of List, to the object ls.
1832 varargs
1834 Warns about unsafe use of variable arguments (varargs) methods,
1835 in particular, those that contain non-reifiable arguments, for
1836 example:
1837 public class ArrayBuilder {
1839 public static <T> void addToList (List<T> listArg, T... elements) {
1840 for (T x : elements) {
1841 listArg.add(x);
1842 }
1843 }
1844 }
1845 A non-reifiable type is a type whose type information is not
1847 fully available at runtime.
1848 The compiler generates the following warning for the definition
1850 of the method ArrayBuilder.addToList:
1851 warning: [varargs] Possible heap pollution from parameterized vararg type T
1853 When the compiler encounters a varargs method, it translates the
1855 varargs formal parameter into an array. However, the Java pro‐
1856 gramming language does not permit the creation of arrays of pa‐
1857 rameterized types. In the method ArrayBuilder.addToList, the
1858 compiler translates the varargs formal parameter T... elements
1859 to the formal parameter T[] elements, an array. However, be‐
1860 cause of type erasure, the compiler converts the varargs formal
1861 parameter to Object[] elements. Consequently, there's a possi‐
1862 bility of heap pollution.
1863JDK 21 2023 JAVAC(1)