| - |
- README- -Open JDK™ Java programming language compiler (
- |
-
| - |
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.
-
-
-
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. | -
| doc/ | -Additional notes about the compiler. | -
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.
- -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. - -
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. - -
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. - -
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.
-
-
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.
-
-
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.
-
-
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. | -
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.
-jtregThis 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.
-
-
-
diff -r ff76730e430e -r 68aea6dcb358 langtools/src/share/opensource/javac/build.properties
--- a/langtools/src/share/opensource/javac/build.properties Wed Mar 12 13:06:00 2008 -0700
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,13 +0,0 @@
-build.jdk.version = 1.7.0
-build.release = ${build.jdk.version}-opensource
-build.number = b00
-build.user.release.suffix = ${user.name}_${build.fullversion.time}
-build.full.version = ${build.release}-${build.user.release.suffix}-${build.number}
-
-# Set jtreg.home to jtreg installation directory
-# jtreg.home =
-
-# Set test.jdk.home to baseline JDK used to run the tests
-# test.jdk.home =
-
-compiler.source.level = 1.5
diff -r ff76730e430e -r 68aea6dcb358 langtools/src/share/opensource/javac/build.xml
--- a/langtools/src/share/opensource/javac/build.xml Wed Mar 12 13:06:00 2008 -0700
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,163 +0,0 @@
-
-
-
Contexts provides a way to share data between the different parts of - the compiler.
- -They provide support for an abstract context, modelled loosely after - ThreadLocal but using a user-provided context instead of the current - thread.
- -Within the compiler, a single Context is used for each - invocation of the compiler. The context is then used to ensure a - single copy of each compiler phase exists per compiler invocation.
- -The context can be used to assist in extending the compiler by - extending its components. To do that, the extended component must - be registered before the base component. We break initialization - cycles by (1) registering a factory for the component rather than - the component itself, and (2) a convention for a pattern of usage - in which each base component registers itself by calling an - instance method that is overridden in extended components. A base - phase supporting extension would look something like this:
- -
- public class Phase {
- protected static final Context.Key<Phase> phaseKey =
- new Context.Key<Phase>();
-
- public static Phase instance(Context context) {
- Phase instance = context.get(phaseKey);
- if (instance == null)
- // the phase has not been overridden
- instance = new Phase(context);
- return instance;
- }
-
- protected Phase(Context context) {
- context.put(phaseKey, this);
- // other intitialization follows...
- }
- }
-
-
- In the compiler, we simply use Phase.instance(context) to get - the reference to the phase. But in extensions of the compiler, we - must register extensions of the phases to replace the base phase, - and this must be done before any reference to the phase is accessed - using Phase.instance(). An extended phase might be declared thus:
- -
- public class NewPhase extends Phase {
- protected NewPhase(Context context) {
- super(context);
- }
- public static void preRegister(final Context context) {
- context.put(phaseKey, new Context.Factory<Phase>() {
- public Phase make() {
- return new NewPhase(context);
- }
- });
- }
- }
-
-
- And is registered early in the extended compiler like this:
- -- NewPhase.preRegister(context); -- - - - diff -r ff76730e430e -r 68aea6dcb358 langtools/src/share/opensource/javac/doc/javac_lifecycle/Enter.html --- a/langtools/src/share/opensource/javac/doc/javac_lifecycle/Enter.html Wed Mar 12 13:06:00 2008 -0700 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,90 +0,0 @@ - - - - - - - - -
In the first phase, all class symbols are entered into their - enclosing scope, descending recursively down the tree for classes - which are members of other classes. The class symbols are given a - MemberEnter object as completer.
In addition, - if any package-info.java files are found, - containing package annotations, then the TopLevel tree node for - the package-info.java file is put on the "to do" as well. -
- -In the second phase, classes are completed using - MemberEnter.complete(). Completion might occur on demand, but - any classes that are not completed that way will be eventually - completed by processing the `uncompleted' queue. Completion - entails -
Whereas the first phase is organized as a sweep through all - compiled syntax trees, the second phase is demand. Members of a - class are entered when the contents of a class are first - accessed. This is accomplished by installing completer objects in - class symbols for compiled classes which invoke the member-enter - phase for the corresponding class tree.
- -Classes migrate from one phase to the next via queues:
- -- class enter -> (Enter.uncompleted) --> member enter (1) - -> (MemberEnter.halfcompleted) --> member enter (2) - -> (Todo) --> attribute - (only for toplevel classes) -- - - - diff -r ff76730e430e -r 68aea6dcb358 langtools/src/share/opensource/javac/doc/javac_lifecycle/JavaCompiler.html --- a/langtools/src/share/opensource/javac/doc/javac_lifecycle/JavaCompiler.html Wed Mar 12 13:06:00 2008 -0700 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,79 +0,0 @@ - - - - - - - - -
- JavaCompiler provides (and enforces) a use-once method to compile a list of source files.
- It invokes the various phases of the compiler to cause those source files to be compiled.
-
- Note: Additional files may be parsed later, if they are found on the class/source path, and if they are newer than their matching class file. -
-JavaCompiler processes entries from the "to do" list.
- In so doing, the compiler might find additional classes that need to be
- processed, which may result in additional entries being added to the
- "to do" list. (more...)
-
- The normal main entry point is
- com.sun.tools.javac.main.Main,
- with a public API entry point at
- com.sun.tools.javac.Main which just calls down to com.sun.tools.javac.main.Main.
-
The various parts of the compiler share common information by means of a - Context. - Every invocation of the compiler must have its own Context. - -
- com.sun.tools.javac.main.Main does command line processing to determine the list of files to be compiled, and any applicable options. There are four types of options:
-
-classpath
- -Xlint
- Main invokes
- JavaCompiler (more...)
- After JavaCompiler completes, the list of class symbols that was returned is discarded.
-
-
- - Any and all exceptions are caught and handled, and a return code is - determined. Finally, the compiler exits. -
- - - diff -r ff76730e430e -r 68aea6dcb358 langtools/src/share/opensource/javac/doc/javac_lifecycle/ToDo.html --- a/langtools/src/share/opensource/javac/doc/javac_lifecycle/ToDo.html Wed Mar 12 13:06:00 2008 -0700 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,167 +0,0 @@ - - - - -
- - - -- After the source files have been parsed, and their symbols entered - in the symbol table, the top level classes and some other items end - up on JavaCompiler's "to do" list. -
- -
- For each entry on the "to do" list, JavaCompiler
- processes it as follows:
-
Some parts of the compilation involve modifying the parse tree, - so a copy of the root of the tree is kept prior to such manipulation. -
-- Note: this copy is just used to check whether the class is one of those - found in a compilation unit on the command line (i.e. in rootClasses). -
- -The top level classes are "attributed", using
- Attr,
- meaning that names and other elements within the parse tree are resolved
- and associated with the corresponding types and symbols. Many semantic
- errors may be detected here, either by Attr, or by
- Check.
-
While attributing the tree, class files will be read as necessary. - In addition, if a class is required, and a source file for the class is found - that is newer than the class file, the source file will be automatically parsed - and put on the "to do" list. This is done by registering JavaCompiler as an - implementation of - Attr.SourceCompleter. -
-
- Note: there is a hidden option -attrparseonly which can be used to skip
- the rest of the processing for this file. In so doing, it "breaks" the
- protocol use to save and restore the source file used to report error
- messages (Log.useSource). There is a "try finally" block which
- could reasonably be used/extended to restore the source file correctly.
-
If there are no errors so far, flow analysis will be done for the class, using - Flow. - Flow analysis is used to check for definite assignment to variables, - and unreachable statements, which may result in additional errors. -
-Note: flow analysis can be suppressed with the hidden
- option -relax.
-
Lower is defined to return a list of trees for the translated classes
- and all the translated inner classes.Lower returns a non-empty list, there is an assertion that
- the list has a single element, in which case, code is generated, using
- Gen,
- and the resulting code is written out using
- ClassWriter.
- Note that Enter will have processed all other TopLevel - putting the individual classes that it finds there on the "to do" - (and not the TopLevel node itself.) -
- --stubs option,
- -s option
- Lower is defined to return a list of trees for the translated classes
- and all the translated inner classes.
- Note: see also the use of Lower earlier in the loop, when processing
- TopLevel trees.
Lower-printflat
- option, the source of the class is printed.
- With the exception of a publicly supported entry point at - com.sun.tools.javac.Main, - javac is organized as a set of packages under - com.sun.tools.javac. -
- -| Sub-package | Description - | ||
|---|---|---|---|
| code - | Classes to represent the internal semantics of a Java program -- - types, symbols, etc. - - | ||
| comp - | Classes that analyse and annotate the parse tree with semantic - details, such as determining the types and symbols referred to by identifiers. - - | ||
| jvm - | Back end classes to read and write class files. - - | ||
| main - | Top-level driver classes. The standard entry point to the compiler is - com.sun.tools.javac.main.Main (more...) - - | ||
| parser - | Classes to read a Java source file and create a corresponding parse tree. - - | ||
| resources - | Resource classes for messages generated by the compiler. Two of the - three classes are automagically generated by a "property file compiler" - from a property source file; the third is automagically generated during - the build to contain build version information. - - | ||
| tree - | Classes representing an annotated syntax tree for a Java program.
- The top level node, representing the contents of a source file is
- Tree.TopLevel.
-
- | util
- | Utility classes used throughout the compiler, providing support for
- diagnostics, access to the file system, and javac's collection classes.
-
-
-
diff -r ff76730e430e -r 68aea6dcb358 langtools/src/share/opensource/javac/doc/javac_lifecycle/style.css
--- a/langtools/src/share/opensource/javac/doc/javac_lifecycle/style.css Wed Mar 12 13:06:00 2008 -0700
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,33 +0,0 @@
-/*
- * 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.
- */
-
-body { color: black; background-color: #eeffee }
-body.contents { background-color: #ddffdd }
-
-li { margin-top:10px }
-p.note { font-size:smaller }
-
-.code { font-family:monospace }
-
diff -r ff76730e430e -r 68aea6dcb358 langtools/src/share/opensource/javac/nbproject/project.xml
--- a/langtools/src/share/opensource/javac/nbproject/project.xml Wed Mar 12 13:06:00 2008 -0700
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,88 +0,0 @@
-
-
-
-
- | |