5.4. Building Sequence Generator: Using Apache Ant
The Sequence Generator project (downloaded from the
CS390X repo) provides an opportunity to see
Apache Ant at work.
You are now going to walk through the building of Sequence Generator. You checked out a local working repository of seqgen
in Exercise 4.4.1, right? Now it's time to build the project and evaluate the quality of that code.
Follow along with the sample build process, below.
As you proceed through the build process, you may see errors.
No matter what happens, keep calm and carry on.
Read the instructions.
Don't expect to understand every word of the build file or output messages.
Read logs carefully and thoughtfully.
Remember: (1) Search engines are your friends. (2) Ask for help.
5.4.1. Finding the Build Instructions
Look for a README
file in the top-level directory of the local repository.
If you don't find a README
file, look for an INSTALL
file.
If you don't find an INSTALL
file,
look for a build script called build.xml
(indicative of Ant), build.gradle
(indicative of Gradle), pom.xml
(indicative of Maven), or makefile
(indicative of Make).
And if you don't find one of those, send a nice email to the maintainers of the project,
and ask them if they could use some help with their installation instructions.
Oh, look, there's a README.TXT
file right there in the top level directory of the trunk
directory.
The version of the README.TXT
file referred to here is Rev: 52
Here are some parts of the
README
file
relevant to the build process:
$ more README.TXT
README Version $Rev: 52 $
Sequence Generation (and demonstration of automated build process)
This project is written in Java.[1]
The build process depends on the Java JDK[3][4] main tools[5] as well as
additional tools provided in the project's lib/ directory.
⋮
The project build automation tool is Apache Ant.[2]
- Command to view all Ant top-level targets: ant -p
- Command to build, document, analyze, and test: ant all
Java .class and .jar build products are placed into a build/ directory subdirectories.
Javadoc output is placed into a doc/ directory.
Tool reports are placed into a reports/ directory, directly or in labeled subdirectories.
Formatted source code is placed into a formattedsrc/ directory.
⋮
$
This indicates that you need to have
Apache Ant installed on your development system.
If
ant
isn't already installed, visit
ant.apache.org/manual for more information about
installing and using Ant.
It also indicates that there are tools supporting the process expected to be
located in the
lib/
directory.
Before we try a build, let's see what's there:
$ ls lib
ant-colorizor.jar j2h.jar java2html.properties junit5/
checkstyle.jar jacoco/ jp_checks.xml pmd/
checkstyle.xsl java2html.jar jp_suppressions.xml spotbugs/
There's definitely some interesting stuff!
Some tools you might want to look-up:
checkstyle,
jacoco,
junit,
pmd,
spotbugs
The README instructions suggest using the command ant -p
to see the available targets, so let's give that a try:
$ ant -p
Buildfile: seqgen/trunk/build.xml
Build file for Sequence Generator (student experimentation)
Main targets:
all clean, generate documentation, analyze source code, run unit tests, check test coverage
checkstyle generate checkstyle report
clean clean up dynamically-created files and directories
coverage Run unit tests with JaCoCo instrumentation and format results
cpd proccess source with CPD
doc generate usage documentation
doc-private generate maintenance documentation
format generate formatted versions of source code
jar Creates a jar file for the product
pmd process source with PMD
run Runs the development version of the program
spotbugs process source files with SpotBugs
test run unit tests and format results
Default target: all
$
Looks like you're ready to try out some of those build
targets. Try each of the following commands.
ant test
ant coverage
ant all
Remember to look in the
reports/
subdirectory
for some results. For example:
$ ls reports
checkstyle_report.html coco/ cpd_report.xml test/
checkstyle_report.xml cpd_report.html pmd_report.html
$ ls reports/coco
default/ index.html jacoco-resources/ jacoco-sessions.html
$
Note that most reports are formatted as HTML, so are best viewed in a web browser,
and that any
index.html
file, if present,
is likely to be the starting point for a directory (e.g.,
reports/coco/index.html
and
reports/test/index.html
).