Fwd: Re: running javadoc against multiple modules
Jonathan Gibbons
jonathan.gibbons at oracle.com
Wed May 30 23:36:42 UTC 2018
Rick,
Thank you for explaining the context of your questions.
With respect, you are mistaken with respect to javac's behavior, if only
because it's the same code shared by javac and javadoc,
--module-source-path requires there to be a level in the directory
hierarchy that is named for the module. The name is required in order
to find the source for a module, when resolve a directive like "requires
moduleName;". Just as javac requires that classes can be looked up in a
directory hierarchy that corresponds to the package hierarchy, so too
does javac and javadoc impose a requirement that the source for a module
be in a suitably-named directory when using the module source path.
It may be that you have not encountered the equivalent situation in
javac if you have managed to compile your code one module at a time,
placing the output from previous compilations on the module path. In
that situation, would would not need to use the --module-source-path
option, which is necessary when you want to read/analyze/compile the
source code for several modules at once.
Although I grant that the text in JEP 261 could be clearer, this is the
relevant text:
>
> In large systems the source code for a particular module may be spread
> across several different directories.In the JDK itself
> <http://openjdk.java.net/jeps/201>,/e.g./, the source files for a
> module may be found in any one of the
> directories|src/<module>/share/classes|,|src/<module>/<os>/classes|,
> or|build/gensrc/<module>|, where|<os>|is the name of the target
> operating system. To express this in a module source path while
> preserving module identities we allow each element of such a path to
> use braces (|{|and|}|) to enclose commas-separated lists of
> alternatives and a single asterisk (|*|) to stand for the module name.
> The module source path for the JDK can then be written as
>
> |{src/*/{share,<os>}/classes,build/gensrc/*}|
The reference to '*' is the presence of the module name.
I understand the difficulty this restriction may cause some existing
older software systems. At some level, I'm impressed you have gotten as
far as you have without running into this restriction before!
All that having been said, there may be a way forward for you. The
following may seen a bit cumbersome, but it may allow you to run javadoc
(or javac) without renaming your source directories. You can do this
with a combination of --module-source-path and --patch-module, as follows:
1. Point --module-source-path at an empty directory. The presence of
the option is required so that the tool is put into "multi-module mode".
2. For each of the modules you want to process, use an option like this:
--patch-module <module-name>=<path-for-module-source>
The <module-name> is as it would appear in the module declaration;
the <path-for-module-source> is a "source path", meaning one or more
directories separated by the system path separator character (either ':'
on Unix-like systems, or ';' on Windows.) As a source path, the
directories on the path must all be directories at the root of a package
hierarchy.
So, for example, for one of your modules, the option would be
--patch-module org.test.firstmodule=./java/firstmodule
And you would repeat that as needed for all the other modules you
want to pass to javadoc
-- Jon
On 5/30/18 4:08 PM, Rick Hillegas wrote:
> Thanks for that explanation, Jon.
>
> I'm asking these questions because I'm near the end of modularizing a
> very old body of software, Apache Derby. I have successfully created
> module descriptors for all of the Derby components and I have not had
> to rename any directories. The naming limitation you describe does not
> constrain javac. Javac does not impose any restrictions on the names
> of the root directories of components.
>
> I do not see this limitation in JEP 261. Stephen Colbourne seems to
> recommend the practice which you are advocating
> (http://blog.joda.org/2017/04/java-se-9-jpms-module-naming.html) but
> he merely states a strong recommendation. My sense is that it is a
> best practice for greenfield projects. It is clearly a big hurdle for
> legacy projects to surmount.
>
> Thanks for this clarification,
> -Rick
>
> On 5/30/18 7:34 AM, Jonathan Gibbons wrote:
>>
>> Sorry, I missed that detail when looking at your example yesterday.
>>
>> The error message says it all.
>>
>> When you're working with multiple modules on the module source path,
>> each module must be in a directory that is named after the module it
>> contains. Think of it as the module-level equivalent of the
>> requirement that classes in a package hierarchy should be organized
>> in a directory hierarchy that mirrors the package hierarchy.
>>
>> If your modules are named org.test.firstmodule and
>> org.test.secondmodule, your ./java directory should contain direct
>> subdirectories with those exact names. Within each directory, you
>> can place the package hierarchy for the content of that module. In
>> simple cases, you can place the package hierarchy directly in the
>> module directory, although with a more complex value for the
>> --module-source-path option, you can set up a system with intervening
>> directories between the module directory and the root of the package
>> hierarchy.
>>
>> The module paths are described in JEP 261.
>> http://openjdk.java.net/jeps/261 Although that JEP does not call out
>> javadoc, the description for javac essentially applies to javadoc as
>> well.
>>
>> -- Jon
>>
>>
>> On 5/29/18 4:02 PM, Rick Hillegas wrote:
>>>
>>> Thanks, Jon. That moved the problem forward. Now I am getting an
>>> error because a module's name does not match the root directory of
>>> its source code. The following command...
>>>
>>> javadoc --module-source-path ./java \
>>> -d build/javadoc \
>>> --module firstmodule,secondmodule
>>>
>>>
>>> ...raises the following errors:
>>>
>>> ./java/secondmodule/module-info.java:1: error: module name org.test.secondmodule
>>> does not match expected name secondmodule
>>> module org.test.secondmodule
>>> ^
>>> ./java/secondmodule/module-info.java:5: error: module not found:
>>> org.test.firstmodule
>>> requires org.test.firstmodule;
>>> ^
>>> error: cannot access module-info
>>> cannot resolve modules
>>> 3 errors
>>>
>>>
>>> I get a different error when I change the names of the modules which
>>> I hand to the --module switch. The following command...
>>>
>>> javadoc --module-source-path ./java \
>>> -d build/javadoc \
>>> --module org.test.firstmodule,org.test.secondmodule
>>>
>>>
>>> ...raises the following error...
>>>
>>> javadoc: error - module org.test.firstmodule not found.
>>>
>>>
>>> I have attached a tarball of my project.
>>>
>>> Thanks for any advice you can give me,
>>> -Rick
>>>
>>>
>>>
>>> -------- Forwarded Message --------
>>> Subject: Re: running javadoc against multiple modules
>>> Date: Tue, 29 May 2018 11:33:10 -0700
>>> From: Jonathan Gibbons <jonathan.gibbons at oracle.com>
>>> To: javadoc-dev at openjdk.java.net
>>>
>>>
>>>
>>> Rick,
>>>
>>> Set --module-sourcepath to the directory containing the modules.
>>>
>>> Something like this should work for you:
>>>
>>> javadoc --module-source-path ./java -d build/javadoc --module
>>> firstmodule,secondmodule
>>>
>>> -- Jon
>>>
>>> On 05/20/2018 04:45 PM, Rick Hillegas wrote:
>>> > I hope that someone can point me at the right documentation for how to
>>> > create javadoc on a multi-module project. My naive googling does not
>>> > find any pertinent examples for how to do this from the command line
>>> > via the javadoc tool. I have looked through the Java 9 tools documents
>>> > titled "Javadoc Guide" and "Tools Reference" but I have not been able
>>> > to puzzle out which combination of options will produce a single,
>>> > unified set of javadoc for multiple modules. This is my first attempt
>>> > to document a multi-module project, so, no doubt, I am missing
>>> > something simple but crucial.
>>> >
>>> > I am using "Java(TM) SE Runtime Environment (build 9+181)". My source
>>> > tree looks like this:
>>> >
>>> > ./java
>>> > ./java/firstmodule
>>> > ./java/firstmodule/firstpackage
>>> > ./java/firstmodule/firstpackage/FirstClass.java
>>> > ./java/firstmodule/module-info.java
>>> > ./java/secondmodule
>>> > ./java/secondmodule/module-info.java
>>> > ./java/secondmodule/secondpackage
>>> > ./java/secondmodule/secondpackage/SecondClass.java
>>> >
>>> >
>>> > The module descriptors look like the following...
>>> >
>>> > module org.test.firstmodule
>>> >
>>> > {
>>> > requires java.base;
>>> > exports firstpackage;
>>> > }
>>> >
>>> >
>>> > ...and...
>>> >
>>> > module org.test.secondmodule
>>> >
>>> > {
>>> > requires java.base;
>>> > requires org.test.firstmodule;
>>> > exports secondpackage;
>>> > }
>>> >
>>> >
>>> > I believe that I have written valid modules, because the following
>>> > command does what I expect it to do:
>>> >
>>> > java -p build/jars/firstmodule.jar:build/jars/secondmodule.jar \
>>> > -m org.test.secondmodule/secondpackage.SecondClass
>>> >
>>> >
>>> > That is, the java command likes my modules well enough. But javadoc
>>> > baffles me.
>>> >
>>> > The following command...
>>> >
>>> > javadoc -sourcepath ./java/firstmodule:./java/secondmodule \
>>> > -d build/javadoc \
>>> > firstpackage secondpackage
>>> >
>>> >
>>> > ...runs without any errors or warnings. However, it produces odd results:
>>> >
>>> > 1) The top level index.html page lists only one module:
>>> > org.test.firstmodule. I expected to see both modules on the landing page.
>>> >
>>> > 2) In addition, SecondClass.html reports that SecondClass lives in the
>>> > org.test.firstmodule module. I expected that the class would report
>>> > its home as org.test.secondmodule.
>>> >
>>> > The following command...
>>> >
>>> > javadoc --module-source-path ./java/firstmodule:./java/secondmodule \
>>> > -d build/javadoc \
>>> > firstpackage secondpackage
>>> >
>>> >
>>> > ...raises the following error...
>>> >
>>> > javadoc: error - No source files for package firstpackage
>>> >
>>> >
>>> > And this command...
>>> >
>>> > javadoc --module-source-path ./java/firstmodule:./java/secondmodule \
>>> > --module org.test.firstmodule,org.test.secondmodule \
>>> > -d build/javadoc \
>>> > firstpackage secondpackage
>>> >
>>> >
>>> > ...objects that...
>>> >
>>> > javadoc: error - module org.test.firstmodule not found.
>>> >
>>> >
>>> > Clearly, I've wandered off into the tall weeds. I would appreciate
>>> > your advice and, if possible, a pointer to a primer on this topic.
>>> >
>>> > Thanks,
>>> > -Rick
>>> >
>>>
>>>
>>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20180530/9598bb2d/attachment-0001.html>
More information about the javadoc-dev
mailing list