You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@ant.apache.org by gi...@apache.org on 2018/02/28 07:01:21 UTC
[06/47] ant git commit: Use HTML 5(-ish), fix links
http://git-wip-us.apache.org/repos/asf/ant/blob/66b52f99/manual/tutorial-HelloWorldWithAnt.html
----------------------------------------------------------------------
diff --git a/manual/tutorial-HelloWorldWithAnt.html b/manual/tutorial-HelloWorldWithAnt.html
index 916ca7a..12edc2b 100644
--- a/manual/tutorial-HelloWorldWithAnt.html
+++ b/manual/tutorial-HelloWorldWithAnt.html
@@ -22,9 +22,9 @@
<body>
<h1>Tutorial: Hello World with Apache Ant</h1>
-<p>This document provides a step by step tutorial for starting Java programming with Apache Ant.
-It does <b>not</b> contain deeper knowledge about Java or Ant. This tutorial has the goal
-to let you see, how to do the easiest steps in Ant.</p>
+<p>This document provides a step by step tutorial for starting Java programming with Apache Ant. It
+does <strong>not</strong> contain deeper knowledge about Java or Ant. This tutorial has the goal to let you see, how to
+do the easiest steps in Ant.</p>
<h2>Content</h2>
<ul>
@@ -36,19 +36,17 @@ to let you see, how to do the easiest steps in Ant.</p>
</ul>
<h2 id="prepare">Preparing the project</h2>
-<p>We want to separate the source from the generated files, so our java source files will
-be in <tt>src</tt> folder. All generated files should be under <tt>build</tt>, and there
-splitted into several subdirectories for the individual steps: <tt>classes</tt> for our compiled
-files and <tt>jar</tt> for our own JAR-file.</p>
-<p>We have to create only the <tt>src</tt> directory. (Because I am working on Windows, here is
-the win-syntax - translate to your shell):</p>
+<p>We want to separate the source from the generated files, so our Java source files will be in <samp>src</samp>
+folder. All generated files should be under <samp>build</samp>, and there split into several subdirectories for the
+individual steps: <samp>classes</samp> for our compiled files and <samp>jar</samp> for our own JAR-file.</p>
-<pre class="code">
-md src
-</pre>
+<p>We have to create only the <samp>src</samp> directory. (Because I am working on Windows, here is the Windows
+syntax—translate to your shell):</p>
-<p>The following simple Java class just prints a fixed message out to STDOUT,
-so just write this code into <tt>src\oata\HelloWorld.java</tt>.</p>
+<pre class="code">md src</pre>
+
+<p>The following simple Java class just prints a fixed message out to STDOUT, so just write this code
+into <samp>src\oata\HelloWorld.java</samp>.</p>
<pre class="code">
package oata;
@@ -57,41 +55,36 @@ public class HelloWorld {
public static void main(String[] args) {
System.out.println("Hello World");
}
-}
-</pre>
+}</pre>
<p>Now just try to compile and run that:</p>
<pre class="code">
md build\classes
javac -sourcepath src -d build\classes src\oata\HelloWorld.java
-java -cp build\classes oata.HelloWorld
-</pre>
+java -cp build\classes oata.HelloWorld</pre>
which will result in
-<pre class="output">
-Hello World
-</pre>
+<pre class="output">Hello World</pre>
-<p>Creating a jar-file is not very difficult. But creating a <i>startable</i> jar-file needs more steps: create a
+<p>Creating a jar-file is not very difficult. But creating a <em>startable</em> jar-file needs more steps: create a
manifest-file containing the start class, creating the target directory and archiving the files.</p>
<pre class="code">
echo Main-Class: oata.HelloWorld>myManifest
md build\jar
jar cfm build\jar\HelloWorld.jar myManifest -C build\classes .
-java -jar build\jar\HelloWorld.jar
-</pre>
+java -jar build\jar\HelloWorld.jar</pre>
-<p><b>Note:</b> Do not have blanks around the >-sign in the <tt>echo Main-Class</tt> instruction because it would
-falsify it!</p>
+<p><strong>Note</strong>: Do not have blanks around the >-sign in the <code>echo
+Main-Class</code> instruction because it would falsify it!</p>
<h2 id="four-steps">Four steps to a running application</h2>
-<p>After finishing the java-only step we have to think about our build process. We <i>have</i> to compile our code, otherwise we couldn't
-start the program. Oh - "start" - yes, we could provide a target for that. We <i>should</i> package our application.
-Now it's only one class - but if you want to provide a download, no one would download several hundreds files ...
-(think about a complex Swing GUI - so let us create a jar file. A startable jar file would be nice ... And it's a
-good practise to have a "clean" target, which deletes all the generated stuff. Many failures could be solved just
-by a "clean build".</p>
-
-<p>By default Ant uses <tt>build.xml</tt> as the name for a buildfile, so our <tt>.\build.xml</tt> would be:</p>
+<p>After finishing the java-only step we have to think about our build process. We <em>have</em> to compile our code,
+otherwise we couldn't start the program. Oh—<q>start</q>—yes, we could provide a target for
+that. We <em>should</em> package our application. Now it's only one class—but if you want to provide a download,
+no one would download several hundreds files ... (think about a complex Swing GUI—so let us create a jar file. A
+startable jar file would be nice ... And it's a good practise to have a <q>clean</q> target, which deletes all the
+generated stuff. Many failures could be solved just by a "clean build".</p>
+
+<p>By default Ant uses <samp>build.xml</samp> as the name for a buildfile, so our <samp>.\build.xml</samp> would be:</p>
<pre class="code">
<project>
@@ -117,28 +110,24 @@ by a "clean build".</p>
<java jar="build/jar/HelloWorld.jar" fork="true"/>
</target>
-</project>
-</pre>
+</project></pre>
<p>Now you can compile, package and run the application via</p>
<pre class="code">
ant compile
ant jar
-ant run
-</pre>
+ant run</pre>
<p>Or shorter with</p>
-<pre class="code">
-ant compile jar run
-</pre>
+<pre class="code">ant compile jar run</pre>
<p>While having a look at the buildfile, we will see some similar steps between Ant and the Java-only commands:</p>
<table>
<tr>
- <th>java-only</th>
+ <th>Java-only</th>
<th>Ant</th>
</tr>
<tr>
- <td valign="top"><pre class="code">
+ <td><pre class="code">
md build\classes
javac
-sourcepath src
@@ -154,15 +143,14 @@ jar cfm
-java -jar build\jar\HelloWorld.jar
- </pre></td>
- <td valign="top"><pre class="code">
+java -jar build\jar\HelloWorld.jar</pre></td>
+ <td><pre class="code">
<mkdir dir="build/classes"/>
<javac
srcdir="src"
destdir="build/classes"/>
-<i><!-- automatically detected --></i>
-<i><!-- obsolete; done via manifest tag --></i>
+<em><!-- automatically detected --></em>
+<em><!-- obsolete; done via manifest tag --></em>
<mkdir dir="build/jar"/>
<jar
destfile="build/jar/HelloWorld.jar"
@@ -172,16 +160,16 @@ java -jar build\jar\HelloWorld.jar
<attribute name="Main-Class" value="oata.HelloWorld"/>
</manifest>
</jar>
-<java jar="build/jar/HelloWorld.jar" fork="true"/>
- </pre></td>
-</tr></table>
+<java jar="build/jar/HelloWorld.jar" fork="true"/></pre></td>
+</tr>
+</table>
<h2 id="enhance">Enhance the build file</h2>
-<p>Now we have a working buildfile we could do some enhancements: many time you are referencing the
-same directories, main-class and jar-name are hard coded, and while invocation you have to remember
-the right order of build steps.</p>
-<p>The first and second point would be addressed with <i>properties</i>, the third with a special property - an attribute
-of the <project>-tag and the fourth problem can be solved using dependencies.</p>
+<p>Now that we have a working buildfile, we could do some enhancements: many time you are referencing the same
+directories, main-class and jar-name are hard coded, and while invoking you have to remember the right order of build
+steps.</p>
+<p>The first and second point would be addressed with <em>properties</em>, the third with a special property—an
+attribute of the <code><project></code> tag and the fourth problem can be solved using dependencies.</p>
<pre class="code">
<project name="HelloWorld" basedir="." default="main">
@@ -222,10 +210,9 @@ of the <project>-tag and the fourth problem can be solved using dependenci
<target name="main" depends="clean,run"/>
-</project>
-</pre>
+</project></pre>
-<p>Now it's easier, just do a <tt class="code">ant</tt> and you will get</p>
+<p>Now it's easier, just do a <code>ant</code> and you will get</p>
<pre class="output">
Buildfile: build.xml
@@ -244,26 +231,26 @@ run:
main:
-BUILD SUCCESSFUL
-</pre>
+BUILD SUCCESSFUL</pre>
<h2 id="ext-libs">Using external libraries</h2>
-<p>Somehow told us not to use syso-statements. For log-Statements we should use a Logging-API - customizable on a high
-degree (including switching off during usual life (= not development) execution). We use Log4J for that, because</p>
+<p>Somehow told us not to use sys-statements. For log-statements we should use a Logging API—customizable to a
+high degree (including switching off during usual life (= not development) execution). We use Log4J for that,
+because</p>
<ul>
<li>it is not part of the JDK (1.4+) and we want to show how to use external libs</li>
<li>it can run under JDK 1.2 (as Ant)</li>
<li>it's highly configurable</li>
<li>it's from Apache ;-)</li>
</ul>
-<p>We store our external libraries in a new directory <tt>lib</tt>. Log4J can be
-<a href="http://www.apache.org/dist/logging/log4j/1.2.13/logging-log4j-1.2.13.zip">downloaded [1]</a> from Logging's Homepage.
-Create the <tt>lib</tt> directory and extract the log4j-1.2.9.jar into that lib-directory. After that we have to modify
-our java source to use that library and our buildfile so that this library could be accessed during compilation and run.
-</p>
-<p>Working with Log4J is documented inside its manual. Here we use the <i>MyApp</i>-example from the
-<a href="http://logging.apache.org/log4j/docs/manual.html">Short Manual [2]</a>. First we have to modify the java source to
-use the logging framework:</p>
+<p>We store our external libraries in a new directory <samp>lib</samp>. Log4J can
+be <a href="https://archive.apache.org/dist/logging/log4j/1.2.17/logging-log4j-1.2.17.zip">downloaded [1]</a> from
+Logging's Homepage. Create the <samp>lib</samp> directory and extract the <samp>log4j-1.2.17.jar</samp> into that
+directory. After that we have to modify our Java source file to use that library and our buildfile so that this library
+could be accessed during compilation and run.</p>
+<p>Working with Log4J is documented inside its manual. Here we use the <var>MyApp</var>-example from
+the <a href="https://logging.apache.org/log4j/1.2/manual.html">Short Manual [2]</a>. First we have to modify the java
+source to use the logging framework:</p>
<pre class="code">
package oata;
@@ -276,17 +263,17 @@ public class HelloWorld {
public static void main(String[] args) {
<b>BasicConfigurator.configure();</b>
- <font color="blue"><b>logger.info("Hello World");</b></font> // the old SysO-statement
+ <span style="color:blue"><b>logger.info("Hello World");</b></span> // the old SysO-statement
}
-}
-</pre>
+}</pre>
<p>Most of the modifications are "framework overhead" which has to be done once. The blue line is our "old System-out"
statement.</p>
-<p>Don't try to run <tt>ant</tt> - you will only get lot of compiler errors. Log4J is not inside the classpath so we have
-to do a little work here. But do not change the CLASSPATH environment variable! This is only for this project and maybe
-you would break other environments (this is one of the most famous mistakes when working with Ant). We introduce Log4J
-(or to be more precise: all libraries (jar-files) which are somewhere under <tt>.\lib</tt>) into our buildfile:</p>
+<p>Don't try to run <code>ant</code>—you will only get lot of compiler errors. Log4J is not on the classpath so we
+have to do a little work here. But do not change the <code>CLASSPATH</code> environment variable! This is only for this
+project and maybe you would break other environments (this is one of the most famous mistakes when working with Ant). We
+introduce Log4J (or to be more precise: all libraries (jar-files) which are somewhere under <samp>.\lib</samp>) into our
+buildfile:</p>
<pre class="code">
<project name="HelloWorld" basedir="." default="main">
@@ -308,43 +295,41 @@ you would break other environments (this is one of the most famous mistakes when
<java fork="true" <b>classname="${main-class}"</b>>
<b><classpath></b>
<b><path refid="classpath"/></b>
- <font color="red"><b><path location="${jar.dir}/${ant.project.name}.jar"/></b></font>
+ <span style="color:red"><b><path location="${jar.dir}/${ant.project.name}.jar"/></b></span>
<b></classpath></b>
</java>
</target>
...
-</project>
-</pre>
+</project></pre>
-<p>In this example we start our application not via its Main-Class manifest-attribute, because we could not provide
-a jarname <i>and</i> a classpath. So add our class in the red line to the already defined path and start as usual. Running
-<tt>ant</tt> would give (after the usual compile stuff):</p>
+<p>In this example we start our application not via its Main-Class manifest-attribute, because we could not provide a
+jarname <em>and</em> a classpath. So add our class in the red line to the already defined path and start as
+usual. Running <code>ant</code> would give (after the usual compile stuff):</p>
-<pre class="output">
-[java] 0 [main] INFO oata.HelloWorld - Hello World
-</pre>
+<pre class="output">[java] 0 [main] INFO oata.HelloWorld - Hello World</pre>
<p>What's that?</p>
<ul>
-<li><i>[java]</i> Ant task running at the moment</li>
-<li><i>0</i> <font size="-1">sorry don't know - some Log4J stuff</font></li>
-<li><i>[main]</i> the running thread from our application </li>
- <li><i>INFO</i> log level of that statement</li>
- <li><i>oata.HelloWorld</i> source of that statement</li>
-<li><i>-</i> separator</li>
-<li><i>Hello World</i> the message</li>
+<li><code>[java]</code> Ant task running at the moment</li>
+<li><code>0</code> <small>sorry, don't know—some Log4J stuff</small></li>
+<li><code>[main]</code> the running thread from our application</li>
+ <li><code>INFO</code> log level of that statement</li>
+ <li><code>oata.HelloWorld</code> source of that statement</li>
+<li><code>-</code> separator</li>
+<li><code>Hello World</code> the message</li>
</ul>
<p>For another layout ... have a look inside Log4J's documentation about using other PatternLayout's.</p>
<h2 id="config-files">Configuration files</h2>
-<p>Why we have used Log4J? "It's highly configurable"? No - all is hard coded! But that is not the debt of Log4J - it's
-ours. We had coded <tt>BasicConfigurator.configure();</tt> which implies a simple, but hard coded configuration. More
-comfortable would be using a property file. In the java source delete the BasicConfiguration-line from the main() method
-(and the related import-statement). Log4J will search then for a configuration as described in it's manual. Then create
-a new file <tt>src/log4j.properties</tt>. That's the default name for Log4J's configuration and using that name would make
-life easier - not only the framework knows what is inside, you too!</p>
+<p>Why we have used Log4J? "It's highly configurable"? No—all is hardcoded! But that is not the fault of
+Log4J—it's ours. We had coded <code>BasicConfigurator.configure();</code> which implies a simple, but hardcoded
+configuration. More comfortable would be using a property file. In the Java source file, delete
+the <code>BasicConfiguration</code> line from the <code>main()</code> method (and the
+related <code>import</code>-statement). Log4J will search then for a configuration as described in it's manual. Then
+create a new file <samp>src/log4j.properties</samp>. That's the default name for Log4J's configuration and using that
+name would make life easier—not only the framework knows what is inside, you too!</p>
<pre class="code">
log4j.rootLogger=DEBUG, <b>stdout</b>
@@ -352,12 +337,13 @@ log4j.rootLogger=DEBUG, <b>stdout</b>
log4j.appender.<b>stdout</b>=org.apache.log4j.ConsoleAppender
log4j.appender.<b>stdout</b>.layout=org.apache.log4j.PatternLayout
-log4j.appender.<b>stdout</b>.layout.ConversionPattern=<font color="blue"><b>%m%n</b></font>
+log4j.appender.<b>stdout</b>.layout.ConversionPattern=<span style="color:blue"><b>%m%n</b></span>
</pre>
-<p>This configuration creates an output channel ("Appender") to console named as <tt>stdout</tt> which prints the
-message (%m) followed by a line feed (%n) - same as the earlier System.out.println() :-) Oooh kay - but we haven't
-finished yet. We should deliver the configuration file, too. So we change the buildfile:</p>
+<p>This configuration creates an output channel (<q>Appender</q>) to console named as <code>stdout</code> which prints
+the message (<q>%m</q>) followed by a line feed (<q>%n</q>)—same as the earlier <code>System.out.println()</code>
+:-) Oooh kay—but we haven't finished yet. We should deliver the configuration file, too. So we change the
+buildfile:</p>
<pre class="code">
...
@@ -368,31 +354,34 @@ finished yet. We should deliver the configuration file, too. So we change the bu
<b><fileset dir="${src.dir}" excludes="**/*.java"/></b>
<b></copy></b>
</target>
- ...
-</pre>
+ ...</pre>
-<p>This copies all resources (as long as they haven't the suffix ".java") to the build directory, so we could
+<p>This copies all resources (as long as they haven't the suffix <samp>.java</samp>) to the build directory, so we could
start the application from that directory and these files will included into the jar.</p>
<h2 id="junit">Testing the class</h2>
-<p>In this step we will introduce the usage of the JUnit [3] testframework in combination with Ant. Because Ant
-has a built-in JUnit 3.8.2 you could start directly using it. Write a test class in <tt>src\HelloWorldTest.java</tt>: </p>
+<p>In this step we will introduce the usage of the JUnit [3] test framework in combination with Ant. Because Ant has a
+built-in JUnit 4.12 you could start directly using it. Write a test class in <samp>src\HelloWorldTest.java</samp>:</p>
<pre class="code">
-public class HelloWorldTest extends junit.framework.TestCase {
+import org.junit.Test;
+public class HelloWorldTest {
+
+ @Test
public void testNothing() {
}
+ @Test
public void testWillAlwaysFail() {
fail("An error message");
}
}</pre>
-<p>Because we dont have real business logic to test, this test class is very small: just show how to start. For
-further information see the JUnit documentation [3] and the manual of <a href="Tasks/junit.html">junit</a> task.
-Now we add a junit instruction to our buildfile:</p>
+<p>Because we don't have real business logic to test, this test class is very small: just show how to start. For further
+information see the JUnit documentation [3] and the manual of <a href="Tasks/junit.html">junit</a> task. Now we add a
+junit instruction to our buildfile:</p>
<pre class="code">
...
@@ -421,18 +410,15 @@ Now we add a junit instruction to our buildfile:</p>
</junit>
</target></b>
- ...
-
-</pre>
+ ...</pre>
-<p>We reuse the path to our own jar file as defined in run-target by
- giving it an ID and making it globally available.
-The <tt>printsummary=yes</tt> lets us see more detailed information than just a "FAILED" or "PASSED" message.
-How much tests failed? Some errors? Printsummary lets us know. The classpath is set up to find our classes.
-To run tests the <tt>batchtest</tt> here is used, so you could easily add more test classes in the future just
-by naming them <tt>*Test.java</tt>. This is a common naming scheme.</p>
+<p>We reuse the path to our own jar file as defined in run-target by giving it an ID and making it globally available.
+The <code>printsummary=yes</code> lets us see more detailed information than just a "FAILED" or "PASSED" message. How
+much tests failed? Some errors? <var>printsummary</var> lets us know. The classpath is set up to find our classes. To
+run tests the <code>batchtest</code> here is used, so you could easily add more test classes in the future just by
+naming them <code>*Test.java</code>. This is a common naming scheme.</p>
-<p>After a <tt class="code">ant junit</tt> you'll get:</p>
+<p>After a <code>ant junit</code> you'll get:</p>
<pre class="output">
...
@@ -442,11 +428,10 @@ junit:
[junit] Test HelloWorldTest FAILED
BUILD SUCCESSFUL
-...
-</pre>
+...</pre>
-<p>We can also produce a report. Something that you (and other) could read after closing the shell ....
-There are two steps: 1. let <junit> log the information and 2. convert these to something readable (browsable).<p>
+<p>We can also produce a report. Something that you (and other) could read after closing the shell .... There are two
+steps: 1. let <code><junit></code> log the information and 2. convert these to something readable (browsable).<p>
<pre class="code">
...
@@ -473,23 +458,21 @@ There are two steps: 1. let <junit> log the information and 2. convert the
<fileset dir="${report.dir}" includes="TEST-*.xml"/>
<report todir="${report.dir}"/>
</junitreport>
- </target></b>
-</pre>
+ </target></b></pre>
-<p>Because we would produce a lot of files and these files would be written to the current directory by default,
-we define a report directory, create it before running the <tt>junit</tt> and redirect the logging to it. The log format
-is XML so <tt>junitreport</tt> could parse it. In a second target <tt>junitreport</tt> should create a browsable
-HTML-report for all generated xml-log files in the report directory. Now you can open the ${report.dir}\index.html and
-see the result (looks something like JavaDoc).<br>
-Personally I use two different targets for junit and junitreport. Generating the HTML report needs some time and you dont
-need the HTML report just for testing, e.g. if you are fixing an error or a integration server is doing a job.
-</p>
+<p>Because we would produce a lot of files and these files would be written to the current directory by default, we
+define a report directory, create it before running the <q>junit</q> and redirect the logging to it. The log format is
+XML so <q>junitreport</q> could parse it. In a second target <q>junitreport</q> should create a browsable HTML report
+for all generated XML log files in the report directory. Now you can open the <samp>${report.dir}\index.html</samp> and
+see the result (looks something like JavaDoc).<br> Personally I use two different targets
+for <code><junit></code> and <code><junitreport></code>. Generating the HTML report needs some time and you
+don't need the HTML report just for testing, e.g. if you are fixing an error or a integration server is doing a job.</p>
<h2 id="resources">Resources</h2>
<ol class="refs">
- <li><a href="http://www.apache.org/dist/logging/log4j/1.2.13/logging-log4j-1.2.13.zip">http://www.apache.org/dist/logging/log4j/1.2.13/logging-log4j-1.2.13.zip</a></li>
- <li><a href="http://logging.apache.org/log4j/docs/manual.html">http://logging.apache.org/log4j/docs/manual.html</a></li>
- <li><a href="http://www.junit.org/index.htm">http://www.junit.org/index.htm</a></li>
+ <li><a href="https://archive.apache.org/dist/logging/log4j/1.2.17/logging-log4j-1.2.17.zip">https://archive.apache.org/dist/logging/log4j/1.2.17/logging-log4j-1.2.17.zip</a></li>
+ <li><a href="https://logging.apache.org/log4j/1.2/manual.html">https://logging.apache.org/log4j/1.2/manual.html</a></li>
+ <li><a href="https://junit.org/junit4">https://junit.org/junit4</a></li>
</ol>
</body>