<!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>