You can not select more than 25 topics Topics must start with a chinese character,a letter or number, can include dashes ('-') and can be up to 35 characters long.

javac.html 39 KiB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964
  1. <!--
  2. Licensed to the Apache Software Foundation (ASF) under one or more
  3. contributor license agreements. See the NOTICE file distributed with
  4. this work for additional information regarding copyright ownership.
  5. The ASF licenses this file to You under the Apache License, Version 2.0
  6. (the "License"); you may not use this file except in compliance with
  7. the License. You may obtain a copy of the License at
  8. http://www.apache.org/licenses/LICENSE-2.0
  9. Unless required by applicable law or agreed to in writing, software
  10. distributed under the License is distributed on an "AS IS" BASIS,
  11. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  12. See the License for the specific language governing permissions and
  13. limitations under the License.
  14. -->
  15. <html lang="en-us">
  16. <head>
  17. <meta http-equiv="Content-Language" content="en-us">
  18. <link rel="stylesheet" type="text/css" href="../stylesheets/style.css">
  19. <title>Javac Task</title>
  20. </head>
  21. <body>
  22. <h2><a name="javac">Javac</a></h2>
  23. <h3>Description</h3>
  24. <p>Compiles a Java source tree.</p>
  25. <p>The source and destination directory will be recursively scanned for Java
  26. source files to compile. Only Java files that have no corresponding
  27. <code>.class</code> file
  28. or where the class file is older than the
  29. <code>.java</code> file will be compiled.</p>
  30. <p>Note: Apache Ant uses only the names of the source and class files to find
  31. the classes that need a rebuild. It will not scan the source and therefore
  32. will have no knowledge about nested classes, classes that are named different
  33. from the source file, and so on. See the
  34. <a href="../Tasks/depend.html"><code>&lt;depend&gt;</code></a> task
  35. for dependency checking based on other than just
  36. existence/modification times.</p>
  37. <p>When the source files are part of a package, the directory structure of
  38. the source tree should follow the package
  39. hierarchy.</p>
  40. <p>It is possible to refine the set of files that are being compiled.
  41. This can be done with the <code>includes</code>, <code>includesfile</code>,
  42. <code>excludes</code>, and <code>excludesfile</code>
  43. attributes. With the <code>includes</code> or
  44. <code>includesfile</code> attribute, you specify the files you want to
  45. have included.
  46. The <code>exclude</code> or <code>excludesfile</code> attribute is used
  47. to specify
  48. the files you want to have excluded. In both cases, the list of files
  49. can be specified by either the filename, relative to the directory(s) specified
  50. in the <code>srcdir</code> attribute or nested <code>&lt;src&gt;</code>
  51. element(s), or by using wildcard patterns. See the section on
  52. <a href="../dirtasks.html#directorybasedtasks">directory-based tasks</a>,
  53. for information on how the
  54. inclusion/exclusion of files works, and how to write wildcard patterns.</p>
  55. <p>It is possible to use different compilers. This can be specified by
  56. either setting the global <code>build.compiler</code> property, which will
  57. affect all <code>&lt;javac&gt;</code> tasks throughout the build, by
  58. setting the <code>compiler</code> attribute, specific to the current
  59. <code>&lt;javac&gt;</code> task or by using a nested element of any
  60. <a href="typedef.html">typedef</a>fed or
  61. <a href="componentdef.html">componentdef</a>fed type that implements
  62. <code>org.apache.tools.ant.taskdefs.compilers.CompilerAdapter</code>.
  63. <a name="compilervalues">Valid values for either the
  64. <code>build.compiler</code> property or the <code>compiler</code>
  65. attribute are:</a></p>
  66. <ul>
  67. <li><code>classic</code> (the standard compiler of JDK 1.1/1.2) &ndash;
  68. <code>javac1.1</code> and
  69. <code>javac1.2</code> can be used as aliases.</li>
  70. <li><code>modern</code> (the standard compiler of JDK 1.3 and later) &ndash;
  71. <code>javac1.3</code> and
  72. <code>javac1.4</code> and
  73. <code>javac1.5</code> and
  74. <code>javac1.6</code> and
  75. <code>javac1.7</code> (<em>since Ant 1.8.2</em>) and
  76. <code>javac1.8</code> (<em>since Ant 1.8.3</em>) and</li>
  77. <code>javac1.9</code> (<em>since Ant 1.9.5</em>) and</li>
  78. <code>javac9</code> (<em>since Ant 1.9.8</em>) can be used as aliases.</li>
  79. <li><code>jikes</code> (the <a
  80. href="http://jikes.sourceforge.net/" target="_top">Jikes</a>
  81. compiler).</li>
  82. <li><code>jvc</code> (the Command-Line Compiler from Microsoft's SDK
  83. for Java / Visual J++) &ndash; <code>microsoft</code> can be used
  84. as an alias.</li>
  85. <li><code>kjc</code> (the <a href="http://www.dms.at/kopi/" target="_top">kopi</a>
  86. compiler).</li>
  87. <li><code>gcj</code> (the gcj compiler from gcc).</li>
  88. <li><code>sj</code> (Symantec java compiler) &ndash;
  89. <code>symantec</code> can be used as an alias.</li>
  90. <li><code>extJavac</code> (run either modern or classic in a JVM of
  91. its own).</li>
  92. </ul>
  93. <p>The default is <code>javac1.x</code> with <code>x</code> depending
  94. on the JDK version you use while you are running Ant.
  95. If you wish to use a different compiler interface than those
  96. supplied, you can write a class that implements the CompilerAdapter interface
  97. (<code>package org.apache.tools.ant.taskdefs.compilers</code>). Supply the full
  98. classname in the <code>build.compiler</code> property or the
  99. <code>compiler</code> attribute.
  100. </p>
  101. <p>The fork attribute overrides the <code>build.compiler</code> property
  102. or <code>compiler</code> attribute setting and
  103. expects a JDK1.1 or higher to be set in <code>JAVA_HOME</code>.
  104. </p>
  105. <p>You can also use the <code>compiler</code> attribute to tell Ant
  106. which JDK version it shall assume when it puts together the command
  107. line switches - even if you set <code>fork=&quot;true&quot;</code>.
  108. This is useful if you want to run the compiler of JDK 1.1 while you
  109. current JDK is 1.2+. If you use
  110. <code>compiler=&quot;javac1.1&quot;</code> and (for example)
  111. <code>depend=&quot;true&quot;</code> Ant will use the command line
  112. switch <code>-depend</code> instead of <code>-Xdepend</code>.</p>
  113. <p>This task will drop all entries that point to non-existent
  114. files/directories from the classpath it passes to the compiler.</p>
  115. <p>The working directory for a forked executable (if any) is the
  116. project's base directory.</p>
  117. <p><strong>Windows Note:</strong>When the modern compiler is used
  118. in unforked mode on Windows, it locks up the files present in the
  119. classpath of the <code>&lt;javac&gt;</code> task, and does not release them.
  120. The side effect of this is that you will not be able to delete or move
  121. those files later on in the build. The workaround is to fork when
  122. invoking the compiler.</p>
  123. <p>If you are using Java 8 or above and your source contains native
  124. methods or fields annotated with the <code>@Native</code> annotation
  125. you can set the <code>nativeheaderdir</code> attribute in order to
  126. use the <code>-h</code> switch of <code>javac</code> to generate the
  127. native header files. Note that the logic Ant uses to determine which
  128. files to compile does not take native headers into account, i.e. if
  129. the <code>.class</code> is more recent than the
  130. corresponding <code>.java</code> file the file will not get compiled
  131. even if a native header file generated for it would be outdated.</p>
  132. <h3>Parameters</h3>
  133. <table border="1" cellpadding="2" cellspacing="0">
  134. <tr>
  135. <td valign="top"><b>Attribute</b></td>
  136. <td valign="top"><b>Description</b></td>
  137. <td align="center" valign="top"><b>Required</b></td>
  138. </tr>
  139. <tr>
  140. <td valign="top">srcdir</td>
  141. <td valign="top">Location of the java files. (See the
  142. <a href="#srcdirnote">note</a> below.)</td>
  143. <td align="center" valign="top">Yes, unless nested <code>&lt;src&gt;</code> elements or <code>modulesourcepath</code> attribute or elements are present.</td>
  144. </tr>
  145. <tr>
  146. <td valign="top">destdir</td>
  147. <td valign="top">Location to store the class files.</td>
  148. <td align="center" valign="top">No</td>
  149. </tr>
  150. <tr>
  151. <td valign="top">includes</td>
  152. <td valign="top">Comma- or space-separated list of files (may be specified using
  153. wildcard patterns) that must be
  154. included; all <code>.java</code> files are included when omitted.</td>
  155. <td valign="top" align="center">No</td>
  156. </tr>
  157. <tr>
  158. <td valign="top">includesfile</td>
  159. <td valign="top">The name of a file that contains a list of files to
  160. include (may be specified using wildcard patterns).</td>
  161. <td valign="top" align="center">No</td>
  162. </tr>
  163. <tr>
  164. <td valign="top">excludes</td>
  165. <td valign="top">Comma- or space-separated list of files (may be specified using
  166. wildcard patterns) that must be excluded; no files (except default
  167. excludes) are excluded when omitted.</td>
  168. <td valign="top" align="center">No</td>
  169. </tr>
  170. <tr>
  171. <td valign="top">excludesfile</td>
  172. <td valign="top">The name of a file that contains a list of files to
  173. exclude (may be specified using wildcard patterns).</td>
  174. <td valign="top" align="center">No</td>
  175. </tr>
  176. <tr>
  177. <td valign="top">classpath</td>
  178. <td valign="top">The classpath to use.</td>
  179. <td align="center" valign="top">No</td>
  180. </tr>
  181. <tr>
  182. <td valign="top">sourcepath</td>
  183. <td valign="top">The sourcepath to use; defaults to the value of the srcdir attribute (or nested <code>&lt;src&gt;</code> elements).
  184. To suppress the sourcepath switch, use <code>sourcepath=&quot;&quot;</code>.</td>
  185. <td align="center" valign="top">No</td>
  186. </tr>
  187. <tr>
  188. <td valign="top">bootclasspath</td>
  189. <td valign="top">
  190. Location of bootstrap class files. (See <a href="#bootstrap">below</a>
  191. for using the -X and -J-X parameters for specifying
  192. the bootstrap classpath).
  193. </td>
  194. <td align="center" valign="top">No</td>
  195. </tr>
  196. <tr>
  197. <td valign="top">classpathref</td>
  198. <td valign="top">The classpath to use, given as a
  199. <a href="../using.html#references">reference</a> to a path defined elsewhere.</td>
  200. <td align="center" valign="top">No</td>
  201. </tr>
  202. <tr>
  203. <td valign="top">sourcepathref</td>
  204. <td valign="top">The sourcepath to use, given as a
  205. <a href="../using.html#references">reference</a> to a path defined elsewhere.</td>
  206. <td align="center" valign="top">No</td>
  207. </tr>
  208. <tr>
  209. <td valign="top">bootclasspathref</td>
  210. <td valign="top">Location of bootstrap class files, given as a
  211. <a href="../using.html#references">reference</a> to a path defined elsewhere.</td>
  212. <td align="center" valign="top">No</td>
  213. </tr>
  214. <tr>
  215. <td valign="top">extdirs</td>
  216. <td valign="top">Location of installed extensions.</td>
  217. <td align="center" valign="top">No</td>
  218. </tr>
  219. <tr>
  220. <td valign="top">encoding</td>
  221. <td valign="top">Encoding of source files. (Note: gcj doesn't support
  222. this option yet.)</td>
  223. <td align="center" valign="top">No</td>
  224. </tr>
  225. <tr>
  226. <td valign="top">nowarn</td>
  227. <td valign="top">Indicates whether the <code>-nowarn</code> switch
  228. should be passed to the compiler; defaults to <code>off</code>.</td>
  229. <td align="center" valign="top">No</td>
  230. </tr>
  231. <tr>
  232. <td valign="top">debug</td>
  233. <td valign="top">Indicates whether source should be compiled with
  234. debug information; defaults to <code>off</code>. If set to
  235. <code>off</code>, <code>-g:none</code> will be passed on the
  236. command line for compilers that support it (for other compilers, no
  237. command line argument will be used). If set to <code>true</code>,
  238. the value of the <code>debuglevel</code> attribute determines the
  239. command line argument.</td>
  240. <td align="center" valign="top">No</td>
  241. </tr>
  242. <tr>
  243. <td valign="top">debuglevel</td>
  244. <td valign="top">Keyword list to be appended to the <code>-g</code>
  245. command-line switch. This will be ignored by all implementations except
  246. <code>modern</code>, <code>classic(ver &gt;= 1.2)</code> and <code>jikes</code>.
  247. Legal values are <code>none</code> or a comma-separated list of the
  248. following keywords:
  249. <code>lines</code>, <code>vars</code>, and <code>source</code>.
  250. If <code>debuglevel</code> is not specified, by default,
  251. nothing will be
  252. appended to <code>-g</code>. If <code>debug</code> is not turned on,
  253. this attribute will be ignored.
  254. </td>
  255. <td align="center" valign="top">No</td>
  256. </tr>
  257. <tr>
  258. <td valign="top">optimize</td>
  259. <td valign="top">
  260. Indicates whether source should be compiled with
  261. optimization; defaults to <code>off</code>. <strong>Note</strong>
  262. that this flag is just ignored by Sun's <code>javac</code> starting
  263. with JDK 1.3 (since compile-time optimization is unnecessary).
  264. </td>
  265. <td align="center" valign="top">No</td>
  266. </tr>
  267. <tr>
  268. <td valign="top">deprecation</td>
  269. <td valign="top">Indicates whether source should be compiled with
  270. deprecation information; defaults to <code>off</code>.</td>
  271. <td align="center" valign="top">No</td>
  272. </tr>
  273. <tr>
  274. <td valign="top">target</td>
  275. <td valign="top">Generate class files for specific VM version
  276. (e.g., <code>1.1</code> or <code>1.2</code>). <b>Note that the
  277. default value depends on the JVM that is running Ant. In
  278. particular, if you use JDK 1.4+ the generated classes will not be
  279. usable for a 1.1 Java VM unless you explicitly set this attribute
  280. to the value 1.1 (which is the default value for JDK 1.1 to
  281. 1.3). We highly recommend to always specify this
  282. attribute.</b><br>
  283. A default value for this attribute can be provided using the magic
  284. <a
  285. href="../javacprops.html#target"><code>ant.build.javac.target</code></a>
  286. property.</td>
  287. <td align="center" valign="top">No</td>
  288. </tr>
  289. <tr>
  290. <td valign="top">verbose</td>
  291. <td valign="top">Asks the compiler for verbose output; defaults to
  292. <code>no</code>.</td>
  293. <td align="center" valign="top">No</td>
  294. </tr>
  295. <tr>
  296. <td valign="top">depend</td> <td valign="top">Enables dependency-tracking
  297. for compilers that support this (<code>jikes</code> and
  298. <code>classic</code>).</td>
  299. <td align="center" valign="top">No</td>
  300. </tr>
  301. <tr>
  302. <td valign="top">includeAntRuntime</td>
  303. <td valign="top">Whether to include the Ant run-time libraries in the
  304. classpath; defaults to <code>yes</code>, unless
  305. <a href="../sysclasspath.html"><code>build.sysclasspath</code></a> is set.
  306. <em>It is usually best to set this to false</em> so the script's behavior is not
  307. sensitive to the environment in which it is run.</td>
  308. <td align="center" valign="top">No</td>
  309. </tr>
  310. <tr>
  311. <td valign="top">includeJavaRuntime</td>
  312. <td valign="top">Whether to include the default run-time
  313. libraries from the executing VM in the classpath;
  314. defaults to <code>no</code>.<br/>
  315. <b>Note:</b> In some setups the run-time libraries may be part
  316. of the "Ant run-time libraries" so you may need to explicitly
  317. set includeAntRuntime to false to ensure that the Java
  318. run-time libraries are not included.</td>
  319. <td align="center" valign="top">No</td>
  320. </tr>
  321. <tr>
  322. <td valign="top">fork</td>
  323. <td valign="top">Whether to execute <code>javac</code> using the
  324. JDK compiler externally; defaults to <code>no</code>.</td>
  325. <td align="center" valign="top">No</td>
  326. </tr>
  327. <tr>
  328. <td valign="top">executable</td>
  329. <td valign="top">Complete path to the <code>javac</code>
  330. executable to use in case of <code>fork=&quot;yes&quot;</code>.
  331. Defaults to the compiler of the Java version that is currently
  332. running Ant. Ignored if <code>fork=&quot;no&quot;</code>.<br>
  333. Since Ant 1.6 this attribute can also be used to specify the
  334. path to the executable when using jikes, jvc, gcj or sj.</td>
  335. <td align="center" valign="top">No</td>
  336. </tr>
  337. <tr>
  338. <td valign="top">memoryInitialSize</td>
  339. <td valign="top">The initial size of the memory for the underlying VM,
  340. if <code>javac</code> is run externally; ignored otherwise. Defaults
  341. to the standard VM memory setting.
  342. (Examples: <code>83886080</code>, <code>81920k</code>, or
  343. <code>80m</code>)</td>
  344. <td align="center" valign="top">No</td>
  345. </tr>
  346. <tr>
  347. <td valign="top">memoryMaximumSize</td>
  348. <td valign="top">The maximum size of the memory for the underlying VM,
  349. if <code>javac</code> is run externally; ignored otherwise. Defaults
  350. to the standard VM memory setting.
  351. (Examples: <code>83886080</code>, <code>81920k</code>, or
  352. <code>80m</code>)</td>
  353. <td align="center" valign="top">No</td>
  354. </tr>
  355. <tr>
  356. <td valign="top">failonerror</td>
  357. <td valign="top">Indicates whether compilation errors
  358. will fail the build; defaults to <code>true</code>.</td>
  359. <td align="center" valign="top">No</td>
  360. </tr>
  361. <tr>
  362. <td valign="top">errorProperty</td>
  363. <td valign="top">
  364. The property to set (to the value "true") if compilation fails.
  365. <em>Since Ant 1.7.1</em>.
  366. </td>
  367. <td align="center" valign="top">No</td>
  368. </tr>
  369. <tr>
  370. <td valign="top">source</td>
  371. <td valign="top">Value of the <code>-source</code> command-line
  372. switch; will be ignored by all implementations prior to
  373. <code>javac1.4</code> (or <code>modern</code> when Ant is not
  374. running in a 1.3 VM), <code>gcj</code> and <code>jikes</code>.<br>
  375. If you use this attribute together with <code>gcj</code>
  376. or <code>jikes</code>, you must make sure that your version
  377. supports the <code>-source</code> (or <code>-fsource</code> for
  378. gcj)
  379. switch. By default, no <code>-source</code> argument will be used
  380. at all.<br>
  381. <b>Note that the default value depends on the JVM that is running
  382. Ant. We highly recommend to always specify this
  383. attribute.</b><br>
  384. A default value for this attribute can be provided using the magic
  385. <a
  386. href="../javacprops.html#source"><code>ant.build.javac.source</code></a>
  387. property.</td>
  388. <td align="center" valign="top">No</td>
  389. </tr>
  390. <tr>
  391. <td valign="top">compiler</td>
  392. <td valign="top">The compiler implementation to use.
  393. If this attribute is not set, the value of the
  394. <code>build.compiler</code> property, if set, will be used.
  395. Otherwise, the default compiler for the current VM will be used.
  396. (See the above <a href="#compilervalues">list</a> of valid
  397. compilers.)</td>
  398. <td align="center" valign="top">No</td>
  399. </tr>
  400. <tr>
  401. <td valign="top">listfiles</td>
  402. <td valign="top">Indicates whether the source files to be compiled will
  403. be listed; defaults to <code>no</code>.</td>
  404. <td align="center" valign="top">No</td>
  405. </tr>
  406. <tr>
  407. <td valign="top">tempdir</td>
  408. <td valign="top">Where Ant should place temporary files.
  409. This is only used if the task is forked and the
  410. command line args length exceeds 4k.
  411. <em>Since Ant 1.6</em>.</td>
  412. <td align="center" valign="top">
  413. No; default is <i>java.io.tmpdir</i>.
  414. </td>
  415. </tr>
  416. <tr>
  417. <td valign="top">updatedProperty</td>
  418. <td valign="top">
  419. The property to set (to the value "true")
  420. if compilation has taken place
  421. and has been successful.
  422. <em>Since Ant 1.7.1</em>.
  423. </td>
  424. <td align="center" valign="top">No</td>
  425. </tr>
  426. <tr>
  427. <td valign="top">includeDestClasses</td>
  428. <td valign="top">
  429. This attribute controls whether to include the
  430. destination classes directory in the classpath
  431. given to the compiler.
  432. The default value of this is "true" and this
  433. means that previously compiled classes are on
  434. the classpath for the compiler. This means that "greedy" compilers
  435. will not recompile dependent classes that are already compiled.
  436. In general this is a good thing as it stops the compiler
  437. for doing unnecessary work. However, for some edge cases,
  438. involving generics, the javac compiler
  439. needs to compile the dependent classes to get the generics
  440. information. One example is documented in the bug report:
  441. <a href="http://issues.apache.org/bugzilla/show_bug.cgi?id=40776">
  442. Bug 40776 - a problem compiling a Java 5 project with generics</a>.
  443. Setting the attribute to "false" will cause the compiler
  444. to recompile dependent classes.
  445. <em>Since Ant 1.7.1</em>.
  446. </td>
  447. <td align="center" valign="top">No - default is "true"</td>
  448. </tr>
  449. <tr>
  450. <td valign="top">createMissingPackageInfoClass</td>
  451. <td valign="top">
  452. Some package level annotations in <code>package-info.java</code>
  453. files don't create any <code>package-info.class</code> files so
  454. Ant would recompile the same file every time.<br/>
  455. Starting with Ant 1.8 Ant will create an
  456. empty <code>package-info.class</code> for
  457. each <code>package-info.java</code> if there isn't one created
  458. by the compiler.<br/>
  459. In some setups this additional class causes problems and it can
  460. be suppressed by setting this attribute to "false".
  461. <em>Since Ant 1.8.3</em>.
  462. </td>
  463. <td align="center" valign="top">No - default is "true"</td>
  464. </tr>
  465. <tr>
  466. <td valign="top">modulepath</td>
  467. <td valign="top">
  468. Specify where to find application modules. A list of directories of modules, module files or exploded modules.
  469. <em>since Ant 1.9.7</em>
  470. </td>
  471. <td align="center" valign="top">No</td>
  472. </tr>
  473. <tr>
  474. <td valign="top">modulepathref</td>
  475. <td valign="top">
  476. The modulepath to use, given as <a href="../using.html#references">reference</a> to a PATH defined elsewhere.
  477. <em>since Ant 1.9.7</em></td>
  478. <td align="center" valign="top">No</td>
  479. </tr>
  480. <tr>
  481. <td valign="top">modulesourcepath</td>
  482. <td valign="top">
  483. Specify where to find input source files for multiple module compilation.
  484. <em>since Ant 1.9.7</em>
  485. </td>
  486. <td align="center" valign="top">Yes, unless <code>srcdir</code> attribute or nested <code>&lt;src&gt;</code> elements are present</td>
  487. </tr>
  488. <tr>
  489. <td valign="top">modulesourcepathref</td>
  490. <td valign="top">
  491. The modulesourcepath to use, given as <a href="../using.html#references">reference</a> to a PATH defined elsewhere.
  492. <em>since Ant 1.9.7</em></td>
  493. <td align="center" valign="top">No</td>
  494. </tr>
  495. <tr>
  496. <td valign="top">upgrademodulepath</td>
  497. <td valign="top">
  498. Specify the location of modules that replace upgradeable modules in the runtime image.
  499. <em>since Ant 1.9.7</em>
  500. </td>
  501. <td align="center" valign="top">No</td>
  502. </tr>
  503. <tr>
  504. <td valign="top">upgrademodulepathref</td>
  505. <td valign="top">
  506. The upgrademodulepath to use, given as <a href="../using.html#references">reference</a> to a PATH defined elsewhere.
  507. <em>since Ant 1.9.7</em></td>
  508. <td align="center" valign="top">No</td>
  509. </tr>
  510. <tr>
  511. <td valign="top">nativeheaderdir</td>
  512. <td valign="top">
  513. Specify where to place generated native header files. Ignored
  514. when running on JDK &lt; 8.
  515. <em>Since Ant 1.9.8</em>.
  516. <td align="center" valign="top">No</td>
  517. </tr>
  518. <tr>
  519. <td valign="top">release</td>
  520. <td valign="top">
  521. Specify the value for the <code>--release</code> switch.Ignored
  522. when running on JDK &lt; 9.<br>
  523. When set and running on JDK &gt;= 9 the source and target
  524. attributes as well as the bootclasspath will be ignored.
  525. <em>Since Ant 1.9.8</em>.
  526. <td align="center" valign="top">No</td>
  527. </tr>
  528. </table>
  529. <h3>Parameters specified as nested elements</h3>
  530. <p>This task forms an implicit <a href="../Types/fileset.html">FileSet</a> and
  531. supports most attributes of <code>&lt;fileset&gt;</code>
  532. (<code>dir</code> becomes <code>srcdir</code>) as well as the nested
  533. <code>&lt;include&gt;</code>, <code>&lt;exclude&gt;</code> and
  534. <code>&lt;patternset&gt;</code> elements.</p>
  535. <h4><code>srcdir</code>, <code>classpath</code>, <code>sourcepath</code>,
  536. <code>bootclasspath</code>, <code>modulepath</code>, <code>modulesourcepath</code>,
  537. <code>upgrademodulepath</code> and <code>extdirs</code></h4>
  538. <p><code>&lt;javac&gt;</code>'s <code>srcdir</code>, <code>classpath</code>,
  539. <code>sourcepath</code>, <code>bootclasspath</code>,
  540. <code>extdirs</code>, <code>modulepath</code>, <code>modulesourcepath</code>,
  541. and <code>upgrademodulepath</code> attributes are
  542. <a href="../using.html#path">path-like structures</a>
  543. and can also be set via nested
  544. <code>&lt;src&gt;</code> (note the different name!),
  545. <code>&lt;classpath&gt;</code>,
  546. <code>&lt;sourcepath&gt;</code>,
  547. <code>&lt;bootclasspath&gt;</code>,
  548. <code>&lt;extdirs&gt;</code>,
  549. <code>&lt;modulepath&gt;</code>,
  550. <code>&lt;modulesourcepath&gt;</code> and
  551. <code>&lt;upgrademodulepath&gt;</code>
  552. elements, respectively.</p>
  553. <h4>compilerarg</h4>
  554. <p>You can specify additional command line arguments for the compiler
  555. with nested <code>&lt;compilerarg&gt;</code> elements. These elements
  556. are specified like <a href="../using.html#arg">Command-line
  557. Arguments</a> but have an additional attribute that can be used to
  558. enable arguments only if a given compiler implementation will be
  559. used.</p>
  560. <table border="1" cellpadding="2" cellspacing="0">
  561. <tr>
  562. <td width="12%" valign="top"><b>Attribute</b></td>
  563. <td width="78%" valign="top"><b>Description</b></td>
  564. <td width="10%" valign="top"><b>Required</b></td>
  565. </tr>
  566. <tr>
  567. <td valign="top">value</td>
  568. <td align="center" rowspan="4">See
  569. <a href="../using.html#arg">Command-line Arguments</a>.</td>
  570. <td align="center" rowspan="4">Exactly one of these.</td>
  571. </tr>
  572. <tr>
  573. <td valign="top">line</td>
  574. </tr>
  575. <tr>
  576. <td valign="top">file</td>
  577. </tr>
  578. <tr>
  579. <td valign="top">path</td>
  580. </tr>
  581. <tr>
  582. <td valign="top">prefix</td>
  583. <td align="center" rowspan="2">See
  584. <a href="../using.html#arg">Command-line Arguments</a>.
  585. <em>Since Ant 1.8.</em></td>
  586. <td valign="top" align="center">No</td>
  587. </tr>
  588. <tr>
  589. <td valign="top">suffix</td>
  590. <td valign="top" align="center">No</td>
  591. </tr>
  592. <tr>
  593. <td valign="top">compiler</td>
  594. <td>Only pass the specified argument if the chosen
  595. compiler implementation matches the value of this attribute.
  596. Legal values are the
  597. same as those in the above <a href="#compilervalues">list</a> of valid
  598. compilers.)</td>
  599. <td align="center">No</td>
  600. </tr>
  601. </table>
  602. <h4>compilerclasspath <em>since Ant 1.8.0</em></h4>
  603. <p>A <a href="../using.html#path">PATH like structure</a> holding the
  604. classpath to use when loading the compiler implementation if a
  605. custom class has been specified. Doesn't have any effect when
  606. using one of the built-in compilers.</p>
  607. <h4>Any nested element of a type that implements CompilerAdapter
  608. <em>since Ant 1.8.0</em></h4>
  609. <p>If a defined type implements the <code>CompilerAdapter</code>
  610. interface a nested element of that type can be used as an
  611. alternative to the <code>compiler</code> attribute.</p>
  612. <h3>Examples</h3>
  613. <pre> &lt;javac srcdir=&quot;${src}&quot;
  614. destdir=&quot;${build}&quot;
  615. classpath=&quot;xyz.jar&quot;
  616. debug=&quot;on&quot;
  617. source=&quot;1.4&quot;
  618. /&gt;</pre>
  619. <p>compiles all <code>.java</code> files under the <code>${src}</code>
  620. directory, and stores
  621. the <code>.class</code> files in the <code>${build}</code> directory.
  622. The classpath used includes <code>xyz.jar</code>, and compiling with
  623. debug information is on. The source level is 1.4,
  624. so you can use <code>assert</code> statements.</p>
  625. <pre> &lt;javac srcdir=&quot;${src}&quot;
  626. destdir=&quot;${build}&quot;
  627. fork=&quot;true&quot;
  628. source=&quot;1.2&quot;
  629. target=&quot;1.2&quot;
  630. /&gt;</pre>
  631. <p>compiles all <code>.java</code> files under the <code>${src}</code>
  632. directory, and stores the <code>.class</code> files in the
  633. <code>${build}</code> directory. This will fork off the javac
  634. compiler using the default <code>javac</code> executable.
  635. The source level is 1.2 (similar to 1.1 or 1.3) and
  636. the class files should be runnable under JDK 1.2+ as well.</p>
  637. <pre> &lt;javac srcdir=&quot;${src}&quot;
  638. destdir=&quot;${build}&quot;
  639. fork=&quot;java$$javac.exe&quot;
  640. source=&quot;1.5&quot;
  641. /&gt;</pre>
  642. <p>compiles all <code>.java</code> files under the <code>${src}</code>
  643. directory, and stores the <code>.class</code> files in the
  644. <code>${build}</code> directory. This will fork off the javac
  645. compiler, using the executable named <code>java$javac.exe</code>. Note
  646. that the <code>$</code> sign needs to be escaped by a second one.
  647. The source level is 1.5, so you can use generics.</p>
  648. <pre> &lt;javac srcdir=&quot;${src}&quot;
  649. destdir=&quot;${build}&quot;
  650. includes=&quot;mypackage/p1/**,mypackage/p2/**&quot;
  651. excludes=&quot;mypackage/p1/testpackage/**&quot;
  652. classpath=&quot;xyz.jar&quot;
  653. debug=&quot;on&quot;
  654. /&gt;</pre>
  655. <p>compiles <code>.java</code> files under the <code>${src}</code>
  656. directory, and stores the
  657. <code>.class</code> files in the <code>${build}</code> directory.
  658. The classpath used includes <code>xyz.jar</code>, and debug information is on.
  659. Only files under <code>mypackage/p1</code> and <code>mypackage/p2</code> are
  660. used. All files in and below the <code>mypackage/p1/testpackage</code>
  661. directory are excluded from compilation.
  662. You didn't specify a source or target level,
  663. so the actual values used will depend on which JDK you ran Ant with.</p>
  664. <pre> &lt;javac srcdir=&quot;${src}:${src2}&quot;
  665. destdir=&quot;${build}&quot;
  666. includes=&quot;mypackage/p1/**,mypackage/p2/**&quot;
  667. excludes=&quot;mypackage/p1/testpackage/**&quot;
  668. classpath=&quot;xyz.jar&quot;
  669. debug=&quot;on&quot;
  670. /&gt;</pre>
  671. <p>is the same as the previous example, with the addition of a second
  672. source path, defined by
  673. the property <code>src2</code>. This can also be represented using nested
  674. <code>&lt;src&gt;</code> elements as follows:</p>
  675. <pre> &lt;javac destdir=&quot;${build}&quot;
  676. classpath=&quot;xyz.jar&quot;
  677. debug=&quot;on&quot;&gt;
  678. &lt;src path=&quot;${src}&quot;/&gt;
  679. &lt;src path=&quot;${src2}&quot;/&gt;
  680. &lt;include name=&quot;mypackage/p1/**&quot;/&gt;
  681. &lt;include name=&quot;mypackage/p2/**&quot;/&gt;
  682. &lt;exclude name=&quot;mypackage/p1/testpackage/**&quot;/&gt;
  683. &lt;/javac&gt;</pre>
  684. <p>If you want to run the javac compiler of a different JDK, you
  685. should tell Ant, where to find the compiler and which version of JDK
  686. you will be using so it can choose the correct command line switches.
  687. The following example executes a JDK 1.1 javac in a new process and
  688. uses the correct command line switches even when Ant is running in a
  689. Java VM of a different version:</p>
  690. <pre> &lt;javac srcdir=&quot;${src}&quot;
  691. destdir=&quot;${build}&quot;
  692. fork=&quot;yes&quot;
  693. executable=&quot;/opt/java/jdk1.1/bin/javac&quot;
  694. compiler=&quot;javac1.1&quot;
  695. /&gt;</pre>
  696. <p><a name="srcdirnote"><b>Note:</b></a>
  697. If you wish to compile only source files located in certain packages below a
  698. common root, use the <code>include</code>/<code>exclude</code> attributes
  699. or <code>&lt;include&gt;</code>/<code>&lt;exclude&gt;</code> nested elements
  700. to filter for these packages. Do not include part of your package structure
  701. in the <code>srcdir</code> attribute
  702. (or nested <code>&lt;src&gt;</code> elements), or Ant will recompile your
  703. source files every time you run your compile target. See the
  704. <a href="http://ant.apache.org/faq.html#always-recompiles">Ant FAQ</a>
  705. for additional information.</p>
  706. <p>
  707. If you wish to compile only files explicitly specified and disable
  708. javac's default searching mechanism then you can unset the sourcepath
  709. attribute:
  710. <pre> &lt;javac sourcepath=&quot;&quot; srcdir=&quot;${src}&quot;
  711. destdir=&quot;${build}&quot; &gt;
  712. &lt;include name="**/*.java"/&gt;
  713. &lt;exclude name="**/Example.java"/&gt;
  714. &lt;/javac&gt;</pre>
  715. That way the javac will compile all java source files under &quot;${src}&quot;
  716. directory but skip the examples. The compiler will even produce errors if some of
  717. the non-example files refers to them.
  718. </p>
  719. <p>
  720. If you wish to compile with a special JDK (another than the one Ant is currently using),
  721. set the <code>executable</code> and <code>fork</code> attribute. Using <code>taskname</code>
  722. could show in the log, that these settings are fix.
  723. <pre> &lt;javac srcdir=&quot;&quot;
  724. destdir=&quot;&quot;
  725. executable=&quot;path-to-java14-home/bin/javac&quot;
  726. fork=&quot;true&quot;
  727. taskname=&quot;javac1.4&quot; /&gt;</pre>
  728. </p>
  729. <p><b>Note:</b> If you are using Ant on Windows and a new DOS window pops up
  730. for every use of an external compiler, this may be a problem of the JDK you are
  731. using. This problem may occur with all JDKs &lt; 1.2.</p>
  732. <p>
  733. If you want to activate other compiler options like <i>lint</i> you could use
  734. the <tt>&lt;compilerarg&gt;</tt> element:
  735. <pre> &lt;javac srcdir="${src.dir}"
  736. destdir="${classes.dir}"
  737. classpathref="libraries"&gt;
  738. &lt;compilerarg value="-Xlint"/&gt;
  739. &lt;/javac&gt; </pre>
  740. </p>
  741. <p>If you want to use a custom
  742. CompilerAdapter <code>org.example.MyAdapter</code> you can either
  743. use the compiler attribute:</p>
  744. <pre>
  745. &lt;javac srcdir="${src.dir}"
  746. destdir="${classes.dir}"
  747. compiler="org.example.MyAdapter"/&gt;
  748. </pre>
  749. <p>or a define a type and nest this into the task like in:</p>
  750. <pre>
  751. &lt;componentdef classname="org.example.MyAdapter"
  752. name="myadapter"/&gt;
  753. &lt;javac srcdir="${src.dir}"
  754. destdir="${classes.dir}"&gt;
  755. &lt;myadapter/&gt;
  756. &lt;/javac&gt;
  757. </pre>
  758. <p>in which case your compiler adapter can support attributes and
  759. nested elements of its own.</p>
  760. <pre> &lt;javac srcdir=&quot;${src}&quot;
  761. destdir=&quot;${build}&quot;
  762. includeantruntime=&quot;false&quot;
  763. modulepath=&quot;modules&quot;
  764. source=&quot;9&quot;
  765. /&gt;</pre>
  766. <p>compiles all <code>.java</code> files in a single module under the <code>${src}</code> directory,
  767. and stores the <code>.class</code> files in the <code>${build}</code> directory. The compilation uses
  768. application modules located in <code>modules</code> folder.The source level is <code>9</code> to enable modules.</p>
  769. <pre> &lt;javac modulesourcepath=&quot;${src}/*/{gen,lin{32,64}}/classes&quot;
  770. destdir=&quot;${build}&quot;
  771. includeantruntime=&quot;false&quot;
  772. modulepath=&quot;modules&quot;
  773. source=&quot;9&quot;
  774. /&gt;</pre>
  775. <p>compiles all <code>.java</code> files in <code>gen/classes</code>, <code>lin32/classes</code> and
  776. <code>lin64/classes</code> in all source modules under the <code>${src}</code> directory.
  777. Generates module directories in the <code>${build}</code> directory. Each generated module directory under
  778. the <code>${build}</code> directory contains <code>.class</code> files from corresponding source module.
  779. The <code>*</code> is a token representing the name of any of the modules in the compilation module set.
  780. The <code>{ ... , ... }</code> express alternates for expansion.
  781. The compilation uses application modules located in <code>modules</code> folder.The source level is
  782. <code>9</code> to enable modules.</p>
  783. <h3>Jikes Notes</h3>
  784. <p>You need Jikes 1.15 or later.</p>
  785. <p>Jikes supports some extra options, which can be set be defining
  786. the properties shown below prior to invoking the task. The setting
  787. for each property will be in affect for all <code>&lt;javac&gt;</code>
  788. tasks throughout the build.
  789. The Ant developers are aware that
  790. this is ugly and inflexible &ndash; expect a better solution in the future.
  791. All the options are boolean, and must be set to <code>true</code> or
  792. <code>yes</code> to be
  793. interpreted as anything other than false. By default,
  794. <code>build.compiler.warnings</code> is <code>true</code>,
  795. while all others are <code>false</code>.</p>
  796. <table border="1" cellpadding="2" cellspacing="0">
  797. <tr>
  798. <td valign="top"><b>Property</b></td>
  799. <td valign="top"><b>Description</b></td>
  800. <td align="center" valign="top"><b>Default</b></td>
  801. </tr>
  802. <tr>
  803. <td valign="top">
  804. build.compiler.emacs
  805. </td>
  806. <td valign="top">
  807. Enable emacs-compatible error messages.
  808. </td>
  809. <td valign="top">
  810. <code>false</code>
  811. </td>
  812. </tr>
  813. <tr>
  814. <td valign="top">
  815. build.compiler.fulldepend
  816. </td>
  817. <td valign="top">
  818. Enable full dependency checking; see<br>
  819. the <code>+F</code> switch in the Jikes manual.
  820. </td>
  821. <td valign="top">
  822. <code>false</code>
  823. </td>
  824. </tr>
  825. <tr>
  826. <td valign="top">
  827. build.compiler.pedantic
  828. </td>
  829. <td valign="top">
  830. Enable pedantic warnings.
  831. </td>
  832. <td valign="top">
  833. <code>false</code>
  834. </td>
  835. </tr>
  836. <tr>
  837. <td valign="top">
  838. build.compiler.warnings<br>
  839. <strong>Deprecated</strong>. Use
  840. <code>&lt;javac&gt;</code>'s <code>nowarn</code>
  841. attribute instead.
  842. </td>
  843. <td valign="top">
  844. Don't disable warning messages.
  845. </td>
  846. <td valign="top">
  847. <code>true</code>
  848. </td>
  849. </tr>
  850. </table>
  851. <h3>Jvc Notes</h3>
  852. <p>Jvc will enable Microsoft extensions unless you set the property
  853. <code>build.compiler.jvc.extensions</code> to false before invoking
  854. <code>&lt;javac&gt;</code>.</p>
  855. <h3><a name="bootstrap">Bootstrap Options</h3>
  856. <p>
  857. The Sun javac compiler has a <em>bootclasspath</em> command
  858. line option - this corresponds to the "bootclasspath" attribute/element
  859. of the &lt;javac&gt; task. The Sun compiler also allows more
  860. control over the boot classpath using the -X and -J-X attributes.
  861. One can set these by using the &lt;compilerarg&gt;. Since Ant 1.6.0,
  862. there is a shortcut to convert path references to strings that
  863. can by used in an OS independent fashion (see
  864. <a href="../using.html#pathshortcut">pathshortcut</a>). For example:
  865. </p>
  866. <pre>
  867. &lt;path id="lib.path.ref"&gt;
  868. &lt;fileset dir="lib" includes="*.jar"/&gt;
  869. &lt;/path&gt;
  870. &lt;javac srcdir="src" destdir="classes"&gt;
  871. &lt;compilerarg arg="-Xbootclasspath/p:${toString:lib.path.ref}"/&gt;
  872. &lt;/javac&gt;
  873. </pre>
  874. </p>
  875. <h3>OpenJDK Notes</h3>
  876. <p>
  877. The <a href="https://openjdk.dev.java.net/">openjdk</a>
  878. project has provided the javac
  879. <a href="https://openjdk.dev.java.net/compiler/">compiler</a>
  880. as an opensource project. The output of this project is a
  881. <code>javac.jar</code> which contains the javac compiler.
  882. This compiler may be used with the <code>&lt;javac&gt;</code> task with
  883. the use of a <code>-Xbootclasspath/p</code> java argument. The argument needs
  884. to be given to the runtime system of the javac executable, so it needs
  885. to be prepended with a "-J". For example:
  886. <blockquote><pre>
  887. &lt;property name="patched.javac.jar"
  888. location="${my.patched.compiler}/dist/lib/javac.jar"/&gt;
  889. &lt;presetdef name="patched.javac"&gt;
  890. &lt;javac fork="yes"&gt;
  891. &lt;compilerarg value="-J-Xbootclasspath/p:${patched.javac.jar}"/&gt;
  892. &lt;/javac&gt;
  893. &lt;/presetdef&gt;
  894. &lt;patched.javac srcdir="src/java" destdir="build/classes"
  895. debug="yes"/&gt;
  896. </pre></blockquote>
  897. <h3>Note on package-info.java</h3>
  898. <p>
  899. <code>package-info.java</code> files were introduced in Java5 to
  900. allow package level annotations. On compilation, if the java file
  901. does not contain runtime annotations, there will be no .class file
  902. for the java file. Up to <b>Ant 1.7.1</b>, when the &lt;javac&gt;
  903. task is run again, the
  904. task will try to compile the package-info java files again.
  905. </p>
  906. <p>With Ant 1.7.1 a different kind of logic was introduced that
  907. involved the timestamp of the directory that would normally
  908. contain the .class file. This logic turned out to lead to Ant not
  909. recompiling <code>package-info.java</code> in certain setup.</p>
  910. <p>Starting with Ant 1.8.0 Ant will create
  911. "empty" <code>package-info.class</code> files if it compiles
  912. a <code>package-info.java</code> and
  913. no <code>package-info.class</code> file has been created by the
  914. compiler itself.</p>
  915. </body>
  916. </html>