# Copyright (c) 1997, 2014, 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

# under the terms of the GNU General Public License version 2 only, as

# published by the Free Software Foundation.  Oracle designates this

# particular file as subject to the "Classpath" exception as provided

# by Oracle in the LICENSE file that accompanied this code.

#

# This code is distributed in the hope that it will be useful, but WITHOUT

# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

# version 2 for more details (a copy is included in the LICENSE file that

# accompanied this code).

#

# You should have received a copy of the GNU General Public License version

# 2 along with this work; if not, write to the Free Software Foundation,

# Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

#

# Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

# or visit www.oracle.com if you need additional information or have any

# questions.

#

include $(SPEC)

include MakeBase.gmk

#################################################################

#

# CORE_PKGS environment variable has been moved to the following file

#

include CORE_PKGS.gmk

#

# Load environment variables for API package names that are not part of

# the Java SE platform

#

include NON_CORE_PKGS.gmk

.SUFFIXES: # Delete the default suffixes

.SUFFIXES: .java

#

# Definitions for directories

#

DOCSDIR := $(OUTPUT_ROOT)/docs

TEMPDIR := $(OUTPUT_ROOT)/docstemp

HOTSPOT_DOCS_IMPORT_PATH=$(HOTSPOT_OUTPUTDIR)/docs

BUILD_NUMBER=$(JDK_BUILD_NUMBER)

JAVADOC_CMD = $(JAVA) \

    -Djava.awt.headless=true \

    $(NEW_JAVADOC) \

    -bootclasspath $(JDK_OUTPUTDIR)/classes

# Copyright year for beginning of Java and some of the apis

# (Needed when creating the javadocs)

FIRST_COPYRIGHT_YEAR = 1993

DOMAPI_FIRST_COPYRIGHT_YEAR = 2005

MIRROR_FIRST_COPYRIGHT_YEAR = 2004

DOCLETAPI_FIRST_COPYRIGHT_YEAR = 1993

TAGLETAPI_FIRST_COPYRIGHT_YEAR = 1993

JDI_FIRST_COPYRIGHT_YEAR = 1999

JAAS_FIRST_COPYRIGHT_YEAR = 1998

JGSS_FIRST_COPYRIGHT_YEAR = 2000

SMARTCARDIO_FIRST_COPYRIGHT_YEAR = 2005

HTTPSERVER_FIRST_COPYRIGHT_YEAR = 2005

MGMT_FIRST_COPYRIGHT_YEAR = 2003

ATTACH_FIRST_COPYRIGHT_YEAR = 2005

JCONSOLE_FIRST_COPYRIGHT_YEAR = 2006

SCTPAPI_FIRST_COPYRIGHT_YEAR = 2009

TRACING_FIRST_COPYRIGHT_YEAR = 2008

TREEAPI_FIRST_COPYRIGHT_YEAR = 2005

JNLP_FIRST_COPYRIGHT_YEAR = 1998

PLUGIN2_FIRST_COPYRIGHT_YEAR = 2007

JDKNET_FIRST_COPYRIGHT_YEAR = 2014

# Oracle name

FULL_COMPANY_NAME = Oracle and/or its affiliates

# Copyright address

COMPANY_ADDRESS = 500 Oracle Parkway<br>Redwood Shores, CA 94065 USA.

# The trademark symbol

TRADEMARK = ™

# Common copyright lines used

# The word "Copyright" might optionally be a link to the file cpyr.html.

# The first year of copyright may vary or not be available.

# The address to the company might be optional.

COMMA:= ,

EMPTY:=

SPACE:=$(EMPTY) $(EMPTY)

COPYRIGHT_SYMBOL = &\#x00a9;

# Macro to construct the copyright line

# (The GNU make 3.78.1 "if" conditional is broken, fixed in GNU make 3.81)

define CopyrightLine # optionalurl optionalfirstyear optionaladdress

$(if $(strip $1),<a href="$(strip $1)">Copyright</a>,Copyright) \

$(COPYRIGHT_SYMBOL) $(if $2,$2${COMMA},) $(COPYRIGHT_YEAR),\

$(FULL_COMPANY_NAME). $3 All rights reserved.

endef

# Url to root of documents

DOCSDIR_URL = {@docroot}/$(GET2DOCSDIR)

# Url to copyright html file

COPYRIGHT_URL = $(DOCSDIR_URL)/legal/cpyr.html

# Url to bug filing site

BUG_SUBMIT_URL = http://bugreport.java.com/bugreport/

# Common line for how to submit a bug or rfe

