1JAVAC(1)                         JDK Commands                         JAVAC(1)
2
3
4

NAME

6       javac - read Java declarations and compile them into class files
7

SYNOPSIS

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

DESCRIPTION

20       The  javac  command reads source files that contain module, package and
21       type declarations written in the Java programming  language,  and  com‐
22       piles them into class files that run on the Java Virtual Machine.
23
24       The javac command can also process annotations in Java source files and
25       classes.
26
27       Source files must have a file name extension  of  .java.   Class  files
28       have a file name extension of .class.  Both source and class files nor‐
29       mally have file names that identify the contents.  For example, a class
30       called  Shape would be declared in a source file called Shape.java, and
31       compiled into a class file called Shape.class.
32
33       There are two ways to specify source files to javac:
34
35       · For a small number of source files, you can list their file names  on
36         the command line.
37
38       · For  a large number of source files, you can use the @filename option
39         on the command line to specify an argument file that lists their file
40         names.  See Standard Options for a description of the option and Com‐
41         mand-Line Argument Files for a description of javac argument files.
42
43       The order of source files specified on the command line or in an  argu‐
44       ment  file is not important.  javac will compile the files together, as
45       a group, and will automatically resolve any  dependencies  between  the
46       declarations in the various source files.
47
48       javac  expects  that source files are arranged in one or more directory
49       hierarchies on the file system,  described  in  Arrangement  of  Source
50       Code.
51
52       To  compile a source file, javac needs to find the declaration of every
53       class or interface that is used, extended, or implemented by  the  code
54       in  the source file.  This lets javac check that the code has the right
55       to access those classes and interfaces.   Rather  than  specifying  the
56       source  files  of  those classes and interfaces explicitly, you can use
57       command-line options to tell javac where to  search  for  their  source
58       files.  If you have compiled those source files previously, you can use
59       options to tell javac where  to  search  for  the  corresponding  class
60       files.   The  options,  which  all have names ending in "path", are de‐
61       scribed in Standard Options, and further  described  in  Configuring  a
62       Compilation and Searching for Module, Package and Type Declarations.
63
64       By default, javac compiles each source file to a class file in the same
65       directory as the source file.  However, it is recommended to specify  a
66       separate destination directory with the -d option.
67
68       Command-line  options  and environment variables also control how javac
69       performs various tasks:
70
71       · Compiling code to run on earlier releases of the JDK.
72
73       · Compiling code to run under a debugger.
74
75       · Checking for stylistic issues in Java source code.
76
77       · Checking for problems in javadoc comments (/** ... */).
78
79       · Processing annotations in source files and class files.
80
81       · Upgrading and patching modules in the compile-time environment.
82
83       javac supports Compiling for Earlier Releases Of The Platform  and  can
84       also be invoked from Java code using one of a number of APIs
85

OPTIONS

