Virtual Team Tools Build Instructions

      Copyright (c) 2008, Iparelan Solutions, LLC. All rights reserved.

For convenience, these instructions assume that the virtual team tools "root
directory" is stored in the environment VTT_HOME. The build proper has no
dependency on the setting of this environment variable. Bash syntax is used.


                                Prerequisites

* bash
* JDK 1.6
* Ant 1.7.1
* patch (see ${VTT_HOME}/External/HardcoreJava/build.xml)
* Cygwin for systems without bash and patch
* PMD 4.2.2 (testing)
* FindBugs 1.3.4 (testing)
* TestNG 5.8 (testing)


                                  Execution

Execute the build entry point script to invoke the build:

                              cd ${VTT_HOME}/scm
                              ./build

The build entry point script may be invoked with one or more "targets" that
specify components and operations. A target looks like this:

                           <component>-<operations>

Omitting the "operations" portion of the target simply builds the jar package
for "component." Here is a table of targets and what they do:

 <component>           jar
 <component>-clean     delete build artifacts
 <component>-doc       generate javadoc documentation
 <component>-test      invoke static analyzers and unit tests
 <component>-doc-test  composite target, faster than "doc" + "test" separately

See the "Dependencies" section below for the component names.

The special component meta-symbol "all" may be used to apply operations over
all components, e.g. all-doc-test.


                                Configuration

The file ${VTT_HOME}/scm/build.properties contains several property settings
that control various aspects of the build. Consult the documentation embedded
in this file for more information on build configuration.


                                 Dependencies

The file ${VTT_HOME}/scm/components.xml is the component dependencies
script. It specifies all of the components in the system, the locations of the
component source directories, and the build-time dependencies among
components.


                                   Cleaning

Cleaning is somewhat "smart" because it is a conditional operation. It is
designed this way to promote faster builds by using previously built artifacts
when it is reasonable to do so.

Simple invoking <component>-clean does not necessarily cause build artifacts
to be deleted for "component."  Ordinarily, a clean operation for a particular
component will actually delete build artifacts only if at least one of the
following two conditions are true:

  1. Some component on which the component depends has been changed.

  2. A build script for the component has been changed.

Add the following argument to the build entry point script invocation to force
a clean operation on a component:

                      -D<component>.clean.required=true

For example, to force a clean of the "foo" component:

                 cd ${VTT_HOME}/scm
                 ./build foo-clean -Dfoo.clean.required=true

The target "all-clean" is special because it performs an unconditional clean
of all components. It behaves as if -D<component>.clean.required=true is set
for all components.

There is one exception to the "unconditional" behavior of the "all-clean"
target: it does not necessarily delete all Javadoc documentation artifacts. It
is desirable to avoid generating Javadoc documentation too frequently because
the process of building Javadoc can be relatively time consuming compared to
other build operations. Add the following argument to the build entry point
script invocation to delete javadoc when performing a clean operation:

                               -Dclean.doc=true

For example, to clean absolutely everything that is cleanable:

                      cd ${VTT_HOME}/scm
                      ./build all-clean -Dclean.doc=true

Finally, the ${VTT_HOME}/External/package-cache is outside the scope of all
clean operations. It contains packages downloaded from various locations that
contain external build dependencies. The presence of these packages allows
development to continue in the absence of network connectivity. Only an
explicit manual deletion of the contents of this directory will cause external
packages to be deleted.


                   Development Environment Projects/Plugins

Currently, the only virtual team tools development environment "plugin" is for
Emacs. This plugin is implemented in the file
${VTT_HOME}/scm/iparelan-build.el.

Development of build projects/plugins for other development environments is
welcome.