BUG_SUBMIT_LINE = <a href="$(BUG_SUBMIT_URL)">Submit a bug or feature</a>

# Url to devdocs page

# Was: http://java.sun.com/javase/6/webnotes/devdocs-vs-specs.html

DEV_DOCS_URL-7 = http://download.oracle.com/javase/7/docs/index.html

DEV_DOCS_URL-8 = http://download.oracle.com/javase/8/docs/index.html

DEV_DOCS_URL = $(DEV_DOCS_URL-$(JDK_MINOR_VERSION))

DOCS_BASE_URL = http://download.oracle.com/javase/7/docs

# Common Java trademark line

JAVA_TRADEMARK_LINE = Java is a trademark or registered trademark of \

$(FULL_COMPANY_NAME) in the US and other countries.

#################################################################

# Macros:

# List of all possible directories for javadoc to look for sources

# NOTE: Quotes are required around sourcepath argument only on Windows.

# Otherwise, you get "No packages or classes specified." due

# to $(PATH_SEP) being interpreted as an end of

# command (newline or shell ; character)

ALL_SOURCE_DIRS := $(wildcard \

      $(JDK_TOPDIR)/src/*/share/classes \

      $(JDK_TOPDIR)/src/*/$(OPENJDK_TARGET_OS)/classes \

      $(JDK_TOPDIR)/src/*/$(OPENJDK_TARGET_OS_TYPE)/classes \

      $(LANGTOOLS_TOPDIR)/src/*/share/classes \

      $(CORBA_TOPDIR)/src/*/share/classes \

      $(JAXP_TOPDIR)/src/*/share/classes \

      $(JAXWS_TOPDIR)/src/*/share/classes \

      $(JDK_OUTPUTDIR)/gensrc/j* \

      $(JDK_OUTPUTDIR)/gendocsrc_rmic \

      $(CORBA_OUTPUTDIR)/gensrc/j* \

      $(JDK_TOPDIR)/src/*/share/doc/stub \

      ) \

      #

# List with classpath separator between them

EMPTY:=

SPACE:= $(EMPTY) $(EMPTY)

RELEASEDOCS_SOURCEPATH = \

    $(subst $(SPACE),$(PATH_SEP),$(strip $(ALL_SOURCE_DIRS)))

define prep-target

	$(MKDIR) -p $(@D)

	$(RM) $@

endef

# Prep for javadoc creation, assumes $@ is an index.html file

define prep-javadoc

	@if [ -f "$@" -a "$?" != "" ] ; then \

	  $(ECHO) "# Dependencies have changed: $?"; \

	fi

	$(RM) -r $(@D)

	$(MKDIR) -p $(@D)

endef

$(eval $(call FillCacheFind, $(ALL_SOURCE_DIRS)))

define PackageDependencies

  $(call CacheFind, $(wildcard $(foreach p, $(subst .,/,$1), $(addsuffix /$p, $(ALL_SOURCE_DIRS)))))

endef

# Given a list of packages, add packages that exist to $@, print summary

define PackageFilter # packages

	@if [ "$1" != "" ] ; then \

	  for p in $1 ; do \

	    pd=`$(ECHO) $${p} | $(SED) -e 's@[.]@/@g'`; \

	    found="false"; \

	    for cp in $(ALL_SOURCE_DIRS) ; do \

	      if [ -d $${cp}/$${pd} ] ; then \

	        $(ECHO) "$${p}" >> $@; \

	        found="true"; \

	        break; \

	      fi; \

	    done; \

	    if [ "$${found}" = "false" ] ; then \

	      $(ECHO) "WARNING: Package not found: $${p}"; \

	    fi; \

	  done; \

	fi

endef

# Print out a summary of the javadoc command about to be run

define JavadocSummary # optionsfile packagesfile

	@$(ECHO) "# Running javadoc for $(patsubst $(OUTPUT_ROOT)/%,%,$@)" $(LOG_WARN)

	@($(ECHO) "# Options (`$(BASENAME) $1`):"; $(SED) -e 's@^@#   @' $1) $(LOG_DEBUG)

	@($(ECHO) "# Packages (`$(BASENAME) $2`):";$(SED) -e 's@^@#   @' $2) $(LOG_DEBUG)

endef

#

# Temporary directory for javadoc creation

#

DOCSTMPDIR = $(TEMPDIR)/doctmp

#

# Different api directories created from root directory

#

COREAPI_DOCSDIR = $(DOCSDIR)/api

JDK_API_DOCSDIR = $(DOCSDIR)/jdk/api

JRE_API_DOCSDIR = $(DOCSDIR)/jre/api

