Ant In 30 Minutes Or Less

1
Ant In 30 Minutes Or Less
2
The Who, What, When and Where

• Part of the Jakarta project, a sub-project of
  Apache
• Jakarta is the sub-heading for all the Java
  oriented Apache projects
• Open source, BSD style license application
  providing build functions for Java programs
• Available since mid 2000
• http//jakarta.apache.org/ant/

3
The Basics

• Ant replaces the popular 'make' utility used by
  many C/C developers. 'Make' lacks a file format
  that is easily parsed, has variations in
  implementations, and lacks extensibility.
• Ant attempts to address all of these flaws.
• Ant files are simple XML files with nodes in the
  XML file representing a hierarchy of major tasks
  (called 'targets') that can be performed and a
  series of steps to perform each one. This makes
  them easy for both man and machine to create and
  understand.

4
The Basics (2)

• Since Ant is written in Java itself, it is
  available on any platform for which you will be
  developing programs.
• You can write new custom tasks for unique
  development needs and put the code into an Ant
  extension JAR. With the JAR in place your tasks
  are indistinguishable from any other task in Ant.

5
Targets

• Represent the fundamental tasks you want the
  build file to perform.
• For Java applications these are often things like
  creating the Javadocs for the application,
  compiling and creating a JAR file, running unit
  tests, running a compiled application, etc.
• Complex tasks can be broken up into multiple
  targets representing separate steps.
• Referred to by name.

6
Dependencies

• Allow you to structure a set of targets so that a
  given target won't execute until any necessary
  precursor targets have successfully run (and any
  dependencies they may have as well).

7
Tasks

• Ant has a large set of built-in tasks.
• There are over 50 different "core" tasks that Ant
  knows how to perform out of the box.
• Some of the most common tasks involve compiling
  source code, creating JAR files, copying
  files/directories, deleting files, and running
  Java programs.
• Once you've learned as little as eight of the
  built-in tasks you should be able to set up a
  build file for the most important jobs in most
  projects.

8
Tasks (2)

• You aren't limited to just the core set.
• There are over 30 more tasks that are enabled
  with a set of optional JAR files you put in an
  Ant subdirectory. Most of these tasks are either
  very seldom used or are of use only if you are
  using a specific tool in your development (e.g.
  Perforce, JProbe, Clearcase, etc.).
• More third party tasks are coming all the time.
• You can create your own tasks.

9
Property

• Creates a name-value pair that can be used
  throughout a build script. Useful for storing
  settings like directory names that can change in
  one place (even in a file outside the main
  buildfile if you desire).
• Sets the property "foo.dist" to be equal to the
  value "dist". This can then be used in any of the
  attributes of other Ant tasks using
  "foo.dist".
• ltproperty name"foo.dist" value"dist"/gt

10
Property (2)

• Pulls all the properties from a file. The format
  of the file is the traditional "namevalue" style
  that Java properties files have always used.
• ltproperty file"build.properties"/gt
• Demonstrates that properties can also be pulled
  from system environment variables on certain
  operating systems (not necessarily all though).
• ltproperty environment"env"/gtltecho
  message"ANT_HOME is set to env.ANT_HOME"/gt

11
Copy

• Copies a file or set of files to another
  location. Does not overwrite existing files if
  they are newer unless you specify that you want
  it to overwrite.
• Has the secondary ability to do simple
  replacements in text as it copies.
• Copy a single file.
• ltcopy file"myfile.txt" tofile"mycopy.txt"/gt

12
Copy (2)

• Copy all the files from one directory to another,
  skipping any java source files.
• ltcopy todir"../dest/dir" gt ltfileset
  dir"src_dir"gt ltexclude name"/.java"/gt
  lt/filesetgtlt/copygt
• Copy all the files from the directory
  ../backup/dir to src_dir. Replace occurrences
  of "_at_TITLE_at_" in the files with "Foo Bar".
• ltcopy todir"../backup/dir"gt ltfileset
  dir"src_dir"/gt ltfiltersetgt ltfilter
  token"TITLE" value"Foo Bar"/gt
  lt/filtersetgtlt/copygt

13
Delete

• Deletes files, directories, or sets of files.
• Delete a single file.
• ltdelete file"/lib/ant.jar"/gt
• Delete all the .bak files from this directory and
  sub-directories.
• ltdeletegt ltfileset dir"." includes"/.bak"/gt
  lt/deletegt
• Delete the build directory and everything (files
  and directories) inside it.
• ltdelete includeEmptyDirs"true"gt ltfileset
  dir"build"/gtlt/deletegt

