Summary

Update the --module-source-path option in javac and javadoc to support an additional form that allows a user to specify an arbitrary explicit source path for a module.

Problem

The current form of the --module-source-path option was designed at a time when the design idiom was to provide a single non-repeatable option that described the paths for all modules together. In addition, the module source path needs to provide so-called "leaky" semantics (i.e. standard classpath semantics) for the file system components that provide the source for any one individual module, while providing the appropriate strong encapsulation between modules. As a result, the current form of the value for the --module-source-path option is a rudimentary pattern, that is based on the assumption that for any file system component that contains source code for a module, the file path for that component contains a directory named for the module.

While that assumption is often true, and can be made true for any new software, there are some important use-cases where it may not be true: these cases typically involving existing code whose project layout does not have the requisite property.

There is currently no way to support such cases from the command-line, although such cases can be supported when using the javax.tools API. (See JDK-8173914)

It would be good to support such cases.

Users may also find it preferable to provide an explicit path for each module in any compilation, instead of using the existing pattern-based form.

Solution

Leverage the syntax designed for the --patch-module option, which went through a similar design evolution. That form is sufficiently distinct from the form of the existing --module-source-path option that it can be supported as an addition to the existing form, instead of a replacement.

It is sufficient to change the support in javac; javadoc simply delegates any analysis of the --module-source-path option to an internal copy of javac.

Specification

A new term, the module-pattern form is introduced, to described the existing form of the --module_source-path option (see The Module-Pattern Form, below).

A new form, called the module-specific form is introduced, to allow an explicit search path to be given for any specific module. This form is:

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

For reference, this is the same form currently used for the --patch-module option.

Multiple instances of the --module-source-path option may be given, each one using either the module-pattern form or the module-specific form, subject to the following limitations:

• the module-pattern form may be used at most once
• the module-specific form may be used at most once for any given module

If the module-specific form is used for any module, the associated search path overrides any path that might otherwise have been inferred from the module-pattern form.

The module-specific form is just provided as a way to provide a source path for a specific module. There is no change to the way that the module source path for any and all modules is interpreted by the module system.

The module-specific form is recommended for use when it is convenient to do so, and especially when only a few modules are involved.

Compatibility

The module-pattern form is a series of items separated by the path separator character. Each item consists of an initial file path, optionally followed by a * (representing the module name), optionally followed by an additional relative file path, for use when the package root for the module source code is not an immediate subdirectory of the module-named directory. There are additional rules permitting the use of braces ({ }) to allow a more concise representation when separate items have a lot of text in common. For the purposes of this specification, it is sufficient to note that the items in the module-pattern form of the --module-source-path option all begin with an initial file path.

In contrast, the module-specific form always begins "module-name=", where the module-name is a dotted identifier. It is highly unlikely that any existing module-pattern form would begin with a dotted identifier followed by =, and so a simple lexical check can be used to disambiguate the two forms. In the unlikely event that an existing usage should begin with "dotted-identifier=", it can trivially adjusted by prefixing it with ./ or .\ depending on the file separator character for the platform.

The Module-Pattern Form

The module-pattern form was introduced in JDK-8142968, but was not formally defined there.

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

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

2. 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
   etc

   The braces may be nested.

   This rule is applied for all such usages of braces.

3. 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.

4. 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.