1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
|
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<html>
<head>
<meta http-equiv="Content-Language" content="en-us">
<link rel="stylesheet" type="text/css" href="stylesheets/style.css">
<title>Installing Apache Ant</title>
</head>
<body>
<h1>Installing Apache Ant</h1>
<h2><a name="getting">Getting Apache Ant</a></h2>
<h3>The Short Story</h3>
<p>To get up and running with the binary edition of Ant quickly, follow these steps:
<ol>
<li>Make sure you have a Java environment installed, See <a href="#sysrequirements">System
Requirements</a> for details.</li>
<li>Download Ant. See <a href="#getBinary">Binary Edition</a> for details.</li>
<li>Uncompress the downloaded file into a directory.</li>
<li>Set environmental variables <code>JAVA_HOME</code> to your Java environment, <code>ANT_HOME</code> to
the directory you uncompressed Ant to, and add <code>${ANT_HOME}/bin</code> (Unix) or
<code>%ANT_HOME%/bin</code> (Windows) to your <code>PATH</code>. See <a href="#setup">Setup</a> for details.</li>
<li>Optionally, from the <code>ANT_HOME</code> directory run <code>ant -f fetch.xml -Ddest=system</code> to get
the library dependencies of most of the Ant tasks that require them. If you don't do this, many of the dependent
Ant tasks will not be available. See <a href="#optionalTasks">Optional Tasks</a> for details and other options
for the -Ddest parameter.</li>
<li>Optionally, add any desired Antlibs. See <a href="http://ant.apache.org/antlibs/proper.html" target="_top">Ant Libraries</a> for a list.
</ol>
</p>
<p>
Note that the links in the list above will give more details about each of the steps,
should you need them. Or you can just continue reading the rest of this document.
</p>
The short story for working with the Ant source code (not needed if you are working with the binary edition) is:
<ol>
<li>Get the source code. See <a href="#sourceEdition">Source Edition</a> for details.</li>
<li> Build Ant. See <a href="#buildingant">Building Ant</a> for details.</li>
</ol>
<p>
</p>
<p>
For the full story, continue reading.
</p>
<h3><a name="getBinary">Binary Edition</a></h3>
<p>The latest stable version of Ant is available from the Ant web page <a
href="http://ant.apache.org/" target="_top">http://ant.apache.org/</a>
</p>
<p>The binary edition of Ant is shipped with 3 different compression formats:
<ol>
<li><b>.zip</b> - Recommended compression format for Windows, can also be used on other platforms. Supported
by many programs and some operating systems natively.</li>
<li><b>.tar.gz</b> - Uses the tar program to gather files together, and gzip to compress and uncompress.</li>
<li><b>.tar.bz2</b> - Uses the tar program to gather files together, and bzip2 to compress and uncompress..</li>
</ol>
Choose the format that is best supported for your platform.
</p>
<h3>As a binary in an RPM Package</h3>
<p>Consult the <a href="#jpackage">jpackage</a> section below.</p>
<h3>Bundled in IDEs</h3>
<p>
All the main Java IDEs ship with Ant, products such as Eclipse, NetBeans
and IntelliJ IDEA. If you install Ant this way you usually get the most recent
release of Ant at the time the IDE was released. Some of the IDEs (Eclipse
and NetBeans in particular) ship with extra tasks that only work if
IDE-specific tools are on Ant's path. To use these on command-line versions
of Ant, the relevant JARs need to be added to the command-line Ant as
extra libraries/tasks. Note that if it is an IDE task or extension that is
not behaving, the Ant team is unable to field bug reports. Try the IDE mailing
lists first, who will cross-file bugs if appropriate.
</p>
<p>
IDE's can invariably be pointed at different Ant installations. This lets
developers upgrade to a new release of Ant, and eliminate inconsistencies
between command-line and IDE Ant.
</p>
<h3>Bundled in Java applications</h3>
<p>
Many Java applications, most particularly application servers, ship with
a version of Ant. These are primarily for internal use by the application,
using the Java APIs to delegate tasks such as JSP page compilation to the Ant
runtime. Such distributions are usually unsupported by everyone. Particularly
troublesome are those products that not only ship with their own Ant release,
they add their own version of ANT.BAT or ant.sh to the PATH. If Ant starts
behaving wierdly after installing something, try the
<a href="#diagnostics">diagnostics</a> advice.
</p>
<h3><a name="sourceEdition">Source Edition</a></h3>
<p>If you prefer the source edition, you can download the source for the latest
Ant release from
<a href="http://ant.apache.org/srcdownload.cgi" target="_top">http://ant.apache.org/srcdownload.cgi</a>.
If you prefer the leading-edge code, you can access
the code as it is being developed via SVN. The Ant website has details on
<a href="http://ant.apache.org/svn.html" target="_top">accessing SVN</a>.
All bug fixes will go in against the HEAD of the source tree, and the first
response to many bugreps will be "have you tried the latest version".
Don't be afraid to download and build a prererelease edition, as everything
other than new features are usually stable.
</p>
<p>
See the section <a href="#buildingant">Building Ant</a> on how to
build Ant from the source code.
You can also access the
<a href="http://svn.apache.org/viewcvs.cgi/ant/" target="_top">
Ant SVN repository</a> on-line. </p>
<h3 name="archives">Archive Download Area Layout</h3>
<p>
Older versions of Ant are available in the archives at <a
href="http://archive.apache.org/dist/ant/" target="_top">http://archive.apache.org/dist/ant/</a>. The
files are organized as follows.
</p>
<table>
<tr>
<th>Filename or Path</th>
<th>Description</th>
</tr>
<tr>
<td>KEYS</td>
<td>PGP-Keysfile. It contains the PGP-keys of Ant developers so you can 'trust' the distribution. </td>
</tr>
<tr>
<td>RELEASE-NOTES-{version}.html</td>
<td>
Release notes of the given version in HTML format. When upgrading your Ant installation you
should have a look at the <i>Changes that could break older environments</i> section.
</td>
</tr>
<tr>
<td>ant-current-bin.zip</td>
<td>
ZIP-Archive containing the compiled version of Ant in the last released version. It is recommended that
you do not download the latest version this way, as the standard way of downloading described above will
redirect you to a mirror closer to you, thus making the download faster for you and reducing the load
on Apache servers.
</td>
</tr>
<tr>
<td>ant-current-src.zip</td>
<td>
ZIP-Archive containing the sources of Ant. If you have this you could compile Ant itself.
If you do not have the <i>required</i> dependencies, the classes depending on them are just not
built. Again, it is preferred to use the standard way of getting the source package described above
to make your download quicker and to reduce the load on Apache servers.
</td>
</tr>
<tr>
<td>ant-current-*.asc</td>
<td>
Security file for checking the correctness of the zip file. This one is the
<a href="http://en.wikipedia.org/wiki/Pretty_Good_Privacy" target="_blank">PGP</a> key.
</td>
</tr>
<tr>
<td>ant-current-*.md5</td>
<td>
Security file for checking the correctness of the zip file. This one is the
<a href="http://en.wikipedia.org/wiki/Md5" target="_blank">MD5</a> key.
</td>
</tr>
<tr>
<td>ant-current-*.sha1</td>
<td>
Security file for checking the correctness of the zip file. This one is the
<a href="http://en.wikipedia.org/wiki/SHA-1" target="_blank">SHA1</a> key.
</td>
</tr>
<tr>
<td>antlibs/</td>
<td>
This directory holds the Antlibs that are made of available by the Apache Ant project.
Antlibs are bundles of Ant tasks that are not delivered as part of the Ant core but are
available as optional downloads.
</td>
</tr>
<tr>
<td>binaries/</td>
<td>
The binaries directory holds specific Ant releases bundled in both ZIP and tar.gz compression
formats. The named releases are in contrast to the ant-current-bin.zip file in the parent
directory, which is always guaranteed to be the most current release of Ant.
</td>
</tr>
<tr>
<td>common/</td>
<td>
The common directory holds various files, such as the Apache License file that Ant is licensed
under, that people may wish to examine without having to download the whole Ant distribution.
</td>
</tr>
<tr>
<td>source/</td>
<td>
The source directory holds the source code for specific Ant releases bundled in both ZIP and
tar.gz compression formats. The named releases are in contrast to the ant-current-src.zip file
in the parent directory, which is always guaranteed to hold the source code for the most current
release of Ant.
</td>
</tr>
</table>
<hr>
<h2><a name="sysrequirements">System Requirements</a></h2>
Ant has been used successfully on many platforms, including Linux,
commercial flavours of Unix such as Solaris and HP-UX,
Windows NT-platforms, OS/2 Warp, Novell Netware 6, OpenVMS and MacOS X.
The platforms used most for development are, in no particular order,
Linux, MacOS X, Windows XP and Unix; these are therefore that platforms
that tend to work best. As of Ant1.7, Windows 9x is no longer supported.
<p>
For the current version of Ant, you will also need a JDK installed on
your system, version 1.4 or later required, 1.5 or later strongly recommended.
The later the version of Java , the more Ant tasks you get.
</p>
<p>
<strong>Note: </strong>If a JDK is not present, only the JRE runtime, then many tasks will not work.
</p>
<p>
<strong>Note: </strong>
Ant 1.8.* works with jdk1.4 and higher, Ant 1.7.* works with jdk1.3 and higher, Ant 1.6.* works with jdk 1.2 and higher,
Ant 1.2 to Ant 1.5.* work with jdk 1.1 and higher.
</p>
<h3>Open Source Java Runtimes</h3>
<p>
The Ant team strongly supports users running Ant on Kaffe and other
open source Java runtimes, and so strives to have a product that works
well on those platforms. What appears to work well is Kaffe with
Gnu Classpath and the Xerces and Xalan libraries.
</p>
<hr>
<h2><a name="installing">Installing Ant</a></h2>
<p>The binary distribution of Ant consists of the following directory layout:
<pre>
ant
+--- README, LICENSE, fetch.xml, other text files. //basic information
+--- bin // contains launcher scripts
|
+--- lib // contains Ant jars plus necessary dependencies
|
+--- docs // contains documentation
| |
| +--- images // various logos for html documentation
| |
| +--- manual // Ant documentation (a must read ;-)
|
+--- etc // contains xsl goodies to:
// - create an enhanced report from xml output of various tasks.
// - migrate your build files and get rid of 'deprecated' warning
// - ... and more ;-)
</pre>
Only the <code>bin</code> and <code>lib</code> directories are
required to run Ant.
To install Ant, choose a directory and copy the distribution
files there. This directory will be known as ANT_HOME.
</p>
<table width="80%">
<tr>
<td colspan="2">
<b>Windows 95, Windows 98 & Windows ME Note:</b>
</td>
</tr>
<tr>
<td width="5%"> </td>
<td><i>
Note that current releases of Ant no longer support these systems. If you are using an older
version of Ant, however, the script used to launch Ant will have
problems if ANT_HOME is a long filename (i.e. a filename which is not
of the format known as "8.3"). This is due to
limitations in the OS's handling of the <code>"for"</code>
batch-file statement. It is recommended, therefore, that Ant be
installed in a <b>short</b>, 8.3 path, such as C:\Ant. </i>
</td>
</tr>
<tr>
<td width="5%"> </td>
<td>
<p>On these systems you will also need to configure more environment
space to cater for the environment variables used in the Ant launch script.
To do this, you will need to add or update the following line in
the <code>config.sys</code> file
</p>
<p><code>shell=c:\command.com c:\ /p /e:32768</code></p>
</td>
</tr>
</table>
<h3><a name="setup">Setup</a></h3>
<p>
Before you can run Ant there is some additional set up you
will need to do unless you are installing the <a href="#jpackage">RPM
version from jpackage.org</a>:</p>
<ul>
<li>Add the <code>bin</code> directory to your path.</li>
<li>Set the <code>ANT_HOME</code> environment variable to the
directory where you installed Ant. On some operating systems, Ant's
startup scripts can guess <code>ANT_HOME</code> (Unix dialects and
Windows NT/2000), but it is better to not rely on this behavior.</li>
<li>Optionally, set the <code>JAVA_HOME</code> environment variable
(see the <a href="#advanced">Advanced</a> section below).
This should be set to the directory where your JDK is installed.</li>
</ul>
<p>Operating System-specific instructions for doing this from the command
line are in the <a href="#windows">Windows</a>, <a href="#bash">Linux/Unix (bash)</a>,
and <a href="#tcshcsh">Linux/Unix (csh)</a> sections. Note that using this method,
the settings will only be valid for the command line session you run them in.</p>
<p><strong>Note:</strong> Do not install Ant's ant.jar file into the lib/ext
directory of the JDK/JRE. Ant is an application, whilst the extension
directory is intended for JDK extensions. In particular there are security
restrictions on the classes which may be loaded by an extension.</p>
<table width="80%">
<tr>
<td colspan="2">
<b>Windows Note:</b>
</td>
</tr>
<tr>
<td width="5%"> </td>
<td>
The ant.bat script makes use of three environment variables -
ANT_HOME, CLASSPATH and JAVA_HOME. <b>Ensure</b> that ANT_HOME and JAVA_HOME variables are set,
and that they do <b><u>not</u></b> have quotes (either
' or ") and they do <b><u>not</u></b> end with \ or with /. CLASSPATH should be unset or
empty.
</td>
</tr>
</table>
<h3><a name="checkInstallation">Check Installation</a></h3>
<p>You can check the basic installation with opening a new shell and typing <tt>ant</tt>. You
should get a message like this
<pre>
Buildfile: build.xml does not exist!
Build failed
</pre>
So Ant works. This message is there because you need to write an individual buildfile for your
project. With a <tt>ant -version</tt> you should get an output like
<pre>
Apache Ant version 1.7.1 compiled on June 27 2008
</pre>
</p>
<p>If this does not work ensure your environment variables are set right. They must resolve to:
<ul>
<li>required: %ANT_HOME%\bin\ant.bat</li>
<li>optional: %JAVA_HOME%\bin\java.exe</li>
<li>required: %PATH%=...<i>maybe-other-entries</i>...;%ANT_HOME%\bin;...<i>maybe-other-entries</i>...</li>
</ul>
<b>ANT_HOME</b> is used by the launcher script for finding the libraries.
<b>JAVA_HOME</b> is used by the launcher for finding the JDK/JRE to use. (JDK is recommended as some tasks
require the java tools.) If not set, the launcher tries to find one via the %PATH% environment variable.
<b>PATH</b> is set for user convenience. With that set you can just start <i>ant</i> instead of always typing
<i>the/complete/path/to/your/ant/installation/bin/ant</i>.
</p>
<h3><a name="optionalTasks">Optional Tasks</a></h3>
<p>Ant supports a number of optional tasks. An optional task is a task which
typically requires an external library to function. The optional tasks are
packaged together with the core Ant tasks.</p>
<p>The external libraries required by each of the optional tasks is detailed
in the <a href="#librarydependencies">Library Dependencies</a> section. These external
libraries must be added to Ant's classpath, in any of the following ways:
</p>
<ul>
<li><p>
In <code><i>ANT_HOME</i>/lib</code>. This makes the JAR files available to all
Ant users and builds.
</p></li>
<li><p>
In <code>${user.home}/.ant/lib</code> (as of Ant 1.6). This
allows different users to add new libraries to Ant. All JAR files
added to this directory are available to command-line Ant.
</p></li>
<li><p>
On the command line with a <code>-lib</code> parameter. This lets
you add new JAR files on a case-by-case basis.
</p></li>
<li><p>
In the <code>CLASSPATH</code> environment variable. Avoid this; it makes
the JAR files visible to <i>all</i> Java applications, and causes
no end of support calls. See <a href="#classpath">below</a> for details.
</p>
</li>
<li><p>
In some <code><classpath></code> accepted by the task itself.
For example, as of Ant 1.7.0 you can run the <code><junit></code>
task without <code>junit.jar</code> in Ant's own classpath, so long as
it is included (along with your program and tests) in the classpath
passed when running the task.
</p><p>
Where possible, this option is generally
to be preferred, as the Ant script itself can determine the best path
to load the library from: via relative path from the basedir (if you
keep the library under version control with your project), according
to Ant properties, environment variables, Ivy downloads, whatever you like.
</p></li>
</ul>
<p>
If you are using the binary version of Ant, or if you are working from source
code, you can easily gather most of the dependencies and install them for use
with your Ant tasks. In your <code>ANT_HOME</code> directory you should see a
file called <code>fetch.xml</code>. This is an Ant script that you can run to
install almost all the dependencies the optional Ant tasks need.
</p>
<p>
To do so, change to the <code>ANT_HOME</code> directory and execute the command:
</p>
<blockquote>
<pre>ant -f fetch.xml -Ddest=<i>[option]</i></pre>
</blockquote
<p>
where option is one of the following, as described above:
<ul>
<li><code>system</code> - store in Ant's lib directory <i>(Recommended)</i></li>
<li><code>user</code> - store in the user's home directory</li>
<li><code>optional</code> - store in Ant's source code lib/optional directory, used if building Ant source code</li>
</ul>
</p>
<p>
You may also need to set proxy settings. See the <a href="#proxy">Proxy Settings</a> section for details.
</p>
<p>
Note that not all dependencies are gathered using <code>fetch.xml</code>. Tasks that depend on
commercial software, in particular, will require you to have the commercial software installed
in order to be used.
</p>
<p>The Apache Ant Project also provides additional tasks and types that are available as separately
downloaded Ant Libraries. You can see the the list of available Antlibs at
the <a href="http://ant.apache.org/antlibs/proper.html" target="_top">Ant Libraries</a> page.
</p>
<p>You can also find tasks and types provided by third-party projects at the
<a href="http://ant.apache.org/external.html" target="_top">External Tools and Tasks</a> page.
</p>
<p>
IDEs have different ways of adding external JAR files and third-party tasks
to Ant. Usually it is done by some configuration dialog. Sometimes JAR files
added to a project are automatically added to ant's classpath.
</p>
<h3><a name="classpath">The <code>CLASSPATH</code> environment variable</a></h3>
<p>
The <code>CLASSPATH</code> environment variable is a source of many Ant support queries. As
the round trip time for diagnosis on the Ant user mailing list can be slow, and
because filing bug reports complaining about 'ant.bat' not working will be
rejected by the developers as WORKSFORME "this is a configuration problem, not a
bug", you can save yourself a lot of time and frustration by following some
simple steps.
</p>
<ol>
<li>Do not ever set <code>CLASSPATH</code>. Ant does not need it, it only causes confusion
and breaks things.
</li>
<li>If you ignore the previous rule, do not ever, ever, put quotes in the
<code>CLASSPATH</code>, even if there is a space in a directory. This will break Ant, and it
is not needed. </li>
<li>If you ignore the first rule, do not ever, ever, have a trailing backslash
in a <code>CLASSPATH</code>, as it breaks Ant's ability to quote the string. Again, this is
not needed for the correct operation of the <code>CLASSPATH</code> environment variable, even
if a DOS directory is to be added to the path. </li>
<li>You can stop Ant using the <code>CLASSPATH</code> environment variable by setting the
<code>-noclasspath</code> option on the command line. This is an easy way
to test for classpath-related problems.</li>
</ol>
<p>
The usual symptom of <code>CLASSPATH</code> problems is that ant will not run with some error
about not being able to find <code>org.apache.tools.ant.launch.Launcher</code>, or, if you have got the
quotes/backslashes wrong, some very weird Java startup error. To see if this is
the case, run <code>ant -noclasspath</code> or unset the <code>CLASSPATH</code> environment
variable.
</p>
<p>
You can also make your Ant script reject this environment
variable just by placing the following at the top of the script (or in an init target):
</p>
<pre>
<property environment="env."/>
<property name="env.CLASSPATH" value=""/>
<fail message="Unset $CLASSPATH / %CLASSPATH% before running Ant!">
<condition>
<not>
<equals arg1="${env.CLASSPATH}" arg2=""/>
</not>
</condition>
</fail>
</pre>
<h3><a name="proxy">Proxy Configuration</a></h3>
<p> Many Ant built-in and third-party tasks use network connections to retrieve
files from HTTP servers. If you are behind a firewall with a proxy server, then
Ant needs to be configured with the proxy. Here are the different ways to do
this. </p>
<ul>
<li><b>With Java1.5</b><br>
<p>
When you run Ant on Java1.5, you could try to use the automatic proxy setup
mechanism with <code>-autoproxy</code>.
</p>
</li>
<li><b>With explicit JVM properties.</b><br>
<p>
These are documented <a
href="http://download.oracle.com/javase/1.5.0/docs/guide/net/properties.html" target="_top">by Oracle</a>,
and control the proxy behaviour of the entire JVM. To set them in Ant, declare
them in the <code>ANT_OPTS</code> environment variable. This is the best option
for a non-mobile system. For a laptop, you have to change these settings as you
roam. To set ANT_OPTS:
</p>
<blockquote>
<p>
For csh/tcsh:
</p>
<pre>
setenv ANT_OPTS "-Dhttp.proxyHost=proxy -Dhttp.proxyPort=8080"
</pre>
<p>
For bash:
</p>
<pre>
export ANT_OPTS="-Dhttp.proxyHost=proxy -Dhttp.proxyPort=8080"
</pre>
<p>
For Windows, set the environment variable in the appropriate dialog box
and open a new console. or, by hand
</p>
<pre>
set ANT_OPTS = -Dhttp.proxyHost=proxy -Dhttp.proxyPort=8080
</pre>
</p>
</blockquote>
</li>
<li><b>In the build file itself</b><br>
<p>
If you are writing a build file that is always to be used behind the firewall,
the <setproxy> task lets you configure the proxy (which it does by setting
the JVM properties). If you do this, we strongly recommend using ant properties
to define the proxy host, port, etc, so that individuals can override the
defaults.</li>
</p>
</ul>
<p> The Ant team acknowledges that this is unsatisfactory. Until the JVM
automatic proxy setup works properly everywhere, explicit JVM options via
ANT_ARGS are probably the best solution. Setting properties on Ant's
command line do not work, because those are <i>Ant properties</i> being set, not
JVM options. This means the following does not set up the command line:
</p>
<pre>ant -Dhttp.proxyHost=proxy -Dhttp.proxyPort=81</pre>
<p> All it does is set up two Ant properties.</p>
<p>One other troublespot with
proxies is with authenticating proxies. Ant cannot go beyond what the JVM does
here, and as it is very hard to remotely diagnose, test and fix proxy-related
problems, users who work behind a secure proxy will have to spend much time
configuring the JVM properties until they are happy. </p>
<h3><a name="windows">Windows and OS/2</a></h3>
<p>Assume Ant is installed in <code>c:\ant\</code>. The following sets up the
environment:</p>
<pre>set ANT_HOME=c:\ant
set JAVA_HOME=c:\jdk-1.5.0.05
set PATH=%PATH%;%ANT_HOME%\bin</pre>
<h3><a name="bash">Linux/Unix (bash)</a></h3>
<p>Assume Ant is installed in <code>/usr/local/ant</code>. The following sets up
the environment:</p>
<pre>export ANT_HOME=/usr/local/ant
export JAVA_HOME=/usr/local/jdk-1.5.0.05
export PATH=${PATH}:${ANT_HOME}/bin</pre>
<h3><a name="tcshcsh">Linux/Unix (csh)</a></h3>
<pre>setenv ANT_HOME /usr/local/ant
setenv JAVA_HOME /usr/local/jdk/jdk-1.5.0.05
set path=( $path $ANT_HOME/bin )</pre>
<p>
Having a symbolic link set up to point to the JVM/JDK version makes updates more seamless. </p>
<a name="jpackage"></a>
<h3>RPM version from jpackage.org</h3>
<p>
The <a href="http://www.jpackage.org" target="_top">JPackage project</a> distributes an RPM version of Ant.
With this version, it is not necessary to set <code> JAVA_HOME </code>or
<code> ANT_HOME </code>environment variables and the RPM installer will correctly
place the Ant executable on your path.
</p>
<p>
<b>NOTE:</b> <em>Since Ant 1.7.0</em>, if the <code>ANT_HOME</code>
environment variable is set, the jpackage distribution will be
ignored.
</p>
<p>
Optional jars for the JPackage version are handled in two ways. The easiest, and
best way is to get these external libraries from JPackage if JPackage has them
available. (Note: for each such library, you will have to get both the external
package itself (e.g. <code>oro-2.0.8-2jpp.noarch.rpm</code>) and the small library that links
ant and the external package (e.g. <code>ant-apache-oro-1.6.2-3jpp.noarch.rpm</code>).
</p><p>
However, JPackage does not package proprietary software, and since some of the
optional packages depend on proprietary jars, they must be handled as follows.
This may violate the spirit of JPackage, but it is necessary if you need these proprietary packages.
For example, suppose you want to install support for netrexx, which jpackage does not
support:
<ol>
<li>Decide where you want to deploy the extra jars. One option is in <code>$ANT_HOME/lib</code>,
which, for JPackage is usually <code>/usr/share/ant/lib</code>. Another, less messy option
is to create an <code>.ant/lib</code> subdirectory of your home directory and place your
non-jpackage ant jars there, thereby avoiding mixing jpackage
libraries with non-jpackage stuff in the same folder.
More information on where Ant finds its libraries is available
<a href="http://ant.apache.org/manual/running.html#libs">here</a></li>
<li>Download a non-jpackage binary distribution from the regular
<a href="http://ant.apache.org/bindownload.cgi" target="_top">Apache Ant site</a></li>
<li>Unzip or untar the distribution into a temporary directory</li>
<li>Copy the linking jar, in this case <code>ant-jai.jar</code>, into the library directory you
chose in step 1 above.</li>
<li>Copy the proprietary jar itself into the same directory.</li>
</ol>
Finally, if for some reason you are running on a system with both the JPackage and Apache versions of Ant
available, if you should want to run the Apache version (which will have to be specified with an absolute file name,
not found on the path), you should use Ant's <code>--noconfig</code> command-line switch to avoid JPackage's classpath mechanism.
<h3><a name="advanced">Advanced</a></h3>
<p>There are lots of variants that can be used to run Ant. What you need is at
least the following:</p>
<ul>
<li>The classpath for Ant must contain <code>ant.jar</code> and any jars/classes
needed for your chosen JAXP-compliant XML parser.</li>
<li>When you need JDK functionality
(such as for the <a href="Tasks/javac.html">javac</a> task or the
<a href="Tasks/rmic.html">rmic</a> task), then <code>tools.jar</code>
must be added. The scripts supplied with Ant,
in the <code>bin</code> directory, will add
the required JDK classes automatically, if the <code>JAVA_HOME</code>
environment variable is set.</li>
<li>When you are executing platform-specific applications, such as the
<a href="Tasks/exec.html">exec</a> task or the
<a href="Tasks/cvs.html">cvs</a> task, the property <code>ant.home</code>
must be set to the directory containing where you installed Ant. Again
this is set by the Ant scripts to the value of the ANT_HOME environment
variable.</li>
</ul>
The supplied ant shell scripts all support an <tt>ANT_OPTS</tt>
environment variable which can be used to supply extra options
to ant. Some of the scripts also read in an extra script stored
in the users home directory, which can be used to set such options. Look
at the source for your platform's invocation script for details.
<hr>
<h2><a name="buildingant">Building Ant</a></h2>
<p>To build Ant from source, you can either install the Ant source distribution
or checkout the ant module from SVN. See <a href="#sourceEdition">Source Edition</a> for details.</p>
<p>Once you have installed the source, change into the installation
directory.</p>
<p>Set the <code>JAVA_HOME</code> environment variable
to the directory where the JDK is installed.
See <a href="#installing">Installing Ant</a>
for examples on how to do this for your operating system. </p>
<p><b>Note</b>: The bootstrap process of Ant requires a greedy
compiler like Sun's javac or jikes. It does not work with gcj or
kjc.</p>
<p>Make sure you have downloaded any auxiliary jars required to
build tasks you are interested in. These should be
added to the <code>lib/optional</code>
directory of the source tree.
See <a href="#librarydependencies">Library Dependencies</a>
for a list of JAR requirements for various features.
Note that this will make the auxiliary JAR
available for the building of Ant only. For running Ant you will
still need to
make the JARs available as described under
<a href="#installing">Installing Ant</a>.</p>
<p>You can also get most of the auxiliary jar files (ie. the jar files
that various optional Ant tasks depend on) by running Ant on the
<code>fetch.xml</code> build file. See <a href="#optionalTasks">Optional
Tasks</a> for instructions on how to do this.
</p>
<p>As of version 1.7.0 Ant has a hard dependency on JUnit. The <code>fetch.xml</code> build
script will download JUnit automatically, but if you don't use this you must
install it manually into <code>lib/optional</code> (download it from
<a href="http://junit.org/" target="_top">JUnit.org</a>) if you are
using a source distribution of Ant.</p>
<p>Your are now ready to build Ant:</p>
<blockquote>
<p><code>build -Ddist.dir=<<i>directory_to_contain_Ant_distribution</i>> dist</code> (<i>Windows</i>)</p>
<p><code>sh build.sh -Ddist.dir=<<i>directory_to_contain_Ant_distribution</i>> dist</code> (<i>Unix</i>)</p>
</blockquote>
<p>This will create a binary distribution of Ant in the directory you specified.</p>
<p>The above action does the following:</p>
<ul>
<li>If necessary it will bootstrap the Ant code. Bootstrapping involves the manual
compilation of enough Ant code to be able to run Ant. The bootstrapped Ant is
used for the remainder of the build steps. </li>
<li>Invokes the bootstrapped Ant with the parameters passed to the build script. In
this case, these parameters define an Ant property value and specify the "dist" target
in Ant's own <code>build.xml</code> file.</li>
<li>Create the ant.jar and ant-launcher.jar JAR files</li>
<li>Create optional JARs for which the build had the relevant libraries. If
a particular library is missing from ANT_HOME/lib/optional, then the matching
ant- JAR file will not be created. For example, ant-junit.jar is only built
if there is a junit.jar in the optional directory.</li>
</ul>
<p>On most occasions you will not need to explicitly bootstrap Ant since the build
scripts do that for you. If however, the build file you are using makes use of features
not yet compiled into the bootstrapped Ant, you will need to manually bootstrap.
Run <code>bootstrap.bat</code> (Windows) or <code>bootstrap.sh</code> (UNIX)
to build a new bootstrap version of Ant.</p>
If you wish to install the build into the current <code>ANT_HOME</code>
directory, you can use:
<blockquote>
<p><code>build install</code> (<i>Windows</i>)</p>
<p><code>sh build.sh install</code> (<i>Unix</i>)</p>
</blockquote>
You can avoid the lengthy Javadoc step, if desired, with:
<blockquote>
<p><code>build install-lite</code> (<i>Windows</i>)</p>
<p><code>sh build.sh install-lite</code> (<i>Unix</i>)</p>
</blockquote>
This will only install the <code>bin</code> and <code>lib</code> directories.
<p>Both the <code>install</code> and
<code>install-lite</code> targets will overwrite
the current Ant version in <code>ANT_HOME</code>.</p>
<p>Ant's build script will try to set executable flags for its shell
scripts on Unix-like systems. There are various reasons why the
chmod-task might fail (like when you are running the build script as
a different user than the one who installed Ant initially). In this
case you can set the Ant property <code>chmod.fail</code> to false
when starting the build like in
<blockquote>
<p><code>sh build.sh install -Dchmod.fail=false</code></p>
</blockquote>
and any error to change permission will not result in a build failure.</p>
<hr>
<h2><a name="librarydependencies">Library Dependencies</a></h2>
<p>The following libraries are needed in Ant's classpath
if you are using the
indicated feature. Note that only one of the regexp libraries is
needed for use with the mappers
(and Java includes a regexp implementation which
Ant will find automatically).
You will also need to install the particular
Ant optional jar containing the task definitions to make these
tasks available. Please refer to the <a href="#optionalTasks">
Installing Ant / Optional Tasks</a> section above.</p>
<table border="1" cellpadding="2" cellspacing="0">
<tr>
<td><b>Jar Name</b></td>
<td><b>Needed For</b></td>
<td><b>Available At</b></td>
</tr>
<tr>
<td>jakarta-regexp-1.3.jar</td>
<td>regexp type with mappers (if you do not wish to use java.util.regex)</td>
<td><a href="http://attic.apache.org/projects/jakarta-regexp.html" target="_top">http://attic.apache.org/projects/jakarta-regexp.html</a></td>
</tr>
<tr>
<td>jakarta-oro-2.0.8.jar</td>
<td>regexp type with mappers (if you do not wish to use java.util.regex) and the Perforce tasks<br>
To use the FTP task,
you need jakarta-oro 2.0.8 or later, and <a href="#commons-net">commons-net</a></td>
<td><a href="http://attic.apache.org/projects/jakarta-oro.html" target="_top">http://attic.apache.org/projects/jakarta-oro.html</a></td>
</tr>
<tr>
<td>junit.jar</td>
<td><code><junit></code> task. May be in classpath passed to task rather than Ant's classpath.</td>
<td><a href="http://www.junit.org/" target="_top">http://www.junit.org/</a></td>
</tr>
<tr>
<td>xalan.jar</td>
<td>junitreport task</td>
<td><a href="http://xml.apache.org/xalan-j/" target="_top">http://xml.apache.org/xalan-j/</a></td>
</tr>
<tr>
<td>antlr.jar</td>
<td>antlr task</td>
<td><a href="http://www.antlr.org/" target="_top">http://www.antlr.org/</a></td>
</tr>
<tr>
<td>bsf.jar</td>
<td>script task
<p>
<strong>Note</strong>: Ant 1.6 and later require Apache BSF, not
the IBM version. I.e. you need BSF 2.3.0-rc1 or later.
</p>
<p>
<strong>Note</strong>: BSF 2.4.0 is needed to use a post 1.5R3 version
of rhino's javascript.
</p>
<p>
<strong>Note</strong>: BSF 2.4.0 uses jakarta-commons-logging
so it needs the commons-logging.jar.
</p>
</td>
<td><a href="http://jakarta.apache.org/bsf/" target="_top">http://jakarta.apache.org/bsf/</a></td>
</tr>
<tr>
<td>Groovy jars</td>
<td>Groovy with script and scriptdef tasks<br>
You need to get the groovy jar and two asm jars from a groovy
installation. The jars are groovy-[version].jar, asm-[version].jar and
asm-util-[version].jar and antlr-[version].jar.
As of groovy version 1.0-JSR-06, the jars are
groovy-1.0-JSR-06.jar, antlr-2.7.5.jar, asm-2.2.jar and asm-util-2.2.jar.
Alternatively one may use the embedded groovy jar file.
This is located in the embedded directory of the groovy distribution.
This bundles all the needed jar files into one jar file.
It is called groovy-all-[version].jar.
</td>
<td>
<a href="http://groovy.codehaus.org/" target="_top">http://groovy.codehaus.org/</a>
<br>
The asm jars are also available from the creators of asm -
<a href="http://asm.objectweb.org/" target="_top">http://asm.objectweb.org/</a>
</td>
</tr>
<tr>
<td>netrexx.jar</td>
<td>netrexx task, Rexx with the script task</td>
<td><a href="http://www.ibm.com/software/awdtools/netrexx/download.html" target="_top">
http://www.ibm.com/software/awdtools/netrexx/download.html</a></td>
</tr>
<tr>
<td>js.jar</td>
<td>Javascript with script task<br>
If you use Apache BSF 2.3.0-rc1, you must use rhino 1.5R3 (later
versions of BSF (e.g. version 2.4.0) work with 1.5R4 and higher).</td>
<td><a href="http://www.mozilla.org/rhino/" target="_top">http://www.mozilla.org/rhino/</a></td>
</tr>
<tr>
<td>jython.jar</td>
<td>Python with script task<br>
Warning : jython.jar also contains classes from jakarta-oro.
Remove these classes if you are also using jakarta-oro.</td>
<td><a href="http://jython.sourceforge.net/" target="_top">http://jython.sourceforge.net/</a></td>
</tr>
<tr>
<td>jpython.jar</td>
<td>Python with script task <b>deprecated, jython is the preferred engine</b></td>
<td><a href="http://www.jpython.org/" target="_top">http://www.jpython.org/</a></td>
</tr>
<tr>
<td>jacl.jar and tcljava.jar</td>
<td>TCL with script task</td>
<td><a href="http://www.scriptics.com/software/java/" target="_top">http://www.scriptics.com/software/java/</a></td>
</tr>
<tr>
<td>BeanShell JAR(s)</td>
<td>BeanShell with script task.
<br>
<strong>Note</strong>: Ant requires BeanShell version 1.3 or
later</td>
<td><a href="http://www.beanshell.org/" target="_top">http://www.beanshell.org/</a></td>
</tr>
<tr>
<td>jruby.jar</td>
<td>Ruby with script task</td>
<td><a href="http://jruby.org/" target="_top">http://jruby.org/</a></td>
</tr>
<tr>
<td>judo.jar</td>
<td>Judoscript with script task</td>
<td><a href="http://www.judoscript.org/" target="_top">http://www.judoscript.org/</a></td>
</tr>
<tr>
<td>commons-logging.jar</td>
<td>CommonsLoggingListener</td>
<td><a href="http://commons.apache.org/logging/"
target="_top">http://commons.apache.org/logging/</a></td>
</tr>
<tr>
<td>log4j.jar</td>
<td>Log4jListener</td>
<td><a href="http://logging.apache.org/log4j/"
target="_top">http://logging.apache.org/log4j/</a></td>
</tr>
<tr>
<td><a name="commons-net">commons-net.jar</a></td>
<td>ftp, rexec and telnet tasks<br>
jakarta-oro 2.0.8 or later is required together with commons-net 1.4.0.<br>
For all users, a minimum version of commons-net of 1.4.0 is recommended. Earlier
versions did not support the full range of configuration options, and 1.4.0 is needed
to compile Ant.
</td>
<td><a href="http://commons.apache.org/net/"
target="_top">http://commons.apache.org/net/</a></td>
</tr>
<tr>
<td>bcel.jar</td>
<td>classfileset data type,
JavaClassHelper used by the ClassConstants filter reader and
optionally used by ejbjar for dependency determination
</td>
<td><a href="http://commons.apache.org/bcel/" target="_top">http://commons.apache.org/bcel/</a></td>
</tr>
<tr>
<td>mail.jar</td>
<td>Mail task with Mime encoding, and the MimeMail task</td>
<td><a href="http://www.oracle.com/technetwork/java/index-jsp-139225.html"
target="_top">http://www.oracle.com/technetwork/java/index-jsp-139225.html</a></td>
</tr>
<tr>
<td>activation.jar</td>
<td>Mail task with Mime encoding, and the MimeMail task</td>
<td><a href="http://www.oracle.com/technetwork/java/javase/jaf-135115.html"
target="_top">http://www.oracle.com/technetwork/java/javase/jaf-135115.html</a></td>
</tr>
<tr>
<td>jdepend.jar</td>
<td>jdepend task</td>
<td><a href="http://www.clarkware.com/software/JDepend.html"
target="_top">http://www.clarkware.com/software/JDepend.html</a></td>
</tr>
<tr>
<td>resolver.jar <b>1.1beta or later</b></td>
<td>xmlcatalog datatype <em>only if support for external catalog files is desired</em></td>
<td><a href="http://xml.apache.org/commons/"
target="_top">http://xml.apache.org/commons/</a>.</td>
</tr>
<tr>
<td>jsch.jar <b>0.1.42 or later</b></td>
<td>sshexec and scp tasks</td>
<td><a href="http://www.jcraft.com/jsch/index.html"
target="_top">http://www.jcraft.com/jsch/index.html</a></td>
</tr>
<tr>
<td>JAI - Java Advanced Imaging</td>
<td>image task</td>
<td><a href="https://jai.dev.java.net/"
target="_top">https://jai.dev.java.net/</a></td>
</tr>
</table>
<br>
<h2><a name="Troubleshooting">Troubleshooting</a></h2>
<h3><a name="diagnostics">Diagnostics</a></h3>
<p> Ant has a built in diagnostics feature. If you run <code>ant
-diagnostics</code> ant will look at its internal state and print it out. This
code will check and print the following things. </p>
<ul>
<li>Where Ant is running from. Sometimes you can be surprised.</li>
<li>The version of ant.jar and of the ant-*.jar containing the optional tasks -
and whether they match</li>
<li>Which JAR files are in ANT_HOME/lib
<li>Which optional tasks are available. If a task is not listed as being
available, either it is not present, or libraries that it depends on are
absent.</li>
<li>XML Parser information</li>
<li>JVM system properties
</li>
<li>The status of the temp directory. If this is not writable, or its clock is
horribly wrong (possible if it is on a network drive), a lot of tasks will fail
with obscure error messages.</li>
<li>The current time zone as Java sees it. If this is not what it should be for
your location, then dependency logic may get confused.
</ul>
<p>
Running <code>ant -diagnostics</code> is a good way to check that ant is
installed. It is also a first step towards self-diagnosis of any problem.
Any configuration problem reported to the user mailing list will probably
result ins someone asking you to run the command and show the results, so
save time by using it yourself.
</p>
<p>
For under-IDE diagnostics, use the <diagnostics> task to run the same
tests as an ant task. This can be added to a diagnostics target in a build
file to see what tasks are available under the IDE, what the XML parser and
classpath is, etc.
</p>
<h3><a name="ant-user">user mailing list</a></h3>
<p> If you cannot get Ant installed or working, the Ant user mailing list is the
best place to start with any problem. Please do your homework first, make sure
that it is not a <a href="#classpath"><code>CLASSPATH</code></a> problem, and run a <a
href="#diagnostics">diagnostics check</a> to see what Ant thinks of its own
state. Why the user list, and not the developer list?
Because there are more users than developers, so more people who can help you. </p>
<p>
Please only file a bug report against Ant for a configuration/startup problem if
there really is a fixable bug in Ant related to configuration, such as it not
working on a particular platform, with a certain JVM version, etc, or if you are
advised to do it by the user mailing list.
</p>
</body>
</html>
|
