mirror of
https://github.com/openjdk/jdk.git
synced 2026-04-10 15:08:43 +00:00
331 lines
15 KiB
HTML
331 lines
15 KiB
HTML
<!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>
|