Docs.gmk revision 2620:69879afbd98f
1# Copyright (c) 1997, 2017, Oracle and/or its affiliates. All rights reserved. 2# DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 3# 4# This code is free software; you can redistribute it and/or modify it 5# under the terms of the GNU General Public License version 2 only, as 6# published by the Free Software Foundation. Oracle designates this 7# particular file as subject to the "Classpath" exception as provided 8# by Oracle in the LICENSE file that accompanied this code. 9# 10# This code is distributed in the hope that it will be useful, but WITHOUT 11# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 12# FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 13# version 2 for more details (a copy is included in the LICENSE file that 14# accompanied this code). 15# 16# You should have received a copy of the GNU General Public License version 17# 2 along with this work; if not, write to the Free Software Foundation, 18# Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 19# 20# Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 21# or visit www.oracle.com if you need additional information or have any 22# questions. 23# 24 25default: all 26 27include $(SPEC) 28include MakeBase.gmk 29include Modules.gmk 30include ProcessMarkdown.gmk 31include ZipArchive.gmk 32include $(JDK_TOPDIR)/make/Tools.gmk 33include $(JDK_TOPDIR)/make/ModuleTools.gmk 34 35# This is needed to properly setup DOCS_MODULES. 36$(eval $(call ReadImportMetaData)) 37 38################################################################################ 39 40# Hook to include the corresponding custom file, if present. 41$(eval $(call IncludeCustomExtension, , Docs.gmk)) 42 43################################################################################ 44# Javadoc settings 45 46# On top of the sources that was used to compile the JDK, we need some 47# extra java.rmi sources that are used just for javadoc. 48MODULES_SOURCE_PATH := $(call PathList, $(call GetModuleSrcPath) \ 49 $(SUPPORT_OUTPUTDIR)/rmic/* $(JDK_TOPDIR)/src/*/share/doc/stub) 50 51# Should we use -Xdocrootparent? Allow custom to overwrite. 52DOCROOTPARENT_FLAG ?= TRUE 53 54# URLs 55JAVADOC_BASE_URL := http://www.oracle.com/pls/topic/lookup?ctx=javase9&id=homepage 56BUG_SUBMIT_URL := http://bugreport.java.com/bugreport/ 57COPYRIGHT_URL := {@docroot}/../legal/cpyr.html 58LICENSE_URL := http://www.oracle.com/technetwork/java/javase/terms/license/java9speclicense.html 59REDISTRIBUTION_URL := http://www.oracle.com/technetwork/java/redist-137594.html 60 61 62# In order to get a specific ordering it's necessary to specify the total 63# ordering of tags as the tags are otherwise ordered in order of definition. 64JAVADOC_TAGS := \ 65 -tag beaninfo:X \ 66 -tag revised:X \ 67 -tag since.unbundled:X \ 68 -tag spec:X \ 69 -tag specdefault:X \ 70 -tag Note:X \ 71 -tag ToDo:X \ 72 -tag 'apiNote:a:API Note:' \ 73 -tag 'implSpec:a:Implementation Requirements:' \ 74 -tag 'implNote:a:Implementation Note:' \ 75 -tag param \ 76 -tag return \ 77 -tag throws \ 78 -taglet build.tools.taglet.ModuleGraph \ 79 -tag since \ 80 -tag version \ 81 -tag serialData \ 82 -tag factory \ 83 -tag see \ 84 -tag 'jvms:a:See <cite>The Java™ Virtual Machine Specification</cite>:' \ 85 -tag 'jls:a:See <cite>The Java™ Language Specification</cite>:' \ 86 -taglet build.tools.taglet.ExtLink \ 87 -taglet build.tools.taglet.Incubating \ 88 -tagletpath $(BUILDTOOLS_OUTPUTDIR)/jdk_tools_classes \ 89 $(CUSTOM_JAVADOC_TAGS) \ 90 # 91 92# Which doclint checks to ignore 93JAVADOC_DISABLED_DOCLINT := accessibility html missing syntax reference 94 95# The initial set of options for javadoc 96JAVADOC_OPTIONS := -XDignore.symbol.file=true -use -keywords -notimestamp \ 97 -serialwarn -encoding ISO-8859-1 -breakiterator -splitIndex --system none \ 98 -html5 -javafx --expand-requires transitive 99 100# Should we add DRAFT stamps to the generated javadoc? 101ifeq ($(VERSION_IS_GA), true) 102 IS_DRAFT := false 103else 104 IS_DRAFT := true 105endif 106 107################################################################################ 108# General text snippets 109 110FULL_COMPANY_NAME := Oracle and/or its affiliates 111COMPANY_ADDRESS := 500 Oracle Parkway<br>Redwood Shores, CA 94065 USA 112 113ifeq ($(IS_DRAFT), true) 114 DRAFT_MARKER_STR := <br><strong>DRAFT $(VERSION_STRING)</strong> 115 ifeq ($(VERSION_BUILD), 0) 116 DRAFT_MARKER_TITLE := [ad-hoc build] 117 else 118 DRAFT_MARKER_TITLE := [build $(VERSION_BUILD)] 119 endif 120endif 121 122JAVADOC_WINDOW_TITLE := Java Platform SE $(VERSION_SPECIFICATION) \ 123 $(DRAFT_MARKER_TITLE) 124 125JAVADOC_HEADER_TITLE := $(subst $(SPACE), ,$(strip \ 126 <strong>Java™ Platform<br>Standard Ed. \ 127 $(VERSION_SPECIFICATION)</strong>$(DRAFT_MARKER_STR))) 128 129JAVADOC_BOTTOM := \ 130 <span style="font-size:smaller"> \ 131 <a href="$(BUG_SUBMIT_URL)">Submit a bug or feature</a><br> \ 132 For further API reference and developer documentation, see \ 133 <a href="$(JAVADOC_BASE_URL)/index.html" target="_blank">Java SE \ 134 Documentation</a>. That documentation contains more detailed, \ 135 developer-targeted descriptions, with conceptual overviews, definitions \ 136 of terms, workarounds, and working code examples.<br> \ 137 Java is a trademark or registered trademark of $(FULL_COMPANY_NAME) in \ 138 the US and other countries.<br> \ 139 <a href="$(COPYRIGHT_URL)">Copyright</a> \ 140 © 1993, $(COPYRIGHT_YEAR), $(FULL_COMPANY_NAME). \ 141 $(COMPANY_ADDRESS). All rights reserved. \ 142 Use is subject to <a href="$(LICENSE_URL)">license terms</a>. Also see the \ 143 <a href="$(REDISTRIBUTION_URL)">documentation redistribution policy</a>. \ 144 $(DRAFT_MARKER_STR)</span> 145 146JAVADOC_TOP := \ 147 <div style="background-color: $(HASH)EEEEEE"><div style="padding: 6px; \ 148 margin-top: 2px; margin-bottom: 6px; margin-left: 6px; margin-right: \ 149 6px; text-align: justify; font-size: 80%; font-family: Helvetica, Arial, \ 150 sans-serif; font-weight: normal;">Please note that the specifications \ 151 and other information contained herein are not final and are subject to \ 152 change. The information is being made available to you solely for \ 153 purpose of evaluation.</div></div> 154 155################################################################################ 156# JDK javadoc titles/text snippets 157 158JDK_JAVADOC_DOC_TITLE := Java™ Platform, Standard Edition Development Kit \ 159 (JDK™) $(VERSION_SPECIFICATION)<br>API Specification 160 161################################################################################ 162# Java SE javadoc titles/text snippets 163 164JAVASE_JAVADOC_DOC_TITLE := Java™ Platform, Standard Edition \ 165 $(VERSION_SPECIFICATION)<br>API Specification 166 167################################################################################ 168# Functions 169 170# Helper function for creating a png file from a dot file generated by the 171# GenGraphs tool. 172# param 1: SetupJavadocGeneration namespace ($1) 173# param 2: module name 174# 175define setup_gengraph_dot_to_png 176 $1_$2_DOT_SRC := $$($1_GENGRAPHS_DIR)/$2.dot 177 $1_$2_PNG_TARGET := $$($1_TARGET_DIR)/$2-graph.png 178 179 # For each module needing a graph, create a png file from the dot file 180 # generated by the GenGraphs tool and store it in the target dir. 181 $$($1_$2_PNG_TARGET): $$($1_GENGRAPHS_MARKER) 182 $$(call MakeDir, $$(@D)) 183 $$(call ExecuteWithLog, $$($1_$2_DOT_SRC), \ 184 $$(DOT) -Tpng -o $$($1_$2_PNG_TARGET) $$($1_$2_DOT_SRC)) 185 186 $1_MODULEGRAPH_TARGETS += $$($1_$2_PNG_TARGET) 187endef 188 189################################################################################ 190# Setup make rules for creating the API documentation, using javadoc and other 191# tools if needed. 192# 193# Parameter 1 is the name of the rule. This name is used as variable prefix. 194# Targets generated are returned as $1_JAVADOC_TARGETS and 195# $1_MODULEGRAPH_TARGETS. Note that the index.html file will work as a "touch 196# file" for all the magnitude of files that are generated by javadoc. 197# 198# Remaining parameters are named arguments. These include: 199# MODULES - Modules to generate javadoc for 200# NAME - The name of the javadoc compilation, to be presented to the user 201# TARGET_DIR - Where to store the output 202# OVERVIEW - Path to an html overview file 203# DOC_TITLE - Title to use in -doctitle. 204# WINDOW_TITLE - Title to use in -windowtitle. 205# HEADER_TITLE - Title to use in -header. 206# BOTTOM_TEXT - Text to use in -bottom. 207# TOP_TEXT - Text to use in -top. 208# 209SetupApiDocsGeneration = $(NamedParamsMacroTemplate) 210define SetupApiDocsGenerationBody 211 212 # Figure out all modules, both specified and transitive, that will be processed 213 # by javadoc. 214 $1_TRANSITIVE_MODULES := $$(call FindTransitiveDepsForModules, $$($1_MODULES)) 215 $1_ALL_MODULES := $$(sort $$($1_MODULES) $$($1_TRANSITIVE_MODULES)) 216 217 ifeq ($$(ENABLE_FULL_DOCS), true) 218 # Tell the ModuleGraph taglet to generate html links to soon-to-be-created 219 # png files with module graphs. 220 $1_JAVA_ARGS += -DenableModuleGraph=true 221 endif 222 223 # Always include tags and basic options 224 $1_OPTIONS := $$(JAVADOC_TAGS) $$(JAVADOC_OPTIONS) 225 226 $1_OPTIONS += -overview $$($1_OVERVIEW) 227 $1_OPTIONS += --module-source-path $$(MODULES_SOURCE_PATH) 228 $1_OPTIONS += --module $$(call CommaList, $$($1_MODULES)) 229 230 # Create a string like "-Xdoclint:all,-syntax,-html,..." 231 $1_OPTIONS += -Xdoclint:all,$$(call CommaList, $$(addprefix -, \ 232 $$(JAVADOC_DISABLED_DOCLINT))) 233 234 ifeq ($$($$DOCROOTPARENT_FLAG), TRUE) 235 $1_OPTIONS += -Xdocrootparent $$(JAVADOC_BASE_URL) 236 endif 237 238 $1_OPTIONS += -doctitle '$$($1_DOC_TITLE)' 239 $1_OPTIONS += -windowtitle '$$($1_WINDOW_TITLE)' 240 $1_OPTIONS += -header '$$($1_HEADER_TITLE)' 241 $1_OPTIONS += -bottom '$$($1_BOTTOM_TEXT)' 242 ifeq ($$(IS_DRAFT), true) 243 $1_OPTIONS += -top '$$($1_TOP_TEXT)' 244 endif 245 246 # Do not store debug level options in VARDEPS. 247 ifneq ($$(LOG_LEVEL), trace) 248 $1_LOG_OPTION += -quiet 249 else 250 $1_LOG_OPTION += -verbose 251 endif 252 253 $1_VARDEPS := $$($1_JAVA_ARGS) $$($1_OPTIONS) $$(MODULES_SOURCE_PATH) \ 254 $$($1_ALL_MODULES) 255 $1_VARDEPS_FILE := $$(call DependOnVariable, $1_VARDEPS, \ 256 $$(SUPPORT_OUTPUTDIR)/docs/$1.vardeps) 257 258 # Get a list of all files in all the source dirs for all included modules 259 $1_SOURCE_DEPS := $$(call CacheFind, $$(wildcard $$(foreach module, \ 260 $$($1_ALL_MODULES), $$(call FindModuleSrcDirs, $$(module))))) 261 262 # Javadoc creates a lot of files but use index.html as a marker 263 $$($1_TARGET_DIR)/index.html: $$(BUILD_TOOLS_JDK) $$($1_VARDEPS_FILE) \ 264 $$($1_SOURCE_DEPS) $$($1_OVERVIEW) 265 $$(call LogWarn, Generating $$($1_NAME) API javadoc for \ 266 $$(words $$($1_ALL_MODULES)) modules) 267 $$(call LogInfo, Javadoc modules: $$($1_ALL_MODULES)) 268 $$(call MakeDir, $$($1_TARGET_DIR)) 269 $$(call ExecuteWithLog, $$(SUPPORT_OUTPUTDIR)/docs/$1, \ 270 $$(JAVA) -Djava.awt.headless=true $$($1_JAVA_ARGS) \ 271 $$(NEW_JAVADOC) -d $$($1_TARGET_DIR) \ 272 $$(JAVADOC_TAGS) $$($1_OPTIONS) $$($1_LOG_OPTION)) 273 274 $1_JAVADOC_TARGETS := $$($1_TARGET_DIR)/index.html 275 276 ifeq ($$(ENABLE_FULL_DOCS), true) 277 # We have asked ModuleGraph to generate links to png files. Now we must 278 # produce the png files. 279 280 # Locate which modules has the @moduleGraph tag in their module-info.java 281 $1_MODULES_NEEDING_GRAPH := $$(strip $$(foreach m, $$($1_ALL_MODULES), \ 282 $$(if $$(shell $$(GREP) -e @moduleGraph \ 283 $$(wildcard $$(addsuffix /module-info.java, \ 284 $$(call FindModuleSrcDirs, $$m)))), \ 285 $$m) \ 286 )) 287 288 # First we run the GenGraph tool. It will query the module structure of the 289 # running JVM and output .dot files for all existing modules. 290 GENGRAPHS_PROPS := \ 291 $$(JDK_TOPDIR)/make/src/classes/build/tools/jigsaw/javadoc-graphs.properties 292 293 $1_GENGRAPHS_DIR := $$(SUPPORT_OUTPUTDIR)/docs/$1-gengraphs 294 $1_GENGRAPHS_MARKER := $$($1_GENGRAPHS_DIR)/_gengraphs_run.marker 295 296 $$($1_GENGRAPHS_MARKER): $$(BUILD_JIGSAW_TOOLS) $$(GENGRAPHS_PROPS) 297 $$(call LogInfo, Running gengraphs for $$($1_NAME) API documentation) 298 $$(call MakeDir, $$($1_GENGRAPHS_DIR)) 299 $$(call ExecuteWithLog, $$($1_GENGRAPHS_DIR)/gengraphs, \ 300 $$(TOOL_GENGRAPHS) --spec --output $$($1_GENGRAPHS_DIR) \ 301 --dot-attributes $$(GENGRAPHS_PROPS) && \ 302 $$(TOUCH) $$($1_GENGRAPHS_MARKER)) 303 304 # For each module needing a graph, create a png file from the dot file 305 # generated by the GenGraphs tool and store it in the target dir. 306 # They will depend on $1_GENGRAPHS_MARKER, and will be added to $1. 307 $$(foreach m, $$($1_MODULES_NEEDING_GRAPH), \ 308 $$(eval $$(call setup_gengraph_dot_to_png,$1,$$m)) \ 309 ) 310 endif 311endef 312 313################################################################################ 314# Setup generation of the JDK API documentation (javadoc + modulegraph) 315 316# All modules to have docs generated by docs-jdk-api target 317JDK_JAVADOC_MODULES := $(sort $(DOCS_MODULES)) 318 319JDK_JAVADOC_OVERVIEW := $(JDK_TOPDIR)/src/java.base/share/classes/overview-core.html 320 321$(eval $(call SetupApiDocsGeneration, JDK_API, \ 322 MODULES := $(JDK_JAVADOC_MODULES), \ 323 NAME := JDK, \ 324 TARGET_DIR := $(DOCS_OUTPUTDIR)/api, \ 325 OVERVIEW := $(JDK_JAVADOC_OVERVIEW), \ 326 DOC_TITLE := $(JDK_JAVADOC_DOC_TITLE), \ 327 WINDOW_TITLE := $(JAVADOC_WINDOW_TITLE), \ 328 HEADER_TITLE := $(JAVADOC_HEADER_TITLE), \ 329 BOTTOM_TEXT := $(JAVADOC_BOTTOM), \ 330 TOP_TEXT := $(JAVADOC_TOP), \ 331)) 332 333# Targets generated are returned in JDK_API_JAVADOC_TARGETS and 334# JDK_API_MODULEGRAPH_TARGETS. 335 336################################################################################ 337# Setup generation of the Java SE API documentation (javadoc + modulegraph) 338 339# The Java SE module scope is just java.se.ee and it's transitive modules. 340JAVASE_JAVADOC_MODULES := java.se.ee 341 342JAVASE_JAVADOC_OVERVIEW := $(JDK_TOPDIR)/src/java.base/share/classes/overview-core.html 343 344$(eval $(call SetupApiDocsGeneration, JAVASE_API, \ 345 MODULES := $(JAVASE_JAVADOC_MODULES), \ 346 NAME := Java SE, \ 347 TARGET_DIR := $(IMAGES_OUTPUTDIR)/javase-docs/api, \ 348 OVERVIEW := $(JAVASE_JAVADOC_OVERVIEW), \ 349 DOC_TITLE := $(JAVASE_JAVADOC_DOC_TITLE), \ 350 WINDOW_TITLE := $(JAVADOC_WINDOW_TITLE), \ 351 HEADER_TITLE := $(JAVADOC_HEADER_TITLE), \ 352 BOTTOM_TEXT := $(JAVADOC_BOTTOM), \ 353 TOP_TEXT := $(JAVADOC_TOP), \ 354)) 355 356# Targets generated are returned in JAVASE_API_JAVADOC_TARGETS and 357# JAVASE_API_MODULEGRAPH_TARGETS. 358 359################################################################################ 360# Copy JDK specs files 361 362# For all html documentation in $module/share/specs directories, copy it 363# unmodified 364 365ALL_MODULES := $(call FindAllModules) 366COPY_SPEC_FILTER := %.html %.gif %.jpg %.mib %.css 367 368$(foreach m, $(ALL_MODULES), \ 369 $(eval SPECS_$m := $(call FindModuleSpecsDirs, $m)) \ 370 $(foreach d, $(SPECS_$m), \ 371 $(if $(filter $(COPY_SPEC_FILTER), $(call CacheFind, $d)), \ 372 $(eval $(call SetupCopyFiles, COPY_$m, \ 373 SRC := $d, \ 374 FILES := $(filter $(COPY_SPEC_FILTER), $(call CacheFind, $d)), \ 375 DEST := $(DOCS_OUTPUTDIR)/specs/, \ 376 )) \ 377 $(eval JDK_SPECS_TARGETS += $(COPY_$m)) \ 378 ) \ 379 ) \ 380) 381 382# Copy the global resources 383GLOBAL_SPECS_RESOURCES_DIR := $(JDK_TOPDIR)/make/data/docs-resources/specs 384$(eval $(call SetupCopyFiles, COPY_GLOBAL_RESOURCES, \ 385 SRC := $(GLOBAL_SPECS_RESOURCES_DIR), \ 386 FILES := $(call CacheFind, $(GLOBAL_SPECS_RESOURCES_DIR)), \ 387 DEST := $(DOCS_OUTPUTDIR)/specs/, \ 388)) 389JDK_SPECS_TARGETS += $(COPY_GLOBAL_RESOURCES) 390 391ifeq ($(ENABLE_FULL_DOCS), true) 392 # For all markdown files in $module/share/specs directories, convert them to 393 # html. 394 395 GLOBAL_SPECS_DEFAULT_CSS_FILE := $(DOCS_OUTPUTDIR)/specs/resources/jdk-default.css 396 397 $(foreach m, $(ALL_MODULES), \ 398 $(eval SPECS_$m := $(call FindModuleSpecsDirs, $m)) \ 399 $(foreach d, $(SPECS_$m), \ 400 $(if $(filter %.md, $(call CacheFind, $d)), \ 401 $(eval $(call SetupProcessMarkdown, CONVERT_MARKDOWN_$m_$(patsubst $(TOPDIR)/%,%,$d), \ 402 SRC := $d, \ 403 FILES := $(filter %.md, $(call CacheFind, $d)), \ 404 DEST := $(DOCS_OUTPUTDIR)/specs/, \ 405 CSS := $(GLOBAL_SPECS_DEFAULT_CSS_FILE), \ 406 )) \ 407 ) \ 408 $(eval JDK_SPECS_TARGETS += $(CONVERT_MARKDOWN_$m_$(patsubst $(TOPDIR)/%,%,$d))) \ 409 ) \ 410 ) 411endif 412 413# Special treatment for generated documentation 414 415JDWP_PROTOCOL := $(SUPPORT_OUTPUTDIR)/gensrc/jdk.jdi/jdwp-protocol.html 416$(eval $(call SetupCopyFiles, COPY_JDWP_PROTOCOL, \ 417 FILES := $(JDWP_PROTOCOL), \ 418 DEST := $(DOCS_OUTPUTDIR)/specs/jdwp, \ 419)) 420JDK_SPECS_TARGETS += $(COPY_JDWP_PROTOCOL) 421 422# Get jvmti.html from the main jvm variant (all variants' jvmti.html are identical). 423JVMTI_HTML := $(HOTSPOT_OUTPUTDIR)/variant-$(JVM_VARIANT_MAIN)/gensrc/jvmtifiles/jvmti.html 424$(eval $(call SetupCopyFiles, COPY_JVMTI_HTML, \ 425 FILES := $(JVMTI_HTML), \ 426 DEST := $(DOCS_OUTPUTDIR)/specs, \ 427)) 428JDK_SPECS_TARGETS += $(COPY_JVMTI_HTML) 429 430################################################################################ 431# Optional target which bundles all generated javadocs into a zip archive. 432 433JAVADOC_ZIP_NAME := jdk-$(VERSION_STRING)-docs.zip 434JAVADOC_ZIP_FILE := $(OUTPUT_ROOT)/bundles/$(JAVADOC_ZIP_NAME) 435 436$(eval $(call SetupZipArchive, BUILD_JAVADOC_ZIP, \ 437 SRC := $(DOCS_OUTPUTDIR), \ 438 ZIP := $(JAVADOC_ZIP_FILE), \ 439 EXTRA_DEPS := $(JDK_API_JAVADOC_TARGETS) $(JDK_API_MODULEGRAPH_TARGETS) \ 440 $(JDK_SPECS_TARGETS), \ 441)) 442 443ZIP_TARGETS += $(BUILD_JAVADOC_ZIP) 444 445################################################################################ 446 447docs-jdk-api-javadoc: $(JDK_API_JAVADOC_TARGETS) $(JDK_API_CUSTOM_TARGETS) 448 449docs-jdk-api-modulegraph: $(JDK_API_MODULEGRAPH_TARGETS) 450 451docs-javase-api-javadoc: $(JAVASE_API_JAVADOC_TARGETS) $(JAVASE_API_CUSTOM_TARGETS) 452 453docs-javase-api-modulegraph: $(JAVASE_API_MODULEGRAPH_TARGETS) 454 455docs-jdk-specs: $(JDK_SPECS_TARGETS) 456 457docs-zip: $(ZIP_TARGETS) 458 459all: docs-jdk-api-javadoc docs-jdk-api-modulegraph docs-javase-api-javadoc \ 460 docs-javase-api-modulegraph docs-jdk-specs docs-zip 461 462.PHONY: default all docs-jdk-api-javadoc docs-jdk-api-modulegraph \ 463 docs-javase-api-javadoc docs-javase-api-modulegraph docs-jdk-specs docs-zip 464