--- old/make/Docs.gmk 2019-07-21 01:32:47.117735212 +0200 +++ new/make/Docs.gmk 2019-07-21 01:32:46.933735604 +0200 @@ -1,4 +1,4 @@ -# Copyright (c) 1997, 2019, Oracle and/or its affiliates. All rights reserved. +# Copyright (c) 1997, 2018, Oracle and/or its affiliates. All rights reserved. # DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. # # This code is free software; you can redistribute it and/or modify it @@ -26,13 +26,11 @@ include $(SPEC) include MakeBase.gmk -include Execute.gmk include Modules.gmk -include ModuleTools.gmk include ProcessMarkdown.gmk -include ToolsJdk.gmk include ZipArchive.gmk -include TextFileProcessing.gmk +include $(TOPDIR)/make/ToolsJdk.gmk +include $(TOPDIR)/make/ModuleTools.gmk # This is needed to properly setup DOCS_MODULES. $(eval $(call ReadImportMetaData)) @@ -65,7 +63,7 @@ # URLs JAVADOC_BASE_URL := https://docs.oracle.com/pls/topic/lookup?ctx=javase$(VERSION_NUMBER)&id=homepage BUG_SUBMIT_URL := https://bugreport.java.com/bugreport/ -COPYRIGHT_URL := legal/copyright.html +COPYRIGHT_URL := {@docroot}/../legal/copyright.html LICENSE_URL := https://www.oracle.com/technetwork/java/javase/terms/license/java$(VERSION_NUMBER)speclicense.html REDISTRIBUTION_URL := https://www.oracle.com/technetwork/java/redist-137594.html @@ -85,14 +83,13 @@ -tag param \ -tag return \ -tag throws \ - -taglet build.tools.taglet.JSpec\$$JLS \ - -taglet build.tools.taglet.JSpec\$$JVMS \ -taglet build.tools.taglet.ModuleGraph \ - -taglet build.tools.taglet.ToolGuide \ -tag since \ -tag serialData \ -tag factory \ -tag see \ + -tag 'jvms:a:See The Java™ Virtual Machine Specification:' \ + -tag 'jls:a:See The Java™ Language Specification:' \ -taglet build.tools.taglet.ExtLink \ -taglet build.tools.taglet.Incubating \ -tagletpath $(BUILDTOOLS_OUTPUTDIR)/jdk_tools_classes \ @@ -150,15 +147,6 @@ HEADER_STYLE := style="margin-top: 14px;" endif -# $1 - Relative prefix to COPYRIGHT_URL -COPYRIGHT_BOTTOM = \ - Copyright \ - © 1993, $(COPYRIGHT_YEAR), $(FULL_COMPANY_NAME), \ - $(COMPANY_ADDRESS).
All rights reserved. \ - Use is subject to license terms and the \ - documentation redistribution policy. \ - $(DRAFT_MARKER_STR) - JAVADOC_BOTTOM := \ Report a bug or suggest an enhancement
\ For further API reference and developer documentation see the \ @@ -168,13 +156,26 @@ of terms, workarounds, and working code examples.
\ Java is a trademark or registered trademark of $(FULL_COMPANY_NAME) in \ the US and other countries.
\ - $(call COPYRIGHT_BOTTOM, {@docroot}/../) + Copyright \ + © 1993, $(COPYRIGHT_YEAR), $(FULL_COMPANY_NAME), \ + $(COMPANY_ADDRESS).
All rights reserved. \ + Use is subject to license terms and the \ + documentation redistribution policy. \ + $(DRAFT_MARKER_STR) JAVADOC_TOP := \
$(DRAFT_TEXT)
+JDK_INDEX_CONTENT := \ + \ + \ + \ + \ + \ + + ################################################################################ # JDK javadoc titles/text snippets @@ -202,13 +203,10 @@ # For each module needing a graph, create a png file from the dot file # generated by the GenGraphs tool and store it in the target dir. - $$(eval $$(call SetupExecute, gengraphs_png_$1_$2, \ - INFO := Running dot for module graphs for $2, \ - DEPS := $$(gengraphs_$1_TARGET), \ - OUTPUT_FILE := $$($1_$2_PNG_TARGET), \ - SUPPORT_DIR := $$($1_GENGRAPHS_DIR), \ - COMMAND := $$(DOT) -Tpng -o $$($1_$2_PNG_TARGET) $$($1_$2_DOT_SRC), \ - )) + $$($1_$2_PNG_TARGET): $$($1_GENGRAPHS_MARKER) + $$(call MakeDir, $$(@D)) + $$(call ExecuteWithLog, $$($1_$2_DOT_SRC), \ + $$(DOT) -Tpng -o $$($1_$2_PNG_TARGET) $$($1_$2_DOT_SRC)) $1_MODULEGRAPH_TARGETS += $$($1_$2_PNG_TARGET) endef @@ -276,8 +274,7 @@ $1_INDIRECT_EXPORTS := $$(call FindTransitiveIndirectDepsForModules, $$($1_MODULES)) $1_ALL_MODULES := $$(sort $$($1_MODULES) $$($1_INDIRECT_EXPORTS)) - $1_JAVA_ARGS := -Dextlink.spec.version=$$(VERSION_SPECIFICATION) \ - -Djspec.version=$$(VERSION_SPECIFICATION) + $1_JAVA_ARGS := -Dextlink.spec.version=$$(VERSION_SPECIFICATION) ifeq ($$(ENABLE_FULL_DOCS), true) # Tell the ModuleGraph taglet to generate html links to soon-to-be-created @@ -344,21 +341,21 @@ $$(SUPPORT_OUTPUTDIR)/docs/$1.vardeps) # Get a list of all files in all the source dirs for all included modules - $1_SOURCE_DEPS := $$(call FindFiles, $$(wildcard $$(foreach module, \ + $1_SOURCE_DEPS := $$(call CacheFind, $$(wildcard $$(foreach module, \ $$($1_ALL_MODULES), $$(call FindModuleSrcDirs, $$(module))))) - $$(eval $$(call SetupExecute, javadoc_$1, \ - WARN := Generating $1 javadoc for $$(words $$($1_ALL_MODULES)) modules, \ - INFO := Javadoc modules: $$($1_ALL_MODULES), \ - DEPS := $$(BUILD_TOOLS_JDK) $$($1_VARDEPS_FILE) $$($1_SOURCE_DEPS) \ - $$($1_OVERVIEW), \ - OUTPUT_DIR := $$($1_TARGET_DIR), \ - SUPPORT_DIR := $$(SUPPORT_OUTPUTDIR)/docs, \ - COMMAND := $$($1_JAVADOC_CMD) -d $$($1_TARGET_DIR) $$($1_OPTIONS) \ - $$($1_LOG_OPTION), \ - )) + # Javadoc creates a lot of files but use index.html as a marker + $$($1_TARGET_DIR)/index.html: $$(BUILD_TOOLS_JDK) $$($1_VARDEPS_FILE) \ + $$($1_SOURCE_DEPS) $$($1_OVERVIEW) + $$(call LogWarn, Generating $1 javadoc for \ + $$(words $$($1_ALL_MODULES)) modules) + $$(call LogInfo, Javadoc modules: $$($1_ALL_MODULES)) + $$(call MakeDir, $$($1_TARGET_DIR)) + $$(call ExecuteWithLog, $$(SUPPORT_OUTPUTDIR)/docs/$1, \ + $$($1_JAVADOC_CMD) -d $$($1_TARGET_DIR) \ + $$($1_OPTIONS) $$($1_LOG_OPTION)) - $1_JAVADOC_TARGETS := $$(javadoc_$1_TARGET) + $1_JAVADOC_TARGETS := $$($1_TARGET_DIR)/index.html ifeq ($$(ENABLE_FULL_DOCS), true) # We have asked ModuleGraph to generate links to png files. Now we must @@ -378,18 +375,19 @@ $$(TOPDIR)/make/jdk/src/classes/build/tools/jigsaw/javadoc-graphs.properties $1_GENGRAPHS_DIR := $$(SUPPORT_OUTPUTDIR)/docs/$1-gengraphs + $1_GENGRAPHS_MARKER := $$($1_GENGRAPHS_DIR)/_gengraphs_run.marker - $$(eval $$(call SetupExecute, gengraphs_$1, \ - INFO := Running gengraphs for $1 documentation, \ - DEPS := $$(BUILD_JIGSAW_TOOLS) $$(GENGRAPHS_PROPS), \ - OUTPUT_DIR := $$($1_GENGRAPHS_DIR), \ - COMMAND := $$(TOOL_GENGRAPHS) --spec --output $$($1_GENGRAPHS_DIR) \ - --dot-attributes $$(GENGRAPHS_PROPS), \ - )) + $$($1_GENGRAPHS_MARKER): $$(BUILD_JIGSAW_TOOLS) $$(GENGRAPHS_PROPS) + $$(call LogInfo, Running gengraphs for $1 documentation) + $$(call MakeDir, $$($1_GENGRAPHS_DIR)) + $$(call ExecuteWithLog, $$($1_GENGRAPHS_DIR)/gengraphs, \ + $$(TOOL_GENGRAPHS) --spec --output $$($1_GENGRAPHS_DIR) \ + --dot-attributes $$(GENGRAPHS_PROPS) && \ + $$(TOUCH) $$($1_GENGRAPHS_MARKER)) # For each module needing a graph, create a png file from the dot file # generated by the GenGraphs tool and store it in the target dir. - # They will depend on gengraphs_$1_TARGET, and will be added to $1. + # They will depend on $1_GENGRAPHS_MARKER, and will be added to $1. $$(foreach m, $$($1_MODULES_NEEDING_GRAPH), \ $$(eval $$(call setup_gengraph_dot_to_png,$1,$$m)) \ ) @@ -487,11 +485,18 @@ ################################################################################ -# Copy the global resources, including the top-level redirect index.html +JDK_INDEX_HTML := $(DOCS_OUTPUTDIR)/index.html + +$(JDK_INDEX_HTML): + $(ECHO) '$(JDK_INDEX_CONTENT)' > $@ + +JDK_INDEX_TARGETS += $(JDK_INDEX_HTML) + +# Copy the global resources GLOBAL_SPECS_RESOURCES_DIR := $(TOPDIR)/make/data/docs-resources/ $(eval $(call SetupCopyFiles, COPY_GLOBAL_RESOURCES, \ SRC := $(GLOBAL_SPECS_RESOURCES_DIR), \ - FILES := $(call FindFiles, $(GLOBAL_SPECS_RESOURCES_DIR)), \ + FILES := $(call CacheFind, $(GLOBAL_SPECS_RESOURCES_DIR)), \ DEST := $(DOCS_OUTPUTDIR), \ )) JDK_INDEX_TARGETS += $(COPY_GLOBAL_RESOURCES) @@ -507,19 +512,19 @@ ################################################################################ # Copy JDK specs files -# For all non html/md files in $module/share/specs directories, copy them +# For all html documentation in $module/share/specs directories, copy it # unmodified ALL_MODULES := $(call FindAllModules) -COPY_SPEC_FILTER := %.gif %.jpg %.mib %.css +COPY_SPEC_FILTER := %.html %.gif %.jpg %.mib %.css $(foreach m, $(ALL_MODULES), \ $(eval SPECS_$m := $(call FindModuleSpecsDirs, $m)) \ $(foreach d, $(SPECS_$m), \ - $(if $(filter $(COPY_SPEC_FILTER), $(call FindFiles, $d)), \ + $(if $(filter $(COPY_SPEC_FILTER), $(call CacheFind, $d)), \ $(eval $(call SetupCopyFiles, COPY_$m, \ SRC := $d, \ - FILES := $(filter $(COPY_SPEC_FILTER), $(call FindFiles, $d)), \ + FILES := $(filter $(COPY_SPEC_FILTER), $(call CacheFind, $d)), \ DEST := $(DOCS_OUTPUTDIR)/specs/, \ )) \ $(eval JDK_SPECS_TARGETS += $(COPY_$m)) \ @@ -527,102 +532,43 @@ ) \ ) -# Create copyright footer files that can be provided as input to pandoc. We -# need different files for different relative paths to the copyright.html -# file. The number 0-2 below represent how many extra directory levels down -# below the specs dir the specs html file is located. Each file name is -# stored in a variable SPECS_BOTTOM_FILE_$n where $n is 0, 1 or 2. -SPECS_BOTTOM =
$(COPYRIGHT_BOTTOM) -# The legal dir is one ../ below the specs dir, so start with one ../. -specs_bottom_rel_path := ../ -$(foreach n, 0 1 2, \ - $(eval SPECS_BOTTOM_FILE_$n := $(SUPPORT_OUTPUTDIR)/docs/full-specs-bottom-$n.txt) \ - $(eval SPECS_BOTTOM_$n := $(call SPECS_BOTTOM,$(specs_bottom_rel_path))) \ - $(eval $(SPECS_BOTTOM_FILE_$n): \ - $(call DependOnVariable, SPECS_BOTTOM_$n) ; \ - $(PRINTF) '$(SPECS_BOTTOM_$n)' > $$@ \ - ) \ - $(eval specs_bottom_rel_path := $(specs_bottom_rel_path)../) \ -) - -# For all html files in $module/share/specs directories, copy and add the -# copyright footer. - -$(foreach m, $(ALL_MODULES), \ - $(eval SPECS_$m := $(call FindModuleSpecsDirs, $m)) \ - $(foreach d, $(SPECS_$m), \ - $(foreach f, $(filter %.html, $(call FindFiles, $d)), \ - $(eval $m_$f_NOF_SUBDIRS := $(words $(subst /, $(SPACE), $(subst $d, , $(dir $f))))) \ - $(eval $m_$f_NAME := PROCESS_HTML_$m_$(strip $(call RelativePath, $f, $(TOPDIR)))) \ - $(eval $(call SetupTextFileProcessing, $($m_$f_NAME), \ - SOURCE_FILES := $f, \ - SOURCE_BASE_DIR := $d, \ - OUTPUT_DIR := $(DOCS_OUTPUTDIR)/specs/, \ - REPLACEMENTS := \ - => $(SPECS_BOTTOM_$($m_$f_NOF_SUBDIRS)), \ - )) \ - $(eval JDK_SPECS_TARGETS += $($($m_$f_NAME))) \ - ) \ - ) \ -) - -ifeq ($(ENABLE_PANDOC), true) +ifeq ($(ENABLE_FULL_DOCS), true) # For all markdown files in $module/share/specs directories, convert them to - # html, if we have pandoc (otherwise we'll just skip this). + # html. GLOBAL_SPECS_DEFAULT_CSS_FILE := $(DOCS_OUTPUTDIR)/resources/jdk-default.css $(foreach m, $(ALL_MODULES), \ $(eval SPECS_$m := $(call FindModuleSpecsDirs, $m)) \ $(foreach d, $(SPECS_$m), \ - $(foreach f, $(filter %.md, $(call FindFiles, $d)), \ - $(eval $m_$f_NOF_SUBDIRS := $(words $(subst /, $(SPACE), $(subst $d, , $(dir $f))))) \ - $(eval $m_$f_BOTTOM_FILE := $(SPECS_BOTTOM_FILE_$($m_$f_NOF_SUBDIRS))) \ - $(eval $m_$f_NAME := SPECS_TO_HTML_$m_$(strip $(call RelativePath, $f, $(TOPDIR)))) \ - $(eval $(call SetupProcessMarkdown, $($m_$f_NAME), \ + $(if $(filter %.md, $(call CacheFind, $d)), \ + $(eval $m_$d_NAME := SPECS_TO_HTML_$m_$(strip $(call RelativePath, $d, $(TOPDIR)))) \ + $(eval $(call SetupProcessMarkdown, $($m_$d_NAME), \ SRC := $d, \ - FILES := $f, \ + FILES := $(filter %.md, $(call CacheFind, $d)), \ DEST := $(DOCS_OUTPUTDIR)/specs/, \ CSS := $(GLOBAL_SPECS_DEFAULT_CSS_FILE), \ - OPTIONS := -A $($m_$f_BOTTOM_FILE), \ - EXTRA_DEPS := $($m_$f_BOTTOM_FILE), \ - POST_PROCESS := $(TOOL_FIXUPPANDOC), \ )) \ - $(eval JDK_SPECS_TARGETS += $($($m_$f_NAME))) \ + $(eval JDK_SPECS_TARGETS += $($($m_$d_NAME))) \ ) \ ) \ ) # For all markdown files in $module/share/man directories, convert them to # html. - - # Create dynamic man pages from markdown using pandoc. We need - # PANDOC_HTML_MANPAGE_FILTER, a wrapper around - # PANDOC_HTML_MANPAGE_FILTER_JAVASCRIPT. This is created by buildtools-jdk. - - # We should also depend on the source javascript filter - PANDOC_HTML_MANPAGE_FILTER_JAVASCRIPT := \ - $(TOPDIR)/make/scripts/pandoc-html-manpage-filter.js - $(foreach m, $(ALL_MODULES), \ $(eval MAN_$m := $(call FindModuleManDirs, $m)) \ $(foreach d, $(MAN_$m), \ - $(foreach f, $(filter %.md, $(call FindFiles, $d)), \ - $(eval $m_$f_NAME := MAN_TO_HTML_$m_$(strip $(call RelativePath, $f, $(TOPDIR)))) \ - $(eval $(call SetupProcessMarkdown, $($m_$f_NAME), \ + $(if $(filter %.md, $(call CacheFind, $d)), \ + $(eval $m_$d_NAME := MAN_TO_HTML_$m_$(strip $(call RelativePath, $d, $(TOPDIR)))) \ + $(eval $(call SetupProcessMarkdown, $($m_$d_NAME), \ SRC := $d, \ - FILES := $f, \ + FILES := $(filter %.md, $(call CacheFind, $d)), \ DEST := $(DOCS_OUTPUTDIR)/specs/man, \ - FILTER := $(PANDOC_HTML_MANPAGE_FILTER), \ CSS := $(GLOBAL_SPECS_DEFAULT_CSS_FILE), \ REPLACEMENTS := @@VERSION_SHORT@@ => $(VERSION_SHORT), \ - OPTIONS := -A $(SPECS_BOTTOM_FILE_1), \ - POST_PROCESS := $(TOOL_FIXUPPANDOC), \ - EXTRA_DEPS := $(PANDOC_HTML_MANPAGE_FILTER) \ - $(PANDOC_HTML_MANPAGE_FILTER_JAVASCRIPT) \ - $(SPECS_BOTTOM_FILE_1), \ )) \ - $(eval JDK_SPECS_TARGETS += $($($m_$f_NAME))) \ + $(eval JDK_SPECS_TARGETS += $($($m_$d_NAME))) \ ) \ ) \ ) @@ -634,23 +580,19 @@ # Special treatment for generated documentation JDWP_PROTOCOL := $(SUPPORT_OUTPUTDIR)/gensrc/jdk.jdi/jdwp-protocol.html -$(eval $(call SetupTextFileProcessing, PROCESS_JDWP_PROTOCOL, \ - SOURCE_FILES := $(JDWP_PROTOCOL), \ - OUTPUT_DIR := $(DOCS_OUTPUTDIR)/specs/jdwp, \ - REPLACEMENTS := \ - => $(SPECS_BOTTOM_1), \ +$(eval $(call SetupCopyFiles, COPY_JDWP_PROTOCOL, \ + FILES := $(JDWP_PROTOCOL), \ + DEST := $(DOCS_OUTPUTDIR)/specs/jdwp, \ )) -JDK_SPECS_TARGETS += $(PROCESS_JDWP_PROTOCOL) +JDK_SPECS_TARGETS += $(COPY_JDWP_PROTOCOL) # Get jvmti.html from the main jvm variant (all variants' jvmti.html are identical). JVMTI_HTML ?= $(HOTSPOT_OUTPUTDIR)/variant-$(JVM_VARIANT_MAIN)/gensrc/jvmtifiles/jvmti.html -$(eval $(call SetupTextFileProcessing, PROCESS_JVMTI_HTML, \ - SOURCE_FILES := $(JVMTI_HTML), \ - OUTPUT_DIR := $(DOCS_OUTPUTDIR)/specs/, \ - REPLACEMENTS := \ - => $(SPECS_BOTTOM_0), \ +$(eval $(call SetupCopyFiles, COPY_JVMTI_HTML, \ + FILES := $(JVMTI_HTML), \ + DEST := $(DOCS_OUTPUTDIR)/specs, \ )) -JDK_SPECS_TARGETS += $(PROCESS_JVMTI_HTML) +JDK_SPECS_TARGETS += $(COPY_JVMTI_HTML) ################################################################################ # Optional target which bundles all generated javadocs into a zip archive. @@ -668,10 +610,6 @@ ZIP_TARGETS += $(BUILD_JAVADOC_ZIP) ################################################################################ -# Hook to include the corresponding custom file, if present. -$(eval $(call IncludeCustomExtension, Docs-post.gmk)) - -################################################################################ docs-jdk-api-javadoc: $(JDK_API_JAVADOC_TARGETS) $(JDK_API_CUSTOM_TARGETS)