This file is topics/java/deployment/ant/gettingStarted/antBasicConcepts.txt

P. Conrad, 01/06/06




Necessary background
=====================


Read "backgroundAboutAnt.txt" and "gettingStartedWithAnt.txt",
also in the topics/java/deployment/ant/gettingStarted/ directory
before reading this file.

XML concepts:

The Ant "build.xml" file is an XML file.  So you need to be familiar
with XML concepts such as "element", "attribute", "open tag", "close tag"
"self-closing tag", and "properly nested" before continuing.

Optional background:

Since many readers may be familiar with the Make utility under
Unix, but are just learning Ant, I will make reference to Make at various
times.    Readers not familiar with Make can just skip these references.


Conventions used
================

We'll say things like "An Ant file contains exactly one <project> element".

Strictly speaking, in XML terminology, this is wrong, because
<project> is actually an open tag, not an element.   The element
is the whole thing:

<project>
some content
</project>

By convention though, it is more convenient to refer to elements by
their open tag name, especially in plain text.  That way, the
<angle-brackets> signal the reader that we are talking about an XML
element.


The quick version
=================

You need to know, at a minimum, about three XML elements used
in the build.xml file:

 <project>, <target> and <task>.

A build.xml file contains a single <project> element.

A <project> element can contain several <target> elements.

Each <target> element can contain several <task> elements.

<task> elements actually "do stuff" like compiling, making a jar file,
running a Junit test, or echoing some text to the screen.  In all,
there are over 70 task elements built into Ant for doing all sorts of
useful things related to Java development.  You'll only need to learn
a handful of these to get started, and can learn the others as/when you
need them.



The two most basic tasks are:

  <javac srcdir="." />

     Compile the java code in the source directory (in this case "." 
     signifying the current directory).


  <echo>
     Write some text out to the screen.  Hi Mom! I'm compiling my app!!!
  </echo>


A helpfile of tasks is here:
    http://ant.apache.org/manual/tasksoverview.html

Important required attributes:
 
 <project default="all">  Typing "ant" alone on command line fires off "foo"

                         [Note: older documentation says that the 
                           default attribute is required.  Apparently, 
                           in recent versions it is not required.]

 <target name="all">      Every target has to have a name.

Important optional attributes

 <target name="all" depends="compile, test, makeJar">

 <target name="makeJar" depends="compile, test">

     This says that the targets compile, test and makeJar should all
     be done first before the target "all", and that "compile and test"
     should be done before "makeJar".


Quick version: one more important element: <property>
====================================================

One more thing that can be in the build.xml file is
<property> elements.  These are usually inside
the <project> element, in a list before the list
of <target> elements, at the same level,and are typically
specified with self-closing tags.


<project default="all">
  <property name="greeting" value="Hi Mom!" />
  <property name="jarFileName" location="./jarFiles/myJarFile.jar" />

  <target name="all">
  ...
  </target>
  
  [... more targets here... ]

</project>

There are lots of uses of properties, but for the quick
version, I'll explain just two:

  <property name="greeting" value="Hi Mom!" />

Now "greeting" is a symbol for the string "Hi Mom!".
You can dereference the symbol with ${greeting}, e.g.

 <echo>
   ${greeting}
 </echo>

instead of
  <echo>
   Hi Mom!
  </echo>

The line   
  <property name="jarFileName" location="./myJarFile.jar" />

works the same, except that the "location" refers to a filename.  By
using "location" instead of "value", Ant does some extra stuff, like
converting / to \ on Windows, and converting relative pathnames
like the one above (note the . symbol) into absolute pathnames.

You could use jarFileName in a jar task such as:

 <jar destfile="${jarFileName}" basedir="." includes="*.class" />


There are many other uses of properties, which we'll save for 
later.   It is probably best to discover these as and when you
need them.

Details: the bulld.xml file, projects and targets
=================================================

Every build.xml file contains exactly one "project", which should
be the top level single element in the XML file:


<?xml version="1.0" ?>
<project default="foo">
        .
        .
        .
</project>

The <?xml version="1.0" ?> declaration is "supposed to be there" since
it tells the XML processor that this is an XML file.     But Ant seems to be
perfectly happy whether it is there or not.

The "default" attribute is required on the <project> element.  

The default element says which of several "targets" should be "built"
if you just type

> ant

at the Unix (or Windows or Mac) command line without specifying a particular
target.  

(For those familiar with the Unix Make utiltity: the value of the
default attribute is analogous to the "first" target that appears in a
Makefile, which is the one that is fired by default if you just type
"make")

Targets are specified inside the project element.  Each target
has a required attribute called "name".  You can fire up a specific 
target by typing the name of the target on the ant command line:

> ant foo

or 

> and bar

<project default="foo">

  <target name="foo">
  ...
  </target>

  <target name="bar">
  ...
  </target>

  ... etc...

</project>


More typical target names would be things like:


<project default="compile">

  <target name="compile">
  ...
  </target>

  <target name="runTests">
  ...
  </target>


  <target name="makeJarFiles">
  ...
  </target>

  <target name="deployMyApp">
  ...
  </target>


  ... etc...

</project>




Details: Targets contain tasks
==============================

@@@ continue here...



Details: Other uses of properties
=================================

@@@ continue here...

You can define your own properties (see the "quick version" description
of properties above.

There are also at least two kinds of built-in properties.


 (1) You can access all the properties of the Java System.getProperties()
     method.  For example:

    <echo>
      Hello {$user.name}.   I am compiling on a ${os.name} system.
    </echo> 

The URL belows are two places that list these properties

 http://java.sun.com/docs/books/tutorial/essential/system/properties.html
 http://java.sun.com/j2se/1.5.0/docs/api/java/lang/System.html#getProperties()

A few other useful ones (meaning is self-explanatory)

    java.class.path
    java.home
    java.version.number

 (2) There are properties specific to ANT:

  For example:
     ant.project.name     the name attribute of the <project> element.

    <echo>
      The name of this project is ${ant.project.name}
    </echo>

  There is a complete list at:
 
     http://ant.apache.org/manual/using.html#built-in-props