javac modes

[Jonathan Gibbons]

In the new world of JDK 7, modules, and Jigsaw, we are beginning to see 
to more talk of "modes", such as the ability of the JVM to run code in 
"legacy mode" or "module mode".  javac has some additional kinds of 
modes, which are all somewhat independent of each other, and which 
should not be confused.  This note attempts to describe the different 
kinds of modes supported by javac.


1. JVM execution mode

This refers to the way in which javac is run by the underlying JVM.

1.a) module mode

In module mode, the javac launcher invokes the javac module directly.

1.b) legacy mode

In legacy mode, the javac launcher invokes javac using a main class and 
a class path.

1.c) bootstrap mode

In bootstrap mode, javac is executed by putting the classes for javac on 
the JVM bootclasspath of an earlier version of javac. (javac 
-J-Xbootclasspath/p:javac.jar ...)  The javac classes must have been 
compiled for use with that earlier version. This mode is always used to 
compile the rest of the JDK classes.


The default JVM execution mode for javac is a property of how the javac 
launcher is created. Module mode and legacy mode can be selected by 
using the JVM's -Xmode option, which can be escaped through the javac 
command line using -J in the normal manner. (i.e.  javac -J-Xmode:legacy 
...)

In module mode, the javac launcher will use the default system module 
library to locate the javac module. See the mail thread [1] for a 
discussion of using the JVM -L option to change the module library used 
to locate the javac module and the modules it depends on.

For the most part, javac's functionality is independent of the JVM 
execution mode used to start javac. However, some of javac's other modes 
rely on a system property "sun.boot.class.path" being set by the JVM 
runtime to a path for the standard runtime classes, such as found in 
rt.jar or its equivalent. See mail thread [2] for more discussion on 
sun.boot.class.path.


2. Module resolution mode

This refers to the way in which javac locates classes and resolves 
module dependencies. Some of the modes here are just for bootstrapping 
and testing purposes.

2.a) Jigsaw mode

This is the primary, default, module resolution mode. It requires that 
javac has access to the org.openjdk.jigsaw API, and that a module 
library is available, meaning that either a library has been specified 
with the -L option, or javac has been run in the module JVM execution 
mode (1.a, above.)

2.b) 294 RI mode

This has been newly identified, and is not yet supported. It will likely 
be akin to a subset of Jigsaw mode, in which module properties are 
inferred from the compilation environment without the use of 
module-info.java.

2.c) ZeroMod mode

ZeroMod refers to a primitive module resolver built directly into javac. 
It is primarily intended for bootstrapping (i.e. building JDK without 
the benefit of Jigsaw itself) and for testing those aspects of javac 
functionality which do not directly depend on Jigsaw functionality. It 
is used if javac is executed in bootstrap or legacy mode: i.e. if the 
Jigsaw API is not available or if no module library is available.  This 
mode can also be forced by the use of the hidden javac option 
-XDzeroMod. The ZeroMod module resolver provides only very minimal 
support for version queries and version selection.

2.d) No modules mode

Modules are not supported in this mode. Classes are located in the same 
way as for earlier versions of javac. It can be thought of as "javac's 
legacy mode". This mode can be selected with the hidden javac option 
-XDnomodules, although it is intended that this is for debugging and 
testing purposes only. javac provides equivalent legacy command line 
functionality using "single-module" mode (3.a) and any of the other 
module resolution modes (2.a, 2.b, 2.c) although the internal code paths 
within javac will be different in these cases.


3. Module compilation mode

This refers to whether javac is compiling classes for multiple modules 
at the same time, or not.

3.a) Single module mode

This is used to compile non-modular code or for code in a single module. 
This is the mode that will be automatically used for any javac command 
line that was valid for earlier versions of javac. In this mode, the -d, 
-classpath and -sourcepath options all have the same usage as before.

3.b) Multi-module mode

This is used to compile source code for multiple modules in the the same 
compilation. It is used if the new option "-modulepath" is used instead 
of "-classpath".  In this mode, the -d and -sourcepath options both use 
an extra level of directory naming above the standard package directory 
hierarchy.


In both modes, a module or modules found on the command line (either 
explicitly or on one of the available path options) will be taken into 
account by the module resolver, which will look for any unresolved 
dependencies in the system module library, or a library specified by the 
-L option. Note that this means that in Jigsaw mode (2.a) javac will 
create and use a "temporary library" in memory to handle the modules 
found in the compilation environment.


---------------------

[1] -L:
http://mail.openjdk.java.net/pipermail/jigsaw-dev/2010-April/000756.html

[2] sun.boot.class.path
http://mail.openjdk.java.net/pipermail/jigsaw-dev/2010-April/000758.html