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 described in Standard
67       Options.
68
69       Command-line options and environment variables also control  how  javac
70       performs various tasks:
71
72       · Compiling code to run on earlier releases of the JDK.
73
74       · Compiling code to run under a debugger.
75
76       · Checking for stylistic issues in Java source code.
77
78       · Checking for problems in javadoc comments (/** ... */).
79
80       · Processing annotations in source files and class files.
81
82       · Upgrading and patching modules in the compile-time environment.
83
84       javac  supports  Compiling for Earlier Releases Of The Platform and can
85       also be invoked from Java code using one of a number of APIs
86

OPTIONS

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

ENVIRONMENT VARIABLES

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

COMMAND-LINE ARGUMENT FILES

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

ARRANGEMENT OF SOURCE CODE

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

CONFIGURING A COMPILATION

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

CONFIGURING THE MODULE SYSTEM

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

SEARCHING FOR MODULE, PACKAGE AND TYPE DECLARATIONS

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

DIRECTORY HIERARCHIES

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

THE MODULE SOURCE PATH OPTION

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

PATCHING MODULES

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

ANNOTATION PROCESSING

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

COMPILING FOR EARLIER RELEASES OF THE PLATFORM

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

APIS

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

EXAMPLES OF USING -XLINT KEYS

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