Provide zipped javadoc archive from make

Thu Apr 7 12:48:39 UTC 2016

> Hello,
>
> For the JDK 9 change, beware that we are going to be making new bundle targets for all kinds of
> bundles. I'm hoping to start that work soon. It might mean a reimplementation of this patch, not
> sure yet. Your docs bundle is quite different from the bundle we need so we likely need to produce
> both. I might need to rewrite the whole old messy Javadoc.gmk while at it, will see.

Sure! Do as as you feel right with this patch. Apply it before or after refactoring or command me 
any way you wish.

>
> In 9, instead of echo, please use $(call LogInfo, ). No need for quotes in that case.
>
sure. done. Now it dont print to stdout, but I guess its purpose.

> I just now noticed the trailing ';' on lines that do not end with backslash.  Please remove those.
> That goes for the 8u patch too if they are present there.

Sure. Done too. Just wondering, why?

https://jvanek.fedorapeople.org/oracle/jdk9/webrevs/zip-docs/v2/

Thanx!

   J.
>
> /Erik
>
> On 2016-04-07 13:10, Jiri Vanek wrote:
>> Hello!
>>
>> As I sad I did:
>> I used your patch (also with remarks and suggestions from the last email)
>> http://pkgs.fedoraproject.org/cgit/rpms/java-1.8.0-openjdk.git/tree/jdk8-archivedJavadoc.patch
>> created subpackage
>>
>> http://pkgs.fedoraproject.org/cgit/rpms/java-1.8.0-openjdk.git/commit/?id=db2f51d7465b7e4602b50bca7fa54e2900a3c8c3
>>
>> And here it goes in Fedora rawhide as javadoc-zip:
>> http://koji.fedoraproject.org/koji/buildinfo?buildID=750919
>>
>> And there is webrev for 9:
>>
>> https://jvanek.fedorapeople.org/oracle/jdk9/webrevs/zip-docs/v1/
>> https://jvanek.fedorapeople.org/oracle/jdk9/webrevs/zip-docs/v1/webrev.zip
>>
>>
>> Looking forward for feedback!
>>
>>
>> Best regards from CZ
>>   J.
>> On 04/04/2016 11:56 AM, Erik Joelsson wrote:
>>> Hello,
>>>
>>> There is still an mkdir instead of $(MKDIR).
>>>
>>> The comments don't read very well, here is a suggestion.
>>>
>>> "Optional target which bundles all generated javadocs into a zip archive. The dependency on docs is
>>> handled in Main.gmk. Incremental building of docs is currently broken so if you invoke zip-docs
>>> after docs, the docs are always rebuilt."
>>>
>>> "Add the core docs as prerequisite to the archive to trigger a rebuild if the core docs were
>>> rebuilt. Ideally any doc rebuild should trigger this, but the way prerequisites are currently setup
>>> in this file, that is hard to achieve."
>>>
>>> /Erik
>>>
>>> On 2016-04-01 16:55, Jiri Vanek wrote:
>>>> On 03/31/2016 04:18 PM, Erik Joelsson wrote:
>>>>> Hello,
>>>>
>>>> https://jvanek.fedorapeople.org/oracle/jdk8/webrevs/zip-javadocs/v3/
>>>> https://jvanek.fedorapeople.org/oracle/jdk8/webrevs/zip-javadocs/v3/webrev.zip
>>>>
>>>> All should be fixed.
>>>>
>>>> *however* I did not tested it. I was working on another machine, and plain jdk8 (without u) was
>>>> there... And it do not built on f23 anymore.
>>>> Still I think best test will be to already include it to fedora RPMs and start to work on jdk9's
>>>> version.
>>>>
>>>>>
>>>>> The comment has not been updated after the dependencies changed.
>>>>>
>>>>> Please use $(MKDIR), $(RM) -f and $(LN).
>>>>
>>>> Right. I was so careful in v1 an now such an mistake.
>>>>>
>>>>> There is no need for the dash before rm since rm -f won't fail and we haven't used it like that
>>>>> before in these makefiles.
>>>>
>>>> sure.
>>>>>
>>>>> Please don't remove the assembly dir after zipping. In general, we keep intermediate files around
>>>>> for easier debugging of the build.
>>>>
>>>> As you command!
>>>>>
>>>>> On 2016-03-31 15:20, Jiri Vanek wrote:
>>>> ...snip...
>>>>> Note that the change for 9 will be quite different. The makefiles have evolved quite a bit.
>>>> good to know :)
>>>>
>>>>>>>
>>>>>>
>>>>> Yes, dependencies here are broken. I don't expect you to fix it in this patch. It's rare that
>>>>> people build docs incrementally so it hasn't been a priority to fix. For now, I suppose you can
>>>>> add back the COREAPI_INDEX_FILE so that the zip is rebuilt if the coreapi docs were rebuilt, but
>>>>> with a comment that dependencies are actually broken and this is just a reasonable workaround. At
>>>>> least ordering is properly handled in Main.gmk now.
>>>>
>>>> Should be done. Again thank you for support
>>>>
>>>> J.
>>>>>
>>>>> /Erik
>>>>>>> * Please don't use temporary directories outside the build output dir. Such directories always
>>>>>>> risk
>>>>>>> being left behind by failed builds. We need the build to only create files in the designated
>>>>>>> output
>>>>>>> dir.
>>>>>>
>>>>>> fixed.
>>>>>>
>>>>>>> * --display-globaldots is not a good option to use in this context. It won't work well with file
>>>>>>> logging of the build and I doubt it's valid for all platforms we build on.
>>>>>>
>>>>>> sure.   Removed.
>>>>>>
>>>>>>
>>>>>> Thanx!
>>>>>>   J.
>>>>>>>
>>>>>>> /Erik
>>>>>>>
>>>>>>> On 2016-03-29 18:24, Jiri Vanek wrote:
>>>>>>>> Hello Again!
>>>>>>>>
>>>>>>>> Sorry for delay in reply.
>>>>>>>>
>>>>>>>> There is webrev
>>>>>>>>
>>>>>>>> https://jvanek.fedorapeople.org/oracle/jdk8/webrevs/zip-javadocs/v1/
>>>>>>>> https://jvanek.fedorapeople.org/oracle/jdk8/webrevs/zip-javadocs/v1/webrev.zip
>>>>>>>>
>>>>>>>> with patch as was (moreover) agreed in this thread for *jdk8*
>>>>>>>>
>>>>>>>> As I was studying the makefiles, I think I did not violated to much conditions by this hunk of
>>>>>>>> code:)
>>>>>>>> I thought that 8 will be much more simple, but at the end it evolved to same "find all
>>>>>>>> roots" as
>>>>>>>> discussed for 9 and modules.
>>>>>>>>
>>>>>>>> The only thing I don't like in this patch is unsuitability of zip to zip directories with
>>>>>>>> stripped
>>>>>>>> path.
>>>>>>>>
>>>>>>>> I went by pushd/popd  but I had seen you like cd in make files more.
>>>>>>>>
>>>>>>>>
>>>>>>>> Thanx for any feedback!
>>>>>>>>
>>>>>>>>   J.
>>>>>>>>
>>>>>>>> On 03/08/2016 03:50 PM, Erik Joelsson wrote:
>>>>>>>>> I wouldn't go that far, but I won't have time to look into it for a while yet at least.
>>>>>>>>>
>>>>>>>>> /Erik
>>>>>>>>>
>>>>>>>>> On 2016-03-08 15:34, Jiri Vanek wrote:
>>>>>>>>>> Ping?
>>>>>>>>>>
>>>>>>>>>> Or is this going to be considered closed-wont "fix"?
>>>>>>>>>>
>>>>>>>>>> Thanx!
>>>>>>>>>>
>>>>>>>>>>  J.
>>>>>>>>>> On 02/29/2016 04:24 PM, Jiri Vanek wrote:
>>>>>>>>>>> On 02/26/2016 08:05 PM, Jonathan Gibbons wrote:
>>>>>>>>>>>> On 02/26/2016 03:49 AM, Jiri Vanek wrote:
>>>>>>>>>>>>> On 02/25/2016 06:34 PM, Jonathan Gibbons wrote:
>>>>>>>>>>>>>> On 02/25/2016 09:23 AM, Jiri Vanek wrote:
>>>>>>>>>>>>>>>
>>>>>>>>>>>>>>> I must be missing something. Dozens? Of varius runs of javadoc?
>>>>>>>>>>>>>>>
>>>>>>>>>>>>>>> I thought that javadoc ending at the end in single drectory is one single javadoc for
>>>>>>>>>>>>>>> java. If
>>>>>>>>>>>>>>> you are referring to javadoc generated by "per module" then one jjoined zip is enough
>>>>>>>>>>>>>>> for me.
>>>>>>>>>>>>>>
>>>>>>>>>>>>>>
>>>>>>>>>>>>>> Jiri,
>>>>>>>>>>>>>>
>>>>>>>>>>>>>> If you accept the premise  that javadoc writes one stylesheet.css file per run of
>>>>>>>>>>>>>> javadoc,
>>>>>>>>>>>>>> take a
>>>>>>>>>>>>>> look at the following list:
>>>>>>>>>>>>>
>>>>>>>>>>>>> Then my goal will be to crate a trget, which takes
>>>>>>>>>>>>> build/linux-x86_64-normal-server-release/images/docs/
>>>>>>>>>>>>> and pack it to
>>>>>>>>>>>>>  build/linux-x86_64-normal-server-release/images/javadoc.zip
>>>>>>>>>>>>>
>>>>>>>>>>>>> It should contains also the "smaller api" you are mentioning below? If not, then those
>>>>>>>>>>>>> should
>>>>>>>>>>>>> appear in this zip too.
>>>>>>>>>>>>>>
>>>>>>>>>>>>>> $ find build/linux-x86_64-normal-server-release/images/docs/ -name stylesheet.css
>>>>>>>>>>>>>> build/linux-x86_64-normal-server-release/images/docs/jdk/api/dynalink/stylesheet.css
>>>>>>>>>>>>>> build/linux-x86_64-normal-server-release/images/docs/jdk/api/attach/spec/stylesheet.css
>>>>>>>>>>>>>> build/linux-x86_64-normal-server-release/images/docs/jdk/api/javac/tree/stylesheet.css
>>>>>>>>>>>>>> build/linux-x86_64-normal-server-release/images/docs/jdk/api/jconsole/spec/stylesheet.css
>>>>>>>>>>>>>> build/linux-x86_64-normal-server-release/images/docs/jdk/api/jpda/jdi/stylesheet.css
>>>>>>>>>>>>>> build/linux-x86_64-normal-server-release/images/docs/jdk/api/javadoc/doclet/stylesheet.css
>>>>>>>>>>>>>>
>>>>>>>>>>>>>> build/linux-x86_64-normal-server-release/images/docs/jdk/api/javadoc/old/doclet/stylesheet.css
>>>>>>>>>>>>>>
>>>>>>>>>>>>>>
>>>>>>>>>>>>>> build/linux-x86_64-normal-server-release/images/docs/jdk/api/javadoc/old/taglet/stylesheet.css
>>>>>>>>>>>>>>
>>>>>>>>>>>>>>
>>>>>>>>>>>>>> build/linux-x86_64-normal-server-release/images/docs/jdk/api/nashorn/stylesheet.css
>>>>>>>>>>>>>> build/linux-x86_64-normal-server-release/images/docs/api/stylesheet.css
>>>>>>>>>>>>>> build/linux-x86_64-normal-server-release/images/docs/jre/api/nio/sctp/spec/stylesheet.css
>>>>>>>>>>>>>> build/linux-x86_64-normal-server-release/images/docs/jre/api/plugin/dom/stylesheet.css
>>>>>>>>>>>>>> build/linux-x86_64-normal-server-release/images/docs/jre/api/security/jaas/spec/stylesheet.css
>>>>>>>>>>>>>>
>>>>>>>>>>>>>>
>>>>>>>>>>>>>> build/linux-x86_64-normal-server-release/images/docs/jre/api/security/smartcardio/spec/stylesheet.css
>>>>>>>>>>>>>>
>>>>>>>>>>>>>>
>>>>>>>>>>>>>>
>>>>>>>>>>>>>>
>>>>>>>>>>>>>>
>>>>>>>>>>>>>>
>>>>>>>>>>>>>> build/linux-x86_64-normal-server-release/images/docs/jre/api/security/jgss/spec/stylesheet.css
>>>>>>>>>>>>>>
>>>>>>>>>>>>>>
>>>>>>>>>>>>>> build/linux-x86_64-normal-server-release/images/docs/jre/api/management/extension/stylesheet.css
>>>>>>>>>>>>>>
>>>>>>>>>>>>>>
>>>>>>>>>>>>>>
>>>>>>>>>>>>>> build/linux-x86_64-normal-server-release/images/docs/jre/api/net/httpserver/spec/stylesheet.css
>>>>>>>>>>>>>>
>>>>>>>>>>>>>>
>>>>>>>>>>>>>> build/linux-x86_64-normal-server-release/images/docs/jre/api/net/socketoptions/spec/stylesheet.css
>>>>>>>>>>>>>>
>>>>>>>>>>>>>>
>>>>>>>>>>>>>>
>>>>>>>>>>>>>>
>>>>>>>>>>>>>> build/linux-x86_64-normal-server-release/images/docs/jre/api/accessibility/jaccess/spec/stylesheet.css
>>>>>>>>>>>>>>
>>>>>>>>>>>>>>
>>>>>>>>>>>>>>
>>>>>>>>>>>>>>
>>>>>>>>>>>>>>
>>>>>>>>>>>>>>
>>>>>>>>>>>>>>
>>>>>>>>>>>>>> The "main"/"Java SE" javadoc bundle that most are aware of is the shortest filename,
>>>>>>>>>>>>>> in the
>>>>>>>>>>>>>> middle
>>>>>>>>>>>>>> of the list, but there are lots of other smaller APIs that get their own doc bundle. You
>>>>>>>>>>>>>> can
>>>>>>>>>>>>>> get at
>>>>>>>>>>>>>> most of them in released doc sets through the top-level "brick wall" page, or by using
>>>>>>>>>>>>>> your
>>>>>>>>>>>>>> favorite
>>>>>>>>>>>>>> search engine.
>>>>>>>>>>>>>
>>>>>>>>>>>>> Hmm.. Do you have some?  javadoc offline search is quite painful think. (Even with new
>>>>>>>>>>>>> search in
>>>>>>>>>>>>> 9, which seems to have some troubles on local filesystem). The best search engine I
>>>>>>>>>>>>> know is
>>>>>>>>>>>>> (unluckily) https://github.com/judovana/JavadocOfflineSearch
>>>>>>>>>>>>
>>>>>>>>>>>> The point of the preceding list was to say that each directory containing stylesheet.css
>>>>>>>>>>>> is the
>>>>>>>>>>>> root
>>>>>>>>>>>> of a separate, distinct, javadoc bundle.  So the smaller APIs that get their own bundle are
>>>>>>>>>>>> precisely the ones given in the preceding list, other than the main javadoc bundle.
>>>>>>>>>>>>
>>>>>>>>>>>> The point of the comment about the brick wall and search engines was to indicate how most
>>>>>>>>>>>> people
>>>>>>>>>>>> will find these doc bundles in normal use, when they don't have a cheat sheet like the list
>>>>>>>>>>>> above.
>>>>>>>>>>>
>>>>>>>>>>> yes I got that. But Then this compressed shattered javadoc needs more thoughts.
>>>>>>>>>>>
>>>>>>>>>>> What is expected format of distribution?
>>>>>>>>>>> I can imagine: web accessible, unapcked "all docs" and "zipepd "all docs".
>>>>>>>>>>> But never several zips, or several directories.
>>>>>>>>>>>
>>>>>>>>>>> What is what I'm missing behind this effort to deliver javadocs per-module?
>>>>>>>>>>>
>>>>>>>>>>>>
>>>>>>>>>>>> As far as IDEs wanting to access javadoc bundles, I would expect that to make all the docs
>>>>>>>>>>>> available, you would want to zip up *each* directory containing stylesheet.css given in the
>>>>>>>>>>>> preceding list. If you just zip up the top API directory, sure, that will include all the
>>>>>>>>>>>> files,
>>>>>>>>>>>> but
>>>>>>>>>>>> the reality is that the IDE will likely not have any way of knowing about the minor doc
>>>>>>>>>>>> bundles in
>>>>>>>>>>>> all jre/ and jdk/ directories and subdirectories.
>>>>>>>>>>>
>>>>>>>>>>> Indeed, when you pack top level javadoc directroy as top level of archive (so javadco will
>>>>>>>>>>> become
>>>>>>>>>>> zipped1.zip!javadoc) then indeed, Netbeasn refuse to load it whole 9just few parts)
>>>>>>>>>>>
>>>>>>>>>>> However when you pack it  that content of javadoc will be the top of the archive
>>>>>>>>>>> (zipped2.zip!{api,jdk,jre,platform}) then NB loads it fine.
>>>>>>>>>>>
>>>>>>>>>>> If even this is wrong, then as last approach is really to restructuralise docs after theirs
>>>>>>>>>>> generation/before zipping to structure where top level directory will the "one with style"
>>>>>>>>>>>
>>>>>>>>>>> dynalink/stylesheet.css
>>>>>>>>>>> spec/stylesheet.css
>>>>>>>>>>> tree/stylesheet.css
>>>>>>>>>>> spec/stylesheet.css
>>>>>>>>>>> jdi/stylesheet.css
>>>>>>>>>>> doclet/stylesheet.css
>>>>>>>>>>> nashorn/stylesheet.css
>>>>>>>>>>> api/stylesheet.css
>>>>>>>>>>> spec/stylesheet.css
>>>>>>>>>>> dom/stylesheet.css
>>>>>>>>>>> spec/stylesheet.css
>>>>>>>>>>> spec/stylesheet.css
>>>>>>>>>>> ...
>>>>>>>>>>>
>>>>>>>>>>> But looking to the occurences of "spec" There is something wrong with those assumptions :)
>>>>>>>>>>>
>>>>>>>>>>>
>>>>>>>>>>> As for indexing and viewing tools - They works fine with both zipepd1 and zipped2 (but
>>>>>>>>>>> there is
>>>>>>>>>>> not
>>>>>>>>>>> much to try)
>>>>>>>>>>>
>>>>>>>>>>> Seeing the impact of packaging, I think it is one more +1 to add this packing target, so
>>>>>>>>>>> JDK's
>>>>>>>>>>> javadoc is pacaked in known, "laodable" way.
>>>>>>>>>>>
>>>>>>>>>>> Thanx!
>>>>>>>>>>>    J.
>>>>>>>>>>>
>>>>>>>>>>>>
>>>>>>>>>>>> -- Jon
>>>>>>>>>>>>
>>>>>>>>>>>>
>>>>>>>>>>>>>>
>>>>>>>>>>>>>> --
>>>>>>>>>>>>>
>>>>>>>>>>>>>
>>>>>>>>>>>>> Thanx a lot!
>>>>>>>>>>>>>   J.
>>>>>>>>>>>>
>>>>>>>>>>>
>>>>>>>>>>
>>>>>>>>>
>>>>>>>>
>>>>>>>
>>>>>>
>>>>>
>>>>
>>>
>>
>