Provide zipped javadoc archive from make

Fri Apr 1 14:55:21 UTC 2016

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