lib module.
We use Ant to drive the build, but the logic for building and
assembling modules resides in the BuildModule taskdef,
which reads module dependencies from the Eclipse .classpath files
and assembles the product according to the templates in the
product directory.
This makes it easy to change dependencies and add modules,
but could make it difficult to debug if something were to go wrong.
.classpath file, there is no need to update build scripts when
adding or removing modules or changing their dependencies, so long
as they are all in the base modules directory (usually the base of
the eclipse workspace).
Likewise, updating a product assembly should be easy,
since they are based on introspection of the product directories.
Still, the taskdef workings are not obvious in the build script, so
this section makes clear some of the implicit logic
in case it's required when debugging build failures or
to make changes.
lib/build/build.jar.
That means code updates in the build module are not reflected in
the build process until the build.jar produced by
building this build module replaces that found in
lib/build/build.jar. Once the module update is
confirmed, the new lib/build/build.jar must be checked in
to propogate the changes to other users.
The scripts support an Ant variable check.build.jar
by warning when lib/build/build.jar is out of date.
BuildModule task
The
BuildModule
taskdef implements an integrated module or product build.
Module builds are based on the Eclipse .classpath
file, and can produce
a jar with the module classes, with two variations:
- include only the module classes,
or assemble the jar complete with all antecedent modules and
libraries;
- compile the module(s) with or without any
testing source or libraries
If there is a file {moduleName}.mf.txt
in the module directory, it will be used as the manifest for the
module jar file.
Product builds are defined by introspection of a
products subdirectory like
products/tools for the AspectJ installer.
These have an install directory for installer resources
and a dist directory containing all files belonging in
the distribution, including 0-length placeholders for the module build
results. These placeholder file names are mapped to the originating
module by the task itself (yes, an awful hack).
Version synchronization
The version is expressed in the jar manifests, in the Version class,
and in some documentation files. The build script
ensures all version expressions
are aligned. When not doing or testing release builds,
developers use the default "DEVELOPMENT" version.
The build version is set in
build-properties.xml and propogated
using Ant copy filters out to
the aspectjrt.jar manifest,
the aspectjtools.jar manifest
and to
../bridge/src/org/aspectj/bridge/Version.java
which the build.xml init-version task
generates from a template
lib/BridgeVersion.java.txt.
To avoid updating Version.java whenever
build-properties.xml changes, a task
src/org/aspectj/internal/tools/ant/taskdefs/VersionUptodate.java
determines whether Version.java has the same version by scanning the source file.
The scan is dim-witted; do not change the lines flagged in the template
without also changing the scanning code in the task.
Temporary aj-{name} and persistant aspectj-{name}
Top-level temporary build directories are prefixed "aj-",
so you can safely destroy any such directory or ignore it
in CVS or the Eclipse package explorer. By default the build script
puts them at the same level as other modules. In build scripts, property names
follow a similar convention; those prefixed "aj-" may be deleted at will, while
"aspectj-" names are source directories which should never be deleted.
Debugging build problems
Running under Eclipse
When running Ant from eclipse,
do not use the default Eclipse Ant classpath; remove those jars and
add all the libraries in ../lib/ant/lib
as well as in ../lib/junit.
Why new or changed modules might not work
The BuildModule taskdef makes some assumptions about the naming,
position, and contents of module directories and files.
Understand those (documented in
BuildModule.java) before using non-standard module directories.
Silent classpath and build failures
warning: When Ant runs compile processes, sometimes Jar files
are not closed until the process quits. When running Ant under Eclipse,
that means the jar files are not writable until eclipse quits.
This affects build products (e.g., installers) which are run under eclipse
(e.g., by opening with the "default system editor") and libraries used
when compiling under Javac (if not zip products or input). This problem
presents as files not being writable, i.e., deleted or modified.
One workaround is to delete any existing build products
before re-creating them. The problem with this is that Ant provides no
notice of that deletes fail when deleting with quiet="on", but when not
running in quiet mode, deletes will fail if the directory does not exist.
The workaround-workaround would be to create any required directories
before trying to deleting any files, with the result of creating unused
empty directories.
Currently BuildModule tasks forks the Javac command to try to work around
this problem, but the Zip commands do not work around it.
If under Eclipse, you get strange behavior with Ant builds, clear
out everything and build from the command line. In some cases, you
have to exit Eclipse before files can be deleted. (*sigh*)