7197849: Update new build-infra makefiles
Reviewed-by: ihse, erikj, ohrstrom, tbell
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>Doc Process Notes</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
</head>
<body>
<h3><a name="REGEXP"></a><br>
REGEXP</h3>
<p> REGEXP is a list of wildcard patterns that determines which packages listed
in CORE_PKGS.gmk go into which summary-table on the main API index page. It
was motivated by the need to divide the world into "core packages"
(java.*) and "extension packages" (javax.*). In time, the distinction
went away. The whole table is now called "Platform Packages"--which
eliminated the need for this list of regular expressions. But it lingered on,
accreting all of the packages in the JVM, one by one. I pruned it back to "*",
so it now covers every package in the Java platform API docs. If some separation
is needed in the future, it can grow back into a colon-separated list, starting
with this, which is in all respects equivalent to "*" at this point
in time:</p>
<blockquote>
<pre>REGEXP = "java.*:javax.*:org.ietf*:org.omg.</pre>
</blockquote>
<h3><a name="releaseTargets"></a><br>
Release Targets</h3>
<p> (Thanks to Kelly O'Hair for this info.)</p>
<p> The <tt>rel-coredocs</tt> and <tt>rel-docs</tt> targets were added by Eric
Armstrong. <tt>rel-coredocs</tt> assumes the kind of large, 32-bit machine used
in the javapubs group's docs-release process. It specifies memory settings accordingly
to maximize performance.</p>
<p> The performance settings, like the sanity check, are most important for the
core docs--the platform APIs. Running javadoc on those APIs takes a significant
amount of time and memory. Setting the initial heap size as large as possible
is important to prevent thrashing as the heap grows. Setting the maximum as
large as necessary is also important to keep the job from failing.</p>
<blockquote>
<p> <tt>-J-Xmx512</tt> sets a maximum of 512, which became necessary in 6.0<br>
<tt>-J-Xms256</tt> sets starting size to 256 (default is 8)</p>
</blockquote>
<p> <tt>rel-coredocs</tt> also includes a sanity check to help ensure that <tt>BUILD_NUMBER</tt>
and <tt>MILESTONE</tt> are specified properly when docs are built outside of
the normal release engineering process, with the intention of releasing them
on the web or in a downloaded docs bundle. (When invoked in release engineering's
control build, the values are always set properly. But when the targets are
run by themselves, they default to b00 and "internal"--which silently
sabotage the result of a build that can take many hours to complete.</p>
</body>
</html>