Product SiteDocumentation Site

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

5.4.2. Trying Out Ant

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).