14
Mkdir

• Creates a directory.
• Creates a directory with a name and location
  specified by the "DistributionDir" property.
• ltmkdir dir"DistributionDir"/gt
• Creates a subdirectory called "jars" in the
  location specified by the "Distribution"
  property.
• ltmkdir dir"Distribution/jars"/gt

15
Javac

• Compiles Java source code. Attempts to do so in
  an intelligent fashion so that files that already
  have an up to date .class file are not
  recompiled.
• Compiles all java source files under the src
  directory and puts the resulting .class files in
  the build directory. xyz.jar is included in
  the classpath during the compilation. Debugging
  information will be included in the .class files.
• ltjavac srcdir"src" destdir"build"
  classpath"xyz.jar" debug"on"/gt

16
Javac (2)

• Compiles the code in the directories src and
  src2 to the build directory. The xyz.jar is
  included in the classpath during compilation.
  Note that the include and exclude entries narrow
  the set of code that will be compiled out of the
  two source directories. As with the previous
  example, debugging information will be included
  in the .class files.
• ltjavac destdir"build" classpath"xyz.jar"
  debug"on"gt ltsrc path"src"/gt ltsrc
  path"src2"/gt ltinclude name"mypackage/p1/"
  /gt ltinclude name"mypackage/p2/"/gt ltexclude
  name"mypackage/p1/testpackage/"/gtlt/javacgt

17
Jar

• Creates a JAR file from a set of files or updates
  an already existing JAR.
• Will automatically supply a manifest file for the
  JAR or use one you specify.

18
Jar (2)

• Creates a JAR file called app.jar from all the
  files in the build/classes directory. The file
  is put in the dist/lib directory.
• ltjar jarfile"dist/lib/app.jar"
  basedir"build/classes"/gt
• Note the use of properties like dist and
  build. These are variables which can be set in
  the Ant file, via an external file, or even set
  on the command line as the Ant build file is
  invoked.

19
Jar (3)

• Creates a JAR file from all the files in
  build/classes and src/resources. Note that
  any files named Test.class in the first directory
  are not included in the JAR. Also note that we
  used two distinct filesets to specify the files
  neede for this JAR.
• ltjar jarfile"dist/lib/app.jar"gt ltfileset
  dir"build/classes" excludes"/Test.class"/gt
  ltfileset dir"src/resources"/gtlt/jargt

20
Javadoc

• Creates Javadocs from Java source code files.
• Builds Javadoc only for the packages beginning
  with "com.lumptylump..." in the "src" directory.
• ltjavadoc packagenames"com.lumptylump."
  sourcepath"src" destdir"apidoc"/gt

21
Java

• Can be used to invoke a Java program from within
  an Ant build file. Capable of forking off a
  separate process so that a System.exit() cannot
  kill the Ant build.
• Invokes a class named test.Main from within
  test.jar. Passes the argument -h to test.Main.
• ltjava classname"test.Main"gt ltarg value"-h"/gt
  ltclasspathgt ltpathelement location"\test.jar"
  /gt ltpathelement path"java.class.path"/gt
  lt/classpathgtlt/javagt

22
Java (2)

• Invokes a class named test.Main in a separate VM.
  Passes the argument -h to test.Main and
  "-Xrunhprofcpusamples,filelog.txt,depth3" to
  the forked VM to request profiling.
• ltjava classname"test.Main" fork"yes"gt
  ltsysproperty key"DEBUG" value"true"/gt ltarg
  value"-h"/gt ltjvmarg value"-Xrunhprofcpusampl
  es,filelog.txt,depth3"/gtlt/javagt

