Ant build

From Tom

Jump to: navigation, search

During time, we have added a number of ant targets to the main buildfile of Tom, using inconsistent naming scheme. This makes the buildfile bloated, and makes it difficult to maintain.

In this section, we try to summarize the principal targets of the main buildfile, provide a description, and name them, using a consistent naming scheme.

Contents

Current state

all                            cleans, build, test all
bootinstall                    Install src tree into stable tree
bootstrap                      Bootstrap source
build.stable                   compile the TOM stable sources
bundle.src                     Prepare bundle (src) for eclipse
bundle.stable                  Prepare bundle (stable) for eclipse
clean                          Cleans everything in the project
clean.all                      Cleans everything (stable, src, test, doc, dist)
clean.dist                     Mr proper
clean.examples                 Clean the examples
clean.src                      Purges the generated devel files
clean.src.dist                 Remove the src distribution
clean.stable                   Purges the generated stable files
clean.stable.dist              Remove the stable distribution
clean.test                     Cleans acceptance tests directory
cruisecontrol-examples-src     Build and test examples with tom-src
cruisecontrol-examples-stable  Build and test examples with tom-stable
cruisecontrol-src              Compile and run acceptance tests
cruisecontrol-stable           Compile and run acceptance tests
dist.all                       Prepare stable and devel distributions
examples                       Build and test examples with jtom-source
examples.stable                Build and test examples with jtom-stable
junit                          Runs junit acceptance tests
junit.opt                      Runs junit acceptance tests with optimization
manual.bootinstall             Install src tree into stable tree
prepare.plugin.src             prepare the workspace to build tom eclipse plugin
source.distribution            Creates a  ready to distribute tom-sources.tgz 
src                            compile the TOM development sources
src.all                        cleans, build, test junit
src.dist                       Prepare a distribution ready source package
src.doc                        Build javadoc for src
src.www                        Upload javadoc for src
stable                         build and install the boot
stable.all                     cleans, build, test all
stable.dist                    Prepare a distribution ready stable package
stable.doc                     Build javadoc for stable
stable.junit                   Runs junit acceptance tests compiled with stable
test                           Compile acceptance tests
test.opt                       Compile acceptance tests with optimizer
test.stable                    Compile and run acceptance tests with stable

Default target: stable

Build of examples

In order to simplify and automatize the build of Tom examples, we provide a common build framework intended to make the integration of a new example as easy as possible. Examples are placed in directories under trunk/examples. Each of these directories corresponds to a Java package, in which the example is implemented. For an example to be seen by the build framework, it has to provide a build.xml file, defining four mandatory targets: clean, build, junit and dist.

Targets to define
clean 
remove all build artifacts for the example
build 
build the example
junit 
run tests for the example
dist  
distribute the example, putting the examples file in the archive file those name is in the distrib.zip property

It is mandatory for those build.xml buildfiles to rely on the TOM_HOME environment variable to select the Tom compiler and libraries to use. In order to ease the definition of those tasks, the common.xml file is provided, defining default tasks. For an example using Tom and Gom with Java, with the common options, and where the example directory and package do match -- here, addressbook -- the build.xml can be as simple as:

<?xml version="1.0" encoding="UTF-8"?>
<project name="Build the addressbook example" default="build" basedir="..">
  <import file="../common.xml"/>
  <property name="example" value="addressbook"/>
  <property name="distribute" value="yes"/>
</project>

basedir is set to .. as the root of the package hierarchy is the examples directory, and this file is placed in the examples/addressbook directory. We import the common.xml file, and then define the example property, which is used by the default targets. We also set the distribute property to yes in order to enable the distribution of the example. Setting it to no or letting it undefined results in the example not being packaged in the distribution.

When using the common.xml, it is still possible to overwrite the default definitions of the targets, for customizing the build. However, the clean target should not be customized, as an example's build should never write file in other places than the gen/${example} and build/${example} destinations, neither the junit target, since tests' classnames (and only tests') should be prefixed by Test.

Predefined targets

The common.xml also defines a few useful targets, that aim at making the definition of a custom build easier. Those targets all assumes the example property to be set.

Targets
tomcompile 
Compiles all "normal" Tom sources in the example (ignores parsers .g.t).
gomcompile 
Compiles all Gom sources in the example, passing the value of example property as package.
gompointercompile 
Same as gomcompile, with --termpointer option.
gomtermgraphcompile 
Same as gomcompile, with --termgraph option.
gomfreshcompile 
Same as gomcompile, with --fresh option.
gombuild 
Same as gomcompile, but do not pass any package argument (thus require the use of "dotted" module name).
gomantlradapterbuild 
Compiles Gom source files with gomantlradapter. Expects grammar as argument.
javacompile 
Compiles all Java source and generated files.


Cleansing of the ant targets

I would like to introduce a bit of order into the ant targets that are available for the different buildfiles, in order to avoid the usual confusions between clean.src and src.clean.

Propositions
use src, stable and all systematically as prefix for an action command, thus clean.src should become src.clean.
whenever an action command is available as prefixed command, the version without prefix is a shortcut to the src version. Limit their number.
use buildtests and runtests as action commands to manage the test suite, instead of test and junit
Personal tools
Create a book