--- a/langtools/src/share/opensource/javac/README-template.html Wed Apr 23 14:35:26 2008 +0400
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,330 +0,0 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
-<!--
-Copyright 2006 Sun Microsystems, Inc. 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. Sun designates this
-particular file as subject to the "Classpath" exception as provided
-by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
-CA 95054 USA or visit www.sun.com if you need additional information or
-have any questions.
--->
-
-<html>
- <head>
- <meta name="jdk-version" content="$(JDK_VERSION)">
- <meta name="full-version" content="$(FULL_VERSION)">
- <meta name="release" content="$(RELEASE)">
- <meta name="date" content="$(BUILD_DATE)">
- <link href="doc/document.css" rel="stylesheet">
- <title>OpenJDK: javac -- README</title>
- <style type="text/css">
- p.noteX { margin-left:18pt; text-indent:-18pt }
- </style>
- </head>
- <body>
- <table width="100%" cellspacing="0" cellpadding="0" border="0"
- summary="This table is for formatting purposes only.">
- <tr>
- <td class="sun-darkblue"> </td>
- </tr>
- <tr>
- <td class="sun-darkblue">
- <h1>README</h1>
-
- <h2>Open JDK™ Java programming language compiler (<code>javac</code>)<br>
- Version $(RELEASE)
- <!--$(FULL_VERSION)--></h2>
- <h4>$(BUILD_DATE)</h4>
- </td>
- </tr>
- <tr>
- <td class="sun-lightblue"> </td>
- </tr>
- </table>
-
- <a name="top"></a>
-
- <!--<p class="nav-link">[<a href="#intro">Skip TOC</a>]</p>-->
-
- <h2>Table of Contents</h2>
-
- <ul>
- <li><a href="#intro">Introduction</a></li>
- <li><a href="#files">Files and Directories</a></li>
- <li><a href="#specs">Specifications</a></li>
- <li><a href="#build">Building the compiler</a></li>
- <li><a href="#run">Running the compiler</a></li>
- <li><a href="#test">Testing the compiler</a></li>
- </ul>
-
- <h2><a name="intro">Introduction</a></h2>
- <p>This bundle contains the source code for <code>javac</code>, a compiler for
- the Java™ programming language.
- Build files are provided for use with
- <a href="http://www.netbeans.org">NetBeans</a>,
- <a href="http://ant.apache.org/">Apache Ant</a> or
- <a href="http://www.gnu.org/software/make/">GNU make</a>.
- The bundle also contains a set of compiler tests, for use with the
- <a href="https://openjdk.dev.java.net/jtreg/">jtreg</a> test harness.
-
-
- <h2><a name="files">Files and Directories</a></h2>
- When you install the compiler bundle, a directory named
- <code>compiler</code> will be created, containing the following:
- <table>
- <thead>
- <tr><th>Name<th>Description
- </thead>
- <tbody>
- <tr>
- <td>README.html</td>
- <td>This file.</td>
- </tr>
- <tr>
- <td>nbproject/project.xml</td>
- <td>A NetBeans project file.
- </tr>
- <tr>
- <td>src/share/classes/</td>
- <td>The source files for the compiler.</td>
- </tr>
- <tr>
- <td>build.xml</td>
- <td>A build file for building the compiler, suitable for
- use with NetBeans and Apache Ant.</td>
- </tr>
- <tr>
- <td>build.properties</td>
- <td>Build properties, used by build.xml.</td>
- </tr>
- <tr>
- <td>Makefile</td>
- <td>A Makefile for building the compiler, suitable for use
- with GNU make.</td>
- </tr>
- <tr>
- <td>test/tools/javac/</td>
- <td>Regression tests for the compiler, for use with the JDK regression
- test harness, jtreg.</td>
- </tr>
- <tr>
- <td><a href="doc">doc/</a></td>
- <td>Additional notes about the compiler.</td>
- </tr>
- </tbody>
- </table>
-
- <h2><a name="specs">Specifications</a></h2>
- <p>The compiler is a program for compiling source code written in the Java
- programming language into class files suitable for execution on a Java
- virtual machine. It also provides API for annotation processing,
- and invoking the compiler programmatically.
- <p>These behaviors are governed by the following specifications:
- <ul>
- <li>Java Language Specification (JLS)</li>
- <li>Java Virtual Machine Specification (JVMS)</li>
- <li>Java Compiler API (JSR 199)</li>
- <li>Pluggable Annotation Processing API (JSR 269)</li>
- </ul>
- <p>For more details on these specifications, see the
- <a href="http://download.java.net/jdk6/docs/technotes/guides/javac/index.html">javac Guide</a>.
- </p>
-
- <p>These specifications are controlled by the Java Community Process
- (<a href="http://jcp.org/">JCP</a>.) All implementations of these specifications
- must pass the appropriate test suites.</p>
-
- <p><b>Notice regarding JSR 199 and JSR 269:</b>
- This is an implementation of an early-draft
- specification developed under the Java Community Process (JCP)
- and is made available for testing and evaluation purposes only.
- The code is not compatible with any specification of the JCP.
-
- <h2><a name="build">Building the compiler</a></h2>
-
- <h3>System Requirements</h3>
- <p><code>javac</code> is written in the Java programming language.
- As a general rule, it can normally be compiled using tools in the
- latest released version of the JDK.
- (That is, a development version of <code>javac</code> version 7
- can be built with JDK version 6, etc.)
- To <a href="#bootstrap">bootstrap</a> the compiler, you should also have
- a copy of the target JDK.</p>
-
- <p>You can build <code>javac</code> using
- <a href="#build.netbeans">NetBeans</a>,
- <a href="#build.ant">Apache Ant</a>,
- or <a href="#build.make">GNU make</a>.
- </p>
-
- <p>To run the compiler tests, you will need the
- <a href="https://openjdk.dev.java.net/jtreg/">jtreg test harness</a>.
-
- <h3><a name="bootstrap">Bootstrapping the compiler</a></h3>
-
- <p>The source for the compiler is such that it can be compiled using the latest
- publicly released version of the JDK.In practice, it is typically desirable
- to compile it first using the latest publicly released version of the JDK,
- and then again using itself, and the target platform on which it will be run.
- This not only provides a good initial test of the newly built compiler, it
- also means the compiler is built with the latest compiler sources, against
- the target libraries.
-
- <h3><a name="build.netbeans">Building with NetBeans</a></h3>
- <p>The installation directory for the compiler is set up as a free-form NetBeans project,
- so to build the compiler using NetBeans, you just have to open the
- project and build it in the normal way, for example, by using the operations
- on the <code>Build</code> menu.
- <p>To run the tests, you will have to edit properties in the
- <code>build.properties</code> file, to specify where you have installed
- the <code>jtreg</code> harness and, possibly, a different version of
- JDK to use when running the tests.
-
- <h3><a name="build.ant">Building with Apache Ant</a></h3>
- <p>To build the compiler, go to the compiler installation directory, and run "ant".</p>
- <pre>
- % cd <i>install-dir</i>
- % ant
- </pre>
- <p>To run the tests, you will have to edit properties in the
- <code>build.properties</code> file, to specify where you have installed
- the <code>jtreg</code> harness and, possibly, a different version of
- JDK to use when running the tests. Then, you can run the tests using the
- "test" target.
-
- <h3><a name="build.make">Building with GNU make</a></h3>
- <p>To build the compiler, go to the compiler installation directory, and type "make".</p>
- You should not have CLASSPATH and JAVAHOME environment variables set when you
- do this.
- <pre>
- % cd <i>install-dir</i>
- % make
- </pre>
- <p>To run the tests, you will have to specify where you have installed
- the <code>jtreg</code> harness and, possibly, a different version of
- JDK to use when running the tests. Then, you can run the tests using the
- "test" target. You can specify the values by giving them on the command
- line when you run <code>make</code> or by editing the values into the Makefile.
-
- <h3>What gets built?</h3>
- <p>Whichever build tool you use, the results are put in the <code>dist</code>
- subdirectory of your installation directory. The following files will be built.
- <table>
- <thead>
- <tr><th>Name<th>Description
- </thead>
- <tbody>
- <tr>
- <td>dist/lib/javac.jar</td>
- <td>This is an executable jar file containing the compiler.</td>
- </tr>
- <tr>
- <td>dist/bin/javac</td>
- <td>This is a simple shell script to invoke the compiler.</td>
- </tr>
- </tbody>
- </table>
-
- <h3>Notes</h3>
-
- <p class="note"><i>Property files:</i>
- It is possible to compile the resource property files into equivalent
- class files, for a minor performance improvement. For simplicity, that
- feature is not included here.</p>
-
- <p class="note"><i>The launcher:</i>
- JDK uses a program informally called "the launcher" which is used as
- a wrapper for all JDK tools, including <code>java</code>,
- <code>javac</code>, <code>javadoc</code>, and so on. The program is a deployed
- as a platform-dependent binary, thus obviating the need for a shell
- script to invoke the tools. Again for simplicity, and because that program
- is not normally considered part of <code>javac</code>, that program is
- not included here.</p
-
- <h2><a name="run">Running the compiler</a></h2>
- <p>Once you have built the compiler, you can run it in a number of ways.
- <ul>
- <li>
- <p>Use the generated script, perhaps by putting it on your shell's
- command execution path.</p>
- <pre> % <i>install-dir</i>/dist/bin/javac HelloWorld.java</pre>
- <p>or</p>
- <pre> % javac HelloWorld.java</pre>
- </li>
- <li><p>Execute javac.jar with the <code>java</code> command.</p>
- <pre> % java -jar <i>install-dir</i>/dist/lib/javac.jar HelloWorld.java</pre>
- </li>
- <li><p>Execute javac.jar directly. Depending on your operating system,
- you may be able to execute the jar file directly.</p>
- <pre> % <i>install-dir</i>/dist/lib/javac.jar HelloWorld.java</pre>
- <p>See the
- <a href="http://java.sun.com/j2se/1.5.0/docs/guide/jar/jarGuide.html">Jar File Overview</a>
- for details.</p>
- </li>
- </ul>
-
- <h2><a name="test">Testing the compiler with <code>jtreg</code></h2>
- <p>This bundle contains a large test suite of unit and regression tests
- used to test <code>javac</code>. They are part of the JDK Regression Test
- Suite, which uses the
- <a href="https://openjdk.dev.java.net/jtreg/">jtreg test harness</a>.
- This harness is
- designed to run both API-style tests, and command-line tests, such as
- found in the tests for <code>javac</code>.</p>
-
- <p>The simplest way to run the tests is to prepend the newly created
- copy of <code>javac.jar</code> to the bootstrap class path of a
- compatible version of JDK (meaning, it must accept the class file
- versions of newly compiled classes.) To do this, you can use
- the <code>-Xbootclasspath/p:</code><i><path></i> option
- for <code>jtreg</code>. This option is similar to the equivalent
- option for the <code>java</code> command.
-
- <p><i><b>Note:</b>Some of the tests, written as shell tests, do not yet
- support this mode of operation. You should use the
- <code>-noshell</code> to disable these tests for the time being.
- This restriction will be lifted in the near future.</i>
-
- <p><i><b>Note:</b>Four additional tests are ignored, using the <code>jtreg</code>
- <code>@ignore</code> tag, because of problems caused by bugs that have not yet
- been addressed.
-
- <p>You can run the compiler tests with a command such as the following:</p>
-
- <pre> % jtreg -jdk:<i>jdk</i> -Xbootclasspath/p:<i>my-javac.jar</i> -verbose -noshell test/tools/javac</pre>
-
- <p>Depending on the verbose options used, some amount of detail of the result
- of each test is written to the console. In addition, an HTML report about the
- entire test run is written to a report directory, and a results file is written for
- each test, in a "work" directory. The location of these directories can be
- specified on the <code>jtreg</code> command line; the actual locations used
- are reported to the console at the conclusion of the test run.
-
- <p>For more information on <code>jtreg</code>, use the
- the <code>-help</code> option for command-line help, or
- the <code>-onlineHelp</code> option for the built-in online help.
- Both of these options may optionally be followed by search
- keywords</p>
-
- <p><code>jtreg</code> can also be run from Ant. See
- <code>jtreg -onlineHelp ant</code> for details.</p>
-
- <p>Both <code>build.xml</code> and <code>Makefile</code> contain "test" targets for running the tests.
-
- </body>
-</html>