Actually, RM is "rm -f" so $(RM) -f is redundant. /Magnus
> 31 mars 2016 kl. 07:18 skrev Erik Joelsson <erik.joels...@oracle.com>: > > Hello, > > The comment has not been updated after the dependencies changed. > > Please use $(MKDIR), $(RM) -f and $(LN). > > 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. > > Please don't remove the assembly dir after zipping. In general, we keep > intermediate files around for easier debugging of the build. > >> On 2016-03-31 15:20, Jiri Vanek wrote: >> >> Here we go! >> https://jvanek.fedorapeople.org/oracle/jdk8/webrevs/zip-javadocs/v2/ >> https://jvanek.fedorapeople.org/oracle/jdk8/webrevs/zip-javadocs/v2/webrev.zip >> >>> >>> I can't seem to find your name on the OCA list [1], have you signed it? >>> Otherwise we cannot accept >>> patches from you. >> >> As Andrew wrote down @redhat.com should do the job. > Good to know! >>> >>> I can comment and review the patch from a build point of view. There is a >>> separate processes for >>> approving it for inclusion in an older release, like JDK 8. >> >> I'm aware of it. Once you are happy , I will use the patch in 8's rpms, and >> rpepare webrev for 9. Later, if luck allows, I will ask for backporting to 8. > Note that the change for 9 will be quite different. The makefiles have > evolved quite a bit. >>> >>> That said, your patch is mostly reasonable but there are a few things that >>> needs changing. >> >> Thank you very much for review and advices! >>> >>> In Main.gmk. >>> * Please follow the current pattern of declaring both "zip-docs" and >>> "zip-docs-only" and make >>> zip-docs depend on docs. Dependencies between top level targets should be >>> handled in the top level >>> makefile. >> >> Done. Although Now I'm a bit unsure about the dependencies, as described >> lower (*). >>> >>> In Javadock.gmk. >>> * Please use := instead of = for variable declarations. This particular >>> file unfortunately has many >>> bad examples of where = is misused. >> >> Fixed. I can fix the file as separate changeset for jdk9 if you agree. > No need. I would rather rewrite this old clunky piece of makefile completely > than waste time on patching it. It's one of the rare files we never fully > converted to the new style of makefiles in JDK 8. >>> * The file should be named jdk-$(FULL_VERSION)-docs.zip >> done >> >> Although now it have date. However not-nice, definitely reasonable. > Right, for adhoc default configured builds, they do. This can be overridden > on the configure command line using --with-user-release-suffix. >> >>> * The file should be created in $(OUTPUT_ROOT)/bundles >> >> Done. >> >>> * Having the archive only depend on COREAPI_INDEX_FILE is broken if you >>> also include the other docs. >>> Either depend on all and include all or only include the core docs. If you >>> only include the core >>> docs, the targets and file names should probably change. Depending on all >>> is currently tricky since >>> Javadock.gmk is badly written and uses a lot of phony targets instead of >>> the actual targets for >>> dependency management. That would need to be fixed. >> >> Well yes:( (*) >> >> I'm aware of the brokenness of it, but what to depend on? >> I wonted to avoid any other configuration, so whatever make docs generates, >> this target will pack. >> But I stumbled over (now clear) bug in Javadock.gmk. - any time make docs >> (make docs-only seems broken) is invoked, it always regenerate all javadocs. >> >> So by calling make zip-docs, with dependencies you recommended, it causes >> javadoc to be regenerated. >> >> >> It seems to me out of scope of this patch, but if you feel differently, I >> will happily elaborate. > 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. > > /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. >
