Fwd: Re: running javadoc against multiple modules
Jonathan Gibbons
jonathan.gibbons at oracle.com
Mon Jun 4 15:58:49 UTC 2018
Rick,
I will have to set up a clone of your world, using the attachment you
provided last week, to investigate this further.
-- Jon
On 6/2/18 8:12 AM, Rick Hillegas wrote:
> 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/20180604/2e4b3673/attachment-0001.html>
More information about the javadoc-dev
mailing list