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.
