javac modes

[Mandy Chung]

Jon,

Thanks for writing this up.  This is very helpful and we can use the 
same terminology thereafter.

One question related to (2.a) Jigsaw mode:  what happens when javac runs 
in the legacy JVM execution mode (1.b) from a jdk-module-image (i.e. 
javac can access to the org.openjdk.jigsaw API  and the system module 
library is available)?

Mandy

Jonathan Gibbons wrote:
> 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