Apache/ant
1
0
Fork 0
mirror of https://github.com/apache/ant.git synced 2025-05-18 14:04:48 +00:00
Code Issues Packages Projects Releases Wiki Activity
ant/docs/manual/CoreTasks/javac.html
Stefan Bodewig b6a3e9df36 License police on documentation files: 
(1) Make sure there is a Copyright notice on all visible files.

(2) Make sure all years in which the file has been modified are
listed.

(3) Make sure the format is consistent, i.e. separate consecutive
years with a dash, not a comma.

When Stephane changed starteam.html it has been 2001 in France but
2002 in Australia - does that mean we add 2002 to the Copyright line
or not?  ;-)


git-svn-id: https://svn.apache.org/repos/asf/ant/core/trunk@270652 13f79535-47bb-0310-9956-ffa450edef68
2002-01-10 08:48:33 +00:00

434 lines
17 KiB
HTML
Raw Blame History

<html>
<head>
<meta http-equiv="Content-Language" content="en-us">
<title>Apache Ant User Manual</title>
</head>
<body>
<h2><a name="javac">Javac</a></h2>
<h3>Description</h3>
<p>Compiles a Java source tree.</p>
<p>The source and destination directory will be recursively scanned for Java
source files to compile. Only Java files that have no corresponding class file
or where the class file is older than the java file will be compiled.</p>
<p>Note: Ant uses only the names of the source and class files to find
the classes that need a rebuild. It will not scan the source and therefor
will have no knowledge about nested classes, classes that are named different
from the source file and so on.</p>
<p>The directory structure of the source tree should follow the package
hierarchy.</p>
<p>It is possible to refine the set of files that are being compiled/copied.
This can be done with the <i>includes</i>, <i>includesfile</i>, <i>excludes</i>, <i>excludesfile</i> and <i>defaultexcludes</i>
attributes. With the <i>includes</i> or <i>includesfile</i> attribute you specify the files you want to
have included by using patterns. The <i>exclude</i> or <i>excludesfile</i> attribute is used to specify
the files you want to have excluded. This is also done with patterns. And
finally with the <i>defaultexcludes</i> attribute, you can specify whether you
want to use default exclusions or not. See the section on <a
href="../dirtasks.html#directorybasedtasks">directory based tasks</a>, on how the
inclusion/exclusion of files works, and how to write patterns.</p>
<p>It is possible to use different compilers. This can be selected with the
&quot;build.compiler&quot; property. Here are the choices:-</p>
<ul>
<li>classic (the standard compiler of JDK 1.1/1.2) - javac1.1 and
javac1.2 can be used as aliases</li>
<li>modern (the standard compiler of JDK 1.3/1.4) - javac1.3 and
javac1.4 can be used as aliases</li>
<li>jikes (the <a
href="http://oss.software.ibm.com/developerworks/opensource/jikes/project" target="_top">Jikes</a>
compiler)</li>
<li>jvc (the Command-Line Compiler from Microsoft's SDK for Java /
Visual J++) - microsoft can be used as an alias</li>
<li>kjc (the <a href="http://www.dms.at/kopi/" target="_top">kopi</a>
compiler)</li>
<li>gcj (the gcj compiler from gcc)</li>
<li>sj (Symantec java compiler) - symantec can be used as an alias</li>
<li>extJavac (run either modern or classic in a JVM of its own)</li>
</ul>
<p>For JDK 1.1/1.2, classic is the default. For JDK 1.3/1.4, modern is the default.
If you wish to use a different compiler interface than those
supplied, write a class that implements the CompilerAdapter interface
(package org.apache.tools.ant.taskdefs.compilers). Supply the full
classname in the &quot;build.compiler&quot; property.
</p>
<p>The fork attribute overrides the build.compiler setting and expects
a JDK1.1 or higher to be set in java.home.
</p>
<p>This task will drop all entries that point to non-existent
files/directories from the CLASSPATH it passes to the compiler.</p>
<p><strong>Windows Note:</strong>When the modern compiler is used
in unforked mode on Windows, it locks up the files present in the
classpath of the &lt;javac&gt; task, and does not release them. The side
effect of this is that you will not be able to delete or move
those files later on in the build. The workaround is to fork when
invoking the compiler.</p>
</p>
<h3>Parameters</h3>
<table border="1" cellpadding="2" cellspacing="0">
<tr>
<td valign="top"><b>Attribute</b></td>
<td valign="top"><b>Description</b></td>
<td align="center" valign="top"><b>Required</b></td>
</tr>
<tr>
<td valign="top">srcdir</td>
<td valign="top">location of the java files. (See Notes at the end)</td>
<td align="center" valign="top">Yes, unless nested <code>&lt;src&gt;</code> elements are present.</td>
</tr>
<tr>
<td valign="top">destdir</td>
<td valign="top">location to store the class files.</td>
<td align="center" valign="top">No</td>
</tr>
<tr>
<td valign="top">includes</td>
<td valign="top">comma-separated list of patterns of files that must be
included; all files are included when omitted.</td>
<td valign="top" align="center">No</td>
</tr>
<tr>
<td valign="top">includesfile</td>
<td valign="top">the name of a file that contains
include patterns.</td>
<td valign="top" align="center">No</td>
</tr>
<tr>
<td valign="top">excludes</td>
<td valign="top">comma-separated list of patterns of files that must be
excluded; no files (except default excludes) are excluded when omitted.</td>
<td valign="top" align="center">No</td>
</tr>
<tr>
<td valign="top">excludesfile</td>
<td valign="top">the name of a file that contains
exclude patterns.</td>
<td valign="top" align="center">No</td>
</tr>
<tr>
<td valign="top">defaultexcludes</td>
<td valign="top">indicates whether default excludes should be used
(<code>yes</code> | <code>no</code>); default excludes are used when omitted.</td>
<td valign="top" align="center">No</td>
</tr>
<tr>
<td valign="top">classpath</td>
<td valign="top">the classpath to use.</td>
<td align="center" valign="top">No</td>
</tr>
<tr>
<td valign="top">bootclasspath</td>
<td valign="top">location of bootstrap class files.</td>
<td align="center" valign="top">No</td>
</tr>
<tr>
<td valign="top">classpathref</td>
<td valign="top">the classpath to use, given as a
<a href="../using.html#references">reference</a> to a PATH defined elsewhere.</td>
<td align="center" valign="top">No</td>
</tr>
<tr>
<td valign="top">bootclasspathref</td>
<td valign="top">location of bootstrap class files, given as a
<a href="../using.html#references">reference</a> to a PATH defined elsewhere.</td>
<td align="center" valign="top">No</td>
</tr>
<tr>
<td valign="top">extdirs</td>
<td valign="top">location of installed extensions.</td>
<td align="center" valign="top">No</td>
</tr>
<tr>
<td valign="top">encoding</td>
<td valign="top">encoding of source files. (gcj doesn't support
this option yet)</td>
<td align="center" valign="top">No</td>
</tr>
<tr>
<td valign="top">nowarn</td>
<td valign="top">indicates whether -nowarn switch should be passed
to the compiler; defaults to <code>off</code>.</td>
<td align="center" valign="top">No</td>
</tr>
<tr>
<td valign="top">debug</td>
<td valign="top">indicates whether source should be compiled with debug
information; defaults to <code>off</code>.</td>
<td align="center" valign="top">No</td>
</tr>
<tr>
<td valign="top">optimize</td>
<td valign="top">indicates whether source should be compiled with
optimization; defaults to <code>off</code>.</td>
<td align="center" valign="top">No</td>
</tr>
<tr>
<td valign="top">deprecation</td>
<td valign="top">indicates whether source should be compiled with
deprecation information; defaults to <code>off</code>.</td>
<td align="center" valign="top">No</td>
</tr>
<tr>
<td valign="top">target</td>
<td valign="top">generate class files for specific VM version (e.g.,
<code>1.1</code> or <code>1.2</code>).</td>
<td align="center" valign="top">No</td>
</tr>
<tr>
<td valign="top">verbose</td>
<td valign="top">asks the compiler for verbose output.</td>
<td align="center" valign="top">No</td>
</tr>
<tr>
<td valign="top">depend</td> <td valign="top">enables dependency-tracking
for compilers that support this (jikes and classic)</td>
<td align="center" valign="top">No</td>
</tr>
<tr>
<td valign="top">includeAntRuntime</td>
<td valign="top">whether to include the Ant run-time libraries;
defaults to <code>yes</code>.</td>
<td align="center" valign="top">No</td>
</tr>
<tr>
<td valign="top">includeJavaRuntime</td>
<td valign="top">whether to include the default run-time
libraries from the executing VM; defaults to <code>no</code>.</td>
<td align="center" valign="top">No</td>
</tr>
<tr>
<td valign="top">fork</td>
<td valign="top">whether to execute Javac using the JDK compiler
externally; defaults to <code>no</code>. You can also give a
complete path to the javac executable to use instead of
<code>yes</code>, which would run the compiler of the Java
vesrion that is currently running Ant.</td>
<td align="center" valign="top">No</td>
</tr>
<tr>
<td valign="top">memoryInitialSize</td>
<td valign="top">the initial size of the memory for the underlying VM, if javac is run
externally, ignored otherwise; defaults to the standard VM memory setting.
(examples: <code>83886080</code>, <code>81920k</code>, or <code>80m</code>)</td>
<td align="center" valign="top">No</td>
</tr>
<tr>
<td valign="top">memoryMaximumSize</td>
<td valign="top">the maximum size of the memory for the underlying VM, if javac is run
externally, ignored otherwise; defaults to the standard VM memory setting.
(examples: <code>83886080</code>, <code>81920k</code>, or <code>80m</code>)</td>
<td align="center" valign="top">No</td>
</tr>
<tr>
<td valign="top">failonerror</td> <td valign="top">
indicates whether the build will continue even if there are compilation errors; defaults to <code>true</code>.
</td>
<td align="center" valign="top">No</td>
</tr>
<tr>
<td valign="top">source</td>
<td valign="top">Value of the <code>-source</code> command line
switch, will be ignored by all implementations except
<code>modern</code>, legal values are &quot;1.3&quot; and
&quot;1.4&quot; - by default, no <code>-source</code> argument
will be used at all.</td>
<td align="center" valign="top">No</td>
</tr>
<tr>
<td valign="top">debuglevel</td>
<td valign="top">Keyword list to be appended to the <code>-g</code> command line
switch. This will be ignored by all implementations except
<code>modern</code> and <code>classic(ver >= 1.2)</code>, legal values are
&quot;none&quot; or a comma separated list of the following keywords.
Valid keywords are &quot;lines&quot;, &quot;vars&quot; and &quot;source&quot;
- if debuglevel is not specified, by default, nothing will be
appended to <code>-g</code>. If debug is not turned on, this attribute will be
ignored.
</td>
<td align="center" valign="top">No</td>
</tr>
</table>
<h3>Parameters specified as nested elements</h3>
<p>This task forms an implicit <a href="../CoreTypes/fileset.html">FileSet</a> and
supports all attributes of <code>&lt;fileset&gt;</code>
(<code>dir</code> becomes <code>srcdir</code>) as well as the nested
<code>&lt;include&gt;</code>, <code>&lt;exclude&gt;</code> and
<code>&lt;patternset&gt;</code> elements.</p>
<h4><code>src</code>, <code>classpath</code>, <code>bootclasspath</code> and <code>extdirs</code></h4>
<p><code>Javac</code>'s <i>srcdir</i>, <i>classpath</i>,
<i>bootclasspath</i> and <i>extdirs</i> attributes are <a
href="../using.html#path">path-like structures</a> and can also be set via nested
<code>&lt;src&gt</code>,
<code>&lt;classpath&gt</code>,
<code>&lt;bootclasspath&gt</code> and
<code>&lt;extdirs&gt</code> elements, respectively.</p>
<h4>compilerarg</h4>
<p>You can specify additional command line arguments for the compiler
with nested <code>&lt;compilerarg&gt;</code> elements. These elements
are specified like <a href="../using.html#arg">Command-line
Arguments</a> but have an additional attribute that can be used to
enable arguments only if a given compiler implementation will be
used.</p>
<table border="1" cellpadding="2" cellspacing="0">
<tr>
<td width="12%" valign="top"><b>Attribute</b></td>
<td width="78%" valign="top"><b>Description</b></td>
<td width="10%" valign="top"><b>Required</b></td>
</tr>
<tr>
<td valign="top">value</td>
<td align="center" rowspan="4">See <a href="../using.html#arg">here</a></td>
<td align="center" rowspan="4">Exactly one of these.</td>
</tr>
<tr>
<td valign="top">line</td>
</tr>
<tr>
<td valign="top">file</td>
</tr>
<tr>
<td valign="top">path</td>
</tr>
<tr>
<td valign="top">implementation</td>
<td align="center">Only use this argument if the chosen
implementation matches this attribute. Possible choices are the
same as those of the build.compiler property.</td>
<td align="center">No.</td>
</tr>
</table>
<h3>Examples</h3>
<pre> &lt;javac srcdir=&quot;${src}&quot;
destdir=&quot;${build}&quot;
classpath=&quot;xyz.jar&quot;
debug=&quot;on&quot;
/&gt;</pre>
<p>compiles all <code>.java</code> files under the <code>${src}</code>
directory, and stores
the <code>.class</code> files in the <code>${build}</code> directory.
The classpath used contains <code>xyz.jar</code>, and debug information is on.</p>
<pre> &lt;javac srcdir=&quot;${src}&quot;
destdir=&quot;${build}&quot;
fork=&quot;true&quot;
/&gt;</pre>
<p>compiles all <code>.java</code> files under the <code>${src}</code>
directory, and stores the <code>.class</code> files in the
<code>${build}</code> directory. This will fork off the javac
compiler using the default javac executable.</p>
<pre> &lt;javac srcdir=&quot;${src}&quot;
destdir=&quot;${build}&quot;
fork=&quot;java$$javac.exe&quot;
/&gt;</pre>
<p>compiles all <code>.java</code> files under the <code>${src}</code>
directory, and stores the <code>.class</code> files in the
<code>${build}</code> directory. This will fork off the javac
compiler using the executable named <code>java$javac.exe</code>. Note
that the <code>$</code> sign needs to be escaped by a second one.</p>
<pre> &lt;javac srcdir=&quot;${src}&quot;
destdir=&quot;${build}&quot;
includes=&quot;mypackage/p1/**,mypackage/p2/**&quot;
excludes=&quot;mypackage/p1/testpackage/**&quot;
classpath=&quot;xyz.jar&quot;
debug=&quot;on&quot;
/&gt;</pre>
<p>compiles <code>.java</code> files under the <code>${src}</code>
directory, and stores the
<code>.class</code> files in the <code>${build}</code> directory.
The classpath used contains <code>xyz.jar</code>, and debug information is on.
Only files under <code>mypackage/p1</code> and <code>mypackage/p2</code> are
used. Files in the <code>mypackage/p1/testpackage</code> directory are excluded
from compilation.</p>
<pre> &lt;javac srcdir=&quot;${src}:${src2}&quot;
destdir=&quot;${build}&quot;
includes=&quot;mypackage/p1/**,mypackage/p2/**&quot;
excludes=&quot;mypackage/p1/testpackage/**&quot;
classpath=&quot;xyz.jar&quot;
debug=&quot;on&quot;
/&gt;</pre>
<p>is the same as the previous example, with the addition of a second
source path, defined by
the property <code>src2</code>. This can also be represented using nested
<code>&lt;src&gt;</code> elements as follows:</p>
<pre> &lt;javac destdir=&quot;${build}&quot;
classpath=&quot;xyz.jar&quot;
debug=&quot;on&quot;&gt;
&lt;src path=&quot;${src}&quot;/&gt;
&lt;src path=&quot;${src2}&quot;/&gt;
&lt;include name=&quot;mypackage/p1/**&quot;/&gt;
&lt;include name=&quot;mypackage/p2/**&quot;/&gt;
&lt;exclude name=&quot;mypackage/p1/testpackage/**&quot;/&gt;
&lt;/javac&gt;</pre>
<p><b>Note:</b> If you are using Ant on Windows and a new DOS window pops up
for every use of an external compiler, this may be a problem of the JDK you are using.
This problem may occur with all JDKs &lt; 1.2.</p>
<p><b>Note:</b> If you wish to compile only source-files located in some packages below a
common root you should not include these packages in the srcdir-attribute. Use include/exclude-attributes
or elements to filter for these packages. If you include part of your package-structure inside the srcdir-attribute
(or nested src-elements) Ant will start to recompile your sources every time you call it.</p>
<h3>Jikes Notes</h3>
Jikes supports some extra options, which can be set be defining
properties prior to invoking the task. The ant developers are aware that
this is ugly and inflexible -expect a better solution in the future. All
the options are boolean, and must be set to &quot;true&quot; or &quot;yes&quot; to be
interpreted as anything other than false; by default
build.compiler.warnings is &quot;true&quot; while all others are &quot;false&quot;</p>
<table border="1" cellpadding="2" cellspacing="0">
<tr>
<td valign="top">
build.compiler.emacs
</td>
<td valign="top">
Enable emacs compatible error messages
</td>
</tr>
<tr>
<td valign="top">
build.compiler.warnings<br>
<b>This property has been deprecated, use the nowarn attribute
instead</b>
</td>
<td valign="top">
don't disable warning messages
</td>
</tr>
<tr>
<td valign="top">
build.compiler.pedantic
</td>
<td valign="top">
enable pedantic warnings
</td>
</tr>
<tr>
<td valign="top">
build.compiler.fulldepend
</td>
<td valign="top">
enable full dependency checking,<br>
&quot;+F&quot; in the jikes manual.
</td>
</tr>
</table>
<hr>
<p align="center">Copyright &copy; 2001 Apache Software Foundation. All rights
Reserved.</p>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink