README

Table of Contents

• Introduction
• Files and Directories
• Specifications
• Building the compiler
• Running the compiler
• Testing the compiler

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

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:

• Java Language Specification (JLS)
• Java Virtual Machine Specification (JVMS)
• Java Compiler API (JSR 199)
• Pluggable Annotation Processing API (JSR 269)

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.

Notice regarding JSR 199 and JSR 269: 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.

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".

        % 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.

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

• Use the generated script, perhaps by putting it on your shell's command execution path.

      % install-dir/dist/bin/javac HelloWorld.java

  or

      % javac HelloWorld.java

• Execute javac.jar with the java command.

      % java -jar install-dir/dist/lib/javac.jar HelloWorld.java

• Execute javac.jar directly. Depending on your operating system, you may be able to execute the jar file directly.

      % install-dir/dist/lib/javac.jar HelloWorld.java

  See the Jar File Overview for details.

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