Fwd: Re: running javadoc against multiple modules
Rick Hillegas
rick.hillegas at gmail.com
Sat Jun 2 15:12:35 UTC 2018
Thanks for that explanation, Jon. You are right, Derby builds one
component at a time, adding previously compiled components onto the
classpaths of later components.
I'm afraid that I haven't figured out what other options to use
alongside --patch-module:
# error: module not found: org.test.secondmodule
# error: module not found: org.test.firstmodule
javadoc --module-source-path ./emptyDir \
-d build/javadoc \
--module org.test.firstmodule,org.test.secondmodule \
--patch-module org.test.firstmodule=./java/firstmodule \
--patch-module org.test.secondmodule=./java/secondmodule
Thanks for any further advice you can give,
-Rick
On 5/30/18 4:36 PM, Jonathan Gibbons wrote:
> 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/20180602/3904bd1c/attachment-0001.html>
More information about the javadoc-dev
mailing list