Previous Top Next
Directory CVS BUILD.XML Scripts

4. SOURCE ORGANIZATION

4.1 Directory Structure

A key recommendation of this manual is to separate the directory hierarchy containing your source code (described in this section) from the directory hierarchy containing your deployable application (described in the preceding section). Maintaining this separation has the following advantages:

As we will see, the ant development tool makes the creation and processing of such directory hierarchies nearly painless.

The actual directory and file hierarchy used to contain the source code of an application can be pretty much anything you like. However, the following organization has proven to be quite generally applicable, and is expected by the example build.xml configuration file that is discussed below. All of these components exist under a top level project source directory for your application:

4.2 Source Code Control

As mentioned earlier, it is highly recommended that you place all of the source files that comprise your application under the management of a source code control system like the Concurrent Version System (CVS). If you elect to do this, every directory and file in the source hierarchy should be registered and saved -- but none of the generated files. If you register binary format files (such as images or JAR libraries), be sure to indicate this to your source code control system.

Detailed instructions for your source code control environment are beyond the scope of this manual. However, the following steps are followed when using a command-line CVS client:

CVS, like other source code control systems, has many additional features (such as the ability to tag the files that made up a particular release, and support for multiple development branches that can later be merged). See the links and references in the Introduction for more information.

4.3 BUILD.XML Configuration File

We will be using the ant tool to manage the compilation of our Java source code files, and creation of the deployment hierarchy. Ant operates under the control of a build file, normally called build.xml, that defines the processing steps required. Like a Makefile, the build.xml file provides several "targets" that support optional development activities (such as creating the associated Javadoc documentation, erasing the deployment home directory so you can build your project from scratch, or creating the web application archive file so you can distribute your application.

To give you a head start, a basic build.xml file is provided that you can customize and install in the project source directory for your application. This file includes comments that describe the various targets that can be executed. Briefly, the following targets are generally provided:

In the following section, scripts will be described that use Ant to compile your project, based on the contents of the build.xml file defined here.

4.4 Shell and Batch Scripts

The primary script we will utilize is generically called the build script. It executes Ant, which reads and processes the build.xml file discussed above. Each time you execute the build script, you will specify the build "target" that you wish to execute. Users of a command line MAKE tool (which processes a makefile) will recognize this approach.

On UNIX-based systems, the following script should be saved as file build.sh in the project source directory, with file permissions that make it executable, and customized as required:

#!/bin/sh
# build.sh -- Build Script for the "Hello, World" Application
# $Id: source.html,v 1.4 2004/02/29 22:42:51 billbarker Exp $

# Identify the custom class path components we need
CP=$TOMCAT_HOME/webapps/admin/WEB-INF/lib/ant.jar:$TOMCAT_HOME/lib/common/servlet.jar
CP=$CP:$TOMCAT_HOME/lib/container/crimson.jar
CP=$CP:$JAVA_HOME/lib/tools.jar

# Execute ANT to perform the requested build target
java -classpath $CP:$CLASSPATH org.apache.tools.ant.Main \
  -Dtomcat.home=$TOMCAT_HOME "$@"

On Windows-based systems, the following script should be saved as file build.bat in the project source directory, and customzed as required:

@echo off
rem build.bat -- Build Script for the "Hello, World" Application
rem $Id: source.html,v 1.4 2004/02/29 22:42:51 billbarker Exp $

set _CP=%CP%

rem Identify the custom class path components we need
set CP=%TOMCAT_HOME%\webapps\admin\WEB-INF\lib\ant.jar;%TOMCAT_HOME%\lib\common\servlet.jar
set CP=%CP%;%TOMCAT_HOME%\lib\container\crimson.jar
set CP=%CP%;%JAVA_HOME%\lib\tools.jar

rem Execute ANT to perform the required build target
java -classpath %CP%;%CLASSPATH% org.apache.tools.ant.Main -Dtomcat.home=%TOMCAT_HOME% %1 %2 %3 %4 %5 %6 %7 %8 %9

set CP=%_CP%
set _CP=

Build script customizations you might consider include: