# HG changeset patch # User ihse # Date 1479818681 -3600 # Node ID 484c28d7fd1bcc453067315e2fbbb2739d4d92ba # Parent bbcdb49521b1c04583457096a43ba28b88632b85 8170077: Properly parallelize javadoc generation Reviewed-by: erikj diff -r bbcdb49521b1 -r 484c28d7fd1b make/Javadoc.gmk --- a/make/Javadoc.gmk Fri Nov 18 15:50:43 2016 +0100 +++ b/make/Javadoc.gmk Tue Nov 22 13:44:41 2016 +0100 @@ -50,11 +50,6 @@ # Should we use -Xdocrootparent? Allow custom to overwrite. DOCROOTPARENT_FLAG = TRUE -# The core api index file is the target for the core api javadocs rule -# and needs to be defined early so that all other javadoc rules may -# depend on it. -CORE_INDEX_FILE := $(JAVADOC_OUTPUTDIR)/api/index.html - # URLs JAVADOC_BASE_URL := http://docs.oracle.com/javase/$(VERSION_SPECIFICATION)/docs BUG_SUBMIT_URL := http://bugreport.java.com/bugreport/ @@ -70,52 +65,82 @@ trademark of $(FULL_COMPANY_NAME) in the US and other countries. CORE_BOTTOM_COPYRIGHT_URL := {@docroot}/../legal/cpyr.html -CORE_BOTTOM_TEXT := $(BUG_SUBMIT_LINE) \ -
For further API reference and developer documentation, see \ -Java SE \ -Documentation. That documentation contains more detailed, \ -developer-targeted descriptions, with conceptual overviews, definitions of \ -terms, workarounds, and working code examples. +CORE_BOTTOM_TEXT := \ + $(BUG_SUBMIT_LINE) \ +
For further API reference and developer documentation, see \ + Java SE \ + Documentation. That documentation contains more detailed, \ + developer-targeted descriptions, with conceptual overviews, definitions of \ + terms, workarounds, and working code examples. ifeq ($(VERSION_IS_GA), true) - DRAFT_HEADER := - DRAFT_BOTTOM := - DRAFT_WINTITLE := - CORE_TOP_EARLYACCESS := + DRAFT_MARKER := + DRAFT_WINDOW_TITLE_MARKER := + EARLYACCESS_TOP := else # We need a draft format when not building the GA version. - DRAFT_HEADER :=
DRAFT $(VERSION_STRING) - DRAFT_BOTTOM :=
DRAFT $(VERSION_STRING) + DRAFT_MARKER :=
DRAFT $(VERSION_STRING) ifeq ($(VERSION_BUILD), 0) - DRAFT_WINTITLE := [ad-hoc build] + DRAFT_WINDOW_TITLE_MARKER := $(SPACE)[ad-hoc build] else - DRAFT_WINTITLE := [build $(VERSION_BUILD)] + DRAFT_WINDOW_TITLE_MARKER := $(SPACE)[build $(VERSION_BUILD)] endif - CORE_TOP_EARLYACCESS := \ -
\ -
\ -Please note that the specifications and other information contained herein are \ -not final and are subject to change. The information is being made available \ -to you solely for purpose of evaluation.
+ EARLYACCESS_TOP := \ +
Please note that the specifications \ + and other information contained herein are not final and are subject to \ + change. The information is being made available to you solely for \ + purpose of evaluation.
endif ################################################################################ +# Special treatment for the core package list. All separate "small" javadoc +# invocation needs to be able to see the core package list. + +ALL_PKG_DIRS := $(dir $(filter %.java, $(call CacheFind, \ + $(wildcard $(JAVADOC_SOURCE_DIRS))))) +ALL_SRC_PREFIXES := $(addsuffix /%, $(wildcard $(JAVADOC_SOURCE_DIRS))) +ALL_PKG_DIRNAMES := $(foreach prefix, $(ALL_SRC_PREFIXES), \ + $(patsubst $(prefix),%, $(filter $(prefix), $(ALL_PKG_DIRS)))) +ALL_PACKAGES := $(sort $(subst /,., $(patsubst %/, %, $(ALL_PKG_DIRNAMES)))) + +# Core packages are all packages beginning with java, javax or org, except a few +# excludes. +JAVA_PACKAGES := $(filter java.%, $(ALL_PACKAGES)) +JAVAX_PACKAGES := $(filter javax.%, $(ALL_PACKAGES)) +ORG_PACKAGES := $(filter org.%, $(ALL_PACKAGES)) + +# Allow custom makefile to add more excluded packages +CORE_EXCLUDED_PACKAGES += \ + java.awt.dnd.peer \ + java.awt.peer \ + javax.smartcardio \ + org.jcp.xml.dsig.internal% \ + org.w3c.dom.css \ + org.w3c.dom.html \ + org.w3c.dom.stylesheets \ + org.w3c.dom.xpath \ + # + +CORE_PACKAGES := $(filter-out $(CORE_EXCLUDED_PACKAGES), \ + $(JAVA_PACKAGES) $(JAVAX_PACKAGES) $(ORG_PACKAGES)) + +CORE_PACKAGES_LIST_DIR := $(SUPPORT_OUTPUTDIR)/docs/core-packages +CORE_PACKAGES_LIST_FILE := $(CORE_PACKAGES_LIST_DIR)/package-list + +CORE_PACKAGES_VARDEPS_FILE := $(call DependOnVariable, CORE_PACKAGES, \ + $(CORE_PACKAGES_LIST_FILE).vardeps) + +$(CORE_PACKAGES_LIST_FILE): $(CORE_PACKAGES_VARDEPS_FILE) + $(call MakeDir, $(@D)) + $(eval $(call ListPathsSafely, CORE_PACKAGES, $@)) + +################################################################################ # Support functions for SetupJavadocGeneration -# Print an option line to the target file -# Arguments: -# arg 1: the option name -# arg 2-3: optional arguments to the option -define AddOption - $(PRINTF) "%s$(if $(strip $2), '%s',)$(if $(strip $3), '%s',)\n" \ - "$(strip $1)"$(if $(strip $2), '$(strip $2)',)$(if $(strip $3), \ - '$(strip $3)',) >> $@ -endef - -# This function goes to great pains to exactly mimic the old behavior -# in all details, including whitespace. +# Generate the text used in the -bottom argument. # Note that COPYRIGHT_YEAR is the current year (from spec.gmk) # Arguments: # arg 1: first copyright year @@ -131,6 +156,34 @@ # Speed up finding by filling cache $(eval $(call FillCacheFind, $(wildcard $(JAVADOC_SOURCE_DIRS)))) +# In order to get a specific ordering it's necessary to specify the total +# ordering of tags as the tags are otherwise ordered in order of definition. +DEFAULT_JAVADOC_TAGS := \ + -tag beaninfo:X \ + -tag revised:X \ + -tag since.unbundled:X \ + -tag spec:X \ + -tag specdefault:X \ + -tag Note:X \ + -tag ToDo:X \ + -tag 'apiNote:a:API Note:' \ + -tag 'implSpec:a:Implementation Requirements:' \ + -tag 'implNote:a:Implementation Note:' \ + -tag param \ + -tag return \ + -tag throws \ + -tag since \ + -tag version \ + -tag serialData \ + -tag factory \ + -tag see \ + -tag 'jvms:a:See The Java™ Virtual Machine Specification:' \ + -tag 'jls:a:See The Java™ Language Specification:' \ + # + +DEFAULT_JAVADOC_OPTIONS := -XDignore.symbol.file=true -use -keywords -notimestamp \ + -serialwarn -encoding ISO-8859-1 -breakiterator --system none + ################################################################################ # Setup make rules for running javadoc. # @@ -171,151 +224,100 @@ # The non-core api javadocs need to be able to access the root of the core # api directory, so for jdk/api or jre/api to get to the core api/ # directory we would use this - $1_RELATIVE_CORE_DIR := $$(strip $$(subst $$(call DirToDotDot, \ - $$(JAVADOC_OUTPUTDIR))/,, $$(call DirToDotDot, \ - $$(JAVADOC_OUTPUTDIR)/$$($1_OUTPUT_DIRNAME)))) + $1_RELATIVE_CORE_DIR := $$(call DirToDotDot, $$($1_OUTPUT_DIRNAME))/api - $1_DEPS += $(CORE_INDEX_FILE) + # We need to tell javadoc the directory in which to find the core package-list + $1_OPTIONS += -linkoffline $$($1_RELATIVE_CORE_DIR) $$(CORE_PACKAGES_LIST_DIR) + + $1_DEPS += $(CORE_PACKAGES_LIST_FILE) endif - ifneq ($$($1_OVERVIEW), ) - $1_DEPS += $$($1_OVERVIEW) + $1_OPTIONS += --add-modules $$(call CommaList, $$($1_MODULES)) + + ifneq ($$(LOG_LEVEL), trace) + $1_OPTIONS += -quiet endif - ifeq ($$($1_DISABLED_DOCLINT), ) - $1_DOCLINT := all - else - # Create a string like "all,-syntax,-html" - $1_DOCLINT := all,$$(call CommaList, $$(addprefix -, $$($1_DISABLED_DOCLINT))) + ifneq ($$($1_DISABLED_DOCLINT), ) + # Create a string like ",-syntax,-html" + $1_DOCLINT_EXCEPTIONS := ,$$(call CommaList, $$(addprefix -, $$($1_DISABLED_DOCLINT))) + endif + $1_OPTIONS += -Xdoclint:all$$($1_DOCLINT_EXCEPTIONS) + + ifneq ($$($1_DOCLINT_PACKAGES), ) + $1_OPTIONS += -Xdoclint/package:$$(call CommaList, $$($1_DOCLINT_PACKAGES)) endif ifeq ($$($1_DOC_TITLE), ) $1_DOC_TITLE := $$($1_TITLE) endif + $1_OPTIONS += -doctitle '$$($1_DOC_TITLE)' ifeq ($$($1_WINDOW_TITLE), ) $1_WINDOW_TITLE := $$(strip $$(subst ™,, $$($1_TITLE))) endif + $1_OPTIONS += -windowtitle '$$($1_WINDOW_TITLE)$$(DRAFT_WINDOW_TITLE_MARKER)' ifeq ($$($1_HEADER_TITLE), ) $1_HEADER_TITLE := $$(strip $$(subst ™,, $$($1_TITLE))) endif - $1_HEADER := $$($1_HEADER_TITLE) + $1_OPTIONS += -header '$$($1_HEADER_TITLE)$$(DRAFT_MARKER)' + + ifneq ($$($1_EXTRA_TOP), ) + $1_OPTIONS += -top '$$($1_EXTRA_TOP)' + endif ifeq ($$($1_BOTTOM_TEXT), ) $1_BOTTOM_TEXT := $(COMMON_BOTTOM_TEXT) endif - $1_BOTTOM := $$(call GenerateBottom, $$($1_FIRST_COPYRIGHT_YEAR), \ $$($1_BOTTOM_COPYRIGHT_URL), $$($1_BOTTOM_TEXT)) - - # The index.html, options, and packages files - $1_INDEX_FILE := $$(JAVADOC_OUTPUTDIR)/$$($1_OUTPUT_DIRNAME)/index.html - $1_OPTIONS_FILE := $$(SUPPORT_OUTPUTDIR)/docs/$1.options - $1_PACKAGES_FILE := $$(SUPPORT_OUTPUTDIR)/docs/$1.packages - - $1_PACKAGES_VARDEPS := $$($1_PACKAGES) - $1_PACKAGES_VARDEPS_FILE := $$(call DependOnVariable, $1_PACKAGES_VARDEPS, \ - $$($1_PACKAGES_FILE).vardeps) + $1_OPTIONS += -bottom '$$($1_BOTTOM)$$(DRAFT_MARKER)' - # Rule for creating a file with the package names in it - $$($1_PACKAGES_FILE): $$($1_PACKAGES_VARDEPS_FILE) - $$(call LogInfo, Creating Javadoc package file for $1) - $$(call MakeDir, $$(@D)) - $$(ECHO) $$($1_PACKAGES) | $$(TR) ' ' '\n' > $$@ - - $1_OPTIONS_VARDEPS := $$($1_EXTRA_TOP) \ - $$($DOCROOTPARENT_FLAG) $$(JAVADOC_BASE_URL) $$($1_DISABLED_DOCLINT) \ - $$($1_DOCLINT_PACKAGES) $$(JAVADOC_SOURCE_DIRS) $$($1_MODULES) \ - $$($1_SPLIT_INDEX) $$($1_OVERVIEW) $$($1_DOC_TITLE) $$($1_WINDOW_TITLE) \ - $$(DRAFT_WINTITLE) $$($1_HEADER) $$(DRAFT_HEADER) $$($1_BOTTOM) \ - $$(DRAFT_BOTTOM)) $$($1_RELATIVE_CORE_DIR) $$(JAVADOC_OUTPUTDIR) - $1_OPTIONS_VARDEPS_FILE := $$(call DependOnVariable, $1_OPTIONS_VARDEPS, \ - $$($1_OPTIONS_FILE).vardeps) + ifneq ($$($1_OVERVIEW), ) + $1_OPTIONS += -overview $$($1_OVERVIEW) + $1_DEPS += $$($1_OVERVIEW) + endif - # Rule for creating a file with javadoc options in it - $$($1_OPTIONS_FILE): $$($1_OPTIONS_VARDEPS_FILE) - $$(call LogInfo, Creating Javadoc options file for $1) - $$(call MakeDir, $$(@D)) - $$(RM) $$@ - $$(call AddOption, -XDignore.symbol.file=true) - ifneq ($$(LOG_LEVEL), trace) - $$(call AddOption, -quiet) - endif - $$(call AddOption, -use) - $$(call AddOption, -keywords) - ifneq ($$($DOCROOTPARENT_FLAG), ) - $$(call AddOption, -Xdocrootparent, $(JAVADOC_BASE_URL)) - endif - # In order to get a specific ordering it's necessary to specify the total - # ordering of tags as the tags are otherwise ordered in order of definition. - $$(call AddOption, -tag, beaninfo:X) - $$(call AddOption, -tag, revised:X) - $$(call AddOption, -tag, since.unbundled:X) - $$(call AddOption, -tag, spec:X) - $$(call AddOption, -tag, specdefault:X) - $$(call AddOption, -tag, Note:X) - $$(call AddOption, -tag, ToDo:X) - $$(call AddOption, -tag, apiNote:a:API Note:) - $$(call AddOption, -tag, implSpec:a:Implementation Requirements:) - $$(call AddOption, -tag, implNote:a:Implementation Note:) - $$(call AddOption, -tag, param) - $$(call AddOption, -tag, return) - $$(call AddOption, -tag, throws) - $$(call AddOption, -tag, since) - $$(call AddOption, -tag, version) - $$(call AddOption, -tag, serialData) - $$(call AddOption, -tag, factory) - $$(call AddOption, -tag, see) - $$(call AddOption, -tag, \ - jvms:a:See The Java™ Virtual Machine Specification:) - $$(call AddOption, -tag, \ - jls:a:See The Java™ Language Specification:) - $$(call AddOption, -Xdoclint:$$($1_DOCLINT)) - ifneq ($$($1_DOCLINT_PACKAGES), ) - $$(call AddOption, -Xdoclint/package:$$(call CommaList, $$($1_DOCLINT_PACKAGES))) - endif - $$(call AddOption, --system, none) - $$(call AddOption, --module-source-path, $$(subst ",, $$(call PathList, $$(JAVADOC_SOURCE_DIRS)))) - $$(call AddOption, --add-modules, $$(call CommaList, $$($1_MODULES))) - $$(call AddOption, -encoding, ISO-8859-1) - $$(call AddOption, -breakiterator) - $$(call AddOption, -serialwarn) - $$(call AddOption, -notimestamp) - ifneq ($$($1_SPLIT_INDEX), ) - $$(call AddOption, -splitIndex) - endif - ifneq ($$($1_OVERVIEW), ) - $$(call AddOption, -overview, $$($1_OVERVIEW)) - endif - $$(call AddOption, -doctitle, $$($1_DOC_TITLE)) - $$(call AddOption, -windowtitle, $$($1_WINDOW_TITLE) $$(DRAFT_WINTITLE)) - $$(call AddOption, -header, $$($1_HEADER)$$(DRAFT_HEADER)) - $$(call AddOption, -bottom, $$($1_BOTTOM)$$(DRAFT_BOTTOM)) - ifneq ($$($1_RELATIVE_CORE_DIR), ) - $$(call AddOption, -linkoffline, $$($1_RELATIVE_CORE_DIR)/api, $$(JAVADOC_OUTPUTDIR)/api/) - endif - ifneq ($$($1_EXTRA_TOP), ) - $$(call AddOption, -top, $$($1_EXTRA_TOP)) - endif + ifneq ($$($1_SPLIT_INDEX), ) + $1_OPTIONS += -splitIndex + endif + + ifneq ($$($DOCROOTPARENT_FLAG), ) + $1_OPTIONS += -Xdocrootparent $(JAVADOC_BASE_URL) + endif + + $1_VARDEPS := $$($1_OPTIONS) $$($1_PACKAGES) + $1_VARDEPS_FILE := $$(call DependOnVariable, $1_VARDEPS, \ + $$(SUPPORT_OUTPUTDIR)/docs/$1.vardeps) $1_PACKAGE_DEPS := $$(call CacheFind, $$(wildcard $$(foreach p, \ $$(subst .,/,$$(strip $$($1_PACKAGES))), \ $$(addsuffix /$$p, $$(wildcard $$(JAVADOC_SOURCE_DIRS)))))) + # If there are many packages, use an @-file... + ifneq ($$(word 17, $$($1_PACKAGES)), ) + $1_PACKAGES_FILE := $$(SUPPORT_OUTPUTDIR)/docs/$1.packages + $1_PACKAGES_ARG := @$$($1_PACKAGES_FILE) + else + $1_PACKAGES_ARG := $$($1_PACKAGES) + endif + + # The index.html which is a marker for all the output from javadoc. + $1_INDEX_FILE := $$(JAVADOC_OUTPUTDIR)/$$($1_OUTPUT_DIRNAME)/index.html + # Rule for actually running javadoc - $$($1_INDEX_FILE): $$($1_OPTIONS_FILE) $$($1_PACKAGES_FILE) \ - $$($1_PACKAGE_DEPS) $$($1_DEPS) - $$(call LogWarn, Generating Javadoc for $$($1_OUTPUT_DIRNAME)) + $$($1_INDEX_FILE): $$($1_VARDEPS_FILE) $$($1_PACKAGE_DEPS) $$($1_DEPS) + $$(call LogWarn, Generating Javadoc from $$(words $$($1_PACKAGES)) package(s) for $$($1_OUTPUT_DIRNAME)) $$(call MakeDir, $$(@D)) - ifneq ($$(findstring $$(LOG_LEVEL), debug trace),) - $$(ECHO) "Contents of $$($1_OPTIONS_FILE):" `$$(CAT) $$($1_OPTIONS_FILE)` - $$(ECHO) "Contents of $$($1_PACKAGES_FILE):" `$$(CAT) $$($1_PACKAGES_FILE)` + ifneq ($$($1_PACKAGES_FILE), ) + $$(eval $$(call ListPathsSafely, $1_PACKAGES, $$($1_PACKAGES_FILE))) endif $$(call ExecuteWithLog, $$(SUPPORT_OUTPUTDIR)/docs/$1.javadoc, \ $$($1_JAVA) -Djava.awt.headless=true $(NEW_JAVADOC) -d $$(@D) \ - @$$($1_OPTIONS_FILE) @$$($1_PACKAGES_FILE)) - $$(TOUCH) $$($1_INDEX_FILE) + $$(DEFAULT_JAVADOC_TAGS) $$(DEFAULT_JAVADOC_OPTIONS) \ + --module-source-path $$(call PathList, $$(JAVADOC_SOURCE_DIRS)) \ + $$($1_OPTIONS) $$($1_PACKAGES_ARG)) # The output returned will be the index.html file $1 := $$($1_INDEX_FILE) @@ -323,35 +325,6 @@ ################################################################################ -# Core packages are all packages beginning with java, javax or org, except a few -# excludes. - -ALL_PKG_DIRS := $(dir $(filter %.java, $(call CacheFind, \ - $(wildcard $(JAVADOC_SOURCE_DIRS))))) -ALL_SRC_PREFIXES := $(addsuffix /%, $(wildcard $(JAVADOC_SOURCE_DIRS))) -ALL_PKG_DIRNAMES := $(foreach prefix, $(ALL_SRC_PREFIXES), \ - $(patsubst $(prefix),%, $(filter $(prefix), $(ALL_PKG_DIRS)))) -ALL_PACKAGES := $(sort $(subst /,., $(patsubst %/, %, $(ALL_PKG_DIRNAMES)))) - -JAVA_PACKAGES := $(filter java.%, $(ALL_PACKAGES)) -JAVAX_PACKAGES := $(filter javax.%, $(ALL_PACKAGES)) -ORG_PACKAGES := $(filter org.%, $(ALL_PACKAGES)) - -# Allow custom makefile to add more excluded packages -CORE_EXCLUDED_PACKAGES += \ - java.awt.dnd.peer \ - java.awt.peer \ - javax.smartcardio \ - org.jcp.xml.dsig.internal% \ - org.w3c.dom.css \ - org.w3c.dom.html \ - org.w3c.dom.stylesheets \ - org.w3c.dom.xpath \ - # - -CORE_PACKAGES := $(filter-out $(CORE_EXCLUDED_PACKAGES), \ - $(JAVA_PACKAGES) $(JAVAX_PACKAGES) $(ORG_PACKAGES)) - $(eval $(call SetupJavadocGeneration, coredocs, \ MODULES := java.se.ee, \ PACKAGES := $(CORE_PACKAGES), \ @@ -367,7 +340,7 @@ SPLIT_INDEX := TRUE, \ BOTTOM_COPYRIGHT_URL := $(CORE_BOTTOM_COPYRIGHT_URL), \ BOTTOM_TEXT := $(CORE_BOTTOM_TEXT), \ - EXTRA_TOP := $(CORE_TOP_EARLYACCESS), \ + EXTRA_TOP := $(EARLYACCESS_TOP), \ )) TARGETS += $(coredocs) @@ -733,19 +706,13 @@ ################################################################################ # Optional target which bundles all generated javadocs into a zip archive. -# The dependency on docs is handled in Main.gmk. - -# 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. JAVADOC_ARCHIVE_NAME := jdk-$(VERSION_STRING)-docs.zip JAVADOC_ARCHIVE_ASSEMBLY_DIR := $(SUPPORT_OUTPUTDIR)/docs/zip-docs JAVADOC_ARCHIVE_DIR := $(OUTPUT_ROOT)/bundles JAVADOC_ARCHIVE := $(JAVADOC_ARCHIVE_DIR)/$(JAVADOC_ARCHIVE_NAME) -$(JAVADOC_ARCHIVE): $(CORE_INDEX_FILE) +$(JAVADOC_ARCHIVE): $(TARGETS) $(COPY_TARGETS) $(call LogInfo, Compressing javadoc to single $(JAVADOC_ARCHIVE_NAME)) $(MKDIR) -p $(JAVADOC_ARCHIVE_DIR) $(RM) -r $(JAVADOC_ARCHIVE_ASSEMBLY_DIR)