PLATFORM_DOCSDIR = $(DOCSDIR)/platform

# 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:

JDKJRE2COREAPI = ../../api

# Common bottom argument

define CommonBottom # year

<font size="-1"><br> $(call CopyrightLine,,$1,)</font>

endef

# Common trademark bottom argument (Not sure why this is used sometimes)

define CommonTrademarkBottom # year

<font size="-1">\

$(BUG_SUBMIT_LINE)<br>$(JAVA_TRADEMARK_LINE)<br>\

$(call CopyrightLine,,$1,$(COMPANY_ADDRESS))\

</font>

endef

# Common echo of option

define OptionOnly # opt

	if [ "$1" != "" ] ; then \

		$(PRINTF) "%s\n" "$1"; \

	fi

endef

define OptionPair # opt arg

	$(PRINTF) "%s '%s'\n" "$1" '$2'

endef

define OptionTrip # opt arg arg

	$(PRINTF) "%s '%s' '%s'\n" "$1" '$2' '$3'

endef

# Core api bottom argument (with special sauce)

COREAPI_BOTTOM = <font size="-1"> $(BUG_SUBMIT_LINE)\

<br>For further API reference and developer documentation, \

see <a href="$(DEV_DOCS_URL)" target="_blank">Java SE Documentation</a>. \

That documentation contains more detailed, developer-targeted descriptions, \

with conceptual overviews, definitions of terms, workarounds, \

and working code examples.<br>\

$(call CopyrightLine,$(COPYRIGHT_URL),$(FIRST_COPYRIGHT_YEAR),)\

</font>

# Common javadoc options used by all bundles

ifdef OPENJDK

  ADDITIONAL_JAVADOCFLAGS = \

      -Xdocrootparent $(DOCS_BASE_URL)

else

  ADDITIONAL_JAVADOCFLAGS =

endif

define COMMON_JAVADOCFLAGS

    $(call OptionOnly,-XDignore.symbol.file=true) ; \

    $(call OptionOnly,-quiet) ; \

    $(call OptionOnly,-use) ; \

    $(call OptionOnly,-keywords) ; \

    $(call OptionPair,-Xprofilespath,$(JDK_TOPDIR)/make/profile-rtjar-includes.txt) ; \

    $(call OptionOnly,$(ADDITIONAL_JAVADOCFLAGS))

endef

# Common javadoc tags used by all bundles

# Java language specification cite

TAG_JLS = jls:a:See <cite> \

The Java&trade; Language Specification</cite>:

# Java virtual machine specification cite

TAG_JVMS = jvms:a:See <cite> \

The Java&trade; Virtual Machine Specification</cite>:

# 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.

define COMMON_JAVADOCTAGS

  $(call OptionPair,-tag,beaninfo:X) ; \

  $(call OptionPair,-tag,revised:X) ; \

  $(call OptionPair,-tag,since.unbundled:X) ; \

  $(call OptionPair,-tag,spec:X) ; \

  $(call OptionPair,-tag,specdefault:X) ; \

  $(call OptionPair,-tag,Note:X) ; \

  $(call OptionPair,-tag,ToDo:X) ; \

  $(call OptionPair,-tag,apiNote:a:API Note:) ; \

  $(call OptionPair,-tag,implSpec:a:Implementation Requirements:) ; \

  $(call OptionPair,-tag,implNote:a:Implementation Note:) ; \

  $(call OptionPair,-tag,param) ; \

  $(call OptionPair,-tag,return) ; \

  $(call OptionPair,-tag,throws) ; \

  $(call OptionPair,-tag,since) ; \

  $(call OptionPair,-tag,version) ; \

  $(call OptionPair,-tag,serialData) ; \

  $(call OptionPair,-tag,factory) ; \

  $(call OptionPair,-tag,see) ; \

  $(call OptionPair,-tag,$(TAG_JVMS)) ; \

  $(call OptionPair,-tag,$(TAG_JLS))

endef

# Draft used for non-fcs documents

DRAFT_HEADER =

ifneq ($(MILESTONE), fcs)

  DRAFT_HEADER = <br><strong>DRAFT&nbsp;$(MILESTONE)-$(BUILD_NUMBER)</strong>

  DRAFT_BOTTOM = <br><strong>DRAFT&nbsp;$(MILESTONE)-$(BUILD_NUMBER)</strong>

  DRAFT_WINTITLE = $(BUILD_NUMBER)

  # Early access top text (not used in FCS releases)

  COREAPI_TOP_EARLYACCESS = \

<div style="background-color: \#EEEEEE"> \

