How I install my development environment for iText (ANT)
In the previous pages, you learned how to get the most recent iText source code
(see SVN) and how to set up your development environment
(see Eclipse). Now we are going to use ANT to compile
and jar the library. We'll also use ANT to create the HTML pages for lowagie.com
and the tutorial pages. In other words: we'll create all the files necessary to
make a new iText release using ANT.For more info about ANT (A Neat Tool), go to ANT site @ Apache.org.
The iText ANT files
Every self-respecting JAVA project has its build.xml file.
Sure, we have heard about Maven, but all sites built with Maven look exactly the same.
Moreover Maven is overkill for a project such as iText; why learn an obscure language
such as APT or mess with POMs, if ANT provides the same functionality in a much
easier way?Let's open our main build.xml in Eclipse (you'll find it under the
src
directory in the main
project):

In the outline panel, you'll see all the available targets; the
help
target being the default target.
Execute the help target, and you'll find the output in the
Console
panel:
Buildfile: C:\itext-core\main\src\build.xml help: [echo] Using ANT for iText help: [echo] COMPILING AND JARRING THE CODE (compile.xml) [echo] ant compile: compiles iText [echo] ant compile.debug: compiles iText and allows you to debug the code [echo] ant jar: compiles and jars iText [echo] ant jar.debug: compiles for debugging and jars iText help: [echo] BUILDING THE iText SITE (site.xml) [echo] ant lowagie.com: Building the lowagie.com pages [echo] ant javadoc: Building the API documentation [echo] ant docs.tar.gz: Building and jarring the API documentation [echo] ant tutorial: creates the tutorial pages (without the examples) [echo] ant tutorial.tar.gz: creates the tutorial and makes tar.gz files help: [echo] MAKING A NEW RELEASE (release.xml) [echo] archive.src: archiving the source (zip and tar.gz) [echo] asian.jar: creates a new version of iTextAsian.jar and iTextAsianCmaps.jar [echo] release: making the all the files needed for a release (except tutorial) BUILD SUCCESSFUL Total time: 375 millisecondsCompare this list with the outline presented by Eclipse, and you'll discover that the
help
target doesn't do anything but listing the available targets.These targets are organized in three groups, each referring to a subscript that can be found in the ant subdirectory:
c:/itext-core/main/src/ant/
These subscripts have more targets than the ones made available through the main ant file build.xml, but in general you won't need them. Please consider these targets to be 'private helper methods'.
In the ant subdirectory, you'll also find an .ant.properties file. I use this file every time I make a new release: it keeps the release number and date for the current or next release.
You will only have to change it if the directory structure you're using on your system is different from mine. No directory is used in a hardcoded way in the ANT scripts. All directories that are used, are defined in this .ant.properties file.
Let's have a closer look at an overview of the 'public' targets in the main ant file, build.xml.
Compiling and jarring
subscript: compile.xml
ant compile
Compiles the sourcecode (i.e. the code in the src directory).
ant jar
Calls compile, then jars the compiled code into iText.jar (in the directory lib
)
You can also use ant compile.debug and ant jar.debug if you need extended debugging capabilities. Don't forget to remove your class files before you execute this target.
Creating the iText site
subscript: site.xmlant lowagie.com
Every page on the site and every tutorial chapter was written in XML
and is converted to HTML using XSLT. The target is self explanatory.
ant javadoc
Creates the API documentation using JAVADOC. You can also immediately make
the docs.tar.gz with ant docs.tar.gz.
ant tutorial
Creates the tutorial pages (HTML only!)If you also want to compile and execute the example code, you need ant tutorial.tar.gz. This will also create two tar.gz.files: one with the HTML, another one with the source code and resulting documents (PDF, RTF,...).
Preparing a release
subscript: release.xmlant archive.src
Makes the src.zip and src.tar.gz file.
ant asian.jar
This creates a zip (a jar is nothing more than a zipped archive)
with the files you need for CJK support (iTextAsian.jar) or advanced
Asian font support (iTextAsianCmaps.jar). Generally, you won't ever
need this target, because the files in these jars never change, and
the jars are stored in the SVN repository.
ant release
This target calls many of the targets listed above:
archive.src, docs.tar.gz, jar, lowagie.com, and release.sf.
This last target is one of the 'private methods' mentioned before.
For every new release, I change the release number and date
in the ant.properties file.
The target release.sf will create files in the directory
build/bin/release/dist
for my own private use;
and it will copy these files to build/bin/release/sf
that can be posted on SourceForge. All these files have the
release number found in the properties file in the filename.
Summary
Usually, when I make a new release, I throw away my build
directory.
Then I execute:
ant release
This creates all the jar, zip and tar.gz files I need to upload
to my site and to SourceForge. But before I do this, I also run:
ant tutorial.tar.gz
This creates the tutorial pages, and compiles and executes all the examples.
Usually I have a look at the sample documents generated by the tutorial
examples to see if no functionality was broken in the new release.