forked from ibmruntimes/openj9-openjdk-jdk11
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathDocs.gmk
299 lines (261 loc) · 16.1 KB
/
Docs.gmk
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
# ===========================================================================
# (c) Copyright IBM Corp. 2018, 2022 All Rights Reserved
# ===========================================================================
# 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.
#
# IBM designates this particular file as subject to the "Classpath" exception
# as provided by IBM 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, see <http://www.gnu.org/licenses/>.
# ===========================================================================
JVMTI_HTML := $(TOPDIR)/closed/variant-server/gensrc/jvmtifiles/jvmti.html
##############################################################################
# Text for openj9 modules
OPENJ9_BASE_URL := https://www.eclipse.org/openj9/
OPENJ9_BUG_SUBMIT_URL := https://github.com/eclipse-openj9/openj9/issues
OPENJ9_JAVADOC_BOTTOM = \
<a href="$(OPENJ9_BASE_URL)" target="_blank">Eclipse OpenJ9 website.</a><br> \
To raise a bug report or suggest an improvement create an <a href="$(OPENJ9_BUG_SUBMIT_URL)" target="_blank">Eclipse Openj9 issue.</a><br> \
Copyright © 1998, $(COPYRIGHT_YEAR) IBM Corp. and others.
##############################################################################
# The javadoc tool only allows for a single setting for headers and footers
# per invocation. The sed command below replaces the footer for the pages
# relating to openj9 classes to the correct value for those classes.
#
# '.' need escaping in the sed regex. If more special characters are introduced
# in the openjdk JAVADOC_BOTTOM in future these would need escaping also.
#
# '&' needs escaping in sed replacement text.
#
# {@docroot} is expanded by javadoc when the html files are created, so the matching
# needs to cater for anything {@docroot} may have been substituted by - '../../../..'
# or '../..' or '..' etc.
# \(\.\./\)*\.\. means zero or more '../' strings followed by '..'
JAVADOC_DOCROOT := \(\.\./\)*\.\.
JAVADOC_BOTTOM_REGEX = $(subst {@docroot},$(JAVADOC_DOCROOT),$(subst .,\.,$(JAVADOC_BOTTOM)))
OPENJ9_SUBST_COMMAND = $(SED) -e '\''s|$(JAVADOC_BOTTOM_REGEX)|$(subst &,\&,$(OPENJ9_JAVADOC_BOTTOM))|g'\''
################################################################################
# Define a javadoc Group for the OpenJ9 specific modules
# Module names are added to DOCS_MODULES in closed/custom/common/Modules.gmk
OPENJ9_GROUP_NAME := OpenJ9
OPENJ9_GROUP_MODULES := openj9.*
OPENJ9_GROUP_DESCRIPTION := \
Modules whose names start with {@code openj9.} contain APIs provided by the \
<a href="$(OPENJ9_BASE_URL)" target="_blank">Eclipse OpenJ9</a> project. \
These APIs can only be used with a JDK which includes the OpenJ9 virtual machine. \
#
JDK_GROUPS += OPENJ9
################################################################################
# Add openj9 specific modules to the list of modules for which javadoc is required
OPENJ9_MODULES := $(filter openj9.%,$(call FindAllModules))
DOCS_MODULES += $(OPENJ9_MODULES)
OPENJDK_JAVADOC_MARKER := $(DOCS_OUTPUTDIR)/api/index.html
OPENJ9_JAVADOC_MARKER := $(SUPPORT_OUTPUTDIR)/docs/_javadoc_JDK_API_openj9.marker
OPENJ9_JAVADOC_SCRIPT := $(SUPPORT_OUTPUTDIR)/docs/_javadoc_openj9_footer_replace.sh
OPENJ9_JAVADOC_TEMP := $(SUPPORT_OUTPUTDIR)/docs/_javadoc_temp.html
JDK_API_CUSTOM_TARGETS += $(OPENJ9_JAVADOC_MARKER)
################################################################################
# The OpenJ9 classes are built from the $(J9JCL_SOURCES_DIR) and closed/src
# directories.
# The packages are beneath directories called /share/classes (or /unix/classes,
# /windows/classes etc.) which do not appear in the javadoc tree structure.
# The commands below replace the footer in the javadoc html pages for the
# following files:
# 1. The openj9 java source files which override the openjdk versions
# 2. The openj9.xxxx modules, including the javadoc generated files such as
# enum class pages, module-summary.html, package-summary.html etc.)
# 3. The com/ibm/xxxx packages, including the javadoc generated files such as
# enum class pages, module-summary.html, package-summary.html etc.)
# A temporary script file is used to avoid xargs command line length issues
# on some platforms.
OPENJ9_JAVADOC_SCRIPT_BODY = \
for path in "$$@" ; do \
if [ -f "$(DOCS_OUTPUTDIR)/api/$$path" ] ; then \
$(CP) -f "$(DOCS_OUTPUTDIR)/api/$$path" "$(OPENJ9_JAVADOC_TEMP)" ; \
$(OPENJ9_SUBST_COMMAND) < "$(OPENJ9_JAVADOC_TEMP)" > "$(DOCS_OUTPUTDIR)/api/$$path" ; \
$(RM) "$(OPENJ9_JAVADOC_TEMP)" ; \
fi ; \
done \
#
$(OPENJ9_JAVADOC_MARKER) : $(OPENJDK_JAVADOC_MARKER)
$(ECHO) '$(OPENJ9_JAVADOC_SCRIPT_BODY)' >$(OPENJ9_JAVADOC_SCRIPT)
$(CD) $(J9JCL_SOURCES_DIR) ; \
$(FIND) . -type f -name '*.java' \
| $(SED) -e 's|/[^/]\+/classes/|/|' -e 's|\.java$$|.html|' \
| $(XARGS) $(BASH) $(OPENJ9_JAVADOC_SCRIPT)
$(CD) $(TOPDIR)/closed/src ; \
$(FIND) . -type f -name '*.java' \
| $(SED) -e 's|/[^/]\+/classes/|/|' -e 's|\.java$$|.html|' \
| $(XARGS) $(BASH) $(OPENJ9_JAVADOC_SCRIPT)
$(CD) $(DOCS_OUTPUTDIR)/api ; \
$(FIND) . -type f '(' -path '*/openj9*/*.html' -o -path '*/com/ibm/*.html' ')' \
| $(XARGS) $(BASH) $(OPENJ9_JAVADOC_SCRIPT)
$(RM) -f $(OPENJ9_JAVADOC_SCRIPT)
$(TOUCH) $@
##############################################################################
# Create javadoc for only the OpenJ9 extensions and modifications.
#
# javadoc automatically retrieves module and package descriptions from the
# module-info.java, package-info.java and package.html files and uses the
# information as part of the module-summary.html and package-summary.html
# files. The module-info.java, package-info.java and package.html files
# used would be from the openjdk project source files if they were not
# overridden by openj9.
# The text taken from these files is replaced by creating a package-info.java
# stub file for each package without a package-info.java file provided by
# openj9, or by removing the text directly from the generated
# module-summary.html file.
JAVASE_BASE_URL := https://docs.oracle.com/en/java/javase/$(VERSION_SPECIFICATION)/docs/api
OPENJ9_ONLY_JAVADOC_MARKER := $(SUPPORT_OUTPUTDIR)/openj9-docs/_javadoc_openj9_only_exec.marker
OPENJ9_ONLY_JAVADOC_SCRIPT := $(SUPPORT_OUTPUTDIR)/openj9-docs/_javadoc_openj9_only_replace.sh
OPENJ9_ONLY_JAVADOC_TEMP := $(SUPPORT_OUTPUTDIR)/openj9-docs/_javadoc_temp.html
JDK_API_CUSTOM_TARGETS += $(OPENJ9_ONLY_JAVADOC_MARKER)
OPENJ9_ONLY_JDK_NAME := OpenJ9 JDK $(VERSION_SPECIFICATION)
OPENJ9_ONLY_DOCDIR := $(IMAGES_OUTPUTDIR)/openj9-docs/api
OPENJ9_ONLY_INDEX_HTML := $(IMAGES_OUTPUTDIR)/openj9-docs/api/index.html
# Create lists of all the openj9 source files and those for which javadoc
# is required.
# javadoc is required for the openj9.xxxx packages and the jdk management
# packages with public methods which are openj9 specific extensions or
# which modify the openjdk implementation behaviour.
# javadoc is not generated for the classes which are replaced by openj9
# but are functionally identical to the openjdk implementations
# (e.g. java.lang.String), since the openjdk javadoc is still applicable.
#
# The list of source files is passed explicitly (via OPENJ9_ONLY_JAVADOC_FILES)
# to the javadoc tool on the command line and used as dependencies
# (via OPENJ9_ONLY_JAVADOC_FILELIST) to identify when the javadoc needs
# regenerating.
OPENJ9_ONLY_FILELIST := $(shell $(FIND) $(J9JCL_SOURCES_DIR) -type f)
OPENJ9_ONLY_JAVADOC_FILELIST := $(shell $(FIND) $(J9JCL_SOURCES_DIR) -type f '(' -path '*/openj9.*/*.java' -o -path '*/jdk.management/*.java' ')')
OPENJ9_ONLY_JAVADOC_FILES := $(SUPPORT_OUTPUTDIR)/openj9-docs/_javadoc_openj9_files.txt
# Set up the javadoc command line options.
# Use -linkoffline to redirect the links to the documentation for the classes
# from the openjdk project source files to the# online Oracle documentation.
# See the javadoc documentation for details of the linkoffline option - e.g.
# https://docs.oracle.com/en/java/javase/14/javadoc/javadoc.html
# Deferred expansion is required for variables because this file is included
# by make/Docs.gmk before variables such as JAVADOC_OPTIONS and JAVADOC_TAGS
# have been defined.
OPENJ9_ONLY_JAVADOC_OPTIONS = $(filter-out --expand-requires transitive,$(JAVADOC_OPTIONS))
OPENJ9_ONLY_JAVADOC_OPTIONS += -linkoffline $(JAVASE_BASE_URL)/ $(DOCS_OUTPUTDIR)/api/
OPENJ9_ONLY_JAVADOC_OPTIONS += $(JAVADOC_TAGS)
OPENJ9_ONLY_JAVADOC_OPTIONS += --module-source-path $(call PathList,$(OPENJ9_STUBS_DIR) $(MODULES_SOURCE_PATH))
OPENJ9_ONLY_JAVADOC_OPTIONS += -Xdoclint:all,$(call CommaList, $(addprefix -, $(JAVADOC_DISABLED_DOCLINT)))
OPENJ9_DOC_TITLE = $(JDK_LONG_NAME)<br>Version $(VERSION_SPECIFICATION)
OPENJ9_WINDOW_TITLE = $(subst &,&,$(JDK_SHORT_NAME))
OPENJ9_HEADER_TITLE = <div $(HEADER_STYLE)><strong>$(JDK_SHORT_NAME)</strong></div>
OPENJ9_ONLY_JAVADOC_OPTIONS += -doctitle '$(OPENJ9_ONLY_JDK_NAME)'
OPENJ9_ONLY_JAVADOC_OPTIONS += -windowtitle '$(OPENJ9_ONLY_JDK_NAME)'
OPENJ9_ONLY_JAVADOC_OPTIONS += -header '<div $(HEADER_STYLE)><strong>$(OPENJ9_ONLY_JDK_NAME)</strong></div>'
OPENJ9_ONLY_JAVADOC_OPTIONS += -bottom '$(OPENJ9_JAVADOC_BOTTOM)'
ifneq ($(LOG_LEVEL), trace)
OPENJ9_ONLY_JAVADOC_OPTIONS += -quiet
else
OPENJ9_ONLY_JAVADOC_OPTIONS += -verbose
endif
OPENJ9_ONLY_JAVADOC_JAVA_ARGS = -Djava.awt.headless=true -Dextlink.spec.version=$(VERSION_SPECIFICATION) -Djspec.version=$(VERSION_SPECIFICATION)
OPENJ9_ONLY_JAVADOC_CMD = $(JAVA) $(OPENJ9_ONLY_JAVADOC_JAVA_ARGS) $(NEW_JAVADOC)
OPENJDK_MODULE_REFERENCE_TEXT := \
These are the OpenJ9 extensions to this module. Refer to <a href="$(JAVASE_BASE_URL)" target="_blank">$(JAVASE_BASE_URL)</a> for the reference implementation documentation.
MODULE_DESCRIPTION_FIRST_LINE := <section role="region">
MODULE_DESCRIPTION_LAST_LINE := <!-- ============ PACKAGES SUMMARY =========== -->
MODULE_DESCRIPTION_REPLACE_TEXT := \
<section class="module-description" id="module.description"> \
<div class="block"> \
<dl class="notes"> \
<dd>$(OPENJDK_MODULE_REFERENCE_TEXT)</dd> \
</dl> \
</div> \
</section> \
\$(NEWLINE)<!-- ============ PACKAGES SUMMARY =========== -->
OPENJDK_JDK_MANAGEMENT_SUMMARY := Defines JDK-specific management interfaces for the JVM.
OPENJDK_JDK_MANAGEMENT_SUMMARY_ERROR_TEXT := \
Error: cannot find text '$(OPENJDK_JDK_MANAGEMENT_SUMMARY)' to replace in generated javadoc file $(OPENJ9_ONLY_INDEX_HTML). \
Check the openjdk jdk.management/module-info.java file and adjust closed/custom/Docs.gmk as required.
# sed_replace_block Replaces a multiline block with replacement text.
# sed matching is greedy.
# $1 should be unique (otherwise all lines from the first occurrence of $1 are deleted).
sed_replace_block = $(SED) '/$(subst /,\/,$(1))/,/$(subst /,\/,$(2))/{/$(subst /,\/,$(2))/ s/.*/$(subst /,\/,$(3))/; t; d}'
# sed_replace_first is a simple string replace, first occurrence only
sed_replace_first = $(SED) 's/$(subst /,\/,$(1))/$(subst /,\/,$(2))/'
# sed_replace_all is a simple string replace, all occurrences
sed_replace_all = $(SED) 's/$(subst /,\/,$(1))/$(subst /,\/,$(2))/g'
ALL_PACKAGE_INFO_FILELIST := $(call FindFiles, $(TOP_SRC_DIRS),package-info.java)
ALL_PACKAGE_INFO_FILELIST += $(call FindFiles, $(TOP_SRC_DIRS),package.html)
OPENJ9_ONLY_PACKAGE_INFO_FILELIST := $(filter %package-info.java, $(OPENJ9_ONLY_FILELIST))
OPENJDK_ONLY_PACKAGE_INFO_FILELIST := $(filter-out $(OPENJ9_ONLY_PACKAGE_INFO_FILELIST),$(ALL_PACKAGE_INFO_FILELIST))
OPENJDK_ONLY_PKGLIST := $(subst /package.html,,$(subst /package-info.java,,$(subst /share/classes,,$(subst $(TOPDIR)/src/,,$(OPENJDK_ONLY_PACKAGE_INFO_FILELIST)))))
OPENJ9_STUBS_DIR := $(SUPPORT_OUTPUTDIR)/openj9-docs/_javadoc_openj9_stub_files
OPENJ9_ONLY_PACKAGE_STUB_DESC := \
/** These are the classes within this package modified by OpenJ9. Refer to <a href="$(JAVASE_BASE_URL)" target="_blank">$(JAVASE_BASE_URL)</a> for the reference implementation documentation.*/
# This shell script replaces the text which came from the openjdk module-info.java files
# with a link to the same file in the Oracle online documentation.
# 1. Find all the module-summary.html files in the generated javadoc.
# 2. For each file, look for a corresponding module-info.java file in the openj9 source tree.
# 3. If there is no corresponding module-info.java file, replace the module description in the
# html file with the redirection text.
# 4. Find and replace the summary text also in the top level index.html file.
OPENJ9_ONLY_JAVADOC_SCRIPT_BODY = \
for file in `$(FIND) $(OPENJ9_ONLY_DOCDIR) -type f` ; do \
$(CP) -f "$$file" "$(OPENJ9_ONLY_JAVADOC_TEMP)" ; \
$(call sed_replace_all,class="externalLink",class="externalLink" target="_blank") <"$(OPENJ9_ONLY_JAVADOC_TEMP)" >"$$file" ; \
done ; \
for file in `cd $(OPENJ9_ONLY_DOCDIR) ; $(FIND) . -type f -name module-summary.html | $(SED) -e 's|^\./||'` ; do \
fullpath=$(OPENJ9_ONLY_DOCDIR)/$$file ; \
dir="$${file%/*}" ; \
topdir="$${file%%/*}" ; \
excepttopdir="$${file\#*/}" ; \
excepttopdir=`$(SED) 's|-summary.html$$|-info.java|' <<<$$excepttopdir` ; \
regex="$$topdir/.*$$excepttopdir" ; \
if ! $(GREP) -qe "$$regex" $(OPENJ9_ONLY_JAVADOC_FILES) ; then \
$(CP) -f "$$fullpath" "$(OPENJ9_ONLY_JAVADOC_TEMP)" ; \
$(call sed_replace_block,$(MODULE_DESCRIPTION_FIRST_LINE),$(MODULE_DESCRIPTION_LAST_LINE),$(MODULE_DESCRIPTION_REPLACE_TEXT)) <"$(OPENJ9_ONLY_JAVADOC_TEMP)" >"$$fullpath" ; \
$(RM) "$(OPENJ9_ONLY_JAVADOC_TEMP)" ; \
fi ; \
done ; \
if ! $(GREP) -q '$(OPENJDK_JDK_MANAGEMENT_SUMMARY)' $(OPENJ9_ONLY_INDEX_HTML) ; then \
$(ECHO) "$$0: $(OPENJDK_JDK_MANAGEMENT_SUMMARY_ERROR_TEXT)" ; \
exit 1 ; \
else \
$(CP) -f "$(OPENJ9_ONLY_INDEX_HTML)" "$(OPENJ9_ONLY_JAVADOC_TEMP)" ; \
$(call sed_replace_first,$(OPENJDK_JDK_MANAGEMENT_SUMMARY),$(OPENJDK_MODULE_REFERENCE_TEXT)) <"$(OPENJ9_ONLY_JAVADOC_TEMP)" >"$(OPENJ9_ONLY_INDEX_HTML)" ; \
$(RM) "$(OPENJ9_ONLY_JAVADOC_TEMP)" ; \
fi ; \
#
OPENJ9_ONLY_JAVADOC_SCRIPT_BODY_ESC = $(subst ','\'',$(OPENJ9_ONLY_JAVADOC_SCRIPT_BODY))
# Create a stub package-info.java file for each package with source files in
# $(J9JCL_SOURCES_DIR) but no package-info.java file. This is then used by javadoc
# instead of the openjdk version to direct the user to the Oracle online
# documentation for that package.
# The dependency on $(OPENJDK_JAVADOC_MARKER) ensures that the docs/api/element-list
# file which is created during the full jdk javadoc generation exists before running
# javadoc for just the openj9 files.
# If running on Windows, the source file names in the response file must be converted to
# Windows format before passing them to javadoc.
OPENJ9_ONLY_JAVADOC_FIXPATH_FILELIST := $(foreach file,$(OPENJ9_ONLY_JAVADOC_FILELIST),$(call FixPath,$(file)))
$(OPENJ9_ONLY_JAVADOC_MARKER) : $(OPENJDK_JAVADOC_MARKER) $(OPENJ9_ONLY_FILELIST)
$(call LogWarn, Generating javadoc for openj9 source files)
$(eval $(call ListPathsSafely,OPENJ9_ONLY_JAVADOC_FIXPATH_FILELIST,$(OPENJ9_ONLY_JAVADOC_FILES)))
for dir in $(OPENJDK_ONLY_PKGLIST) ; do \
$(MKDIR) -p $(OPENJ9_STUBS_DIR)/$${dir} ; \
$(ECHO) '$(OPENJ9_ONLY_PACKAGE_STUB_DESC)' >$(OPENJ9_STUBS_DIR)/$${dir}/package-info.java ; \
topdir="$${dir%%/*}" ; \
excepttopdir="$${dir#*/}" ; \
package=`$(SED) 's|/|.|g' <<<$${excepttopdir}` ; \
$(ECHO) "package $${package};" >>$(OPENJ9_STUBS_DIR)/$${dir}/package-info.java ; \
done
$(OPENJ9_ONLY_JAVADOC_CMD) -d $(OPENJ9_ONLY_DOCDIR) $(OPENJ9_ONLY_JAVADOC_OPTIONS) @$(OPENJ9_ONLY_JAVADOC_FILES)
$(ECHO) '$(OPENJ9_ONLY_JAVADOC_SCRIPT_BODY_ESC)' >$(OPENJ9_ONLY_JAVADOC_SCRIPT)
$(BASH) $(OPENJ9_ONLY_JAVADOC_SCRIPT)
$(RM) -rf $(OPENJ9_ONLY_JAVADOC_SCRIPT) $(OPENJ9_ONLY_JAVADOC_FILES) $(OPENJ9_STUBS_DIR)
$(TOUCH) $@