iText ANT scripts
Another Neat Tool (What is ANT?)
iText comes with a handful of ANT scripts that makes it easy for the developers of iText to compile the code, make a new release, build their site(s). But those scripts are useful for iText users too.
Apache Ant is a Java-based build tool. In theory, it is kind of like Make, but without Make's wrinkles.
If you want to download or install ant, please go to the ANT site @ Apache.org. On this page, you will only find how to use ANT in the context of the iText project.
Using ANT for iText
Every self-respecting JAVA project has its build.xml file. If you want to use ANT for iText, you should start from a specific directory, say D:\iText or /home/blowagie/projects, with two subdirectories 'src' and 'www', one for each CVS module. Directory 'src' should have a build.xml file on the root and a subdirectory 'ant' with all the iText ANT subscripts in it, as well as a properties-file. You can download these scripts in one itext-ant-1.4.5.zip -file.
While running these scripts a third directory 'build' will be created with the results of compile-actions, jar-commands, downloads,... You can change the location of all these directories, by changing the .ant.properties-file.
If you look at the iText build.xml file, you will see that the master build.xml doesn't have a lot of actual code. It calls different subscripts. You can call most of the targets from this master build.xml, but for some of the specialized (hidden) targets, you will need to call the subscript directly with build -f. The default target of the build.xml is 'help' and this is what you get if you call this target:
Buildfile: build.xml

help:
     [echo] Using ANT for iText


help:
     [echo] DOWNLOADING iText (download.xml)
     [echo] ant download: downloads the source code needed to create iText.jar
     [echo] ant download.bin: downloads some precompiled jars and zips
     [echo] ant getFromCvs: downloads the complete CVS repository


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 javadoc: Building the API documentation
     [echo] ant docs.tar.gz: Building and jarring the API documentation
     [echo] ant lowagie.com: Building the lowagie.com part


help:
     [echo] MAKING A NEW RELEASE (release.xml)
     [echo] archive.src: archiving the source
     [echo] ant.zip: makes a zip file with the ANT scripts
     [echo] release.sf: making the release for SourceForge


BUILD SUCCESSFUL
Total time: 1 second
Downloading iText
subscript: download.xml
ant -f download.xml download
This action gets the src.tar.gz from SourceForge and unzips+untars it under the 'src' directory. The source code can now be compiled.
ant -f download.xml download.bin
Downloads some jars you needs for specific functionality, such as parsing XML, hyphenation, using Asian fonts,... Use this, just to make sure you have all the right jars in the CLASSPATH that is used in the other ANT scripts.
ant -f download.xml getFromCvs
Downloads the complete CVS repository. If this doesn't work, please check the SourceForge status information. Anonymous CVS could be down.
Compiling and jarring
subscript: compile.xml
ant -f compile.xml compile
Compiles the downloaded sourcecode (i.e. the code in the src directory).
ant -f compile.xml jar
Jars the compiled code into iText.jar
You can also use compile.debug and jar.debug if you need extended debugging capabilities.
Creating HTML
subscript: site.xml
ant -f site.xml javadoc
Creates the API documentation using JAVADOC. You can also immediately make the docs.tar.gz with ant -f site.xml docs.tar.gz.
ant -f site.xml 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.
Preparing a release
subscript: release.xml
ant -f release.xml archive.src
Makes the src.zip and src.tar.gz file.
ant -f release.xml release.sf
Once src.zip, src.tar.gz, iText.jar and docs.tar.gz are created with some of the other ANT instructions, this command will copy those files to files that have the release number in the filename. For every new release, you should change the 'official' release number and the 'early access' release number the release was based on in the ant.properties file.
Releasing all in once
If you want to make a complete new release, you have to export both CVS modules 'src' and 'www' and change directory to 'www/ant'. ant release will first download some jars that don't need to be compiled. Then src.tar.gz, src.zip, ant.zip and docs.tar.gz will be constructed. The code will be compiled and jarred into iText.jar. The pages for lowagie.com will be constructed and the files that will need to be uploaded to SourceForge will get a releasenumber in their filename. Later on, more functionality will be added to generate examples and tutorial chapters. Usually I (Bruno) will do this. You won't need this target, nor ant lowagie.com, nor some other hidden targets.
SourceForge.net Logo
Amazon books: amazon.co.uk-link