Provide zipped javadoc archive from make

Thu Apr 7 13:13:04 UTC 2016

On 04/07/2016 03:01 PM, Erik Joelsson wrote:
>
>
> On 2016-04-07 14:48, Jiri Vanek wrote:
>>> 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.
> It does if you build with LOG=info.

I see. Thanx!
>>
>>> 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?
>>
> It's just not the style we use. We try to keep a uniform style in all the makefiles.

I thought so, Fair enough:) And thank you!
>> https://jvanek.fedorapeople.org/oracle/jdk9/webrevs/zip-docs/v2/
>>
> This patch looks good enough for now. You can push it if you like.

My patches to OpenJDK are very sparse, so I don't have commit access.  If you are willing to push on 
my behalf, I will be very happy.

Thank yo very much fr reviews!

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