javac modes

[Jonathan Gibbons]

Mandy,

The only connection between "JVM execution mode" (1.*) and "module 
resolution mode" (2.*) is the issues related to the sun.boot.class.path 
property. In situations where sun.boot.class.path does not come into 
play, JVM execution mode and module resolution mode are completely 
independent.  Thus, Jigsaw module resolution mode (2.a) should work just 
fine in legacy JVM execution mode (1.b). 

I'll have another note perhaps later today on practical ways to run 
javac and the javac regression tests in different combinations of these 
modes.

-- Jon



Mandy Chung wrote:
> 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
>