Fix Version/s: 12
Compatibility Risk Description:The proposed new syntax is highly unlikely to clash with any existing usage of the option.
Interface Kind:add/remove/modify command line option
--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.
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
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.
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
--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
--module-source-path option to an internal copy of javac.
A new term, the module-pattern form is introduced, to described the existing form
--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:
=file-path ( path-separator file-path )*
For reference, this is the same form currently used for the
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
- 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.
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
.\ 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:
The argument is considered to be a series of segments separated by the path separator character (
;on Windows, and
Each segment containing curly braces of the form
,alt2 )* } string2
is considered to be replaced by a series of segments formed by "expanding" the braces:
string1 alt1 string2
string1 alt2 string2
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.