Provide zipped javadoc archive from make

Erik Joelsson erik.joelsson at oracle.com
Thu Apr 7 13:01:30 UTC 2016 


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 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.
> https://jvanek.fedorapeople.org/oracle/jdk9/webrevs/zip-docs/v2/
>
This patch looks good enough for now. You can push it if you like.

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

More information about the build-dev mailing list