1 # Copyright (c) 1997, 2019, 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 
  25 default: all
  26 
  27 include $(SPEC)
  28 include MakeBase.gmk
  29 include Execute.gmk
  30 include Modules.gmk
  31 include ModuleTools.gmk
  32 include ProcessMarkdown.gmk
  33 include ToolsJdk.gmk
  34 include ZipArchive.gmk
  35 include TextFileProcessing.gmk
  36 
  37 # This is needed to properly setup DOCS_MODULES.
  38 $(eval $(call ReadImportMetaData))
  39 
  40 ################################################################################
  41 # Hook to include the corresponding custom file, if present.
  42 $(eval $(call IncludeCustomExtension, Docs.gmk))
  43 
  44 ################################################################################
  45 # This file generates all documentation for OpenJDK.
  46 #
  47 # We will generate API documentation for two different selections of the source
  48 # code: "Java SE", which contains just the modules covered by the top-level
  49 # module java.se and "JDK", which covers all of Java SE and also all
  50 # other available modules that should be documented, including imported modules,
  51 # if any.
  52 #
  53 # We will also generate separate, free-standing specifications from either
  54 # markdown or existing html files.
  55 #
  56 
  57 ################################################################################
  58 # Javadoc settings
  59 
  60 # On top of the sources that was used to compile the JDK, we need some
  61 # extra java.rmi sources that are used just for javadoc.
  62 MODULES_SOURCE_PATH := $(call PathList, $(call GetModuleSrcPath) \
  63     $(SUPPORT_OUTPUTDIR)/rmic/* $(TOPDIR)/src/*/share/doc/stub)
  64 
  65 # URLs
  66 JAVADOC_BASE_URL := https://docs.oracle.com/pls/topic/lookup?ctx=javase$(VERSION_NUMBER)&id=homepage
  67 BUG_SUBMIT_URL := https://bugreport.java.com/bugreport/
  68 COPYRIGHT_URL := legal/copyright.html
  69 LICENSE_URL := https://www.oracle.com/technetwork/java/javase/terms/license/java$(VERSION_NUMBER)speclicense.html
  70 REDISTRIBUTION_URL := https://www.oracle.com/technetwork/java/redist-137594.html
  71 
  72 # In order to get a specific ordering it's necessary to specify the total
  73 # ordering of tags as the tags are otherwise ordered in order of definition.
  74 JAVADOC_TAGS := \
  75     -tag beaninfo:X \
  76     -tag revised:X \
  77     -tag since.unbundled:X \
  78     -tag spec:X \
  79     -tag specdefault:X \
  80     -tag Note:X \
  81     -tag ToDo:X \
  82     -tag 'apiNote:a:API Note:' \
  83     -tag 'implSpec:a:Implementation Requirements:' \
  84     -tag 'implNote:a:Implementation Note:' \
  85     -tag param \
  86     -tag return \
  87     -tag throws \
  88     -taglet build.tools.taglet.JSpec\$$JLS \
  89     -taglet build.tools.taglet.JSpec\$$JVMS \
  90     -taglet build.tools.taglet.ModuleGraph \
  91     -taglet build.tools.taglet.ToolGuide \
  92     -tag since \
  93     -tag serialData \
  94     -tag factory \
  95     -tag see \
  96     -taglet build.tools.taglet.ExtLink \
  97     -taglet build.tools.taglet.Incubating \
  98     -tagletpath $(BUILDTOOLS_OUTPUTDIR)/jdk_tools_classes \
  99     $(CUSTOM_JAVADOC_TAGS) \
 100     #
 101 
 102 # The reference tags must stay stable to allow for comparisons across the
 103 # development cycle. If JAVADOC_TAGS needs to change, make sure that
 104 # REFERENCE_TAGS remains unchanged, by copying and hardcoding, if necessary.
 105 REFERENCE_TAGS := $(JAVADOC_TAGS)
 106 
 107 # Which doclint checks to ignore
 108 JAVADOC_DISABLED_DOCLINT := accessibility html missing syntax reference
 109 
 110 # The initial set of options for javadoc
 111 JAVADOC_OPTIONS := -use -keywords -notimestamp \
 112     -serialwarn -encoding ISO-8859-1 -docencoding UTF-8 -breakiterator \
 113     -splitIndex --system none -javafx --expand-requires transitive \
 114     --override-methods=summary
 115 
 116 # The reference options must stay stable to allow for comparisons across the
 117 # development cycle.
 118 REFERENCE_OPTIONS := -XDignore.symbol.file=true -use -keywords -notimestamp \
 119     -serialwarn -encoding ISO-8859-1 -breakiterator -splitIndex --system none \
 120     -html5 -javafx --expand-requires transitive
 121 
 122 # Should we add DRAFT stamps to the generated javadoc?
 123 ifeq ($(VERSION_IS_GA), true)
 124   IS_DRAFT := false
 125 else
 126   IS_DRAFT := true
 127 endif
 128 
 129 ################################################################################
 130 # General text snippets
 131 
 132 FULL_COMPANY_NAME := Oracle and/or its affiliates
 133 COMPANY_ADDRESS := 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 134 
 135 JAVA_PLATFORM := Java Platform
 136 
 137 ifeq ($(IS_DRAFT), true)
 138   DRAFT_MARKER_STR := <br><strong>DRAFT $(VERSION_STRING)</strong>
 139   ifeq ($(VERSION_BUILD), 0)
 140     DRAFT_MARKER_TITLE := [ad-hoc build]
 141   else
 142     DRAFT_MARKER_TITLE := [build $(VERSION_BUILD)]
 143   endif
 144   DRAFT_TEXT := This specification is not final and is subject to change. \
 145       Use is subject to <a href="$(LICENSE_URL)">license terms</a>.
 146 
 147   # Workaround stylesheet bug
 148   HEADER_STYLE := style="margin-top: 9px;"
 149 else
 150   HEADER_STYLE := style="margin-top: 14px;"
 151 endif
 152 
 153 # $1 - Relative prefix to COPYRIGHT_URL
 154 COPYRIGHT_BOTTOM = \
 155     <a href="$(strip $1)$(COPYRIGHT_URL)">Copyright</a> \
 156     &copy; 1993, $(COPYRIGHT_YEAR), $(FULL_COMPANY_NAME), \
 157     $(COMPANY_ADDRESS).<br>All rights reserved. \
 158     Use is subject to <a href="$(LICENSE_URL)">license terms</a> and the \
 159     <a href="$(REDISTRIBUTION_URL)">documentation redistribution policy</a>. \
 160     $(DRAFT_MARKER_STR) <!-- Version $(VERSION_STRING) -->
 161 
 162 JAVADOC_BOTTOM := \
 163     <a href="$(BUG_SUBMIT_URL)">Report a bug or suggest an enhancement</a><br> \
 164     For further API reference and developer documentation see the \
 165     <a href="$(JAVADOC_BASE_URL)" target="_blank">Java SE \
 166     Documentation</a>, which contains more detailed, \
 167     developer-targeted descriptions with conceptual overviews, definitions \
 168     of terms, workarounds, and working code examples.<br> \
 169     Java is a trademark or registered trademark of $(FULL_COMPANY_NAME) in \
 170     the US and other countries.<br> \
 171     $(call COPYRIGHT_BOTTOM, {@docroot}/../)
 172 
 173 JAVADOC_TOP := \
 174     <div style="padding: 6px; text-align: center; font-size: 80%; \
 175     font-family: DejaVu Sans, Arial, Helvetica, sans-serif; \
 176     font-weight: normal;">$(DRAFT_TEXT)</div>
 177 
 178 ################################################################################
 179 # JDK javadoc titles/text snippets
 180 
 181 JDK_SHORT_NAME := Java SE $(VERSION_SPECIFICATION) &amp; JDK $(VERSION_SPECIFICATION)
 182 JDK_LONG_NAME := Java<sup>&reg;</sup> Platform, Standard Edition \
 183     &amp;&nbsp;Java&nbsp;Development&nbsp;Kit
 184 
 185 ################################################################################
 186 # Java SE javadoc titles/text snippets
 187 
 188 JAVASE_SHORT_NAME := Java SE $(VERSION_SPECIFICATION)
 189 JAVASE_LONG_NAME := Java<sup>&reg;</sup> Platform, Standard Edition
 190 
 191 ################################################################################
 192 # Functions
 193 
 194 # Helper function for creating a png file from a dot file generated by the
 195 # GenGraphs tool.
 196 # param 1: SetupJavadocGeneration namespace ($1)
 197 # param 2: module name
 198 #
 199 define setup_gengraph_dot_to_png
 200   $1_$2_DOT_SRC :=  $$($1_GENGRAPHS_DIR)/$2.dot
 201   $1_$2_PNG_TARGET := $$($1_TARGET_DIR)/$2/module-graph.png
 202 
 203     # For each module needing a graph, create a png file from the dot file
 204     # generated by the GenGraphs tool and store it in the target dir.
 205     $$(eval $$(call SetupExecute, gengraphs_png_$1_$2, \
 206         INFO := Running dot for module graphs for $2, \
 207         DEPS := $$(gengraphs_$1_TARGET), \
 208         OUTPUT_FILE := $$($1_$2_PNG_TARGET), \
 209         SUPPORT_DIR := $$($1_GENGRAPHS_DIR), \
 210         COMMAND := $$(DOT) -Tpng -o $$($1_$2_PNG_TARGET) $$($1_$2_DOT_SRC), \
 211     ))
 212 
 213   $1_MODULEGRAPH_TARGETS += $$($1_$2_PNG_TARGET)
 214 endef
 215 
 216 # Helper function to create the overview.html file to use with the -overview
 217 # javadoc option.
 218 # Returns the filename as $1_OVERVIEW.
 219 #
 220 # param 1: SetupJavadocGeneration namespace ($1)
 221 define create_overview_file
 222   $1_OVERVIEW_TEXT := \
 223       <!DOCTYPE html> \
 224       <html><head></head><body> \
 225       #
 226   ifneq ($$($1_GROUPS),)
 227     $1_OVERVIEW_TEXT += \
 228       <p>This document is divided into \
 229       $$(subst 2,two,$$(subst 3,three,$$(words $$($1_GROUPS)))) sections:</p> \
 230       <blockquote><dl> \
 231       #
 232     $1_OVERVIEW_TEXT += $$(foreach g, $$($1_GROUPS), \
 233         <dt style="margin-top: 8px;">$$($$g_GROUP_NAME)</dt> \
 234         <dd style="margin-top: 8px;">$$($$g_GROUP_DESCRIPTION)</dd> \
 235     )
 236     $1_OVERVIEW_TEXT += \
 237         </dl></blockquote> \
 238         #
 239   endif
 240   $1_OVERVIEW_TEXT += \
 241       </body></html> \
 242       #
 243 
 244   $1_OVERVIEW := $$(SUPPORT_OUTPUTDIR)/docs/$1-overview.html
 245 
 246   $1_OVERVIEW_VARDEPS_FILE := $$(call DependOnVariable, $1_OVERVIEW_TEXT, \
 247       $$($1_OVERVIEW).vardeps)
 248 
 249   $$($1_OVERVIEW): $$($1_OVERVIEW_VARDEPS_FILE)
 250         $$(call LogInfo, Creating overview.html for $1)
 251         $$(call MakeDir, $$(@D))
 252         $$(PRINTF) > $$@ '$$($1_OVERVIEW_TEXT)'
 253 endef
 254 
 255 ################################################################################
 256 # Setup make rules to create an API documentation collection, using javadoc and
 257 # other tools if needed.
 258 #
 259 # Parameter 1 is the name of the rule. This name is used as variable prefix.
 260 # Targets generated are returned as $1_JAVADOC_TARGETS and
 261 # $1_MODULEGRAPH_TARGETS. Note that the index.html file will work as a "touch
 262 # file" for all the magnitude of files that are generated by javadoc.
 263 #
 264 # Remaining parameters are named arguments. These include:
 265 #   MODULES - Modules to generate javadoc for
 266 #   GROUPS - Name of the groups to divide the modules into, if any
 267 #   SHORT_NAME - The short name of this documentation collection
 268 #   LONG_NAME - The long name of this documentation collection
 269 #   TARGET_DIR - Where to store the output
 270 #
 271 SetupApiDocsGeneration = $(NamedParamsMacroTemplate)
 272 define SetupApiDocsGenerationBody
 273 
 274   # Figure out all modules, both specified and transitive indirect exports, that
 275   # will be processed by javadoc.
 276   $1_INDIRECT_EXPORTS := $$(call FindTransitiveIndirectDepsForModules, $$($1_MODULES))
 277   $1_ALL_MODULES := $$(sort $$($1_MODULES) $$($1_INDIRECT_EXPORTS))
 278 
 279   $1_JAVA_ARGS := -Dextlink.spec.version=$$(VERSION_SPECIFICATION) \
 280         -Djspec.version=$$(VERSION_SPECIFICATION)
 281 
 282   ifeq ($$(ENABLE_FULL_DOCS), true)
 283     # Tell the ModuleGraph taglet to generate html links to soon-to-be-created
 284     # png files with module graphs.
 285     $1_JAVA_ARGS += -DenableModuleGraph=true
 286   endif
 287 
 288   # Start with basic options and tags
 289   ifeq ($$($1_OPTIONS), )
 290     $1_OPTIONS := $$(JAVADOC_OPTIONS)
 291   endif
 292   ifeq ($$($1_TAGS), )
 293     $1_TAGS := $$(JAVADOC_TAGS)
 294   endif
 295   $1_OPTIONS += $$($1_TAGS)
 296 
 297   $1_OPTIONS += --module-source-path $$(MODULES_SOURCE_PATH)
 298   $1_OPTIONS += --module $$(call CommaList, $$($1_MODULES))
 299 
 300   # Create a string like "-Xdoclint:all,-syntax,-html,..."
 301   $1_OPTIONS += -Xdoclint:all,$$(call CommaList, $$(addprefix -, \
 302       $$(JAVADOC_DISABLED_DOCLINT)))
 303 
 304   $1_DOC_TITLE := $$($1_LONG_NAME)<br>Version $$(VERSION_SPECIFICATION) API \
 305       Specification
 306   $1_WINDOW_TITLE := $$(subst &amp;,&,$$($1_SHORT_NAME)) $$(DRAFT_MARKER_TITLE)
 307   $1_HEADER_TITLE := <div $$(HEADER_STYLE)><strong>$$($1_SHORT_NAME)</strong> \
 308       $$(DRAFT_MARKER_STR)</div>
 309 
 310   $1_OPTIONS += -doctitle '$$($1_DOC_TITLE)'
 311   $1_OPTIONS += -windowtitle '$$($1_WINDOW_TITLE)'
 312   $1_OPTIONS += -header '$$($1_HEADER_TITLE)'
 313   $1_OPTIONS += -bottom '$$(JAVADOC_BOTTOM)'
 314   ifeq ($$(IS_DRAFT), true)
 315     $1_OPTIONS += -top '$$(JAVADOC_TOP)'
 316   endif
 317 
 318   # Do not store debug level options in VARDEPS.
 319   ifneq ($$(LOG_LEVEL), trace)
 320     $1_LOG_OPTION += -quiet
 321   else
 322     $1_LOG_OPTION += -verbose
 323   endif
 324 
 325   # Generate the overview.html file. This will return the filename in
 326   # $1_OVERVIEW.
 327   $$(eval $$(call create_overview_file,$1))
 328   $1_OPTIONS += -overview $$($1_OVERVIEW)
 329 
 330   $$(foreach g, $$($1_GROUPS), \
 331     $$(eval $1_OPTIONS += -group "$$($$g_GROUP_NAME)" "$$($$g_GROUP_MODULES)") \
 332   )
 333 
 334   ifeq ($$($1_JAVADOC_CMD), )
 335     $1_JAVADOC_CMD := $$(JAVA) -Djava.awt.headless=true $$($1_JAVA_ARGS) \
 336         $$(NEW_JAVADOC)
 337   else
 338     $1_OPTIONS += $$(addprefix -J, $$($1_JAVA_ARGS))
 339   endif
 340 
 341   $1_VARDEPS := $$($1_JAVA_ARGS) $$($1_OPTIONS) $$(MODULES_SOURCE_PATH) \
 342       $$($1_ALL_MODULES) $$($1_JAVADOC_CMD)
 343   $1_VARDEPS_FILE := $$(call DependOnVariable, $1_VARDEPS, \
 344       $$(SUPPORT_OUTPUTDIR)/docs/$1.vardeps)
 345 
 346   # Get a list of all files in all the source dirs for all included modules
 347   $1_SOURCE_DEPS := $$(call FindFiles, $$(wildcard $$(foreach module, \
 348       $$($1_ALL_MODULES), $$(call FindModuleSrcDirs, $$(module)))))
 349 
 350   $$(eval $$(call SetupExecute, javadoc_$1, \
 351       WARN := Generating $1 javadoc for $$(words $$($1_ALL_MODULES)) modules, \
 352       INFO := Javadoc modules: $$($1_ALL_MODULES), \
 353       DEPS := $$(BUILD_TOOLS_JDK) $$($1_VARDEPS_FILE) $$($1_SOURCE_DEPS) \
 354           $$($1_OVERVIEW), \
 355       OUTPUT_DIR := $$($1_TARGET_DIR), \
 356       SUPPORT_DIR := $$(SUPPORT_OUTPUTDIR)/docs, \
 357       COMMAND := $$($1_JAVADOC_CMD) -d $$($1_TARGET_DIR) $$($1_OPTIONS) \
 358           $$($1_LOG_OPTION), \
 359   ))
 360 
 361   $1_JAVADOC_TARGETS := $$(javadoc_$1_TARGET)
 362 
 363   ifeq ($$(ENABLE_FULL_DOCS), true)
 364     # We have asked ModuleGraph to generate links to png files. Now we must
 365     # produce the png files.
 366 
 367     # Locate which modules has the @moduleGraph tag in their module-info.java
 368     $1_MODULES_NEEDING_GRAPH := $$(strip $$(foreach m, $$($1_ALL_MODULES), \
 369       $$(if $$(shell $$(GREP) -e @moduleGraph \
 370           $$(wildcard $$(addsuffix /module-info.java, \
 371           $$(call FindModuleSrcDirs, $$m)))), \
 372         $$m) \
 373     ))
 374 
 375     # First we run the GenGraph tool. It will query the module structure of the
 376     # running JVM and output .dot files for all existing modules.
 377     GENGRAPHS_PROPS := \
 378         $$(TOPDIR)/make/jdk/src/classes/build/tools/jigsaw/javadoc-graphs.properties
 379 
 380     $1_GENGRAPHS_DIR := $$(SUPPORT_OUTPUTDIR)/docs/$1-gengraphs
 381 
 382     $$(eval $$(call SetupExecute, gengraphs_$1, \
 383         INFO := Running gengraphs for $1 documentation, \
 384         DEPS := $$(BUILD_JIGSAW_TOOLS) $$(GENGRAPHS_PROPS), \
 385         OUTPUT_DIR := $$($1_GENGRAPHS_DIR), \
 386         COMMAND := $$(TOOL_GENGRAPHS) --spec --output $$($1_GENGRAPHS_DIR) \
 387             --dot-attributes $$(GENGRAPHS_PROPS), \
 388     ))
 389 
 390     # For each module needing a graph, create a png file from the dot file
 391     # generated by the GenGraphs tool and store it in the target dir.
 392     # They will depend on gengraphs_$1_TARGET, and will be added to $1.
 393     $$(foreach m, $$($1_MODULES_NEEDING_GRAPH), \
 394       $$(eval $$(call setup_gengraph_dot_to_png,$1,$$m)) \
 395     )
 396   endif
 397 endef
 398 
 399 ################################################################################
 400 # Setup generation of the JDK API documentation (javadoc + modulegraph)
 401 
 402 # Define the groups of the JDK API documentation
 403 JavaSE_GROUP_NAME := Java SE
 404 JavaSE_GROUP_MODULES := $(call ColonList, $(sort java.se \
 405     $(call FindTransitiveIndirectDepsForModules, java.se)))
 406 JavaSE_GROUP_DESCRIPTION := \
 407     The Java Platform, Standard Edition (Java SE) APIs define the core Java \
 408     platform for general-purpose computing. These APIs are in modules whose \
 409     names start with {@code java}. \
 410     #
 411 JDK_GROUPS += JavaSE
 412 
 413 JDK_GROUP_NAME := JDK
 414 JDK_GROUP_MODULES := jdk.*
 415 JDK_GROUP_DESCRIPTION := \
 416     The Java Development Kit (JDK) APIs are specific to the JDK and will not \
 417     necessarily be available in all implementations of the Java SE Platform. \
 418     These APIs are in modules whose names start with {@code jdk}. \
 419     #
 420 JDK_GROUPS += JDK
 421 
 422 # If we are importing JavaFX, we need a JavaFX group. In an ideal world, this
 423 # would have been abstracted away to a more proper generic handling of imported
 424 # modules.
 425 ifneq ($(findstring javafx., $(IMPORTED_MODULES)), )
 426   JavaFX_GROUP_NAME := JavaFX
 427   JavaFX_GROUP_MODULES := javafx.*
 428   JavaFX_GROUP_DESCRIPTION := \
 429       The JavaFX APIs define a set of user-interface controls, graphics, \
 430       media, and web packages for developing rich client applications. These \
 431       APIs are in modules whose names start with {@code javafx}. \
 432       #
 433   JDK_GROUPS += JavaFX
 434 endif
 435 
 436 # All modules to have docs generated by docs-jdk-api target
 437 JDK_MODULES := $(sort $(filter-out $(MODULES_FILTER), $(DOCS_MODULES)))
 438 
 439 $(eval $(call SetupApiDocsGeneration, JDK_API, \
 440     MODULES := $(JDK_MODULES), \
 441     GROUPS := $(JDK_GROUPS), \
 442     SHORT_NAME := $(JDK_SHORT_NAME), \
 443     LONG_NAME := $(JDK_LONG_NAME), \
 444     TARGET_DIR := $(DOCS_OUTPUTDIR)/api, \
 445 ))
 446 
 447 # Targets generated are returned in JDK_API_JAVADOC_TARGETS and
 448 # JDK_API_MODULEGRAPH_TARGETS.
 449 
 450 ################################################################################
 451 # Setup generation of the Java SE API documentation (javadoc + modulegraph)
 452 
 453 # The Java SE module scope is just java.se and its transitive indirect
 454 # exports.
 455 JAVASE_MODULES := java.se
 456 
 457 $(eval $(call SetupApiDocsGeneration, JAVASE_API, \
 458     MODULES := $(JAVASE_MODULES), \
 459     SHORT_NAME := $(JAVASE_SHORT_NAME), \
 460     LONG_NAME := $(JAVASE_LONG_NAME), \
 461     TARGET_DIR := $(IMAGES_OUTPUTDIR)/javase-docs/api, \
 462 ))
 463 
 464 # Targets generated are returned in JAVASE_API_JAVADOC_TARGETS and
 465 # JAVASE_API_MODULEGRAPH_TARGETS.
 466 
 467 ################################################################################
 468 # Setup generation of the reference Java SE API documentation (javadoc + modulegraph)
 469 
 470 # The reference javadoc is just the same as javase, but using the BootJDK javadoc
 471 # and a stable set of javadoc options.  Typically it is used for generating
 472 # diffs between the reference javadoc and a javadoc bundle of a specific build
 473 # generated in the same way.
 474 
 475 $(eval $(call SetupApiDocsGeneration, REFERENCE_API, \
 476     MODULES := $(JAVASE_MODULES), \
 477     SHORT_NAME := $(JAVASE_SHORT_NAME), \
 478     LONG_NAME := $(JAVASE_LONG_NAME), \
 479     TARGET_DIR := $(IMAGES_OUTPUTDIR)/reference-docs/api, \
 480     JAVADOC_CMD := $(JAVADOC), \
 481     OPTIONS := $(REFERENCE_OPTIONS), \
 482     TAGS := $(REFERENCE_TAGS), \
 483 ))
 484 
 485 # Targets generated are returned in REFERENCE_API_JAVADOC_TARGETS and
 486 # REFERENCE_API_MODULEGRAPH_TARGETS.
 487 
 488 ################################################################################
 489 
 490 # Copy the global resources, including the top-level redirect index.html
 491 GLOBAL_SPECS_RESOURCES_DIR := $(TOPDIR)/make/data/docs-resources/
 492 $(eval $(call SetupCopyFiles, COPY_GLOBAL_RESOURCES, \
 493     SRC := $(GLOBAL_SPECS_RESOURCES_DIR), \
 494     FILES := $(call FindFiles, $(GLOBAL_SPECS_RESOURCES_DIR)), \
 495     DEST := $(DOCS_OUTPUTDIR), \
 496 ))
 497 JDK_INDEX_TARGETS += $(COPY_GLOBAL_RESOURCES)
 498 
 499 # Copy the legal notices distributed with the docs bundle
 500 $(eval $(call SetupCopyFiles, COPY_DOCS_LEGAL_NOTICES, \
 501     SRC := $(TOPDIR)/src/jdk.javadoc/share/legal, \
 502     FILES := $(wildcard $(TOPDIR)/src/jdk.javadoc/share/legal/*), \
 503     DEST := $(DOCS_OUTPUTDIR)/legal, \
 504 ))
 505 JDK_INDEX_TARGETS += $(COPY_DOCS_LEGAL_NOTICES)
 506 
 507 ################################################################################
 508 # Copy JDK specs files
 509 
 510 # For all non html/md files in $module/share/specs directories, copy them
 511 # unmodified
 512 
 513 ALL_MODULES := $(call FindAllModules)
 514 COPY_SPEC_FILTER := %.gif %.jpg %.mib %.css
 515 
 516 $(foreach m, $(ALL_MODULES), \
 517   $(eval SPECS_$m := $(call FindModuleSpecsDirs, $m)) \
 518   $(foreach d, $(SPECS_$m), \
 519     $(if $(filter $(COPY_SPEC_FILTER), $(call FindFiles, $d)), \
 520       $(eval $(call SetupCopyFiles, COPY_$m, \
 521           SRC := $d, \
 522           FILES := $(filter $(COPY_SPEC_FILTER), $(call FindFiles, $d)), \
 523           DEST := $(DOCS_OUTPUTDIR)/specs/, \
 524       )) \
 525       $(eval JDK_SPECS_TARGETS += $(COPY_$m)) \
 526     ) \
 527   ) \
 528 )
 529 
 530 # Create copyright footer files that can be provided as input to pandoc. We
 531 # need different files for different relative paths to the copyright.html
 532 # file. The number 0-2 below represent how many extra directory levels down
 533 # below the specs dir the specs html file is located. Each file name is
 534 # stored in a variable SPECS_BOTTOM_FILE_$n where $n is 0, 1 or 2.
 535 SPECS_BOTTOM = <hr/>$(COPYRIGHT_BOTTOM)
 536 # The legal dir is one ../ below the specs dir, so start with one ../.
 537 specs_bottom_rel_path := ../
 538 $(foreach n, 0 1 2, \
 539   $(eval SPECS_BOTTOM_FILE_$n := $(SUPPORT_OUTPUTDIR)/docs/full-specs-bottom-$n.txt) \
 540   $(eval SPECS_BOTTOM_$n := $(call SPECS_BOTTOM,$(specs_bottom_rel_path))) \
 541   $(eval $(SPECS_BOTTOM_FILE_$n): \
 542       $(call DependOnVariable, SPECS_BOTTOM_$n) ; \
 543       $(PRINTF) '$(SPECS_BOTTOM_$n)' > $$@ \
 544   ) \
 545   $(eval specs_bottom_rel_path := $(specs_bottom_rel_path)../) \
 546 )
 547 
 548 # For all html files in $module/share/specs directories, copy and add the
 549 # copyright footer.
 550 
 551 $(foreach m, $(ALL_MODULES), \
 552   $(eval SPECS_$m := $(call FindModuleSpecsDirs, $m)) \
 553   $(foreach d, $(SPECS_$m), \
 554     $(foreach f, $(filter %.html, $(call FindFiles, $d)), \
 555       $(eval $m_$f_NOF_SUBDIRS := $(words $(subst /, $(SPACE), $(subst $d, , $(dir $f))))) \
 556       $(eval $m_$f_NAME := PROCESS_HTML_$m_$(strip $(call RelativePath, $f, $(TOPDIR)))) \
 557       $(eval $(call SetupTextFileProcessing, $($m_$f_NAME), \
 558           SOURCE_FILES := $f, \
 559           SOURCE_BASE_DIR := $d, \
 560           OUTPUT_DIR := $(DOCS_OUTPUTDIR)/specs/, \
 561           REPLACEMENTS := \
 562               </body> => $(SPECS_BOTTOM_$($m_$f_NOF_SUBDIRS))</body>, \
 563       )) \
 564       $(eval JDK_SPECS_TARGETS += $($($m_$f_NAME))) \
 565     ) \
 566   ) \
 567 )
 568 
 569 ifeq ($(ENABLE_PANDOC), true)
 570   # For all markdown files in $module/share/specs directories, convert them to
 571   # html, if we have pandoc (otherwise we'll just skip this).
 572 
 573   GLOBAL_SPECS_DEFAULT_CSS_FILE := $(DOCS_OUTPUTDIR)/resources/jdk-default.css
 574 
 575   $(foreach m, $(ALL_MODULES), \
 576     $(eval SPECS_$m := $(call FindModuleSpecsDirs, $m)) \
 577     $(foreach d, $(SPECS_$m), \
 578       $(foreach f, $(filter %.md, $(call FindFiles, $d)), \
 579         $(eval $m_$f_NOF_SUBDIRS := $(words $(subst /, $(SPACE), $(subst $d, , $(dir $f))))) \
 580         $(eval $m_$f_BOTTOM_FILE := $(SPECS_BOTTOM_FILE_$($m_$f_NOF_SUBDIRS))) \
 581         $(eval $m_$f_NAME := SPECS_TO_HTML_$m_$(strip $(call RelativePath, $f, $(TOPDIR)))) \
 582         $(eval $(call SetupProcessMarkdown, $($m_$f_NAME), \
 583             SRC := $d, \
 584             FILES := $f, \
 585             DEST := $(DOCS_OUTPUTDIR)/specs/, \
 586             CSS := $(GLOBAL_SPECS_DEFAULT_CSS_FILE), \
 587             OPTIONS := -A $($m_$f_BOTTOM_FILE), \
 588             EXTRA_DEPS := $($m_$f_BOTTOM_FILE), \
 589             POST_PROCESS := $(TOOL_FIXUPPANDOC), \
 590         )) \
 591         $(eval JDK_SPECS_TARGETS += $($($m_$f_NAME))) \
 592       ) \
 593     ) \
 594   )
 595 
 596   # For all markdown files in $module/share/man directories, convert them to
 597   # html.
 598 
 599   # Create dynamic man pages from markdown using pandoc. We need
 600   # PANDOC_HTML_MANPAGE_FILTER, a wrapper around
 601   # PANDOC_HTML_MANPAGE_FILTER_JAVASCRIPT. This is created by buildtools-jdk.
 602 
 603   # We should also depend on the source javascript filter
 604   PANDOC_HTML_MANPAGE_FILTER_JAVASCRIPT := \
 605       $(TOPDIR)/make/scripts/pandoc-html-manpage-filter.js
 606 
 607   $(foreach m, $(ALL_MODULES), \
 608     $(eval MAN_$m := $(call FindModuleManDirs, $m)) \
 609     $(foreach d, $(MAN_$m), \
 610       $(foreach f, $(filter %.md, $(call FindFiles, $d)), \
 611         $(eval $m_$f_NAME := MAN_TO_HTML_$m_$(strip $(call RelativePath, $f, $(TOPDIR)))) \
 612         $(eval $(call SetupProcessMarkdown, $($m_$f_NAME), \
 613             SRC := $d, \
 614             FILES := $f, \
 615             DEST := $(DOCS_OUTPUTDIR)/specs/man, \
 616             FILTER := $(PANDOC_HTML_MANPAGE_FILTER), \
 617             CSS := $(GLOBAL_SPECS_DEFAULT_CSS_FILE), \
 618             REPLACEMENTS := @@VERSION_SHORT@@ => $(VERSION_SHORT), \
 619             OPTIONS := -A $(SPECS_BOTTOM_FILE_1), \
 620             POST_PROCESS := $(TOOL_FIXUPPANDOC), \
 621             EXTRA_DEPS := $(PANDOC_HTML_MANPAGE_FILTER) \
 622                 $(PANDOC_HTML_MANPAGE_FILTER_JAVASCRIPT) \
 623                 $(SPECS_BOTTOM_FILE_1), \
 624         )) \
 625         $(eval JDK_SPECS_TARGETS += $($($m_$f_NAME))) \
 626       ) \
 627     ) \
 628   )
 629 
 630   # The html generated from markdown also needs the css file
 631   JDK_SPECS_TARGETS += $(COPY_GLOBAL_RESOURCES)
 632 endif
 633 
 634 # Special treatment for generated documentation
 635 
 636 JDWP_PROTOCOL := $(SUPPORT_OUTPUTDIR)/gensrc/jdk.jdi/jdwp-protocol.html
 637 $(eval $(call SetupTextFileProcessing, PROCESS_JDWP_PROTOCOL, \
 638     SOURCE_FILES := $(JDWP_PROTOCOL), \
 639     OUTPUT_DIR := $(DOCS_OUTPUTDIR)/specs/jdwp, \
 640     REPLACEMENTS := \
 641         </body> => $(SPECS_BOTTOM_1)</body>, \
 642 ))
 643 JDK_SPECS_TARGETS += $(PROCESS_JDWP_PROTOCOL)
 644 
 645 # Get jvmti.html from the main jvm variant (all variants' jvmti.html are identical).
 646 JVMTI_HTML ?= $(HOTSPOT_OUTPUTDIR)/variant-$(JVM_VARIANT_MAIN)/gensrc/jvmtifiles/jvmti.html
 647 $(eval $(call SetupTextFileProcessing, PROCESS_JVMTI_HTML, \
 648     SOURCE_FILES := $(JVMTI_HTML), \
 649     OUTPUT_DIR := $(DOCS_OUTPUTDIR)/specs/, \
 650     REPLACEMENTS := \
 651         </body> => $(SPECS_BOTTOM_0)</body>, \
 652 ))
 653 JDK_SPECS_TARGETS += $(PROCESS_JVMTI_HTML)
 654 
 655 ################################################################################
 656 # Optional target which bundles all generated javadocs into a zip archive.
 657 
 658 JAVADOC_ZIP_NAME := jdk-$(VERSION_STRING)-docs.zip
 659 JAVADOC_ZIP_FILE := $(OUTPUTDIR)/bundles/$(JAVADOC_ZIP_NAME)
 660 
 661 $(eval $(call SetupZipArchive, BUILD_JAVADOC_ZIP, \
 662     SRC := $(DOCS_OUTPUTDIR), \
 663     ZIP := $(JAVADOC_ZIP_FILE), \
 664     EXTRA_DEPS := $(JDK_API_JAVADOC_TARGETS) $(JDK_API_MODULEGRAPH_TARGETS) \
 665         $(JDK_SPECS_TARGETS), \
 666 ))
 667 
 668 ZIP_TARGETS += $(BUILD_JAVADOC_ZIP)
 669 
 670 ################################################################################
 671 # Hook to include the corresponding custom file, if present.
 672 $(eval $(call IncludeCustomExtension, Docs-post.gmk))
 673 
 674 ################################################################################
 675 
 676 docs-jdk-api-javadoc: $(JDK_API_JAVADOC_TARGETS) $(JDK_API_CUSTOM_TARGETS)
 677 
 678 docs-jdk-api-modulegraph: $(JDK_API_MODULEGRAPH_TARGETS)
 679 
 680 docs-javase-api-javadoc: $(JAVASE_API_JAVADOC_TARGETS) $(JAVASE_API_CUSTOM_TARGETS)
 681 
 682 docs-javase-api-modulegraph: $(JAVASE_API_MODULEGRAPH_TARGETS)
 683 
 684 docs-reference-api-javadoc: $(REFERENCE_API_JAVADOC_TARGETS) $(REFERENCE_API_CUSTOM_TARGETS)
 685 
 686 docs-reference-api-modulegraph: $(REFERENCE_API_MODULEGRAPH_TARGETS)
 687 
 688 docs-jdk-specs: $(JDK_SPECS_TARGETS)
 689 
 690 docs-jdk-index: $(JDK_INDEX_TARGETS)
 691 
 692 docs-zip: $(ZIP_TARGETS)
 693 
 694 all: docs-jdk-api-javadoc docs-jdk-api-modulegraph docs-javase-api-javadoc \
 695     docs-javase-api-modulegraph docs-reference-api-javadoc \
 696     docs-reference-api-modulegraph docs-jdk-specs docs-jdk-index docs-zip
 697 
 698 .PHONY: default all docs-jdk-api-javadoc docs-jdk-api-modulegraph \
 699     docs-javase-api-javadoc docs-javase-api-modulegraph \
 700     docs-reference-api-javadoc docs-reference-api-modulegraph docs-jdk-specs \
 701     docs-jdk-index docs-zip