javac-java-17 - Man Page

@filename

Reads options and file names from a file. To shorten or simplify the javac command, you can specify one or more files that contain arguments to the javac command (except -J options). This lets you to create javac commands of any length on any operating system. See Command-Line Argument Files.

-Akey[=value]

Specifies options to pass to annotation processors. These options are not interpreted by javac directly, but are made available for use by individual processors. The key value should be one or more identifiers separated by a dot (.).

--add-modules module,module

Specifies root modules to resolve in addition to the initial modules, or all modules on the module path if module is ALL-MODULE-PATH.

--boot-class-path path or -bootclasspath path

Overrides the location of the bootstrap class files.

Note: This can only be used when compiling for releases prior to JDK 9. As applicable, see the descriptions in --release, -source, or -target for details. For JDK 9 or later, see --system.

--class-path path, -classpath path, or -cp path

Specifies where to find user class files and annotation processors. This class path overrides the user class path in the Classpath environment variable.

• If --class-path, -classpath, or -cp are not specified, then the user class path is the value of the Classpath environment variable, if that is set, or else the current directory.
• If not compiling code for modules, if the --source-path or -sourcepath` option is not specified, then the user class path is also searched for source files.
• If the -processorpath option is not specified, then the class path is also searched for annotation processors.

-d directory

Sets the destination directory (or class output directory) for class files. If a class is part of a package, then javac puts the class file in a subdirectory that reflects the module name (if appropriate) and package name. The directory, and any necessary subdirectories, will be created if they do not already exist.

If the -d option is not specified, then javac puts each class file in the same directory as the source file from which it was generated.

Except when compiling code for multiple modules, the contents of the class output directory will be organized in a package hierarchy. When compiling code for multiple modules, the contents of the output directory will be organized in a module hierarchy, with the contents of each module in a separate subdirectory, each organized as a package hierarchy.

Note: When compiling code for one or more modules, the class output directory will automatically be checked when searching for previously compiled classes. When not compiling for modules, for backwards compatibility, the directory is not automatically checked for previously compiled classes, and so it is recommended to specify the class output directory as one of the locations on the user class path, using the --class-path option or one of its alternate forms.

-deprecation

Shows a description of each use or override of a deprecated member or class. Without the -deprecation option, javac shows a summary of the source files that use or override deprecated members or classes. The -deprecation option is shorthand for -Xlint:deprecation.

--enable-preview

Enables preview language features. Used in conjunction with either -source or --release.

-encoding encoding

Specifies character encoding used by source files, such as EUC-JP and UTF-8. If the -encoding option is not specified, then the platform default converter is used.

-endorseddirs directories

Overrides the location of the endorsed standards path.

Note: This can only be used when compiling for releases prior to JDK 9. As applicable, see the descriptions in --release, -source, or -target for details.

-extdirs directories

Overrides the location of the installed extensions. directories is a list of directories, separated by the platform path separator (; on Windows, and : otherwise). Each JAR file in the specified directories is searched for class files. All JAR files found become part of the class path.

If you are compiling for a release of the platform that supports the Extension Mechanism, then this option specifies the directories that contain the extension classes. See [Compiling for Other Releases of the Platform].

Note: This can only be used when compiling for releases prior to JDK 9. As applicable, see the descriptions in --release, -source, or -target for details.

-g

Generates all debugging information, including local variables. By default, only line number and source file information is generated.

-g:[lines, vars, source]

Generates only the kinds of debugging information specified by the comma-separated list of keywords. Valid keywords are:

lines

Line number debugging information.

vars

Local variable debugging information.

source

Source file debugging information.

-g:none

Does not generate debugging information.

-h directory

Specifies where to place generated native header files.

When you specify this option, a native header file is generated for each class that contains native methods or that has one or more constants annotated with the java.lang.annotation.Native annotation. If the class is part of a package, then the compiler puts the native header file in a subdirectory that reflects the module name (if appropriate) and package name. The directory, and any necessary subdirectories, will be created if they do not already exist.

--help, -help or -?

Prints a synopsis of the standard options.

--help-extra or -X

Prints a synopsis of the set of extra options.

--help-lint

Prints the supported keys for the -Xlint option.

-implicit:[none, class]

Specifies whether or not to generate class files for implicitly referenced files:

• -implicit:class --- Automatically generates class files.
• -implicit:none --- Suppresses class file generation.

If this option is not specified, then the default automatically generates class files. In this case, the compiler issues a warning if any class files are generated when also doing annotation processing. The warning is not issued when the -implicit option is explicitly set. See Searching for Module, Package and Type Declarations.

-Joption

Passes option to the runtime system, where option is one of the Java options described on java command. For example, -J-Xms48m sets the startup memory to 48 MB.

Note: The Classpath environment variable, -classpath option, -bootclasspath option, and -extdirs option do not specify the classes used to run javac. Trying to customize the compiler implementation with these options and variables is risky and often does not accomplish what you want. If you must customize the compiler implementation, then use the -J option to pass options through to the underlying Java launcher.

--limit-modules module,module*

Limits the universe of observable modules.

--module module-name (,module-name)* or -m module-name (,module-name)*

Compiles those source files in the named modules that are newer than the corresponding files in the output directory.

--module-path path or -p path

Specifies where to find application modules.

--module-source-path module-source-path

Specifies where to find source files when compiling code in multiple modules. See [Compilation Modes] and The Module Source Path Option.

--module-version version

Specifies the version of modules that are being compiled.

-nowarn

Disables warning messages. This option operates the same as the -Xlint:none option.

-parameters

Generates metadata for reflection on method parameters. Stores formal parameter names of constructors and methods in the generated class file so that the method java.lang.reflect.Executable.getParameters from the Reflection API can retrieve them.

-proc:[none, only]

Controls whether annotation processing and compilation are done. -proc:none means that compilation takes place without annotation processing. -proc:only means that only annotation processing is done, without any subsequent compilation.

-processor class1[,class2,class3...]

Names of the annotation processors to run. This bypasses the default discovery process.

--processor-module-path path

Specifies the module path used for finding annotation processors.

--processor-path path or -processorpath path

Specifies where to find annotation processors. If this option is not used, then the class path is searched for processors.

-profile profile

Checks that the API used is available in the specified profile.

Note: This can only be used when compiling for releases prior to JDK 9. As applicable, see the descriptions in --release, -source, or -target for details.

--release release

Compiles source code according to the rules of the Java programming language for the specified Java SE release, generating class files which target that release. Source code is compiled against the combined Java SE and JDK API for the specified release.

The supported values of release are the current Java SE release and a limited number of previous releases, detailed in the command-line help.

For the current release, the Java SE API consists of the java.*, javax.*, and org.* packages that are exported by the Java SE modules in the release; the JDK API consists of the com.* and jdk.* packages that are exported by the JDK modules in the release, plus the javax.* packages that are exported by standard, but non-Java SE, modules in the release.

For previous releases, the Java SE API and the JDK API are as defined in that release.

Note: When using --release, you cannot also use the --source/-source or --target/-target options.

Note: When using --release to specify a release that supports the Java Platform Module System, the --add-exports option cannot be used to enlarge the set of packages exported by the Java SE, JDK, and standard modules in the specified release.

-s directory

Specifies the directory used to place the generated source files. If a class is part of a package, then the compiler puts the source file in a subdirectory that reflects the module name (if appropriate) and package name. The directory, and any necessary subdirectories, will be created if they do not already exist.

Except when compiling code for multiple modules, the contents of the source output directory will be organized in a package hierarchy. When compiling code for multiple modules, the contents of the source output directory will be organized in a module hierarchy, with the contents of each module in a separate subdirectory, each organized as a package hierarchy.

--source release or -source release

Compiles source code according to the rules of the Java programming language for the specified Java SE release. The supported values of release are the current Java SE release and a limited number of previous releases, detailed in the command-line help.

If the option is not specified, the default is to compile source code according to the rules of the Java programming language for the current Java SE release.

--source-path path or -sourcepath path

Specifies where to find source files. Except when compiling multiple modules together, this is the source code path used to search for class or interface definitions.

Note: Classes found through the class path might be recompiled when their source files are also found. See Searching for Module, Package and Type Declarations.

--system jdk | none

Overrides the location of system modules.

--target release or -target release

Generates class files suitable for the specified Java SE release. The supported values of release are the current Java SE release and a limited number of previous releases, detailed in the command-line help.

Note: The target release must be equal to or higher than the source release. (See --source.)

--upgrade-module-path path

Overrides the location of upgradeable modules.

-verbose

Outputs messages about what the compiler is doing. Messages include information about each class loaded and each source file compiled.

--version or -version

Prints version information.

-Werror

Terminates compilation when warnings occur.

--add-exports module/package=other-module(,other-module)*

Specifies a package to be considered as exported from its defining module to additional modules or to all unnamed modules when the value of other-module is ALL-UNNAMED.

--add-reads module=other-module(,other-module)*

Specifies additional modules to be considered as required by a given module.

--default-module-for-created-files module-name

Specifies the fallback target module for files created by annotation processors, if none is specified or inferred.

-Djava.endorsed.dirs=dirs

Overrides the location of the endorsed standards path.

Note: This can only be used when compiling for releases prior to JDK 9. As applicable, see the descriptions in --release, -source, or -target for details.

-Djava.ext.dirs=dirs

Overrides the location of installed extensions.

Note: This can only be used when compiling for releases prior to JDK 9. As applicable, see the descriptions in --release, -source, or -target for details.

--patch-module module=path

Overrides or augments a module with classes and resources in JAR files or directories.

-Xbootclasspath:path

Overrides the location of the bootstrap class files.

Note: This can only be used when compiling for releases prior to JDK 9. As applicable, see the descriptions in --release, -source, or -target for details.

-Xbootclasspath/a:path

Adds a suffix to the bootstrap class path.

Note: This can only be used when compiling for releases prior to JDK 9. As applicable, see the descriptions in --release, -source, or -target for details.

-Xbootclasspath/p:path

Adds a prefix to the bootstrap class path.

Note: This can only be used when compiling for releases prior to JDK 9. As applicable, see the descriptions in --release, -source, or -target for details.

-Xdiags:[compact, verbose]

Selects a diagnostic mode.

-Xdoclint

Enables recommended checks for problems in javadoc comments

-Xdoclint:(all|none|[-]group)[/access]

Enables or disables specific groups of checks,

group can have one of the following values:

• accessibility
• html
• missing
• reference
• syntax

The variable access specifies the minimum visibility level of classes and members that the -Xdoclint option checks. It can have one of the following values (in order of most to least visible):

• public
• protected
• package
• private

The default access level is private.

For more information about these groups of checks, see the -Xdoclint option of the javadoc command. The -Xdoclint option is disabled by default in the javac command.

For example, the following option checks classes and members (with all groups of checks) that have the access level of protected and higher (which includes protected and public):

-Xdoclint:all/protected

The following option enables all groups of checks for all access levels, except it will not check for HTML errors for classes and members that have the access level of package and higher (which includes package, protected and public):

-Xdoclint:all,-html/package

-Xdoclint/package:[-]packages(,[-]package)*

Enables or disables checks in specific packages. Each package is either the qualified name of a package or a package name prefix followed by .*, which expands to all sub-packages of the given package. Each package can be prefixed with a hyphen (-) to disable checks for a specified package or packages.

-Xlint

Enables all recommended warnings. In this release, enabling all available warnings is recommended.

-Xlint:[-]key(,[-]key)*

Supplies warnings to enable or disable, separated by comma. Precede a key by a hyphen (-) to disable the specified warning.

Supported values for key are:

• all: Enables all warnings.
• auxiliaryclass: Warns about an auxiliary class that's hidden in a source file, and is used from other files.
• cast: Warns about the use of unnecessary casts.
• classfile: Warns about the issues related to classfile contents.
• deprecation: Warns about the use of deprecated items.
• dep-ann: Warns about the items marked as deprecated in javadoc but without the @Deprecated annotation.
• divzero: Warns about the division by the constant integer 0.
• empty: Warns about an empty statement after if.
• exports: Warns about the issues regarding module exports.
• fallthrough: Warns about the falling through from one case of a switch statement to the next.
• finally: Warns about finally clauses that do not terminate normally.
• module: Warns about the module system-related issues.
• opens: Warns about the issues related to module opens.
• options: Warns about the issues relating to use of command line options.
• overloads: Warns about the issues related to method overloads.
• overrides: Warns about the issues related to method overrides.
• path: Warns about the invalid path elements on the command l ine.
• processing: Warns about the issues related to annotation processing.
• rawtypes: Warns about the use of raw types.
• removal: Warns about the use of an API that has been marked for removal.
• requires-automatic: Warns developers about the use of automatic modules in requires clauses.
• requires-transitive-automatic: Warns about automatic modules in requires transitive.
• serial: Warns about the serializable classes that do not provide a serial version ID. Also warns about access to non-public members from a serializable element.
• static: Warns about the accessing a static member using an instance.
• try: Warns about the issues relating to the use of try blocks ( that is, try-with-resources).
• unchecked: Warns about the unchecked operations.
• varargs: Warns about the potentially unsafe vararg methods.
• none: Disables all warnings.

See Examples of Using -Xlint keys.

-Xmaxerrs number

Sets the maximum number of errors to print.

-Xmaxwarns number

Sets the maximum number of warnings to print.

-Xpkginfo:[always, legacy, nonempty]

Specifies when and how the javac command generates package-info.class files from package-info.java files using one of the following options:

always

Generates a package-info.class file for every package-info.java file. This option may be useful if you use a build system such as Ant, which checks that each .java file has a corresponding .class file.

legacy

Generates a package-info.class file only if package-info.java contains annotations. This option does not generate a package-info.class file if package-info.java contains only comments.

Note: A package-info.class file might be generated but be empty if all the annotations in the package-info.java file have RetentionPolicy.SOURCE.

nonempty

Generates a package-info.class file only if package-info.java contains annotations with RetentionPolicy.CLASS or RetentionPolicy.RUNTIME.

-Xplugin:name args

Specifies the name and optional arguments for a plug-in to be run. If args are provided, name and args should be quoted or otherwise escape the whitespace characters between the name and all the arguments. For details on the API for a plugin, see the API documentation for jdk.compiler/com.sun.source.util.Plugin.

-Xprefer:[source, newer]

Specifies which file to read when both a source file and class file are found for an implicitly compiled class using one of the following options. See Searching for Module, Package and Type Declarations.

• -Xprefer:newer: Reads the newer of the source or class files for a type (default).
• -Xprefer:source : Reads the source file. Use -Xprefer:source when you want to be sure that any annotation processors can access annotations declared with a retention policy of SOURCE.

-Xprint

Prints a textual representation of specified types for debugging purposes. This does not perform annotation processing or compilation. The format of the output could change.

-XprintProcessorInfo

Prints information about which annotations a processor is asked to process.

-XprintRounds

Prints information about initial and subsequent annotation processing rounds.

-Xstdout filename

Sends compiler messages to the named file. By default, compiler messages go to System.err.

If the --class-path option or any of its alternate forms are not specified, the class path will default to the value of the CLASSPATH environment variable if it is set. However, it is recommended that this environment variable should not be set, and that the --class-path option should be used to provide an explicit value for the class path when one is required.

The content of the JDK_JAVAC_OPTIONS environment variable, separated by white-spaces ( ) or white-space characters (\n, \t, \r, or \f) is prepended to the command line arguments passed to javac as a list of arguments.

The encoding requirement for the environment variable is the same as the javac command line on the system. JDK_JAVAC_OPTIONS environment variable content is treated in the same manner as that specified in the command line.

Single quotes (') or double quotes (") can be used to enclose arguments that contain whitespace characters. All content between the open quote and the first matching close quote are preserved by simply removing the pair of quotes. In case a matching quote is not found, the launcher will abort with an error message. @files are supported as they are specified in the command line. However, as in @files, use of a wildcard is not supported.

Examples of quoting arguments containing white spaces:

Single Argument File

You could use a single argument file named argfile to hold all javac arguments:

javac @argfile

This argument file could contain the contents of both files shown in the following Two Argument Files example.

Two Argument Files

You can create two argument files: one for the javac options and the other for the source file names. Note that the following lists have no line-continuation characters.

Create a file named options that contains the following:

Linux and macOS:

-d classes
-g
-sourcepath /java/pubs/ws/1.3/src/share/classes

Windows:

-d classes
-g
-sourcepath C:\java\pubs\ws\1.3\src\share\classes

Create a file named classes that contains the following:

MyClass1.java
MyClass2.java
MyClass3.java

Then, run the javac command as follows:

javac @options @classes

Argument Files with Paths

The argument files can have paths, but any file names inside the files are relative to the current working directory (not path1 or path2):

javac @path1/options @path2/classes

When classes and interfaces are organized into a package, the package is represented as a directory, and any subpackages are represented as subdirectories.

For example:

• The package p is represented as a directory called p.
• The package p.q -- that is, the subpackage q of package p -- is represented as the subdirectory q of directory p. The directory tree representing package p.q is therefore p\q on Windows, and p/q on other systems.
• The package p.q.r is represented as the directory tree p\q\r (on Windows) or p/q/r (on other systems).

Within a directory or subdirectory, .java files represent classes and interfaces in the corresponding package or subpackage.

For example:

• The class X declared in package p is represented by the file X.java in the p directory.
• The class Y declared in package p.q is represented by the file Y.java in the q subdirectory of directory p.
• The class Z declared in package p.q.r is represented by the file Z.java in the r subdirectory of p\q (on Windows) or p/q (on other systems).

In some situations, it is convenient to split the code into separate directories, each structured as described above, and the aggregate list of directories specified to javac.

In the Java language, a module is a set of packages designed for reuse. In addition to .java files for classes and interfaces, each module has a source file called module-info.java which:

1. declares the module's name;
2. lists the packages exported by the module (to allow reuse by other modules);
3. lists other modules required by the module (to reuse their exported packages).

When packages are organized into a module, the module is represented by one or more directories representing the packages in the module, one of which contains the module-info.java file. It may be convenient, but it is not required, to use a single directory, named after the module, to contain the module-info.java file alongside the directory tree which represents the packages in the module (i.e., the package hierarchy described above). The exact arrangement of source code for a module is typically dictated by the conventions adopted by a development environment (IDE) or build system.

For example:

• The module a.b.c may be represented by the directory a.b.c, on all systems.
• The module's declaration is represented by the file module-info.java in the a.b.c directory.
• If the module contains package p.q.r, then the a.b.c directory contains the directory tree p\q\r (on Windows) or p/q/r (on other systems).

The development environment may prescribe some directory hierarchy between the directory named for the module and the source files to be read by javac.

For example:

• The module a.b.c may be represented by the directory a.b.c
• The module's declaration and the module's packages may be in some subdirectory of a.b.c, such as src\main\java (on Windows) or src/main/java (on other systems).

• Specify the source files to be compiled on the command line.

If there are no compilation errors, the corresponding class files will be placed in the output directory.

Some systems may limit the amount you can put on a command line; to work around those limits, you can use argument files.

When compiling code for modules, you can also specify source files indirectly, by using the --module or -m option.

• Use the -d option to specify an output directory in which to put the compiled class files.

This will normally be organized in a package hierarchy, unless you are compiling source code from multiple modules, in which case it will be organized as a module hierarchy.

When the compilation has been completed, if you are compiling one or more modules, you can place the output directory on the module path for the Java launcher; otherwise, you can place the place the output directory on the class path for the Java launcher.

The code to be compiled may refer to libraries beyond what is provided by the platform. If so, you must place these libraries on the class path or module path. If the library code is not in a module, place it on the class path; if it is in a module, place it on the module path.

• Use the --class-path option to specify libraries to be placed on the class path. Locations on the class path should be organized in a package hierarchy. You can also use alternate forms of the option: -classpath or -cp.

• Use the --module-path option to specify libraries to be placed on the module path. Locations on the module path should either be modules or directories of modules. You can also use an alternate form of the option: -p.

  See Configuring the Module System for details on how to modify the default configuration of library modules.

Note: the options for the class path and module path are not mutually exclusive, although it is not common to specify the class path when compiling code for one or more modules.

The code to be compiled may refer to types in additional source files that are not specified on the command line. If so, you must put those source files on either the source path or module path. You can only specify one of these options: if you are not compiling code for a module, or if you are only compiling code for a single module, use the source path; if you are compiling code for multiple modules, use the module source path.

• Use the --source-path option to specify the locations of additional source files that may be read by javac. Locations on the source path should be organized in a package hierarchy. You can also use an alternate form of the option: -sourcepath.
• Use the --module-source-path option one or more times to specify the location of additional source files in different modules that may be read by javac, or when compiling source files in multiple modules. You can either specify the locations for each module individually, or you can organize the source files so that you can specify the locations all together. For more details, see The Module Source Path Option.

If you want to be able to refer to types in additional source files but do not want them to be compiled, use the -implicit option.

Note: if you are compiling code for multiple modules, you must always specify a module source path, and all source files specified on the command line must be in one of the directories on the module source path, or in a subdirectory thereof.

This example compiles the Aloha.java, GutenTag.java, Hello.java, and Hi.java source files in the greetings package.

Linux and macOS:

% javac greetings/*.java
% ls greetings
Aloha.class         GutenTag.class      Hello.class         Hi.class
Aloha.java          GutenTag.java       Hello.java          Hi.java

Windows:

C:\>javac greetings\*.java
C:\>dir greetings
Aloha.class         GutenTag.class      Hello.class         Hi.class
Aloha.java          GutenTag.java       Hello.java          Hi.java

After changing one of the source files in the previous example, recompile it:

Linux and macOS:

pwd
/examples
javac greetings/Hi.java

Windows:

C:\>cd
\examples
C:\>javac greetings\Hi.java

Because greetings.Hi refers to other classes in the greetings package, the compiler needs to find these other classes. The previous example works because the default user class path is the directory that contains the package directory. If you want to recompile this file without concern for which directory you are in, then add the examples directory to the user class path by setting Classpath. This example uses the -classpath option.

Linux and macOS:

javac -classpath /examples /examples/greetings/Hi.java

Windows:

C:\>javac -classpath \examples \examples\greetings\Hi.java

If you change greetings.Hi to use a banner utility, then that utility also needs to be accessible through the user class path.

Linux and macOS:

javac -classpath /examples:/lib/Banners.jar \
            /examples/greetings/Hi.java

Windows:

C:\>javac -classpath \examples;\lib\Banners.jar ^
            \examples\greetings\Hi.java

To execute a class in the greetings package, the program needs access to the greetings package, and to the classes that the greetings classes use.

Linux and macOS:

java -classpath /examples:/lib/Banners.jar greetings.Hi

Windows:

C:\>java -classpath \examples;\lib\Banners.jar greetings.Hi

When searching for a source or class file on a path composed of package oriented locations, javac will check each location on the path in turn for the possible presence of the file. The first occurrence of a particular file shadows (hides) any subsequent occurrences of like-named files. This shadowing does not affect any search for any files with a different name. This can be convenient when searching for source files, which may be grouped in different locations, such as shared code, platform-specific code and generated code. It can also be useful when injecting alternate versions of a class file into a package, to debugging or other instrumentation reasons. But, it can also be dangerous, such as when putting incompatible different versions of a library on the class path.

Prior to scanning any module paths for any package or type declarations, javac will lazily scan the following paths and locations to determine the modules that will be used in the compilation.

• The module source path (see the --module-source-path option)
• The path for upgradeable modules (see the --upgrade-module-path option)
• The system modules (see the --system option)
• The user module path ( see the --module-path option)

For any module, the first occurrence of the module during the scan completely shadows (hides) any subsequent appearance of a like-named module. While locating the modules, javac is able to determine the packages exported by the module and to associate with each module a package oriented path for the contents of the module. For any previously compiled module, this path will typically be a single entry for either a directory or a file that provides an internal directory-like hierarchy, such as a JAR file. Thus, when searching for a type that is in a package that is known to be exported by a module, javac can locate the declaration directly and efficiently.

If the module has been previously compiled, the module declaration is located in a file named module-info.class in the root of the package hierarchy for the content of the module.

If the module is one of those currently being compiled, the module declaration will be either the file named module-info.class in the root of the package hierarchy for the module in the class output directory, or the file named module-info.java in one of the locations on the source path or one the module source path for the module.

a Module

When searching for a type that is referenced in code that is not in a module, javac will look in the following places:

• The platform classes (or the types in exported packages of the platform modules) (This is for compiled class files only.)
• Types in exported packages of any modules on the module path, if applicable. (This is for compiled class files only.)

• Types in packages on the class path and/or source path:

  • If both are specified, javac looks for compiled class files on the class path and for source files on the source path.
  • If the class path is specified, but not source path, javac looks for both compiled class files and source files on the class path.
  • If the class path is not specified, it defaults to the current directory.

When looking for a type on the class path and/or source path, if both a compiled class file and a source file are found, the most recently modified file will be used by default. If the source file is newer, it will be compiled and will may override any previously compiled version of the file. You can use the -Xprefer option to override the default behavior.

Module

When searching for a type that is referenced in code in a module, javac will examine the declaration of the enclosing module to determine if the type is in a package that is exported from another module that is readable by the enclosing module. If so, javac will simply and directly go to the definition of that module to find the definition of the required type. Unless the module is another of the modules being compiled, javac will only look for compiled class files files. In other words, javac will not look for source files in platform modules or modules on the module path.

If the type being referenced is not in some other readable module, javac will examine the module being compiled to try and find the declaration of the type. javac will look for the declaration of the type as follows:

• Source files specified on the command line or on the source path or module source path.
• Previously compiled files in the output directory.

In a package hierarchy, directories and subdirectories are used to represent the component parts of the package name, with the source file or compiled class file for a type being stored as a file with an extension of .java or .class in the most nested directory.

For example, in a package hierarchy, the source file for a class com.example.MyClass will be stored in the file com/example/MyClass.java

In a module hierarchy, the first level of directories are named for the modules in the hierarchy; within each of those directories the contents of the module are organized in package hierarchies.

For example, in a module hierarchy, the compiled class file for a type called com.example.MyClass in a module called my.library will be stored in my.library/com/example/MyClass.class.

The various output directories used by javac (the class output directory, the source output directory, and native header output directory) will all be organized in a module hierarchy when multiple modules are being compiled.

Although the source for each individual module should always be organized in a package hierarchy, it may be convenient to group those hierarchies into a module source hierarchy. This is similar to a module hierarchy, except that there may be intervening directories between the directory for the module and the directory that is the root of the package hierarchy for the source code of the module.

For example, in a module source hierarchy, the source file for a type called com.example.MyClass in a module called my.library may be stored in a file such as my.library/src/main/java/com/example/MyClass.java.

The module-specific form allows an explicit search path to be given for any specific module. This form is:

• --module-source-path module-name=file-path (path-separator file-path)*

The path separator character is ; on Windows, and : otherwise.

Note: this is similar to the form used for the --patch-module option.

The module-pattern form allows a concise specification of the module source path for any number of modules organized in regular manner.

• --module-source-path pattern

The pattern is defined by the following rules, which are applied in order:

• The argument is considered to be a series of segments separated by the path separator character (; on Windows, and : otherwise).

• Each segment containing curly braces of the form

  string1{alt1 ( ,alt2 )* } string2

  is considered to be replaced by a series of segments formed by "expanding" the braces:

  string1 alt1 string2
  string1 alt2 string2
  and so on...

  The braces may be nested.

  This rule is applied for all such usages of braces.

• Each segment must have at most one asterisk (*). If a segment does not contain an asterisk, it is considered to be as though the file separator character and an asterisk are appended.

  For any module M, the source path for that module is formed from the series of segments obtained by substituting the module name M for the asterisk in each segment.

  Note: in this context, the asterisk is just used as a special marker, to denote the position in the path of the module name. It should not be confused with the use of * as a file name wildcard character, as found on most operating systems.

Unless annotation processing is disabled with the -proc:none option, the compiler searches for any annotation processors that are available. The search path can be specified with the -processorpath option. If no path is specified, then the user class path is used. Processors are located by means of service provider-configuration files named META-INF/services/javax.annotation.processing. Processor on the search path. Such files should contain the names of any annotation processors to be used, listed one per line. Alternatively, processors can be specified explicitly, using the -processor option.

After scanning the source files and classes on the command line to determine what annotations are present, the compiler queries the processors to determine what annotations they process. When a match is found, the processor is called. A processor can claim the annotations it processes, in which case no further attempt is made to find any processors for those annotations. After all of the annotations are claimed, the compiler does not search for additional processors.

If any processors generate new source files, then another round of annotation processing occurs: Any newly generated source files are scanned, and the annotations processed as before. Any processors called on previous rounds are also called on all subsequent rounds. This continues until no new source files are generated.

After a round occurs where no new source files are generated, the annotation processors are called one last time, to give them a chance to complete any remaining work. Finally, unless the -proc:only option is used, the compiler compiles the original and all generated source files.

If you use an annotation processor that generates additional source files to be included in the compilation, you can specify a default module to be used for the newly generated files, for use when a module declaration is not also generated. In this case, use the --default-module-for-created-files option.

The declarations in source files and previously compiled class files are analyzed by javac in a compilation environment that is distinct from the runtime environment used to execute javac itself. Although there is a deliberate similarity between many javac options and like-named options for the Java launcher, such as --class-path, --module-path and so on, it is important to understand that in general the javac options just affect the environment in which the source files are compiled, and do not affect the operation of javac itself.

The distinction between the compilation environment and runtime environment is significant when it comes to using annotation processors. Although annotations processors process elements (declarations) that exist in the compilation environment, the annotation processor itself is executed in the runtime environment. If an annotation processor has dependencies on libraries that are not in modules, the libraries can be placed, along with the annotation processor itself, on the processor path. (See the --processor-path option.) If the annotation processor and its dependencies are in modules, you should use the processor module path instead. (See the --processor-module-path option.) When those are insufficient, it may be necessary to provide further configuration of the runtime environment. This can be done in two ways:

1. If javac is invoked from the command line, options can be passed to the underlying runtime by prefixing the option with -J.
2. You can start an instance of a Java Virtual Machine directly and use command line options and API to configure an environment in which javac can be invoked via one of its APIs.