Provide zipped javadoc archive from make

Erik Joelsson erik.joelsson at oracle.com
Thu Apr 7 11:57:04 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.

In 9, instead of echo, please use $(call LogInfo, ). No need for quotes 
in that case.

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.

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

More information about the build-dev mailing list