32 include CORE_PKGS.gmk
33 #
34 # Load environment variables for API package names that are not part of
35 # the Java SE platform
36 #
37 include NON_CORE_PKGS.gmk
38
39
40 .SUFFIXES: # Delete the default suffixes
41 .SUFFIXES: .java
42
43 #
44 # Definitions for directories
45 #
46
47 DOCSDIR := $(IMAGES_OUTPUTDIR)/docs
48 DOCSTMPDIR = $(SUPPORT_OUTPUTDIR)/docs
49
50 HOTSPOT_DOCS_IMPORT_PATH=$(HOTSPOT_OUTPUTDIR)/docs
51
52 BUILD_NUMBER=$(JDK_BUILD_NUMBER)
53
54 JAVADOC_CMD = $(JAVA) \
55 -Djava.awt.headless=true \
56 $(NEW_JAVADOC)
57
58 JAVADOC_CMD_SMALL = $(JAVA_SMALL) \
59 -Djava.awt.headless=true \
60 $(NEW_JAVADOC)
61
62 # Copyright year for beginning of Java and some of the apis
63 # (Needed when creating the javadocs)
64 FIRST_COPYRIGHT_YEAR = 1993
65 DOMAPI_FIRST_COPYRIGHT_YEAR = 2005
66 MIRROR_FIRST_COPYRIGHT_YEAR = 2004
67 DOCLETAPI_FIRST_COPYRIGHT_YEAR = 1993
68 TAGLETAPI_FIRST_COPYRIGHT_YEAR = 1993
69 JDI_FIRST_COPYRIGHT_YEAR = 1999
70 JAAS_FIRST_COPYRIGHT_YEAR = 1998
71 JGSS_FIRST_COPYRIGHT_YEAR = 2000
72 SMARTCARDIO_FIRST_COPYRIGHT_YEAR = 2005
73 HTTPSERVER_FIRST_COPYRIGHT_YEAR = 2005
105 # (The GNU make 3.78.1 "if" conditional is broken, fixed in GNU make 3.81)
106 define CopyrightLine # optionalurl optionalfirstyear optionaladdress
107 $(if $(strip $1),<a href="$(strip $1)">Copyright</a>,Copyright) \
108 $(COPYRIGHT_SYMBOL) $(if $2,$2${COMMA},) $(COPYRIGHT_YEAR),\
109 $(FULL_COMPANY_NAME). $3 All rights reserved.
110 endef
111
112 # Url to root of documents
113 DOCSDIR_URL = {@docroot}/$(GET2DOCSDIR)
114
115 # Url to copyright html file
116 COPYRIGHT_URL = $(DOCSDIR_URL)/legal/cpyr.html
117
118 # Url to bug filing site
119 BUG_SUBMIT_URL = http://bugreport.java.com/bugreport/
120
121 # Common line for how to submit a bug or rfe
122 BUG_SUBMIT_LINE = <a href="$(BUG_SUBMIT_URL)">Submit a bug or feature</a>
123
124 # Url to devdocs page
125 # Was: http://java.sun.com/javase/6/webnotes/devdocs-vs-specs.html
126 DEV_DOCS_URL-7 = http://download.oracle.com/javase/7/docs/index.html
127 DEV_DOCS_URL-8 = http://download.oracle.com/javase/8/docs/index.html
128 DEV_DOCS_URL = $(DEV_DOCS_URL-$(JDK_MINOR_VERSION))
129 DOCS_BASE_URL = http://download.oracle.com/javase/7/docs
130
131 # Common Java trademark line
132 JAVA_TRADEMARK_LINE = Java is a trademark or registered trademark of \
133 $(FULL_COMPANY_NAME) in the US and other countries.
134
135 #################################################################
136 # Macros:
137
138
139 # List of all possible directories for javadoc to look for sources
140 # NOTE: Quotes are required around sourcepath argument only on Windows.
141 # Otherwise, you get "No packages or classes specified." due
142 # to $(PATH_SEP) being interpreted as an end of
143 # command (newline or shell ; character)
144 ALL_SOURCE_DIRS := $(wildcard \
145 $(JDK_TOPDIR)/src/*/share/classes \
146 $(JDK_TOPDIR)/src/*/$(OPENJDK_TARGET_OS)/classes \
147 $(JDK_TOPDIR)/src/*/$(OPENJDK_TARGET_OS_TYPE)/classes \
148 $(LANGTOOLS_TOPDIR)/src/*/share/classes \
149 $(NASHORN_TOPDIR)/src/*/share/classes \
296 $(call OptionPair,-tag,specdefault:X) ; \
297 $(call OptionPair,-tag,Note:X) ; \
298 $(call OptionPair,-tag,ToDo:X) ; \
299 $(call OptionPair,-tag,apiNote:a:API Note:) ; \
300 $(call OptionPair,-tag,implSpec:a:Implementation Requirements:) ; \
301 $(call OptionPair,-tag,implNote:a:Implementation Note:) ; \
302 $(call OptionPair,-tag,param) ; \
303 $(call OptionPair,-tag,return) ; \
304 $(call OptionPair,-tag,throws) ; \
305 $(call OptionPair,-tag,since) ; \
306 $(call OptionPair,-tag,version) ; \
307 $(call OptionPair,-tag,serialData) ; \
308 $(call OptionPair,-tag,factory) ; \
309 $(call OptionPair,-tag,see) ; \
310 $(call OptionPair,-tag,$(TAG_JVMS)) ; \
311 $(call OptionPair,-tag,$(TAG_JLS))
312 endef
313
314
315
316 # Draft used for non-fcs documents
317 DRAFT_HEADER =
318 ifneq ($(MILESTONE), fcs)
319 DRAFT_HEADER = <br><strong>DRAFT $(MILESTONE)-$(BUILD_NUMBER)</strong>
320 DRAFT_BOTTOM = <br><strong>DRAFT $(MILESTONE)-$(BUILD_NUMBER)</strong>
321 DRAFT_WINTITLE = $(BUILD_NUMBER)
322 # Early access top text (not used in FCS releases)
323 COREAPI_TOP_EARLYACCESS = \
324 <div style="background-color: \#EEEEEE"> \
325 <div style="padding: 6px; margin-top: 2px; margin-bottom: 6px; \
326 margin-left: 6px; margin-right: 6px; text-align: justify; \
327 font-size: 80%; font-family: Helvetica, Arial, sans-serif; \
328 font-weight: normal;"> \
329 Please note that the specifications and other information \
330 contained herein are not final and are subject to change. \
331 The information is being made available to you solely for purpose of \
332 evaluation. \
333 </div> </div>
334
335 endif
336
337 #################################################################
338
339 #
340 # Load custom Javadoc rules
341 #
342
343 $(eval $(call IncludeCustomExtension, , Javadoc.gmk))
344
345 #################################################################
346
347 #
348 # Default target is same as docs target, create core api and all others it can
349 #
350
351 all: docs
352 docs: coredocs otherdocs
353
354 #################################################################
355 # Production Targets -- USE THESE TARGETS WHEN:
356 # a) You're generating docs outside of release engineering's
357 # standard control build.
358 # b) The docs will be pushed to the web and/or included in
359 # the downloaded doc bundle.
360 #
361 # See: Notes.html#releaseTargets
362 # Note: Spaces precede ifdef/ifndef indents. Tabs precede target commands (!)
363 #
364
365 sanitycheckcoredocs:
366 @$(ECHO) ""
367 @$(ECHO) "Building core api docs with these values:"
368 @$(ECHO) " BUILD_NUMBER = $(BUILD_NUMBER)"
369 @$(ECHO) " MILESTONE = $(MILESTONE)"
370 @$(ECHO) ""
371 ifeq ($(BUILD_NUMBER), b00)
372 @$(ECHO) "ERROR: Build number must be defined"
373 @$(ECHO) "MILESTONE is set to $(MILESTONE)"
374 @$(ECHO) ""
375 exit 1
376 endif
377
378 #############################################################
379 #
380 # coredocs
381 #
382 COREAPI_DOCTITLE = Java$(TRADEMARK) Platform, Standard Edition \
383 $(JDK_MINOR_VERSION)<br>API Specification
384 COREAPI_WINDOWTITLE = Java Platform SE $(JDK_MINOR_VERSION)
385 COREAPI_HEADER = \
386 <strong>Java$(TRADEMARK) Platform<br>Standard Ed. $(JDK_MINOR_VERSION)</strong>
387
388 # Overview file for core apis
389 COREAPI_OVERVIEW = $(JDK_TOPDIR)/src/java.base/share/classes/overview-core.html
390
391 # The index.html, options, and packages files
392 COREAPI_INDEX_FILE = $(COREAPI_DOCSDIR)/index.html
393 COREAPI_OPTIONS_FILE = $(DOCSTMPDIR)/coredocs.options
394 COREAPI_PACKAGES_FILE = $(DOCSTMPDIR)/coredocs.packages
395
396 coredocs: $(COREAPI_INDEX_FILE)
397
398 # Set relative location to core api document root
399 $(COREAPI_INDEX_FILE): GET2DOCSDIR=..
400
401 # Run javadoc if the index file is out of date or missing
402 $(COREAPI_INDEX_FILE): $(COREAPI_OPTIONS_FILE) $(COREAPI_PACKAGES_FILE)
403 $(prep-javadoc)
404 $(call JavadocSummary,$(COREAPI_OPTIONS_FILE),$(COREAPI_PACKAGES_FILE))
405 $(JAVADOC_CMD) -d $(@D) \
406 @$(COREAPI_OPTIONS_FILE) @$(COREAPI_PACKAGES_FILE)
1320 $(JDKNET_OPTIONS_FILE):
1321 $(prep-target)
1322 @($(call COMMON_JAVADOCFLAGS) ; \
1323 $(call COMMON_JAVADOCTAGS) ; \
1324 $(call OptionOnly,-Xdoclint:none) ; \
1325 $(call OptionPair,-sourcepath,$(RELEASEDOCS_SOURCEPATH)) ; \
1326 $(call OptionPair,-encoding,ascii) ; \
1327 $(call OptionOnly,-nodeprecatedlist) ; \
1328 $(call OptionPair,-doctitle,$(JDKNET_DOCTITLE)) ; \
1329 $(call OptionPair,-windowtitle,$(JDKNET_WINDOWTITLE) $(DRAFT_WINTITLE)); \
1330 $(call OptionPair,-header,$(JDKNET_HEADER)$(DRAFT_HEADER)); \
1331 $(call OptionPair,-bottom,$(JDKNET_BOTTOM)$(DRAFT_BOTTOM)); \
1332 $(call OptionTrip,-linkoffline,$(JDKNET2COREAPI),$(COREAPI_DOCSDIR)/); \
1333 ) >> $@
1334
1335 # Create a file with the package names in it
1336 $(JDKNET_PACKAGES_FILE): $(call PackageDependencies,$(JDKNET_PKGS))
1337 $(prep-target)
1338 $(call PackageFilter,$(JDKNET_PKGS))
1339
1340 #############################################################
1341 #release version of core packages ########
1342
1343 # The rel-coredocs and rel-docs targets were added by Eric Armstrong. rel-coredocs
1344 # assumes the kind of large, 32-bit machine used in the javapubs group's docs-release
1345 # process. It specifies memory settings accordingly to maximize performance.
1346 #
1347 # The performance settings, like the sanity check, are most important for the core
1348 # docs--the platform APIs. Running javadoc on those APIs takes a significant amount
1349 # of time and memory. Setting the initial heap size as large as possible is important
1350 # to prevent thrashing as the heap grows. Setting the maximum as large as necessary
1351 # is also important to keep the job from failing.
1352 #
1353 # -J-Xmx512 sets a maximum of 512, which became necessary in 6.0
1354 # -J-Xms256 sets starting size to 256 (default is 8)
1355 #
1356 # rel-coredocs also includes a sanity check to help ensure that BUILD_NUMBER and
1357 # MILESTONE are specified properly when docs are built outside of the normal release
1358 # engineering process, with the intention of releasing them on the web or in a downloaded
1359 # docs bundle. (When invoked in release engineering's control build, the values are always
1360 # set properly. But when the targets are run by themselves, they default to b00 and
1361 # "internal"--which silently sabotage the result of a build that can take many hours
1362 # to complete.
1363
1364 # Maximize performance and ensure that build number & milestone are set.
1365
1366 rel-coredocs: sanitycheckcoredocs
1367 $(MAKE) coredocs
1368
1369 rel-docs: rel-coredocs $(ALL_OTHER_TARGETS)
1370 #
1371 # end of production targets
1372
1373 otherdocs: $(ALL_OTHER_TARGETS)
1374
1375 clean:
1376 $(RM) -r $(DOCSDIR) $(DOCSTMPDIR)
1377
1378 #############################################################
1379 # DEBUG TARGET
1380 # List the values defined in the makefile hierarchy, to make sure everything
1381 # is set properly, and to help identify values we can use instead of making new ones.
1382 # (Most of them come from common/shared/Defs.gmk)
1383 #
1384 # Notes:
1385 # * BUILD_NUMBER defaults to b00 if not set on command line with BUILD_NUMBER=<value>
1386 # * MILESTONE defaults to internal unless set to beta, rc, or fcs on command line
1387 #
1388
1389 #############################################################
1390 .PHONY: all docs coredocs rel-docs otherdocs rel-coredocs \
1391 sanitycheckcoredocs $(ALL_OTHER_TARGETS)
|
32 include CORE_PKGS.gmk
33 #
34 # Load environment variables for API package names that are not part of
35 # the Java SE platform
36 #
37 include NON_CORE_PKGS.gmk
38
39
40 .SUFFIXES: # Delete the default suffixes
41 .SUFFIXES: .java
42
43 #
44 # Definitions for directories
45 #
46
47 DOCSDIR := $(IMAGES_OUTPUTDIR)/docs
48 DOCSTMPDIR = $(SUPPORT_OUTPUTDIR)/docs
49
50 HOTSPOT_DOCS_IMPORT_PATH=$(HOTSPOT_OUTPUTDIR)/docs
51
52 JAVADOC_CMD = $(JAVA) \
53 -Djava.awt.headless=true \
54 $(NEW_JAVADOC)
55
56 JAVADOC_CMD_SMALL = $(JAVA_SMALL) \
57 -Djava.awt.headless=true \
58 $(NEW_JAVADOC)
59
60 # Copyright year for beginning of Java and some of the apis
61 # (Needed when creating the javadocs)
62 FIRST_COPYRIGHT_YEAR = 1993
63 DOMAPI_FIRST_COPYRIGHT_YEAR = 2005
64 MIRROR_FIRST_COPYRIGHT_YEAR = 2004
65 DOCLETAPI_FIRST_COPYRIGHT_YEAR = 1993
66 TAGLETAPI_FIRST_COPYRIGHT_YEAR = 1993
67 JDI_FIRST_COPYRIGHT_YEAR = 1999
68 JAAS_FIRST_COPYRIGHT_YEAR = 1998
69 JGSS_FIRST_COPYRIGHT_YEAR = 2000
70 SMARTCARDIO_FIRST_COPYRIGHT_YEAR = 2005
71 HTTPSERVER_FIRST_COPYRIGHT_YEAR = 2005
103 # (The GNU make 3.78.1 "if" conditional is broken, fixed in GNU make 3.81)
104 define CopyrightLine # optionalurl optionalfirstyear optionaladdress
105 $(if $(strip $1),<a href="$(strip $1)">Copyright</a>,Copyright) \
106 $(COPYRIGHT_SYMBOL) $(if $2,$2${COMMA},) $(COPYRIGHT_YEAR),\
107 $(FULL_COMPANY_NAME). $3 All rights reserved.
108 endef
109
110 # Url to root of documents
111 DOCSDIR_URL = {@docroot}/$(GET2DOCSDIR)
112
113 # Url to copyright html file
114 COPYRIGHT_URL = $(DOCSDIR_URL)/legal/cpyr.html
115
116 # Url to bug filing site
117 BUG_SUBMIT_URL = http://bugreport.java.com/bugreport/
118
119 # Common line for how to submit a bug or rfe
120 BUG_SUBMIT_LINE = <a href="$(BUG_SUBMIT_URL)">Submit a bug or feature</a>
121
122 # Url to devdocs page
123 DOCS_BASE_URL = http://docs.oracle.com/javase/$(VERSION_SPECIFICATION)/docs
124 DEV_DOCS_URL = $(DOCS_BASE_URL)/index.html
125
126 # Common Java trademark line
127 JAVA_TRADEMARK_LINE = Java is a trademark or registered trademark of \
128 $(FULL_COMPANY_NAME) in the US and other countries.
129
130 #################################################################
131 # Macros:
132
133
134 # List of all possible directories for javadoc to look for sources
135 # NOTE: Quotes are required around sourcepath argument only on Windows.
136 # Otherwise, you get "No packages or classes specified." due
137 # to $(PATH_SEP) being interpreted as an end of
138 # command (newline or shell ; character)
139 ALL_SOURCE_DIRS := $(wildcard \
140 $(JDK_TOPDIR)/src/*/share/classes \
141 $(JDK_TOPDIR)/src/*/$(OPENJDK_TARGET_OS)/classes \
142 $(JDK_TOPDIR)/src/*/$(OPENJDK_TARGET_OS_TYPE)/classes \
143 $(LANGTOOLS_TOPDIR)/src/*/share/classes \
144 $(NASHORN_TOPDIR)/src/*/share/classes \
291 $(call OptionPair,-tag,specdefault:X) ; \
292 $(call OptionPair,-tag,Note:X) ; \
293 $(call OptionPair,-tag,ToDo:X) ; \
294 $(call OptionPair,-tag,apiNote:a:API Note:) ; \
295 $(call OptionPair,-tag,implSpec:a:Implementation Requirements:) ; \
296 $(call OptionPair,-tag,implNote:a:Implementation Note:) ; \
297 $(call OptionPair,-tag,param) ; \
298 $(call OptionPair,-tag,return) ; \
299 $(call OptionPair,-tag,throws) ; \
300 $(call OptionPair,-tag,since) ; \
301 $(call OptionPair,-tag,version) ; \
302 $(call OptionPair,-tag,serialData) ; \
303 $(call OptionPair,-tag,factory) ; \
304 $(call OptionPair,-tag,see) ; \
305 $(call OptionPair,-tag,$(TAG_JVMS)) ; \
306 $(call OptionPair,-tag,$(TAG_JLS))
307 endef
308
309
310
311 # Assume we need a draft format whenever the pre-release identifier is non-empty
312 ifneq ($(VERSION_PRE),)
313 DRAFT_HEADER := <br><strong>DRAFT $(VERSION_STRING)</strong>
314 DRAFT_BOTTOM := <br><strong>DRAFT $(VERSION_STRING)</strong>
315 DRAFT_WINTITLE := $(VERSION_BUILD)
316 # Early access top text (not used in FCS releases)
317 COREAPI_TOP_EARLYACCESS := \
318 <div style="background-color: \#EEEEEE"> \
319 <div style="padding: 6px; margin-top: 2px; margin-bottom: 6px; \
320 margin-left: 6px; margin-right: 6px; text-align: justify; \
321 font-size: 80%; font-family: Helvetica, Arial, sans-serif; \
322 font-weight: normal;"> \
323 Please note that the specifications and other information \
324 contained herein are not final and are subject to change. \
325 The information is being made available to you solely for purpose of \
326 evaluation. \
327 </div> </div>
328 else
329 DRAFT_HEADER :=
330 DRAFT_BOTTOM :=
331 DRAFT_WINTITLE :=
332 COREAPI_TOP_EARLYACCESS :=
333 endif
334
335 #################################################################
336
337 #
338 # Load custom Javadoc rules
339 #
340
341 $(eval $(call IncludeCustomExtension, , Javadoc.gmk))
342
343 #################################################################
344
345 #
346 # Default target is same as docs target, create core api and all others it can
347 #
348
349 all: docs
350 docs: coredocs otherdocs
351
352 #############################################################
353 #
354 # coredocs
355 #
356 COREAPI_DOCTITLE = Java$(TRADEMARK) Platform, Standard Edition \
357 $(VERSION_SPECIFICATION)<br>API Specification
358 COREAPI_WINDOWTITLE = Java Platform SE $(VERSION_SPECIFICATION)
359 COREAPI_HEADER = \
360 <strong>Java$(TRADEMARK) Platform<br>Standard Ed. $(VERSION_SPECIFICATION)</strong>
361
362 # Overview file for core apis
363 COREAPI_OVERVIEW = $(JDK_TOPDIR)/src/java.base/share/classes/overview-core.html
364
365 # The index.html, options, and packages files
366 COREAPI_INDEX_FILE = $(COREAPI_DOCSDIR)/index.html
367 COREAPI_OPTIONS_FILE = $(DOCSTMPDIR)/coredocs.options
368 COREAPI_PACKAGES_FILE = $(DOCSTMPDIR)/coredocs.packages
369
370 coredocs: $(COREAPI_INDEX_FILE)
371
372 # Set relative location to core api document root
373 $(COREAPI_INDEX_FILE): GET2DOCSDIR=..
374
375 # Run javadoc if the index file is out of date or missing
376 $(COREAPI_INDEX_FILE): $(COREAPI_OPTIONS_FILE) $(COREAPI_PACKAGES_FILE)
377 $(prep-javadoc)
378 $(call JavadocSummary,$(COREAPI_OPTIONS_FILE),$(COREAPI_PACKAGES_FILE))
379 $(JAVADOC_CMD) -d $(@D) \
380 @$(COREAPI_OPTIONS_FILE) @$(COREAPI_PACKAGES_FILE)
1294 $(JDKNET_OPTIONS_FILE):
1295 $(prep-target)
1296 @($(call COMMON_JAVADOCFLAGS) ; \
1297 $(call COMMON_JAVADOCTAGS) ; \
1298 $(call OptionOnly,-Xdoclint:none) ; \
1299 $(call OptionPair,-sourcepath,$(RELEASEDOCS_SOURCEPATH)) ; \
1300 $(call OptionPair,-encoding,ascii) ; \
1301 $(call OptionOnly,-nodeprecatedlist) ; \
1302 $(call OptionPair,-doctitle,$(JDKNET_DOCTITLE)) ; \
1303 $(call OptionPair,-windowtitle,$(JDKNET_WINDOWTITLE) $(DRAFT_WINTITLE)); \
1304 $(call OptionPair,-header,$(JDKNET_HEADER)$(DRAFT_HEADER)); \
1305 $(call OptionPair,-bottom,$(JDKNET_BOTTOM)$(DRAFT_BOTTOM)); \
1306 $(call OptionTrip,-linkoffline,$(JDKNET2COREAPI),$(COREAPI_DOCSDIR)/); \
1307 ) >> $@
1308
1309 # Create a file with the package names in it
1310 $(JDKNET_PACKAGES_FILE): $(call PackageDependencies,$(JDKNET_PKGS))
1311 $(prep-target)
1312 $(call PackageFilter,$(JDKNET_PKGS))
1313
1314
1315 otherdocs: $(ALL_OTHER_TARGETS)
1316
1317 #############################################################
1318 .PHONY: all docs coredocs otherdocs \
1319 $(ALL_OTHER_TARGETS)
|