Provide zipped javadoc archive from make

Erik Joelsson erik.joelsson at oracle.com
Mon Apr 4 09:56:24 UTC 2016 

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

More information about the build-dev mailing list