23
An Example
lt?xml version"1.0"?gt ltproject name"Sample"
basedir"." default"all"gt lttarget
name"init"gt ltproperty name"unit_name"
value"sample"/gt ltproperty
file"./build.properties"/gt
ltproperty name"BuildDir" value"./build"/gt
ltproperty name"LibDir" value"./lib"/gt
ltproperty name"ClassDir" value"./build/classes"/
gt ltproperty name"JavaDocDir"
value"./docs/apidoc"/gt ltproperty
name"JarDir" value"./build/dist"/gt
ltproperty name"SourceDir" value"./src"/gt
ltproperty name"TestDir" value"./test"/gt
lt!-- Bump the build number before each
build. --gt ltpropertyfile
file"./build.properties"gt ltentry
key"build.number" type"int" operation""
value"1" pattern"00"/gt
lt/propertyfilegt lt!-- Create the
directories where we put all the build products.
--gt ltmkdir dir"BuildDir"/gt
ltmkdir dir"ClassDir"/gt ltmkdir
dir"JarDir"/gt ltmkdir
dir"JavaDocDir"/gt ltecho
message"Build build.number"/gt lt/targetgt
24
An Example (2)
lttarget name"compile" depends"init"gt
ltjavac srcdir"SourceDir" destdir"ClassDir
" debug"true" deprecation"true"gt
ltclasspathgt ltfileset
dir"LibDir"/gt lt/classpathgt
lt/javacgt lt!-- Copy files needed to run
the software to destinations in the
build directory. I do this because I usually pull
all binary files like this from inside
the Jar files that make up my application rather
than having them loose. So they need to
be copied to the class dir so they get
included in the Jar file for the application.
--gt ltcopy todir"ClassDir" gt
ltfileset dir"SourceDir"gt
ltinclude name"/.gif"/gt
ltinclude name"/.jpg"/gt
ltinclude name"/.wav"/gt
ltinclude name"/.dtd"/gt
lt/filesetgt lt/copygt lt/targetgt
lttarget name"jar" depends"init,compile"gt
ltjar jarfile"JarDir/unit_name.jar"
compress"true" basedir"ClassDir"/gt
lt/targetgt lttarget name"all" depends"jar"
description"Build everything."gt ltecho
message"Application built."/gt lt/targetgt
25
An Example (3)
lttarget name"javadoc" depends"init"
description"Javadoc for the code."gt
ltjavadoc packagenames"" sourcepath"SourceDir
" destdir"JavaDocDir"/gt lt/targetgt
lttarget name"clean" depends"init"
description"Clean all build products."gt
ltdelete dir"BuildDir"/gt
lt/targetgt lt/projectgt
26
Output From The Example

• ant clean
• Buildfile build.xmlinitpropertyfile
  Updating property file /home/jmunsch/MyDocuments/
  MyDownloads/CoughUp/build.properties mkdir
  Created dir /home/jmunsch/MyDocuments/MyDownloads
  /CoughUp/build mkdir Created dir
  /home/jmunsch/MyDocuments/MyDownloads/CoughUp/buil
  d/classes mkdir Created dir
  /home/jmunsch/MyDocuments/MyDownloads/CoughUp/buil
  d/dist mkdir Created dir
  /home/jmunsch/MyDocuments/MyDownloads/CoughUp/docs
  /apidoc echo Build 0clean delete
  Deleting directory /home/jmunsch/MyDocuments/MyDow
  nloads/CoughUp/buildBUILD SUCCESSFULTotal
  time 2 seconds
• ant
• Note Just typing Ant invokes the default target.

27
Output From The Example (2)

• ant
• Note Just typing Ant invokes the default target.
• Buildfile build.xmlinitpropertyfile
  Updating property file /home/jmunsch/MyDocuments/
  MyDownloads/CoughUp/build.properties mkdir
  Created dir /home/jmunsch/MyDocuments/MyDownloads
  /CoughUp/build mkdir Created dir
  /home/jmunsch/MyDocuments/MyDownloads/CoughUp/buil
  d/classes mkdir Created dir
  /home/jmunsch/MyDocuments/MyDownloads/CoughUp/buil
  d/dist echo Build 01compile javac
  Compiling 1 source file to /home/jmunsch/MyDocumen
  ts/MyDownloads/CoughUp/build/classesjar
  jar Building jar /home/jmunsch/MyDocuments/MyDo
  wnloads/CoughUp/build/dist/sample.jarall
  echo Application built.BUILD SUCCESSFULTotal
  time 4 seconds

28
Output From The Example (3)

• ant -projecthelp
• Buildfile build.xmlMain targets all
  Build everything. clean Clean all build
  products. javadoc Javadoc for the
  code.Default target all

29
Tools

• Automated Build Tools
• Anthill
• http//www.urbancode.com/projects/anthill/
• Cruise Control
• http//cruisecontrol.sourceforge.net/
• Others
• See the "Related Projects" (http//jakarta.apache.
  org/ant/projects.html) page on the Ant site for
  more

30
Why Ant?

• Features
• More popular than 'make' for building Java
  projects
• It runs on any platform that the Java projects it
  builds are on
• Updated and improved regularly
• Straightforward XML syntax
• Plug-in oriented architecture encourages
  expansion
• Directly supported by some IDEs (with more
  coming)
• Free and open source
• Fast, fast, and oh, did I mention, fast?

31
Questions?