87       javac  provides  standard  options,  and  extra options that are either
88       non-standard or are for advanced use.
89
90       Some options take one or more arguments.  If an argument contains  spa‐
91       ces  or other whitespace characters, the value should be quoted accord‐
92       ing to the conventions of the environment being used to  invoke  javac.
93       If  the option begins with a single dash (-) the argument should either
94       directly follow the option name, or should be separated  with  a  colon
95       (:)  or whitespace, depending on the option.  If the option begins with
96       a double dash (--), the argument may be separated either by  whitespace
97       or by an equals (=) character with no additional whitespace.  For exam‐
98       ple,
99
100              -Aname="J. Duke"
101              -proc:only
102              -d myDirectory
103              --module-version 3
104              --module-version=3
105
106       In the following lists of options, an argument  of  path  represents  a
107       search  path,  composed of a list of file system locations separated by
108       the platform path separator character,  (semicolon  ;  on  Windows,  or
109       colon : on other systems.) Depending on the option, the file system lo‐
110       cations may be directories, JAR files or JMOD files.
111
112   Standard Options
113       @filename
114              Reads options and file names from a file.  To shorten or simpli‐
115              fy  the  javac  command,  you can specify one or more files that
116              contain arguments to the  javac  command  (except  -J  options).
117              This  lets you to create javac commands of any length on any op‐
118              erating system.  See Command-Line Argument Files.
119
120       -Akey[=value]
121              Specifies options to pass to annotation processors.   These  op‐
122              tions are not interpreted by javac directly, but are made avail‐
123              able for use by individual processors.  The key value should  be
124              one or more identifiers separated by a dot (.).
125
126       --add-modules module,module
127              Specifies  root  modules  to  resolve in addition to the initial
128              modules, or all modules on the module path if module is ALL-MOD‐
129              ULE-PATH.
130
131       --boot-class-path path or -bootclasspath path
132              Overrides the location of the bootstrap class files.
133
134              Note: This can only be used when compiling for releases prior to
135              JDK 9.   As  applicable,  see  the  descriptions  in  --release,
136              -source, or -target for details.  For JDK 9 or later, see --sys‐
137              tem.
138
139       --class-path path, -classpath path, or -cp path
140              Specifies where to find user class files and annotation  proces‐
141              sors.   This  class  path  overrides  the user class path in the
142              CLASSPATH environment variable.
143
144              · If --class-path, -classpath, or -cp are  not  specified,  then
145                the  user class path is the value of the CLASSPATH environment
146                variable, if that is set, or else the current directory.
147
148              · If not compiling code for modules,  if  the  --source-path  or
149                -sourcepath` option is not specified, then the user class path
150                is also searched for source files.
151
152              · If the -processorpath option is not specified, then the  class
153                path is also searched for annotation processors.
154
155       -d directory
156              Sets  the  destination directory (or class output directory) for
157              class files.  If a class is part of a package, then  javac  puts
158              the  class  file in a subdirectory that reflects the module name
159              (if appropriate) and package name.  The directory, and any  nec‐
160              essary  subdirectories,  will  be created if they do not already
161              exist.
162
163              If the -d option is not specified, then javac  puts  each  class
164              file  in the same directory as the source file from which it was
165              generated.
166
167              Except when compiling code for multiple modules, the contents of
168              the  class output directory will be organized in a package hier‐
169              archy.  When compiling code for multiple modules,  the  contents
170              of the output directory will be organized in a module hierarchy,
171              with the contents of each module  in  a  separate  subdirectory,
172              each organized as a package hierarchy.
173
174              Note:  When  compiling  code  for one or more modules, the class
175              output directory will automatically be  checked  when  searching
176              for  previously  compiled  classes.  When not compiling for mod‐
177              ules, for backwards compatibility, the directory is not automat‐
178              ically  checked  for  previously  compiled classes, and so it is
179              recommended to specify the class output directory as one of  the
180              locations  on the user class path, using the --class-path option
181              or one of its alternate forms.
182
183       -deprecation
184              Shows a description of each use or override of a deprecated mem‐
185              ber  or  class.   Without the -deprecation option, javac shows a
186              summary of the source files that use or override deprecated mem‐
187              bers  or  classes.   The  -deprecation  option  is shorthand for
188              -Xlint:deprecation.
189
190       --enable-preview
191              Enables preview language features.  Used in conjunction with ei‐
192              ther -source or --release.
193
194       -encoding encoding
195              Specifies  character  encoding  used  by  source  files, such as
196              EUC-JP and UTF-8.  If the -encoding  option  is  not  specified,
197              then the platform default converter is used.
198
199       -endorseddirs directories
200              Overrides the location of the endorsed standards path.
201
202              Note: This can only be used when compiling for releases prior to
203              JDK 9.   As  applicable,  see  the  descriptions  in  --release,
204              -source, or -target for details.
205
206       -extdirs directories
207              Overrides the location of the installed extensions.  directories
208              is a list of directories, separated by the platform path separa‐
209              tor (; on Windows, and : otherwise).  Each JAR file in the spec‐
210              ified directories is searched for class files.   All  JAR  files
211              found become part of the class path.
212
213              If you are compiling for a release of the platform that supports
214              the Extension Mechanism, then this option specifies the directo‐
215              ries  that  contain  the  extension classes.  See [Compiling for
216              Other Releases of the Platform].
217
218              Note: This can only be used when compiling for releases prior to
219              JDK  9.   As  applicable,  see  the  descriptions  in --release,
220              -source, or -target for details.
221
222       -g     Generates all debugging information, including local  variables.
223              By default, only line number and source file information is gen‐
224              erated.
225
226       -g:[lines, vars, source]
227              Generates only the kinds of debugging information  specified  by
228              the comma-separated list of keywords.  Valid keywords are:
229
230              lines  Line number debugging information.
231
232              vars   Local variable debugging information.
233
234              source Source file debugging information.
235
236       -g:none
237              Does not generate debugging information.
238
239       -h directory
240              Specifies where to place generated native header files.
241
242              When  you specify this option, a native header file is generated
243              for each class that contains native methods or that has  one  or
244              more  constants  annotated  with the java.lang.annotation.Native
245              annotation.  If the class is part of a package, then the compil‐
246              er  puts  the native header file in a subdirectory that reflects
247              the module name (if appropriate) and package name.  The directo‐
248              ry, and any necessary subdirectories, will be created if they do
249              not already exist.
250
251       --help, -help or -?
252              Prints a synopsis of the standard options.
253
254       --help-extra or -X
255              Prints a synopsis of the set of extra options.
256
257       -implicit:[none, class]
258              Specifies whether or not to generate class files for  implicitly
259              referenced files:
260
261              · -implicit:class --- Automatically generates class files.
262
263              · -implicit:none --- Suppresses class file generation.
264
265              If  this option is not specified, then the default automatically
266              generates class files.  In this  case,  the  compiler  issues  a
267              warning if any class files are generated when also doing annota‐
268              tion processing.  The warning is not issued when  the  -implicit
269              option is explicitly set.  See Searching for Module, Package and
270              Type Declarations.
271
272       -Joption
273              Passes option to the runtime system, where option is one of  the
274              Java  options described on java command.  For example, -J-Xms48m
275              sets the startup memory to 48 MB.
276
277              Note: The CLASSPATH  environment  variable,  -classpath  option,
278              -bootclasspath  option,  and  -extdirs option do not specify the
279              classes used to run javac.  Trying to customize the compiler im‐
280              plementation with these options and variables is risky and often
281              does not accomplish what you want.  If you  must  customize  the
282              compiler  implementation, then use the -J option to pass options
283              through to the underlying Java launcher.
284
285       --limit-modules module,module*
286              Limits the universe of observable modules.
287
288       --module module-name (,module-name)* or -m module-name (,module-name)*
289              Compiles those source files in the named modules that are  newer
290              than the corresponding files in the output directory.
291
292       --module-path path or -p path
293              Specifies where to find application modules.
294
295       --module-source-path module-source-path
296              Specifies where to find source files when compiling code in mul‐
297              tiple modules.  See [Compilation Modes] and  The  Module  Source
298              Path Option.
299
300       --module-version version
301              Specifies the version of modules that are being compiled.
302
303       -nowarn
304              Disables warning messages.  This option operates the same as the
305              -Xlint:none option.
306
307       -parameters
308              Generates metadata for reflection on method parameters.   Stores
309              formal parameter names of constructors and methods in the gener‐
310              ated  class  file  so  that  the  method  java.lang.reflect.Exe‐
311              cutable.getParameters from the Reflection API can retrieve them.
312
313       -proc:[none, only]
314              Controls whether annotation processing and compilation are done.
315              -proc:none means that compilation takes place without annotation
316              processing.  -proc:only means that only annotation processing is
317              done, without any subsequent compilation.
318
319       -processor class1[,class2,class3...]
320              Names of the annotation processors to run.   This  bypasses  the
321              default discovery process.
322
323       --processor-module-path path
324              Specifies  the  module  path used for finding annotation proces‐
325              sors.
326
327       --processor-path path or -processorpath path
328              Specifies where to find annotation processors.  If  this  option
329              is not used, then the class path is searched for processors.
330
331       -profile profile
332              Checks that the API used is available in the specified profile.
333
334              Note: This can only be used when compiling for releases prior to
335              JDK 9.   As  applicable,  see  the  descriptions  in  --release,
336              -source, or -target for details.
337
338       --release release
339              Compiles source code according to the rules of the Java program‐
340              ming language for the  specified  Java  SE  release,  generating
341              class  files which target that release.  Source code is compiled
342              against the combined Java SE and JDK API for the  specified  re‐
343              lease.
344
345              The  supported values of release are the current Java SE release
346              and a limited number of previous releases, detailed in the  com‐
347              mand-line help.
348
349              For the current release, the Java SE API consists of the java.*,
350              javax.*, and org.* packages that are exported  by  the  Java  SE
351              modules  in  the  release; the JDK API consists of the com.* and
352              jdk.* packages that are exported by the JDK modules in  the  re‐
353              lease,  plus the javax.* packages that are exported by standard,
354              but non-Java SE, modules in the release.
355
356              For previous releases, the Java SE API and the JDK  API  are  as
357              defined in that release.
358
359              Note:   When   using   --release,   you   cannot  also  use  the
360              --source/-source or --target/-target options.
361
362              Note: When using --release to specify a  release  that  supports
363              the Java Platform Module System, the --add-exports option cannot
364              be used to enlarge the set of packages exported by the Java  SE,
365              JDK, and standard modules in the specified release.
366
367       -s directory
368              Specifies  the  directory  used  to  place  the generated source
369              files.  If a class is part of a package, then the compiler  puts
370              the  source file in a subdirectory that reflects the module name
371              (if appropriate) and package name.  The directory, and any  nec‐
372              essary  subdirectories,  will  be created if they do not already
373              exist.
374
375              Except when compiling code for multiple modules, the contents of
376              the source output directory will be organized in a package hier‐
377              archy.  When compiling code for multiple modules,  the  contents
378              of the source output directory will be organized in a module hi‐
379              erarchy, with the contents of each module in a  separate  subdi‐
380              rectory, each organized as a package hierarchy.
381
382       --source release or -source release
383              Compiles source code according to the rules of the Java program‐
384              ming language for the specified Java SE release.  The  supported
385              values  of release are the current Java SE release and a limited
386              number of previous releases, detailed in the command-line help.
387
388              If the option is not specified, the default is to compile source
389              code according to the rules of the Java programming language for
390              the current Java SE release.
391
392       --source-path path or -sourcepath path
393              Specifies where to find source  files.   Except  when  compiling
394              multiple  modules together, this is the source code path used to
395              search for class or interface definitions.
396
397              Note: Classes found through the class path might  be  recompiled
398              when  their source files are also found.  See Searching for Mod‐
399              ule, Package and Type Declarations.
400
401       --system jdk | none
402              Overrides the location of system modules.
403
404       --target release or -target release
405              Generates class files suitable for the  specified  Java  SE  re‐
406              lease.   The supported values of release are the current Java SE
407              release and a limited number of previous releases,  detailed  in
408              the command-line help.
409
410              Note:  The  target  release  must be equal to or higher than the
411              source release.  (See --source.)
412
413       --upgrade-module-path path
414              Overrides the location of upgradeable modules.
415
416       -verbose
417              Outputs messages about what the compiler is doing.  Messages in‐
418              clude  information  about each class loaded and each source file
419              compiled.
420
421       --version or -version
422              Prints version information.
423
424       -Werror
425              Terminates compilation when warnings occur.
426
427   Extra Options
428       --add-exports module/package=other-module(,other-module)*
429              Specifies a package to be considered as exported from its defin‐
430              ing  module to additional modules or to all unnamed modules when
431              the value of other-module is ALL-UNNAMED.
432
433       --add-reads module=other-module(,other-module)*
434              Specifies additional modules to be considered as required  by  a
435              given module.
436
437       --default-module-for-created-files module-name
438              Specifies  the fallback target module for files created by anno‐
439              tation processors, if none is specified or inferred.
440
441       -Djava.endorsed.dirs=dirs
442              Overrides the location of the endorsed standards path.
443
444              Note: This can only be used when compiling for releases prior to
445              JDK  9.   As  applicable,  see  the  descriptions  in --release,
446              -source, or -target for details.
447
448       -Djava.ext.dirs=dirs
449              Overrides the location of installed extensions.
450
451              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
455       --doclint-format [html4|html5]
456              Specifies the format for documentation comments.
457
458       --patch-module module=path
459              Overrides or augments a module with classes and resources in JAR
460              files or directories.
461
462       -Xbootclasspath:path
463              Overrides the location of the bootstrap class files.
464
465              Note: This can only be used when compiling for releases prior to
466              JDK 9.   As  applicable,  see  the  descriptions  in  --release,
467              -source, or -target for details.
468
469       -Xbootclasspath/a:path
470              Adds a suffix to the bootstrap class path.
471
472              Note: This can only be used when compiling for releases prior to
473              JDK 9.   As  applicable,  see  the  descriptions  in  --release,
474              -source, or -target for details.
475
476       -Xbootclasspath/p:path
477              Adds a prefix to the bootstrap class path.
478
479              Note: This can only be used when compiling for releases prior to
480              JDK 9.   As  applicable,  see  the  descriptions  in  --release,
481              -source, or -target for details.
482
483       -Xdiags:[compact, verbose]
484              Selects a diagnostic mode.
485
486       -Xdoclint
487              Enables recommended checks for problems in javadoc comments
488
489       -Xdoclint:(all|none|[-]group)[/access]
490              Enables or disables specific groups of checks,
491
492              group can have one of the following values:
493
494              · accessibility
495
496              · html
497
498              · missing
499
500              · reference
501
502              · syntax
503
504              The  variable  access  specifies the minimum visibility level of
505              classes and members that the -Xdoclint option  checks.   It  can
506              have one of the following values (in order of most to least vis‐
507              ible):
508
509              · public
510
511              · protected
512
513              · package
514
515              · private
516
517              The default access level is private.
518
519              For more information about these groups of checks, see the -Xdo‐
520              clint  option  of  the javadoc command.  The -Xdoclint option is
521              disabled by default in the javac command.
522
523              For example, the following option  checks  classes  and  members
524              (with  all  groups of checks) that have the access level of pro‐
525              tected and higher (which includes protected and public):
526
527                     -Xdoclint:all/protected
528
529              The following option enables all groups of checks for all access
530              levels, except it will not check for HTML errors for classes and
531              members that have the access level of package and higher  (which
532              includes package, protected and public):
533
534                     -Xdoclint:all,-html/package
535
536       -Xdoclint/package:[-]packages(,[-]package)*
537              Enables  or  disables checks in specific packages.  Each package
538              is either the qualified name of a package or a package name pre‐
539              fix  followed  by  .*,  which expands to all sub-packages of the
540              given package.  Each package can be prefixed with a  hyphen  (-)
541              to disable checks for a specified package or packages.
542
543       -Xlint Enables all recommended warnings.  In this release, enabling all
544              available warnings is recommended.
545
546       -Xlint:[-]key(,[-]key)*
547              Supplies warnings to enable  or  disable,  separated  by  comma.
548              Precede a key by a hyphen (-) to disable the specified warning.
549
550              Supported values for key are:
551
552              · all: Enables all warnings.
553
554              · auxiliaryclass:  Warns  about an auxiliary class that's hidden
555                in a source file, and is used from other files.
556
557              · cast: Warns about the use of unnecessary casts.
558
559              · classfile: Warns about the issues related  to  classfile  con‐
560                tents.
561
562              · deprecation: Warns about the use of deprecated items.
563
564              · dep-ann: Warns about the items marked as deprecated in javadoc
565                but without the @Deprecated annotation.
566
567              · divzero: Warns about the division by the constant integer 0.
568
569              · empty: Warns about an empty statement after if.
570
571              · exports: Warns about the issues regarding module exports.
572
573              · fallthrough: Warns about the falling through from one case  of
574                a switch statement to the next.
575
576              · finally:  Warns  about  finally  clauses that do not terminate
577                normally.
578
579              · module: Warns about the module system-related issues.
580
581              · opens: Warns about the issues related to module opens.
582
583              · options: Warns about the issues relating  to  use  of  command
584                line options.
585
586              · overloads: Warns about the issues related to method overloads.
587
588              · overrides: Warns about the issues related to method overrides.
589
590              · path:  Warns  about the invalid path elements on the command l
591                ine.
592
593              · processing: Warns about the issues related to annotation  pro‐
594                cessing.
595
596              · rawtypes: Warns about the use of raw types.
597
598              · removal:  Warns  about  the use of an API that has been marked
599                for removal.
600
601              · requires-automatic: Warns developers about the use of automat‐
602                ic modules in requires clauses.
603
604              · requires-transitive-automatic:  Warns  about automatic modules
605                in requires transitive.
606
607              · serial: Warns about the serializable classes that do not  pro‐
608                vide a serial version ID.  Also warns about access to non-pub‐
609                lic members from a serializable element.
610
611              · static: Warns about the accessing a static member using an in‐
612                stance.
613
614              · try:  Warns about the issues relating to the use of try blocks
615                ( that is, try-with-resources).
616
617              · unchecked: Warns about the unchecked operations.
618
619              · varargs: Warns about the potentially unsafe vararg methods.
620
621              · none: Disables all warnings.
622
623              See Examples of Using -Xlint keys.
624
625       -Xmaxerrs number
626              Sets the maximum number of errors to print.
627
628       -Xmaxwarns number
629              Sets the maximum number of warnings to print.
630
631       -Xpkginfo:[always, legacy, nonempty]
632              Specifies when and how the javac command  generates  package-in‐
633              fo.class  files  from  package-info.java  files using one of the
634              following options:
635
636              always Generates a package-info.class file for every package-in‐
637                     fo.java  file.   This  option  may be useful if you use a
638                     build system such as Ant, which checks  that  each  .java
639                     file has a corresponding .class file.
640
641              legacy Generates  a  package-info.class file only if package-in‐
642                     fo.java contains annotations.  This option does not  gen‐
643                     erate a package-info.class file if package-info.java con‐
644                     tains only comments.
645
646                     Note: A package-info.class file might be generated but be
647                     empty  if  all  the  annotations in the package-info.java
648                     file have RetentionPolicy.SOURCE.
649
650              nonempty
651                     Generates a package-info.class file only  if  package-in‐
652                     fo.java  contains  annotations with RetentionPolicy.CLASS
653                     or RetentionPolicy.RUNTIME.
654
655       -Xplugin:name args
656              Specifies the name and optional arguments for a  plug-in  to  be
657              run.   If  args  are provided, name and args should be quoted or
658              otherwise escape the whitespace characters between the name  and
659              all the arguments.  For details on the API for a plugin, see the
660              API documentation for jdk.compiler/com.sun.source.util.Plugin.
661
662       -Xprefer:[source, newer]
663              Specifies which file to read when both a source file  and  class
664              file are found for an implicitly compiled class using one of the
665              following options.  See Searching for Module, Package  and  Type
666              Declarations.
667
668              · -Xprefer:newer:  Reads  the newer of the source or class files
669                for a type (default).
670
671              · -Xprefer:source : Reads the source file.  Use  -Xprefer:source
672                when  you  want  to be sure that any annotation processors can
673                access annotations declared with a retention policy of SOURCE.
674
675       -Xprint
676              Prints a textual representation of specified types for debugging
677              purposes.  This does not perform annotation processing or compi‐
678              lation.  The format of the output could change.
679
680       -XprintProcessorInfo
681              Prints information about which annotations a processor is  asked
682              to process.
683
684       -XprintRounds
685              Prints  information about initial and subsequent annotation pro‐
686              cessing rounds.
687
688       -Xstdout filename
689              Sends compiler messages to the named file.  By default, compiler
690              messages go to System.err.
691

ENVIRONMENT VARIABLES

693   CLASSPATH
694       If the --class-path option or any of its alternate forms are not speci‐
695       fied, the class path will default to the value of the  CLASSPATH  envi‐
696       ronment  variable  if  it is set.  However, it is recommended that this
697       environment variable should not be set, and that the  --class-path  op‐
698       tion  should  be  used  to provide an explicit value for the class path
699       when one is required.
700
701   JDK_JAVAC_OPTIONS
702       The content of the JDK_JAVAC_OPTIONS environment variable, separated by
703       white-spaces  (  )  or  white-space  characters  (\n, \t, \r, or \f) is
704       prepended to the command line arguments passed to javac as  a  list  of
705       arguments.
706
707       The  encoding  requirement  for the environment variable is the same as
708       the javac command line on the  system.   JDK_JAVAC_OPTIONS  environment
709       variable content is treated in the same manner as that specified in the
710       command line.
711
712       Single quotes (') or double quotes (") can be used to enclose arguments
713       that contain whitespace characters.  All content between the open quote
714       and the first matching close quote are preserved by simply removing the
715       pair  of  quotes.   In case a matching quote is not found, the launcher
716       will abort with an error message.  @files are  supported  as  they  are
717       specified  in  the command line.  However, as in @files, use of a wild‐
718       card is not supported.
719
720       Examples of quoting arguments containing white spaces:
721
722              export JDK_JAVAC_OPTIONS='@"C:\white spaces\argfile"'
723
724              export JDK_JAVAC_OPTIONS='"@C:\white spaces\argfile"'
725
726              export JDK_JAVAC_OPTIONS='@C:\"white spaces"\argfile'
727

COMMAND-LINE ARGUMENT FILES

729       An argument file can include command-line options and source file names
730       in  any  combination.   The arguments within a file can be separated by
731       spaces or new line characters.  If a file name contains  embedded  spa‐
732       ces, then put the whole file name in double quotation marks.
733
734       File names within an argument file are relative to the current directo‐
735       ry, not to the location of the argument file.  Wildcards  (*)  are  not
736       allowed  in these lists (such as for specifying *.java).  Use of the at
737       sign (@) to recursively interpret files is not supported.  The  -J  op‐
738       tions  are  not supported because they're passed to the launcher, which
739       does not support argument files.
740
741       When executing the javac command, pass in the path and name of each ar‐
742       gument  file  with  the  at sign (@) leading character.  When the javac
743       command encounters an argument beginning with the at sign (@),  it  ex‐
744       pands the contents of that file into the argument list.
745
746   Examples of Using javac @filename
747       Single Argument File
748              You  could  use a single argument file named argfile to hold all
749              javac arguments:
750
751                     javac @argfile
752
753              This argument file could contain  the  contents  of  both  files
754              shown in the following Two Argument Files example.
755
756       Two Argument Files
757              You can create two argument files: one for the javac options and
758              the other for the source file names.  Note  that  the  following
759              lists have no line-continuation characters.
760
761              Create a file named options that contains the following:
762
763              Linux and macOS:
764
765                     -d classes
766                     -g
767                     -sourcepath /java/pubs/ws/1.3/src/share/classes
768
769              Windows:
770
771                     -d classes
772                     -g
773                     -sourcepath C:\java\pubs\ws\1.3\src\share\classes
774
775              Create a file named classes that contains the following:
776
777                     MyClass1.java
778                     MyClass2.java
779                     MyClass3.java
780
781              Then, run the javac command as follows:
782
783                     javac @options @classes
784
785       Argument Files with Paths
786              The argument files can have paths, but any file names inside the
787              files are relative to the current working directory  (not  path1
788              or path2):
789
790                     javac @path1/options @path2/classes
791

ARRANGEMENT OF SOURCE CODE

793       In  the  Java  language,  classes  and interfaces can be organized into
794       packages, and packages can be organized into  modules.   javac  expects
795       that  the  physical  arrangement  of source files in directories of the
796       file system will mirror the organization of classes into packages,  and
797       packages into modules.
798
799       It  is  a widely adopted convention that module names and package names
800       begin with a lower-case letter, and that class names begin with an  up‐
801       per-case letter.
802
803   Arrangement of Source Code for a Package
804       When  classes  and interfaces are organized into a package, the package
805       is represented as a directory, and any subpackages are  represented  as
806       subdirectories.
807
808       For example:
809
810       · The package p is represented as a directory called p.
811
812       · The  package p.q -- that is, the subpackage q of package p -- is rep‐
813         resented as the subdirectory q of directory p.   The  directory  tree
814         representing package p.q is therefore p\q on Windows, and p/q on oth‐
815         er systems.
816
817       · The package p.q.r is represented as the directory tree p\q\r (on Win‐
818         dows) or p/q/r (on other systems).
819
820       Within  a  directory or subdirectory, .java files represent classes and
821       interfaces in the corresponding package or subpackage.
822
823       For example:
824
825       · The class X declared in package p is represented by the  file  X.java
826         in the p directory.
827
828       · The class Y declared in package p.q is represented by the file Y.java
829         in the q subdirectory of directory p.
830
831       · The class Z declared in package p.q.r  is  represented  by  the  file
832         Z.java  in  the  r  subdirectory of p\q (on Windows) or p/q (on other
833         systems).
834
835       In some situations, it is convenient to split the  code  into  separate
836       directories, each structured as described above, and the aggregate list
837       of directories specified to javac.
838
839   Arrangement of Source Code for a Module
840       In the Java language, a module is a set of packages designed for reuse.
841       In  addition to .java files for classes and interfaces, each module has
842       a source file called module-info.java which:
843
844       1. declares the module's name;
845
846       2. lists the packages exported by the module (to allow reuse  by  other
847          modules);
848
849       3. lists  other modules required by the module (to reuse their exported
850          packages).
851
852       When packages are organized into a module, the module is represented by
853       one or more directories representing the packages in the module, one of
854       which contains the module-info.java file.  It may be convenient, but it
855       is  not required, to use a single directory, named after the module, to
856       contain the module-info.java file alongside the  directory  tree  which
857       represents  the packages in the module (i.e., the package hierarchy de‐
858       scribed above).  The exact arrangement of source code for a  module  is
859       typically dictated by the conventions adopted by a development environ‐
860       ment (IDE) or build system.
861
862       For example:
863
864       · The module a.b.c may be represented by the directory  a.b.c,  on  all
865         systems.
866
867       · The  module's declaration is represented by the file module-info.java
868         in the a.b.c directory.
869
870       · If the module contains package p.q.r, then the a.b.c  directory  con‐
871         tains  the  directory tree p\q\r (on Windows) or p/q/r (on other sys‐
872         tems).
873
874       The development environment may prescribe some directory hierarchy  be‐
875       tween  the  directory  named  for the module and the source files to be
876       read by javac.
877
878       For example:
879
880       · The module a.b.c may be represented by the directory a.b.c
881
882       · The module's declaration and the module's packages  may  be  in  some
883         subdirectory   of  a.b.c,  such  as  src\main\java  (on  Windows)  or
884         src/main/java (on other systems).
885

CONFIGURING A COMPILATION

887       This section describes how to configure javac to perform a basic compi‐
888       lation.
889
890       See  Configuring  the Module System for additional details for use when
891       compiling for a release of the platform that supports modules.
892
893   Source Files
894       · Specify the source files to be compiled on the command line.
895
896       If there are no compilation errors, the corresponding class files  will
897       be placed in the output directory.
898
899       Some  systems  may  limit  the amount you can put on a command line; to
900       work around those limits, you can use argument files.
901
902       When compiling code for modules, you can also specify source files  in‐
903       directly, by using the --module or -m option.
904
905   Output Directory
906       · Use  the -d option to specify an output directory in which to put the
907         compiled class files.
908
909       This will normally be organized in a package hierarchy, unless you  are
910       compiling  source  code from multiple modules, in which case it will be
911       organized as a module hierarchy.
912
913       When the compilation has been completed, if you are  compiling  one  or
914       more modules, you can place the output directory on the module path for
915       the Java launcher; otherwise, you can place the place the output direc‐
916       tory on the class path for the Java launcher.
917
918   Precompiled Code
919       The  code to be compiled may refer to libraries beyond what is provided
920       by the platform.  If so, you must place these libraries  on  the  class
921       path  or module path.  If the library code is not in a module, place it
922       on the class path; if it is in a module, place it on the module path.
923
924       · Use the --class-path option to specify libraries to be placed on  the
925         class  path.   Locations  on  the class path should be organized in a
926         package hierarchy.  You can also use alternate forms of  the  option:
927         -classpath or -cp.
928
929       · Use the --module-path option to specify libraries to be placed on the
930         module path.  Locations on the module path should either  be  modules
931         or directories of modules.  You can also use an alternate form of the
932         option: -p.
933
934         See Configuring the Module System for details on how  to  modify  the
935         default configuration of library modules.
936
937       Note:  the  options for the class path and module path are not mutually
938       exclusive, although it is not common to specify  the  class  path  when
939       compiling code for one or more modules.
940
941   Additional Source Files
942       The  code  to be compiled may refer to types in additional source files
943       that are not specified on the command line.  If so, you must put  those
944       source  files  on  either the source path or module path.  You can only
945       specify one of these options: if you are not compiling code for a  mod‐
946       ule,  or  if  you  are only compiling code for a single module, use the
947       source path; if you are compiling code for multiple  modules,  use  the
948       module source path.
949
950       · Use  the  --source-path option to specify the locations of additional
951         source files that may be read by javac.  Locations on the source path
952         should  be organized in a package hierarchy.  You can also use an al‐
953         ternate form of the option: -sourcepath.
954
955       · Use the --module-source-path option one or more times to specify  the
956         location  of additional source files in different modules that may be
957         read by javac, or when compiling source files  in  multiple  modules.
958         You can either specify the locations for each module individually, or
959         you can organize the source files so that you can specify  the  loca‐
960         tions all together.  For more details, see The Module Source Path Op‐
961         tion.
962
963       If you want to be able to refer to types in additional source files but
964       do not want them to be compiled, use the -implicit option.
965
966       Note:  if  you are compiling code for multiple modules, you must always
967       specify a module source path, and all source  files  specified  on  the
968       command  line  must  be  in one of the directories on the module source
969       path, or in a subdirectory thereof.
970
971   Example of Compiling Multiple Source Files
972       This example compiles the Aloha.java,  GutenTag.java,  Hello.java,  and
973       Hi.java source files in the greetings package.
974
975       Linux and macOS:
976
977              % javac greetings/*.java
978              % ls greetings
979              Aloha.class         GutenTag.class      Hello.class         Hi.class
980              Aloha.java          GutenTag.java       Hello.java          Hi.java
981
982       Windows:
983
984              C:\>javac greetings\*.java
985              C:\>dir greetings
986              Aloha.class         GutenTag.class      Hello.class         Hi.class
987              Aloha.java          GutenTag.java       Hello.java          Hi.java
988
989   Example of Specifying a User Class Path
990       After  changing one of the source files in the previous example, recom‐
991       pile it:
992
993       Linux and macOS:
994
995              pwd
996              /examples
997              javac greetings/Hi.java
998
999       Windows:
1000
1001              C:\>cd
1002              \examples
1003              C:\>javac greetings\Hi.java
1004
1005       Because greetings.Hi refers to other classes in the greetings  package,
1006       the  compiler  needs to find these other classes.  The previous example
1007       works because the default user class path is the  directory  that  con‐
1008       tains  the package directory.  If you want to recompile this file with‐
1009       out concern for which directory you are in, then add the  examples  di‐
1010       rectory to the user class path by setting CLASSPATH.  This example uses
1011       the -classpath option.
1012
1013       Linux and macOS:
1014
1015              javac -classpath /examples /examples/greetings/Hi.java
1016
1017       Windows:
1018
1019              C:\>javac -classpath \examples \examples\greetings\Hi.java
1020
1021       If you change greetings.Hi to use a banner utility, then  that  utility
1022       also needs to be accessible through the user class path.
1023
1024       Linux and macOS:
1025
1026              javac -classpath /examples:/lib/Banners.jar \
1027                          /examples/greetings/Hi.java
1028
1029       Windows:
1030
1031              C:\>javac -classpath \examples;\lib\Banners.jar ^
1032                          \examples\greetings\Hi.java
1033
1034       To  execute  a class in the greetings package, the program needs access
1035       to the greetings package, and to the classes that the greetings classes
1036       use.
1037
1038       Linux and macOS:
1039
1040              java -classpath /examples:/lib/Banners.jar greetings.Hi
1041
1042       Windows:
1043
1044              C:\>java -classpath \examples;\lib\Banners.jar greetings.Hi
1045

CONFIGURING THE MODULE SYSTEM

1047       If  you want to include additional modules in your compilation, use the
1048       --add-modules option.  This may be necessary  when  you  are  compiling
1049       code  that  is not in a module, or which is in an automatic module, and
1050       the code refers to API in the additional modules.
1051
1052       If you want to restrict the set of modules in your compilation, use the
1053       --limit-modules  option.  This may be useful if you want to ensure that
1054       the code you are compiling is capable of running on  a  system  with  a
1055       limited set of modules installed.
1056
1057       If you want to break encapsulation and specify that additional packages
1058       should be considered as exported from a module, use  the  --add-exports
1059       option.   This may be useful when performing white-box testing; relying
1060       on access to internal API in production code is strongly discouraged.
1061
1062       If you want to specify that additional packages should be considered as
1063       required  by  a module, use the --add-reads option.  This may be useful
1064       when performing white-box testing; relying on access to internal API in
1065       production code is strongly discouraged.
1066
1067       You can patch additional content into any module using the --patch-mod‐
1068       ule option.  See [Patching a Module] for more details.
1069

SEARCHING FOR MODULE, PACKAGE AND TYPE DECLARATIONS

1071       To compile a source file, the compiler often needs information about  a
1072       module  or  type, but the declaration is not in the source files speci‐
1073       fied on the command line.
1074
1075       javac needs type information for every class or interface used, extend‐
1076       ed,  or  implemented in the source file.  This includes classes and in‐
1077       terfaces not explicitly mentioned in the source file, but that  provide
1078       information through inheritance.
1079
1080       For example, when you create a subclass of java.awt.Window, you are al‐
1081       so using  the  ancestor  classes  of  Window:  java.awt.Container,  ja‐
1082       va.awt.Component, and java.lang.Object.
1083
1084       When  compiling  code  for  a  module,  the compiler also needs to have
1085       available the declaration of that module.
1086
1087       A successful search may produce a class file, a source file,  or  both.
1088       If both are found, then you can use the -Xprefer option to instruct the
1089       compiler which to use.
1090
1091       If a search finds and uses a source file, then by  default  javac  com‐
1092       piles that source file.  This behavior can be altered with -implicit.
1093
1094       The  compiler might not discover the need for some type information un‐
1095       til after annotation processing completes.  When the  type  information
1096       is  found  in  a  source file and no -implicit option is specified, the
1097       compiler gives a warning that the file is being compiled without  being
1098       subject to annotation processing.  To disable the warning, either spec‐
1099       ify the file on the command line (so that it will be subject to annota‐
1100       tion  processing) or use the -implicit option to specify whether or not
1101       class files should be generated for such source files.
1102
1103       The way that javac locates the declarations of those types  depends  on
1104       whether the reference exists within code for a module or not.
1105
1106   Searching Package Oriented Paths
1107       When searching for a source or class file on a path composed of package
1108       oriented locations, javac will check each location on the path in  turn
1109       for  the possible presence of the file.  The first occurrence of a par‐
1110       ticular file shadows (hides) any subsequent occurrences  of  like-named
1111       files.   This shadowing does not affect any search for any files with a
1112       different name.  This can  be  convenient  when  searching  for  source
1113       files,  which  may  be  grouped  in different locations, such as shared
1114       code, platform-specific code and generated code.  It can also be useful
1115       when  injecting  alternate  versions of a class file into a package, to
1116       debugging or other instrumentation reasons.  But, it can also  be  dan‐
1117       gerous,  such  as when putting incompatible different versions of a li‐
1118       brary on the class path.
1119
1120   Searching Module Oriented Paths
1121       Prior to scanning any module paths for any  package  or  type  declara‐
1122       tions,  javac will lazily scan the following paths and locations to de‐
1123       termine the modules that will be used in the compilation.
1124
1125       · The module source path (see the --module-source-path option)
1126
1127       · The path for upgradeable modules (see the  --upgrade-module-path  op‐
1128         tion)
1129
1130       · The system modules (see the --system option)
1131
1132       · The user module path ( see the --module-path option)
1133
1134       For any module, the first occurrence of the module during the scan com‐
1135       pletely shadows (hides) any subsequent appearance of a like-named  mod‐
1136       ule.   While locating the modules, javac is able to determine the pack‐
1137       ages exported by the module and to associate with each module a package
1138       oriented  path for the contents of the module.  For any previously com‐
1139       piled module, this path will typically be a single entry for  either  a
1140       directory or a file that provides an internal directory-like hierarchy,
1141       such as a JAR file.  Thus, when searching for a type that is in a pack‐
1142       age that is known to be exported by a module, javac can locate the dec‐
1143       laration directly and efficiently.
1144
1145   Searching for the Declaration of a Module
1146       If the module has been previously compiled, the module  declaration  is
1147       located  in  a  file named module-info.class in the root of the package
1148       hierarchy for the content of the module.
1149
1150       If the module is one of those currently being compiled, the module dec‐
1151       laration will be either the file named module-info.class in the root of
1152       the package hierarchy for the module in the class output directory,  or
1153       the  file  named module-info.java in one of the locations on the source
1154       path or one the module source path for the module.
1155
1156   Searching for the Declaration of a Type When the Reference is not in
1157       a Module
1158
1159       When searching for a type that is referenced in code that is not  in  a
1160       module, javac will look in the following places:
1161
1162       · The  platform classes (or the types in exported packages of the plat‐
1163         form modules) (This is for compiled class files only.)
1164
1165       · Types in exported packages of any modules on the module path, if  ap‐
1166         plicable.  (This is for compiled class files only.)
1167
1168       · Types in packages on the class path and/or source path:
1169
1170         · If  both are specified, javac looks for compiled class files on the
1171           class path and for source files on the source path.
1172
1173         · If the class path is specified, but not source  path,  javac  looks
1174           for both compiled class files and source files on the class path.
1175
1176         · If  the class path is not specified, it defaults to the current di‐
1177           rectory.
1178
1179       When looking for a type on the class path and/or source path, if both a
1180       compiled class file and a source file are found, the most recently mod‐
1181       ified file will be used by default.  If the source file  is  newer,  it
1182       will  be compiled and will may override any previously compiled version
1183       of the file.  You can use the -Xprefer option to override  the  default
1184       behavior.
1185
1186   Searching for the Declaration of a Type When the Reference is in a
1187       Module
1188
1189       When searching for a type that is referenced in code in a module, javac
1190       will examine the declaration of the enclosing module  to  determine  if
1191       the  type  is in a package that is exported from another module that is
1192       readable by the enclosing module.  If so, javac will simply and direct‐
1193       ly  go  to  the definition of that module to find the definition of the
1194       required type.  Unless the module is another of the modules being  com‐
1195       piled,  javac  will only look for compiled class files files.  In other
1196       words, javac will not look for source files in platform modules or mod‐
1197       ules on the module path.
1198
1199       If  the  type  being  referenced  is not in some other readable module,
1200       javac will examine the module being compiled to try and find the decla‐
1201       ration of the type.  javac will look for the declaration of the type as
1202       follows:
1203
1204       · Source files specified on the command line or on the source  path  or
1205         module source path.
1206
1207       · Previously compiled files in the output directory.
1208

DIRECTORY HIERARCHIES

1210       javac generally assumes that source files and compiled class files will
1211       be organized in a file system directory hierarchy or in a type of  file
1212       that  supports  in an internal directory hierarchy, such as a JAR file.
1213       Three different kinds of hierarchy are supported: a package  hierarchy,
1214       a module hierarchy, and a module source hierarchy.
1215
1216       While  javac  is  fairly relaxed about the organization of source code,
1217       beyond the expectation that source will be organized in one or  package
1218       hierarchies,  and can generally accommodate organizations prescribed by
1219       development environments and build tools, Java tools  in  general,  and
1220       javac and the Java launcher in particular, are more stringent regarding
1221       the organization of compiled class files,  and  will  be  organized  in
1222       package hierarchies or module hierarchies, as appropriate.
1223
1224       The  location  of  these  hierarchies  are specified to javac with com‐
1225       mand-line  options,  whose  names  typically  end   in   "path",   like
1226       --source-path  or  --class-path.   Also as a general rule, path options
1227       whose name includes the word module, like --module-path,  are  used  to
1228       specify  module  hierarchies, although some module-related path options
1229       allow a package hierarchy to be specified on a per-module  basis.   All
1230       other path options are used to specify package hierarchies.
1231
1232   Package Hierarchy
1233       In a package hierarchy, directories and subdirectories are used to rep‐
1234       resent the component parts of the package name, with the source file or
1235       compiled class file for a type being stored as a file with an extension
1236       of .java or .class in the most nested directory.
1237
1238       For example, in a package  hierarchy,  the  source  file  for  a  class
1239       com.example.MyClass will be stored in the file com/example/MyClass.java
1240
1241   Module Hierarchy
1242       In a module hierarchy, the first level of directories are named for the
1243       modules in the hierarchy; within each of those directories the contents
1244       of the module are organized in package hierarchies.
1245
1246       For  example, in a module hierarchy, the compiled class file for a type
1247       called com.example.MyClass in a module called my.library will be stored
1248       in my.library/com/example/MyClass.class.
1249
1250       The various output directories used by javac (the class output directo‐
1251       ry, the source output directory, and native  header  output  directory)
1252       will  all  be organized in a module hierarchy when multiple modules are
1253       being compiled.
1254
1255   Module Source Hierarchy
1256       Although the source for each individual module should always  be  orga‐
1257       nized in a package hierarchy, it may be convenient to group those hier‐
1258       archies into a module source hierarchy.  This is similar  to  a  module
1259       hierarchy, except that there may be intervening directories between the
1260       directory for the module and the directory that  is  the  root  of  the
1261       package hierarchy for the source code of the module.
1262
1263       For  example,  in a module source hierarchy, the source file for a type
1264       called com.example.MyClass in a module called my.library may be  stored
1265       in a file such as my.library/src/main/java/com/example/MyClass.java.
1266

THE MODULE SOURCE PATH OPTION

1268       The  --module-source-path option has two forms: a module-specific form,
1269       in which a package path is given for each module containing code to  be
1270       compiled,  and a module-pattern form, in which the source path for each
1271       module is specified by a pattern.  The module-specific form is general‐
1272       ly simpler to use when only a small number of modules are involved; the
1273       module-pattern form may be more convenient when the number  of  modules
1274       is  large and the modules are organized in a regular manner that can be
1275       described by a pattern.
1276
1277       Multiple instances of the --module-source-path  option  may  be  given,
1278       each  one  using  either the module-pattern form or the module-specific
1279       form, subject to the following limitations:
1280
1281       · the module-pattern form may be used at most once
1282
1283       · the module-specific form may be used at most once for any given  mod‐
1284         ule
1285
1286       If  the  module-specific  form  is  used for any module, the associated
1287       search path overrides any path that might otherwise have been  inferred
1288       from the module-pattern form.
1289
1290   Module-specific form
1291       The module-specific form allows an explicit search path to be given for
1292       any specific module.  This form is:
1293
1294       · --module-source-path      module-name=file-path       (path-separator
1295         file-path)*
1296
1297       The path separator character is ; on Windows, and : otherwise.
1298
1299       Note: this is similar to the form used for the --patch-module option.
1300
1301   Module-pattern form
1302       The  module-pattern  form  allows a concise specification of the module
1303       source path for any number of modules organized in regular manner.
1304
1305       · --module-source-path pattern
1306
1307       The pattern is defined by the following rules, which are applied in or‐
1308       der:
1309
1310       · The  argument  is  considered to be a series of segments separated by
1311         the path separator character (; on Windows, and : otherwise).
1312
1313       · Each segment containing curly braces of the form
1314
1315                string1{alt1 ( ,alt2 )* } string2
1316
1317         is considered to be replaced by a series of segments formed  by  "ex‐
1318         panding" the braces:
1319
1320                string1 alt1 string2
1321                string1 alt2 string2
1322                and so on...
1323
1324         The braces may be nested.
1325
1326         This rule is applied for all such usages of braces.
1327
1328       · Each  segment  must have at most one asterisk (*).  If a segment does
1329         not contain an asterisk, it is considered to be as  though  the  file
1330         separator character and an asterisk are appended.
1331
1332         For  any module M, the source path for that module is formed from the
1333         series of segments obtained by substituting the module name M for the
1334         asterisk in each segment.
1335
1336         Note: in this context, the asterisk is just used as a special marker,
1337         to denote the position in the path of the module name.  It should not
1338         be  confused  with the use of * as a file name wildcard character, as
1339         found on most operating systems.
1340

PATCHING MODULES

1342       javac allows any content, whether in source or  compiled  form,  to  be
1343       patched  into any module using the --patch-module option.  You may want
1344       to do this to compile alternative implementations  of  a  class  to  be
1345       patched at runtime into a JVM, or to inject additional classes into the
1346       module, such as when testing.
1347
1348       The form of the option is:
1349
1350       · --patch-module module-name=file-path (path-separator file-path )*
1351
1352       The path separator character is ; on Windows,  and  :  otherwise.   The
1353       paths given for the module must specify the root of a package hierarchy
1354       for the contents of the module
1355
1356       The option may be given at most once for any given module.  Any content
1357       on  the  path will hide any like-named content later in the path and in
1358       the patched module.
1359
1360       When patching source  code  into  more  than  one  module,  the  --mod‐
1361       ule-source-path  must also be used, so that the output directory is or‐
1362       ganized in a module hierarchy, and  capable  of  holding  the  compiled
1363       class files for the modules being compiled.
1364

ANNOTATION PROCESSING

1366       The javac command provides direct support for annotation processing.
1367
1368       The  API  for  annotation  processors  is  defined in the javax.annota‐
1369       tion.processing and javax.lang.model packages and subpackages.
1370
1371   How Annotation Processing Works
1372       Unless annotation processing is disabled with  the  -proc:none  option,
1373       the compiler searches for any annotation processors that are available.
1374       The search path can be specified with the -processorpath option.  If no
1375       path  is  specified,  then the user class path is used.  Processors are
1376       located  by  means  of  service  provider-configuration   files   named
1377       META-INF/services/javax.annotation.processing.  Processor on the search
1378       path.  Such files should contain the names of any annotation processors
1379       to  be  used,  listed  one  per line.  Alternatively, processors can be
1380       specified explicitly, using the -processor option.
1381
1382       After scanning the source files and classes on the command line to  de‐
1383       termine  what annotations are present, the compiler queries the proces‐
1384       sors to determine what annotations  they  process.   When  a  match  is
1385       found,  the processor is called.  A processor can claim the annotations
1386       it processes, in which case no further attempt is made to find any pro‐
1387       cessors  for  those  annotations.   After  all  of  the annotations are
1388       claimed, the compiler does not search for additional processors.
1389
1390       If any processors generate new source files, then another round of  an‐
1391       notation  processing  occurs:  Any  newly  generated  source  files are
1392       scanned, and the  annotations  processed  as  before.   Any  processors
1393       called  on  previous  rounds  are also called on all subsequent rounds.
1394       This continues until no new source files are generated.
1395
1396       After a round occurs where no new source files are generated, the anno‐
1397       tation  processors  are  called one last time, to give them a chance to
1398       complete any remaining work.  Finally, unless the -proc:only option  is
1399       used,  the  compiler  compiles  the  original  and all generated source
1400       files.
1401
1402       If you use an annotation processor  that  generates  additional  source
1403       files to be included in the compilation, you can specify a default mod‐
1404       ule to be used for the newly generated files, for  use  when  a  module
1405       declaration  is  not  also  generated.   In  this  case,  use the --de‐
1406       fault-module-for-created-files option.
1407
1408   Compilation Environment and Runtime Environment.
1409       The declarations in source files and previously  compiled  class  files
1410       are  analyzed  by  javac  in a compilation environment that is distinct
1411       from the runtime environment used to execute  javac  itself.   Although
1412       there  is  a  deliberate  similarity  between  many  javac  options and
1413       like-named options for the Java launcher, such as --class-path,  --mod‐
1414       ule-path  and  so on, it is important to understand that in general the
1415       javac options just affect the environment in which the source files are
1416       compiled, and do not affect the operation of javac itself.
1417
1418       The  distinction  between the compilation environment and runtime envi‐
1419       ronment is significant when it comes to  using  annotation  processors.
1420       Although  annotations  processors  process elements (declarations) that
1421       exist in the compilation environment, the annotation  processor  itself
1422       is executed in the runtime environment.  If an annotation processor has
1423       dependencies on libraries that are not in modules, the libraries can be
1424       placed,  along  with  the annotation processor itself, on the processor
1425       path.  (See the --processor-path option.) If the  annotation  processor
1426       and  its dependencies are in modules, you should use the processor mod‐
1427       ule path instead.  (See the --processor-module-path option.) When those
1428       are  insufficient, it may be necessary to provide further configuration
1429       of the runtime environment.  This can be done in two ways:
1430
1431       1. If javac is invoked from the command line, options can be passed  to
1432          the underlying runtime by prefixing the option with -J.
1433
1434       2. You can start an instance of a Java Virtual Machine directly and use
1435          command line options and API to configure an  environment  in  which
1436          javac can be invoked via one of its APIs.
1437

COMPILING FOR EARLIER RELEASES OF THE PLATFORM

1439       javac  can  compile  code  that  is to be used on other releases of the
1440       platform, using either the --release option,  or  the  --source/-source
1441       and --target/-target options, together with additional options to spec‐
1442       ify the platform classes.
1443
1444       Depending on the desired platform release, there are some  restrictions
1445       on some of the options that can be used.
1446
1447       · When compiling for JDK 8 and earlier releases, you cannot use any op‐
1448         tion that is intended for use with the module system.  This  includes
1449         all of the following options:
1450
1451         · --module-source-path,   --upgrade-module-path,   --system,   --mod‐
1452           ule-path, --add-modules, --add-exports,  --add-opens,  --add-reads,
1453           --limit-modules, --patch-module
1454
1455         If  you  use  the  --source/-source  or --target/-target options, you
1456         should also set the appropriate platform classes using the boot class
1457         path family of options.
1458
1459       · When  compiling  for JDK 9 and later releases, you cannot use any op‐
1460         tion that is intended to configure the boot  class  path.   This  in‐
1461         cludes all of the following options:
1462
1463         · -Xbootclasspath/p:, -Xbootclasspath, -Xbootclasspath/a:, -endorsed‐
1464           dirs, -Djava.endorsed.dirs, -extdirs, -Djava.ext.dirs, -profile
1465
1466         If you use the  --source/-source  or  --target/-target  options,  you
1467         should  also  set the appropriate platform classes using the --system
1468         option to give the location of an appropriate  installed  release  of
1469         JDK.
1470
1471       When  using the --release option, only the supported documented API for
1472       that release may be used; you cannot use any options to break  encapsu‐
1473       lation to access any internal classes.
1474

APIS

1476       The javac compiler can be invoked using an API in three different ways:
1477
1478       The Java Compiler API
1479              This  provides the most flexible way to invoke the compiler, in‐
1480              cluding the ability to compile source files provided  in  memory
1481              buffers or other non-standard file systems.
1482
1483       The ToolProvider API
1484              A  ToolProvider  for  javac  can  be  obtained  by calling Tool‐
1485              Provider.findFirst("javac").  This returns an  object  with  the
1486              equivalent functionality of the command-line tool.
1487
1488              Note: This API should not be confused with the like-named API in
1489              the javax.tools package.
1490
1491       The javac Legacy API
1492              This API is retained for backward compatibility only.   All  new
1493              code should use either the Java Compiler API or the ToolProvider
1494              API.
1495
1496       Note: All other classes and methods found in a package with names  that
1497       start with com.sun.tools.javac (subpackages of com.sun.tools.javac) are
1498       strictly internal and subject to change at any time.
1499

EXAMPLES OF USING -XLINT KEYS

1501       cast   Warns about unnecessary and redundant casts, for example:
1502
1503                     String s = (String) "Hello!"
1504
1505       classfile
1506              Warns about issues related to class file contents.
1507
1508       deprecation
1509              Warns about the use of deprecated items.  For example:
1510
1511                     java.util.Date myDate = new java.util.Date();
1512                     int currentDay = myDate.getDay();
1513
1514              The method java.util.Date.getDay has been deprecated  since  JDK
1515              1.1.
1516
1517       dep-ann
1518              Warns  about  items  that  are  documented  with the @deprecated
1519              Javadoc comment, but do not have the @Deprecated annotation, for
1520              example:
1521
1522                     /**
1523                       * @deprecated As of Java SE 7, replaced by {@link #newMethod()}
1524                       */
1525                     public static void deprecatedMethod() { }
1526                     public static void newMethod() { }
1527
1528       divzero
1529              Warns about division by the constant integer 0, for example:
1530
1531                     int divideByZero = 42 / 0;
1532
1533       empty  Warns about empty statements after ifstatements, for example:
1534
1535                     class E {
1536                         void m() {
1537                              if (true) ;
1538                         }
1539                     }
1540
1541       fallthrough
1542              Checks  the  switch blocks for fall-through cases and provides a
1543              warning message for any that are found.  Fall-through cases  are
1544              cases  in a switch block, other than the last case in the block,
1545              whose code does not include a break statement, allowing code ex‐
1546              ecution  to  fall  through from that case to the next case.  For
1547              example, the code following the case  1  label  in  this  switch
1548              block does not end with a break statement:
1549
1550                     switch (x) {
1551                     case 1:
1552                       System.out.println("1");
1553                       // No break statement here.
1554                     case 2:
1555                       System.out.println("2");
1556                     }
1557
1558              If  the  -Xlint:fallthrough  option was used when compiling this
1559              code,  then  the  compiler  emits  a  warning   about   possible
1560              fall-through  into  case,  with  the  line number of the case in
1561              question.
1562
1563       finally
1564              Warns about finally clauses that cannot be  completed  normally,
1565              for example:
1566
1567                     public static int m() {
1568                       try {
1569                          throw new NullPointerException();
1570                       }  catch (NullPointerException(); {
1571                          System.err.println("Caught NullPointerException.");
1572                          return 1;
1573                        } finally {
1574                          return 0;
1575                        }
1576                       }
1577
1578              The  compiler  generates a warning for the finally block in this
1579              example.  When the int method is called, it returns a  value  of
1580              0.   A finally block executes when the try block exits.  In this
1581              example, when control is transferred to the catch block, the int
1582              method  exits.  However, the finally block must execute, so it's
1583              executed,  even  though  control  was  transferred  outside  the
1584              method.
1585
1586       options
1587              Warns  about  issues that related to the use of command-line op‐
1588              tions.  See Compiling for Earlier Releases of the Platform.
1589
1590       overrides
1591              Warns about issues related to method  overrides.   For  example,
1592              consider the following two classes:
1593
1594                     public class ClassWithVarargsMethod {
1595                       void varargsMethod(String... s) { }
1596                     }
1597
1598                     public class ClassWithOverridingMethod extends ClassWithVarargsMethod {
1599                        @Override
1600                        void varargsMethod(String[] s) { }
1601                     }
1602
1603              The compiler generates a warning similar to the following:.
1604
1605                     warning: [override] varargsMethod(String[]) in ClassWithOverridingMethod
1606                     overrides varargsMethod(String...) in ClassWithVarargsMethod; overriding
1607                     method is missing '...'
1608
1609              When the compiler encounters a varargs method, it translates the
1610              varargs formal parameter into an array.  In  the  method  Class‐
1611              WithVarargsMethod.varargsMethod,  the  compiler  translates  the
1612              varargs formal parameter String... s  to  the  formal  parameter
1613              String[] s,  an  array  that matches the formal parameter of the
1614              method  ClassWithOverridingMethod.varargsMethod.   Consequently,
1615              this example compiles.
1616
1617       path   Warns  about invalid path elements and nonexistent path directo‐
1618              ries on the command line (with regard to  the  class  path,  the
1619              source  path,  and  other  paths).  Such warnings cannot be sup‐
1620              pressed with the @SuppressWarnings annotation.  For example:
1621
1622              · Linux  and  macOS:  javac -Xlint:path -classpath /nonexistent‐
1623                path Example.java
1624
1625              · Windows: javac -Xlint:path -classpath C:\nonexistentpath Exam‐
1626                ple.java
1627
1628       processing
1629              Warns about issues related to annotation processing.   The  com‐
1630              piler  generates  this warning when you have a class that has an
1631              annotation, and you use an annotation processor that cannot han‐
1632              dle  that  type  of  exception.  For example, the following is a
1633              simple annotation processor:
1634
1635              Source file AnnocProc.java:
1636
1637                     import java.util.*;
1638                     import javax.annotation.processing.*;
1639                     import javax.lang.model.*;
1640                     import javaz.lang.model.element.*;
1641
1642                     @SupportedAnnotationTypes("NotAnno")
1643                     public class AnnoProc extends AbstractProcessor {
1644                       public boolean process(Set<? extends TypeElement> elems, RoundEnvironment renv){
1645                          return true;
1646                       }
1647
1648                       public SourceVersion getSupportedSourceVersion() {
1649                          return SourceVersion.latest();
1650                        }
1651                     }
1652
1653              Source file AnnosWithoutProcessors.java:
1654
1655                     @interface Anno { }
1656
1657                     @Anno
1658                     class AnnosWithoutProcessors { }
1659
1660              The following commands compile the  annotation  processor  Anno‐
1661              Proc, then run this annotation processor against the source file
1662              AnnosWithoutProcessors.java:
1663
1664                     javac AnnoProc.java
1665                     javac -cp . -Xlint:processing -processor AnnoProc -proc:only AnnosWithoutProcessors.java
1666
1667              When the compiler runs  the  annotation  processor  against  the
1668              source  file  AnnosWithoutProcessors.java, it generates the fol‐
1669              lowing warning:
1670
1671                     warning: [processing] No processor claimed any of these annotations: Anno
1672
1673              To resolve this issue, you can rename the annotation defined and
1674              used in the class AnnosWithoutProcessors from Anno to NotAnno.
1675
1676       rawtypes
1677              Warns  about  unchecked  operations on raw types.  The following
1678              statement generates a rawtypes warning:
1679
1680                     void countElements(List l) { ... }
1681
1682              The following example does not generate a rawtypes warning:
1683
1684                     void countElements(List<?> l) { ... }
1685
1686              List is a raw type.  However, List<?> is an  unbounded  wildcard
1687              parameterized  type.  Because List is a parameterized interface,
1688              always specify its type argument.  In  this  example,  the  List
1689              formal  argument  is specified with an unbounded wildcard (?) as
1690              its formal type parameter, which means  that  the  countElements
1691              method can accept any instantiation of the List interface.
1692
1693       serial Warns about missing serialVersionUID definitions on serializable
1694              classes.  For example:
1695
1696                     public class PersistentTime implements Serializable
1697                     {
1698                       private Date time;
1699
1700                        public PersistentTime() {
1701                          time = Calendar.getInstance().getTime();
1702                        }
1703
1704                        public Date getTime() {
1705                          return time;
1706                        }
1707                     }
1708
1709              The compiler generates the following warning:
1710
1711                     warning: [serial] serializable class PersistentTime has no definition of
1712                     serialVersionUID
1713
1714              If a serializable class does  not  explicitly  declare  a  field
1715              named  serialVersionUID, then the serialization runtime environ‐
1716              ment calculates a default serialVersionUID value for that  class
1717              based  on various aspects of the class, as described in the Java
1718              Object Serialization Specification.  However, it's strongly rec‐
1719              ommended  that all serializable classes explicitly declare seri‐
1720              alVersionUID values because the default process of computing se‐
1721              rialVersionUID  values is highly sensitive to class details that
1722              can vary depending on compiler implementations.   As  a  result,
1723              this might cause an unexpected InvalidClassExceptions during de‐
1724              serialization.  To guarantee a consistent serialVersionUID value
1725              across  different  Java compiler implementations, a serializable
1726              class must declare an explicit serialVersionUID value.
1727
1728       static Warns about issues relating to the use of static variables,  for
1729              example:
1730
1731                     class XLintStatic {
1732                         static void m1() { }
1733                         void m2() { this.m1(); }
1734                     }
1735
1736              The compiler generates the following warning:
1737
1738                     warning: [static] static method should be qualified by type name,
1739                     XLintStatic, instead of by an expression
1740
1741              To resolve this issue, you can call the static method m1 as fol‐
1742              lows:
1743
1744                     XLintStatic.m1();
1745
1746              Alternately, you can remove the static keyword from the declara‐
1747              tion of the method m1.
1748
1749       try    Warns  about issues relating to the use of try blocks, including
1750              try-with-resources statements.  For example, a warning is gener‐
1751              ated  for  the  following  statement because the resource ac de‐
1752              clared in the try block is not used:
1753
1754                     try ( AutoCloseable ac = getResource() ) {    // do nothing}
1755
1756       unchecked
1757              Gives more detail for unchecked  conversion  warnings  that  are
1758              mandated by the Java Language Specification, for example:
1759
1760                     List l = new ArrayList<Number>();
1761                     List<String> ls = l;       // unchecked warning
1762
1763              During   type   erasure,   the   types   ArrayList<Number>   and
1764              List<String> become ArrayList and List, respectively.
1765
1766              The ls command has the parameterized  type  List<String>.   When
1767              the  List referenced by l is assigned to ls, the compiler gener‐
1768              ates an unchecked warning.  At compile time,  the  compiler  and
1769              JVM  cannot  determine  whether l refers to a List<String> type.
1770              In this case, l does not refer to a List<String> type.  As a re‐
1771              sult, heap pollution occurs.
1772
1773              A  heap pollution situation occurs when the List object l, whose
1774              static type is List<Number>, is assigned to another List object,
1775              ls,  that  has  a different static type, List<String>.  However,
1776              the compiler still allows this assignment.  It must  allow  this
1777              assignment  to  preserve backward compatibility with releases of
1778              Java SE that do not support generics.  Because of type  erasure,
1779              List<Number>  and  List<String> both become List.  Consequently,
1780              the compiler allows the assignment of the object l, which has  a
1781              raw type of List, to the object ls.
1782
1783       varargs
1784              Warns  about unsafe use of variable arguments (varargs) methods,
1785              in particular, those that contain non-reifiable  arguments,  for
1786              example:
1787
1788                     public class ArrayBuilder {
1789                       public static <T> void addToList (List<T> listArg, T... elements) {
1790                         for (T x : elements) {
1791                           listArg.add(x);
1792                         }
1793                       }
1794                     }
1795
1796              A  non-reifiable  type  is  a type whose type information is not
1797              fully available at runtime.
1798
1799              The compiler generates the following warning for the  definition
1800              of the method ArrayBuilder.addToList:
1801
1802                     warning: [varargs] Possible heap pollution from parameterized vararg type T
1803
1804              When the compiler encounters a varargs method, it translates the
1805              varargs formal parameter into an array.  However, the Java  pro‐
1806              gramming  language does not permit the creation of arrays of pa‐
1807              rameterized types.  In the  method  ArrayBuilder.addToList,  the
1808              compiler  translates  the varargs formal parameter T... elements
1809              to the formal parameter T[] elements, an  array.   However,  be‐
1810              cause  of type erasure, the compiler converts the varargs formal
1811              parameter to Object[] elements.  Consequently, there's a  possi‐
1812              bility of heap pollution.
1813
1814
1815
1816JDK 16                               2021                             JAVAC(1)
Impressum