1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> |
|
2 <!-- |
|
3 Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. |
|
4 DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
|
5 |
|
6 This code is free software; you can redistribute it and/or modify it |
|
7 under the terms of the GNU General Public License version 2 only, as |
|
8 published by the Free Software Foundation. Sun designates this |
|
9 particular file as subject to the "Classpath" exception as provided |
|
10 by Sun in the LICENSE file that accompanied this code. |
|
11 |
|
12 This code is distributed in the hope that it will be useful, but WITHOUT |
|
13 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
|
14 FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
|
15 version 2 for more details (a copy is included in the LICENSE file that |
|
16 accompanied this code). |
|
17 |
|
18 You should have received a copy of the GNU General Public License version |
|
19 2 along with this work; if not, write to the Free Software Foundation, |
|
20 Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. |
|
21 |
|
22 Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, |
|
23 CA 95054 USA or visit www.sun.com if you need additional information or |
|
24 have any questions. |
|
25 --> |
|
26 |
|
27 <html> |
|
28 <head> |
|
29 <meta name="jdk-version" content="$(JDK_VERSION)"> |
|
30 <meta name="full-version" content="$(FULL_VERSION)"> |
|
31 <meta name="release" content="$(RELEASE)"> |
|
32 <meta name="date" content="$(BUILD_DATE)"> |
|
33 <link href="doc/document.css" rel="stylesheet"> |
|
34 <title>OpenJDK: javac -- README</title> |
|
35 <style type="text/css"> |
|
36 p.noteX { margin-left:18pt; text-indent:-18pt } |
|
37 </style> |
|
38 </head> |
|
39 <body> |
|
40 <table width="100%" cellspacing="0" cellpadding="0" border="0" |
|
41 summary="This table is for formatting purposes only."> |
|
42 <tr> |
|
43 <td class="sun-darkblue"> </td> |
|
44 </tr> |
|
45 <tr> |
|
46 <td class="sun-darkblue"> |
|
47 <h1>README</h1> |
|
48 |
|
49 <h2>Open JDK™ Java programming language compiler (<code>javac</code>)<br> |
|
50 Version $(RELEASE) |
|
51 <!--$(FULL_VERSION)--></h2> |
|
52 <h4>$(BUILD_DATE)</h4> |
|
53 </td> |
|
54 </tr> |
|
55 <tr> |
|
56 <td class="sun-lightblue"> </td> |
|
57 </tr> |
|
58 </table> |
|
59 |
|
60 <a name="top"></a> |
|
61 |
|
62 <!--<p class="nav-link">[<a href="#intro">Skip TOC</a>]</p>--> |
|
63 |
|
64 <h2>Table of Contents</h2> |
|
65 |
|
66 <ul> |
|
67 <li><a href="#intro">Introduction</a></li> |
|
68 <li><a href="#files">Files and Directories</a></li> |
|
69 <li><a href="#specs">Specifications</a></li> |
|
70 <li><a href="#build">Building the compiler</a></li> |
|
71 <li><a href="#run">Running the compiler</a></li> |
|
72 <li><a href="#test">Testing the compiler</a></li> |
|
73 </ul> |
|
74 |
|
75 <h2><a name="intro">Introduction</a></h2> |
|
76 <p>This bundle contains the source code for <code>javac</code>, a compiler for |
|
77 the Java™ programming language. |
|
78 Build files are provided for use with |
|
79 <a href="http://www.netbeans.org">NetBeans</a>, |
|
80 <a href="http://ant.apache.org/">Apache Ant</a> or |
|
81 <a href="http://www.gnu.org/software/make/">GNU make</a>. |
|
82 The bundle also contains a set of compiler tests, for use with the |
|
83 <a href="https://openjdk.dev.java.net/jtreg/">jtreg</a> test harness. |
|
84 |
|
85 |
|
86 <h2><a name="files">Files and Directories</a></h2> |
|
87 When you install the compiler bundle, a directory named |
|
88 <code>compiler</code> will be created, containing the following: |
|
89 <table> |
|
90 <thead> |
|
91 <tr><th>Name<th>Description |
|
92 </thead> |
|
93 <tbody> |
|
94 <tr> |
|
95 <td>README.html</td> |
|
96 <td>This file.</td> |
|
97 </tr> |
|
98 <tr> |
|
99 <td>nbproject/project.xml</td> |
|
100 <td>A NetBeans project file. |
|
101 </tr> |
|
102 <tr> |
|
103 <td>src/share/classes/</td> |
|
104 <td>The source files for the compiler.</td> |
|
105 </tr> |
|
106 <tr> |
|
107 <td>build.xml</td> |
|
108 <td>A build file for building the compiler, suitable for |
|
109 use with NetBeans and Apache Ant.</td> |
|
110 </tr> |
|
111 <tr> |
|
112 <td>build.properties</td> |
|
113 <td>Build properties, used by build.xml.</td> |
|
114 </tr> |
|
115 <tr> |
|
116 <td>Makefile</td> |
|
117 <td>A Makefile for building the compiler, suitable for use |
|
118 with GNU make.</td> |
|
119 </tr> |
|
120 <tr> |
|
121 <td>test/tools/javac/</td> |
|
122 <td>Regression tests for the compiler, for use with the JDK regression |
|
123 test harness, jtreg.</td> |
|
124 </tr> |
|
125 <tr> |
|
126 <td><a href="doc">doc/</a></td> |
|
127 <td>Additional notes about the compiler.</td> |
|
128 </tr> |
|
129 </tbody> |
|
130 </table> |
|
131 |
|
132 <h2><a name="specs">Specifications</a></h2> |
|
133 <p>The compiler is a program for compiling source code written in the Java |
|
134 programming language into class files suitable for execution on a Java |
|
135 virtual machine. It also provides API for annotation processing, |
|
136 and invoking the compiler programmatically. |
|
137 <p>These behaviors are governed by the following specifications: |
|
138 <ul> |
|
139 <li>Java Language Specification (JLS)</li> |
|
140 <li>Java Virtual Machine Specification (JVMS)</li> |
|
141 <li>Java Compiler API (JSR 199)</li> |
|
142 <li>Pluggable Annotation Processing API (JSR 269)</li> |
|
143 </ul> |
|
144 <p>For more details on these specifications, see the |
|
145 <a href="http://download.java.net/jdk6/docs/technotes/guides/javac/index.html">javac Guide</a>. |
|
146 </p> |
|
147 |
|
148 <p>These specifications are controlled by the Java Community Process |
|
149 (<a href="http://jcp.org/">JCP</a>.) All implementations of these specifications |
|
150 must pass the appropriate test suites.</p> |
|
151 |
|
152 <p><b>Notice regarding JSR 199 and JSR 269:</b> |
|
153 This is an implementation of an early-draft |
|
154 specification developed under the Java Community Process (JCP) |
|
155 and is made available for testing and evaluation purposes only. |
|
156 The code is not compatible with any specification of the JCP. |
|
157 |
|
158 <h2><a name="build">Building the compiler</a></h2> |
|
159 |
|
160 <h3>System Requirements</h3> |
|
161 <p><code>javac</code> is written in the Java programming language. |
|
162 As a general rule, it can normally be compiled using tools in the |
|
163 latest released version of the JDK. |
|
164 (That is, a development version of <code>javac</code> version 7 |
|
165 can be built with JDK version 6, etc.) |
|
166 To <a href="#bootstrap">bootstrap</a> the compiler, you should also have |
|
167 a copy of the target JDK.</p> |
|
168 |
|
169 <p>You can build <code>javac</code> using |
|
170 <a href="#build.netbeans">NetBeans</a>, |
|
171 <a href="#build.ant">Apache Ant</a>, |
|
172 or <a href="#build.make">GNU make</a>. |
|
173 </p> |
|
174 |
|
175 <p>To run the compiler tests, you will need the |
|
176 <a href="https://openjdk.dev.java.net/jtreg/">jtreg test harness</a>. |
|
177 |
|
178 <h3><a name="bootstrap">Bootstrapping the compiler</a></h3> |
|
179 |
|
180 <p>The source for the compiler is such that it can be compiled using the latest |
|
181 publicly released version of the JDK.In practice, it is typically desirable |
|
182 to compile it first using the latest publicly released version of the JDK, |
|
183 and then again using itself, and the target platform on which it will be run. |
|
184 This not only provides a good initial test of the newly built compiler, it |
|
185 also means the compiler is built with the latest compiler sources, against |
|
186 the target libraries. |
|
187 |
|
188 <h3><a name="build.netbeans">Building with NetBeans</a></h3> |
|
189 <p>The installation directory for the compiler is set up as a free-form NetBeans project, |
|
190 so to build the compiler using NetBeans, you just have to open the |
|
191 project and build it in the normal way, for example, by using the operations |
|
192 on the <code>Build</code> menu. |
|
193 <p>To run the tests, you will have to edit properties in the |
|
194 <code>build.properties</code> file, to specify where you have installed |
|
195 the <code>jtreg</code> harness and, possibly, a different version of |
|
196 JDK to use when running the tests. |
|
197 |
|
198 <h3><a name="build.ant">Building with Apache Ant</a></h3> |
|
199 <p>To build the compiler, go to the compiler installation directory, and run "ant".</p> |
|
200 <pre> |
|
201 % cd <i>install-dir</i> |
|
202 % ant |
|
203 </pre> |
|
204 <p>To run the tests, you will have to edit properties in the |
|
205 <code>build.properties</code> file, to specify where you have installed |
|
206 the <code>jtreg</code> harness and, possibly, a different version of |
|
207 JDK to use when running the tests. Then, you can run the tests using the |
|
208 "test" target. |
|
209 |
|
210 <h3><a name="build.make">Building with GNU make</a></h3> |
|
211 <p>To build the compiler, go to the compiler installation directory, and type "make".</p> |
|
212 You should not have CLASSPATH and JAVAHOME environment variables set when you |
|
213 do this. |
|
214 <pre> |
|
215 % cd <i>install-dir</i> |
|
216 % make |
|
217 </pre> |
|
218 <p>To run the tests, you will have to specify where you have installed |
|
219 the <code>jtreg</code> harness and, possibly, a different version of |
|
220 JDK to use when running the tests. Then, you can run the tests using the |
|
221 "test" target. You can specify the values by giving them on the command |
|
222 line when you run <code>make</code> or by editing the values into the Makefile. |
|
223 |
|
224 <h3>What gets built?</h3> |
|
225 <p>Whichever build tool you use, the results are put in the <code>dist</code> |
|
226 subdirectory of your installation directory. The following files will be built. |
|
227 <table> |
|
228 <thead> |
|
229 <tr><th>Name<th>Description |
|
230 </thead> |
|
231 <tbody> |
|
232 <tr> |
|
233 <td>dist/lib/javac.jar</td> |
|
234 <td>This is an executable jar file containing the compiler.</td> |
|
235 </tr> |
|
236 <tr> |
|
237 <td>dist/bin/javac</td> |
|
238 <td>This is a simple shell script to invoke the compiler.</td> |
|
239 </tr> |
|
240 </tbody> |
|
241 </table> |
|
242 |
|
243 <h3>Notes</h3> |
|
244 |
|
245 <p class="note"><i>Property files:</i> |
|
246 It is possible to compile the resource property files into equivalent |
|
247 class files, for a minor performance improvement. For simplicity, that |
|
248 feature is not included here.</p> |
|
249 |
|
250 <p class="note"><i>The launcher:</i> |
|
251 JDK uses a program informally called "the launcher" which is used as |
|
252 a wrapper for all JDK tools, including <code>java</code>, |
|
253 <code>javac</code>, <code>javadoc</code>, and so on. The program is a deployed |
|
254 as a platform-dependent binary, thus obviating the need for a shell |
|
255 script to invoke the tools. Again for simplicity, and because that program |
|
256 is not normally considered part of <code>javac</code>, that program is |
|
257 not included here.</p |
|
258 |
|
259 <h2><a name="run">Running the compiler</a></h2> |
|
260 <p>Once you have built the compiler, you can run it in a number of ways. |
|
261 <ul> |
|
262 <li> |
|
263 <p>Use the generated script, perhaps by putting it on your shell's |
|
264 command execution path.</p> |
|
265 <pre> % <i>install-dir</i>/dist/bin/javac HelloWorld.java</pre> |
|
266 <p>or</p> |
|
267 <pre> % javac HelloWorld.java</pre> |
|
268 </li> |
|
269 <li><p>Execute javac.jar with the <code>java</code> command.</p> |
|
270 <pre> % java -jar <i>install-dir</i>/dist/lib/javac.jar HelloWorld.java</pre> |
|
271 </li> |
|
272 <li><p>Execute javac.jar directly. Depending on your operating system, |
|
273 you may be able to execute the jar file directly.</p> |
|
274 <pre> % <i>install-dir</i>/dist/lib/javac.jar HelloWorld.java</pre> |
|
275 <p>See the |
|
276 <a href="http://java.sun.com/j2se/1.5.0/docs/guide/jar/jarGuide.html">Jar File Overview</a> |
|
277 for details.</p> |
|
278 </li> |
|
279 </ul> |
|
280 |
|
281 <h2><a name="test">Testing the compiler with <code>jtreg</code></h2> |
|
282 <p>This bundle contains a large test suite of unit and regression tests |
|
283 used to test <code>javac</code>. They are part of the JDK Regression Test |
|
284 Suite, which uses the |
|
285 <a href="https://openjdk.dev.java.net/jtreg/">jtreg test harness</a>. |
|
286 This harness is |
|
287 designed to run both API-style tests, and command-line tests, such as |
|
288 found in the tests for <code>javac</code>.</p> |
|
289 |
|
290 <p>The simplest way to run the tests is to prepend the newly created |
|
291 copy of <code>javac.jar</code> to the bootstrap class path of a |
|
292 compatible version of JDK (meaning, it must accept the class file |
|
293 versions of newly compiled classes.) To do this, you can use |
|
294 the <code>-Xbootclasspath/p:</code><i><path></i> option |
|
295 for <code>jtreg</code>. This option is similar to the equivalent |
|
296 option for the <code>java</code> command. |
|
297 |
|
298 <p><i><b>Note:</b>Some of the tests, written as shell tests, do not yet |
|
299 support this mode of operation. You should use the |
|
300 <code>-noshell</code> to disable these tests for the time being. |
|
301 This restriction will be lifted in the near future.</i> |
|
302 |
|
303 <p><i><b>Note:</b>Four additional tests are ignored, using the <code>jtreg</code> |
|
304 <code>@ignore</code> tag, because of problems caused by bugs that have not yet |
|
305 been addressed. |
|
306 |
|
307 <p>You can run the compiler tests with a command such as the following:</p> |
|
308 |
|
309 <pre> % jtreg -jdk:<i>jdk</i> -Xbootclasspath/p:<i>my-javac.jar</i> -verbose -noshell test/tools/javac</pre> |
|
310 |
|
311 <p>Depending on the verbose options used, some amount of detail of the result |
|
312 of each test is written to the console. In addition, an HTML report about the |
|
313 entire test run is written to a report directory, and a results file is written for |
|
314 each test, in a "work" directory. The location of these directories can be |
|
315 specified on the <code>jtreg</code> command line; the actual locations used |
|
316 are reported to the console at the conclusion of the test run. |
|
317 |
|
318 <p>For more information on <code>jtreg</code>, use the |
|
319 the <code>-help</code> option for command-line help, or |
|
320 the <code>-onlineHelp</code> option for the built-in online help. |
|
321 Both of these options may optionally be followed by search |
|
322 keywords</p> |
|
323 |
|
324 <p><code>jtreg</code> can also be run from Ant. See |
|
325 <code>jtreg -onlineHelp ant</code> for details.</p> |
|
326 |
|
327 <p>Both <code>build.xml</code> and <code>Makefile</code> contain "test" targets for running the tests. |
|
328 |
|
329 </body> |
|
330 </html> |
|