<div style="padding: 6px; margin-top: 2px; margin-bottom: 6px; \

margin-left: 6px; margin-right: 6px; text-align: justify; \

font-size: 80%; font-family: Helvetica, Arial, sans-serif; \

font-weight: normal;"> \

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. \

</div> </div>

endif

#################################################################

#

# Load custom Javadoc rules

#

$(eval $(call IncludeCustomExtension, , Javadoc.gmk))

#################################################################

#

# Default target is same as docs target, create core api and all others it can

#

all: docs

docs: coredocs otherdocs

#################################################################

# Production Targets -- USE THESE TARGETS WHEN:

# a) You're generating docs outside of release engineering's

#    standard control build.

# b) The docs will be pushed to the web and/or included in

#    the downloaded doc bundle.

#

# See: Notes.html#releaseTargets

# Note: Spaces precede ifdef/ifndef indents. Tabs precede target commands (!)

#

sanitycheckcoredocs:

	@$(ECHO) ""

	@$(ECHO) "Building core api docs with these values:"

	@$(ECHO) "    BUILD_NUMBER = $(BUILD_NUMBER)"

	@$(ECHO) "    MILESTONE = $(MILESTONE)"

	@$(ECHO) ""

        ifeq ($(BUILD_NUMBER), b00)

	  @$(ECHO) "ERROR: Build number must be defined"

	  @$(ECHO) "MILESTONE is set to $(MILESTONE)"

	  @$(ECHO) ""

	  exit 1

        endif

#############################################################

#

# coredocs

#

COREAPI_DOCTITLE = Java$(TRADEMARK) Platform, Standard Edition \

$(JDK_MINOR_VERSION)<br>API Specification

COREAPI_WINDOWTITLE = Java Platform SE $(JDK_MINOR_VERSION)

COREAPI_HEADER = \

<strong>Java$(TRADEMARK)&nbsp;Platform<br>Standard&nbsp;Ed.&nbsp;$(JDK_MINOR_VERSION)</strong>

# Overview file for core apis

COREAPI_OVERVIEW = $(JDK_TOPDIR)/src/java.base/share/classes/overview-core.html

# The index.html, options, and packages files

COREAPI_INDEX_FILE = $(COREAPI_DOCSDIR)/index.html

COREAPI_OPTIONS_FILE = $(DOCSTMPDIR)/coredocs.options

COREAPI_PACKAGES_FILE = $(DOCSTMPDIR)/coredocs.packages

coredocs: $(COREAPI_INDEX_FILE)

# Set relative location to core api document root

$(COREAPI_INDEX_FILE): GET2DOCSDIR=..

# Run javadoc if the index file is out of date or missing

$(COREAPI_INDEX_FILE): $(COREAPI_OPTIONS_FILE) $(COREAPI_PACKAGES_FILE)

	$(prep-javadoc)

	$(call JavadocSummary,$(COREAPI_OPTIONS_FILE),$(COREAPI_PACKAGES_FILE))

	$(JAVADOC_CMD) -d $(@D) \

	    @$(COREAPI_OPTIONS_FILE) @$(COREAPI_PACKAGES_FILE)

# Create file with javadoc options in it

$(COREAPI_OPTIONS_FILE): $(COREAPI_OVERVIEW)

	$(prep-target)

	@($(call COMMON_JAVADOCFLAGS) ; \

          $(call COMMON_JAVADOCTAGS) ; \

          $(call OptionOnly,-Xdoclint:none) ; \

	  $(call OptionPair,-sourcepath,$(RELEASEDOCS_SOURCEPATH)) ; \

	  $(call OptionPair,-encoding,ISO-8859-1) ; \

	  $(call OptionOnly,-splitIndex) ; \

	  $(call OptionPair,-overview,$(COREAPI_OVERVIEW)) ; \

	  $(call OptionPair,-doctitle,$(COREAPI_DOCTITLE)) ; \

	  $(call OptionPair,-windowtitle,$(COREAPI_WINDOWTITLE) $(DRAFT_WINTITLE)) ; \

	  $(call OptionPair,-header,$(COREAPI_HEADER)$(DRAFT_HEADER)) ; \

	  $(call OptionPair,-bottom,$(COREAPI_BOTTOM)$(DRAFT_BOTTOM)) ; \

	) >> $@

        ifdef COREAPI_TOP_EARLYACCESS

	  @$(call OptionPair,-top,$(COREAPI_TOP_EARLYACCESS)) >> $@

        endif

# Create a file with the package names in it

