Mercurial > jdk8-mips64-public / annotate
common/makefiles/javadoc/Notes.html@2ba6f4da4bf3 (annotated)
common/makefiles/javadoc/Notes.html
Tue, 18 Sep 2012 11:29:16 -0700
- author
- ohair
- date
- Tue, 18 Sep 2012 11:29:16 -0700
- changeset 478
- 2ba6f4da4bf3
- child 839
- 174a54ce39c4
- permissions
- -rw-r--r--
7197849: Update new build-infra makefiles
Reviewed-by: ihse, erikj, ohrstrom, tbell
| ohair@478 | 1 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> |
| ohair@478 | 2 | <html> |
| ohair@478 | 3 | <head> |
| ohair@478 | 4 | <title>Doc Process Notes</title> |
| ohair@478 | 5 | <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> |
| ohair@478 | 6 | </head> |
| ohair@478 | 7 | |
| ohair@478 | 8 | <body> |
| ohair@478 | 9 | <h3><a name="REGEXP"></a><br> |
| ohair@478 | 10 | REGEXP</h3> |
| ohair@478 | 11 | <p> REGEXP is a list of wildcard patterns that determines which packages listed |
| ohair@478 | 12 | in CORE_PKGS.gmk go into which summary-table on the main API index page. It |
| ohair@478 | 13 | was motivated by the need to divide the world into "core packages" |
| ohair@478 | 14 | (java.*) and "extension packages" (javax.*). In time, the distinction |
| ohair@478 | 15 | went away. The whole table is now called "Platform Packages"--which |
| ohair@478 | 16 | eliminated the need for this list of regular expressions. But it lingered on, |
| ohair@478 | 17 | accreting all of the packages in the JVM, one by one. I pruned it back to "*", |
| ohair@478 | 18 | so it now covers every package in the Java platform API docs. If some separation |
| ohair@478 | 19 | is needed in the future, it can grow back into a colon-separated list, starting |
| ohair@478 | 20 | with this, which is in all respects equivalent to "*" at this point |
| ohair@478 | 21 | in time:</p> |
| ohair@478 | 22 | <blockquote> |
| ohair@478 | 23 | <pre>REGEXP = "java.*:javax.*:org.ietf*:org.omg.</pre> |
| ohair@478 | 24 | </blockquote> |
| ohair@478 | 25 | <h3><a name="releaseTargets"></a><br> |
| ohair@478 | 26 | Release Targets</h3> |
| ohair@478 | 27 | <p> (Thanks to Kelly O'Hair for this info.)</p> |
| ohair@478 | 28 | <p> The <tt>rel-coredocs</tt> and <tt>rel-docs</tt> targets were added by Eric |
| ohair@478 | 29 | Armstrong. <tt>rel-coredocs</tt> assumes the kind of large, 32-bit machine used |
| ohair@478 | 30 | in the javapubs group's docs-release process. It specifies memory settings accordingly |
| ohair@478 | 31 | to maximize performance.</p> |
| ohair@478 | 32 | <p> The performance settings, like the sanity check, are most important for the |
| ohair@478 | 33 | core docs--the platform APIs. Running javadoc on those APIs takes a significant |
| ohair@478 | 34 | amount of time and memory. Setting the initial heap size as large as possible |
| ohair@478 | 35 | is important to prevent thrashing as the heap grows. Setting the maximum as |
| ohair@478 | 36 | large as necessary is also important to keep the job from failing.</p> |
| ohair@478 | 37 | <blockquote> |
| ohair@478 | 38 | <p> <tt>-J-Xmx512</tt> sets a maximum of 512, which became necessary in 6.0<br> |
| ohair@478 | 39 | <tt>-J-Xms256</tt> sets starting size to 256 (default is 8)</p> |
| ohair@478 | 40 | </blockquote> |
| ohair@478 | 41 | <p> <tt>rel-coredocs</tt> also includes a sanity check to help ensure that <tt>BUILD_NUMBER</tt> |
| ohair@478 | 42 | and <tt>MILESTONE</tt> are specified properly when docs are built outside of |
| ohair@478 | 43 | the normal release engineering process, with the intention of releasing them |
| ohair@478 | 44 | on the web or in a downloaded docs bundle. (When invoked in release engineering's |
| ohair@478 | 45 | control build, the values are always set properly. But when the targets are |
| ohair@478 | 46 | run by themselves, they default to b00 and "internal"--which silently |
| ohair@478 | 47 | sabotage the result of a build that can take many hours to complete.</p> |
| ohair@478 | 48 | </body> |
| ohair@478 | 49 | </html> |
