Provide zipped javadoc archive from make

Thu Apr 7 11:10:33 UTC 2016

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.
>>>>>>>>>>
>>>>>>>>>
>>>>>>>>
>>>>>>>
>>>>>>
>>>>>
>>>>
>>>
>>
>