README

Open JDK™ Java programming language compiler (javac)
Version 1.7.0-ea

November 2006, updated June 2007
 

Notes

June 2007

These instructions apply to the files found in the compiler source bundle. They do not directly apply to the files available in the OpenJDK Subversion repository. The source code for the compiler is the same in both cases, but the infrastructure files, such as the NetBeans project file, Ant build file, and Makefile are slightly different.

Table of Contents

Introduction

This bundle contains the source code for javac, a compiler for the Java programming language. Build files are provided for use with NetBeans, Apache Ant or GNU make. The bundle also contains a set of compiler tests, for use with the jtreg test harness.

Files and Directories

When you install the compiler bundle, a directory named compiler will be created, containing the following:
Name Description
README.html This file.
nbproject/project.xml A NetBeans project file.
src/share/classes/ The source files for the compiler.
build.xml A build file for building the compiler, suitable for use with NetBeans and Apache Ant.
build.properties Build properties, used by build.xml.
Makefile A Makefile for building the compiler, suitable for use with GNU make.
test/tools/javac/ Regression tests for the compiler, for use with the JDK regression test harness, jtreg.

Specifications

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.

These behaviors are governed by the following specifications:

For more details on these specifications, see the javac Guide.

These specifications are controlled by the Java Community Process (JCP.) All implementations of these specifications must pass the appropriate test suites.

Building the compiler

System Requirements

javac 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 javac version 7 can be built with JDK version 6, etc.) To bootstrap the compiler, you should also have a copy of the target JDK.

You can build javac using NetBeans, Apache Ant, or GNU make.

To run the compiler tests, you will need the jtreg test harness.

Bootstrapping the compiler

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.

Building with NetBeans

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 Build menu.

To run the tests, you will have to edit properties in the build.properties file, to specify where you have installed the jtreg harness and, possibly, a different version of JDK to use when running the tests.

Building with Apache Ant

To build the compiler, go to the compiler installation directory, and run "ant".

        % cd install-dir
        % ant

To run the tests, you will have to edit properties in the build.properties file, to specify where you have installed the jtreg harness and, possibly, a different version of JDK to use when running the tests. Then, you can run the tests using the "test" target.

Building with GNU make

To build the compiler, go to the compiler installation directory, and type "make".

You should not have CLASSPATH and JAVAHOME environment variables set when you do this. 
        % cd install-dir
        % make

To run the tests, you will have to specify where you have installed the jtreg 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 make or by editing the values into the Makefile.

What gets built?

Whichever build tool you use, the results are put in the dist subdirectory of your installation directory. The following files will be built.

Name Description
dist/lib/javac.jar This is an executable jar file containing the compiler.
dist/bin/javac This is a simple shell script to invoke the compiler.

Notes

Property files: 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.

The launcher: JDK uses a program informally called "the launcher" which is used as a wrapper for all JDK tools, including java, javac, javadoc, 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 javac, that program is not included here.

Running the compiler

Once you have built the compiler, you can run it in a number of ways.

Testing the compiler with jtreg

This bundle contains a large test suite of unit and regression tests used to test javac. They are part of the JDK Regression Test Suite, which uses the jtreg test harness. This harness is designed to run both API-style tests, and command-line tests, such as found in the tests for javac.

The simplest way to run the tests is to prepend the newly created copy of javac.jar 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 -Xbootclasspath/p:<path> option for jtreg. This option is similar to the equivalent option for the java command.

Note:Some of the tests, written as shell tests, do not yet support this mode of operation. You should use the -noshell to disable these tests for the time being. This restriction will be lifted in the near future.

Note:Four additional tests are ignored, using the jtreg @ignore tag, because of problems caused by bugs that have not yet been addressed.

You can run the compiler tests with a command such as the following:

    % jtreg -jdk:jdk -Xbootclasspath/p:my-javac.jar -verbose -noshell test/tools/javac

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 jtreg command line; the actual locations used are reported to the console at the conclusion of the test run.

For more information on jtreg, use the the -help option for command-line help, or the -onlineHelp option for the built-in online help. Both of these options may optionally be followed by search keywords

jtreg can also be run from Ant. See jtreg -onlineHelp ant for details.

Both build.xml and Makefile contain "test" targets for running the tests.