$(COREAPI_PACKAGES_FILE): $(call PackageDependencies,$(CORE_PKGS))

	$(prep-target)

	$(call PackageFilter,$(CORE_PKGS))

#############################################################

#

# docletapidocs

#

ALL_OTHER_TARGETS += docletapidocs

DOCLETAPI_DOCDIR := $(JDK_API_DOCSDIR)/javadoc/doclet

DOCLETAPI2COREAPI := ../../$(JDKJRE2COREAPI)

DOCLETAPI_DOCTITLE := Doclet API

DOCLETAPI_WINDOWTITLE := Doclet API

DOCLETAPI_HEADER := <strong>Doclet API</strong>

DOCLETAPI_BOTTOM := $(call CommonTrademarkBottom,$(DOCLETAPI_FIRST_COPYRIGHT_YEAR))

DOCLETAPI_GROUPNAME := Packages

DOCLETAPI_REGEXP := com.sun.javadoc

# DOCLETAPI_PKGS is located in NON_CORE_PKGS.gmk

# The index.html, options, and packages files

DOCLETAPI_INDEX_FILE = $(DOCLETAPI_DOCDIR)/index.html

DOCLETAPI_OPTIONS_FILE = $(DOCSTMPDIR)/docletapi.options

DOCLETAPI_PACKAGES_FILE = $(DOCSTMPDIR)/docletapi.packages

docletapidocs: $(DOCLETAPI_INDEX_FILE)

# Set relative location to core api document root

$(DOCLETAPI_INDEX_FILE): GET2DOCSDIR=$(DOCLETAPI2COREAPI)/..

# Run javadoc if the index file is out of date or missing

$(DOCLETAPI_INDEX_FILE): $(DOCLETAPI_OPTIONS_FILE) $(DOCLETAPI_PACKAGES_FILE) $(COREAPI_INDEX_FILE)

	$(prep-javadoc)

	$(call JavadocSummary,$(DOCLETAPI_OPTIONS_FILE),$(DOCLETAPI_PACKAGES_FILE))

	$(JAVADOC_CMD) -d $(@D) \

	    @$(DOCLETAPI_OPTIONS_FILE) @$(DOCLETAPI_PACKAGES_FILE)

# Create file with javadoc options in it

$(DOCLETAPI_OPTIONS_FILE):

	$(prep-target)

	@($(call COMMON_JAVADOCFLAGS) ; \

          $(call COMMON_JAVADOCTAGS) ; \

	  $(call OptionOnly,-Xdoclint:all) ; \

	  $(call OptionPair,-sourcepath,$(RELEASEDOCS_SOURCEPATH)) ; \

	  $(call OptionPair,-encoding,ascii) ; \

	  $(call OptionOnly,-breakiterator) ; \

	  $(call OptionPair,-doctitle,$(DOCLETAPI_DOCTITLE)) ; \

	  $(call OptionPair,-windowtitle,$(DOCLETAPI_WINDOWTITLE) $(DRAFT_WINTITLE)); \

	  $(call OptionPair,-header,$(DOCLETAPI_HEADER)$(DRAFT_HEADER)) ; \

	  $(call OptionPair,-bottom,$(DOCLETAPI_BOTTOM)$(DRAFT_BOTTOM)) ; \

	  $(call OptionTrip,-group,$(DOCLETAPI_GROUPNAME),$(DOCLETAPI_REGEXP)); \

	  $(call OptionTrip,-linkoffline,$(DOCLETAPI2COREAPI),$(COREAPI_DOCSDIR)/); \

	) >> $@

# Create a file with the package names in it

$(DOCLETAPI_PACKAGES_FILE): $(call PackageDependencies,$(DOCLETAPI_PKGS))

	$(prep-target)

	$(call PackageFilter,$(DOCLETAPI_PKGS))

#############################################################

#

# tagletapidocs

#

ALL_OTHER_TARGETS += tagletapidocs

TAGLETAPI_DOCDIR := $(JDK_API_DOCSDIR)/javadoc/taglet

TAGLETAPI2COREAPI := ../../$(JDKJRE2COREAPI)

TAGLETAPI_BOTTOM := $(call CommonTrademarkBottom,$(TAGLETAPI_FIRST_COPYRIGHT_YEAR))

# TAGLETAPI_FILE is located in NON_CORE_PKGS.gmk

# Temporary directory (special generation rules)

TAGLETAPI_TEMPDIR = $(DOCSTMPDIR)/taglets_temp

# The index.html, options, and packages files

TAGLETAPI_INDEX_FILE = $(TAGLETAPI_DOCDIR)/com/sun/tools/doclets/Taglet.html