mirror of
https://github.com/eclipse-aspectj/aspectj.git
synced 2024-07-24 13:54:45 +02:00
171 lines
7.4 KiB
HTML
171 lines
7.4 KiB
HTML
<html>
|
|
<title>AspectJ build module</title>
|
|
<body>
|
|
<h1>AspectJ build</h1>
|
|
|
|
This build module contains taskdefs and resources for doing builds
|
|
and checking source licenses. This document describes our approach
|
|
to builds and provides some notes for maintaining the build module
|
|
and debugging builds.
|
|
For information
|
|
on running builds and doing testing for the AspectJ project, see
|
|
<a href="readme-build-and-test-aspectj.html">
|
|
readme-build-and-test-aspectj.html</a>.
|
|
|
|
<h3>Approach</h3>
|
|
The AspectJ project source files are broken into modules,
|
|
the subdirectories of the modules directory.
|
|
(To eclipse users, each module is a Java project.)
|
|
The modules are compiled independently and may be assembled
|
|
by the build script into the release jar files.
|
|
All required libraries are checked into the <code>lib</code> 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.
|
|
|
|
|
|
<h3>Maintaining the build module</h3>
|
|
|
|
Because the BuildModule taskdef extracts dependencies from the Eclipse
|
|
<code>.classpath</code> 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.
|
|
|
|
<h4>Build module code updates</h4>
|
|
The build module produces taskdefs used to run the build.
|
|
The scripts avoid bootstrapping by using a build library jar
|
|
checked in to
|
|
<code>lib/build/build.jar</code>.
|
|
That means code updates in the build module are not reflected in
|
|
the build process until the <code>build.jar<code> produced by
|
|
building this <code>build<code> module replaces that found in
|
|
<code>lib/build/build.jar</code>. Once the module update is
|
|
confirmed, the new <code>lib/build/build.jar</code> must be checked in
|
|
to propogate the changes to other users.
|
|
The scripts support an Ant variable <code>check.build.jar</code>
|
|
by warning when <code>lib/build/build.jar</code> is out of date.
|
|
|
|
<h4>BuildModule task</h4>
|
|
The
|
|
<a href="src/org/aspectj/internal/tools/ant/taskdefs/BuildModule.java">
|
|
BuildModule</a>
|
|
taskdef implements an integrated module or product build.
|
|
<p><u>Module builds</u> are based on the Eclipse <code>.classpath</code>
|
|
file, and can produce
|
|
a jar with the module classes, with two variations:
|
|
<ul>
|
|
<li> include only the module classes,
|
|
or assemble the jar complete with all antecedent modules and
|
|
libraries;
|
|
</li><li>compile the module(s) with or without any
|
|
testing source or libraries
|
|
</li>
|
|
</ul>
|
|
If there is a file {moduleName}.mf.txt
|
|
in the module directory, it will be used as the manifest for the
|
|
module jar file.
|
|
|
|
<p><u>Product builds</u> are defined by introspection of a
|
|
<a href="products">products</a> subdirectory like
|
|
<a href="products/tools">products/tools</a> for the AspectJ installer.
|
|
|
|
These have an <code>install</code> directory for installer resources
|
|
and a <code>dist</code> 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).
|
|
|
|
<p>
|
|
<a name="version"></a>
|
|
<h4>Version synchronization</h4>
|
|
The version is expressed in the jar manifests, in the <code>Version</code> 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.
|
|
|
|
<p>The build version is set in
|
|
<a href="build-properties.xml">build-properties.xml</a> and propogated
|
|
using Ant copy filters out to
|
|
the <a href="../runtime/runtime.mf.txt">aspectjrt.jar manifest</a>,
|
|
the <a href="../ajbrowser/ajbrowser.mf.txt">aspectjtools.jar manifest</a>
|
|
|
|
and to
|
|
<a href="../bridge/src/org/aspectj/bridge/Version.java">
|
|
../bridge/src/org/aspectj/bridge/Version.java</a>
|
|
which the <a href="build.xml">build.xml</a> <code>init-version</code> task
|
|
generates from a template
|
|
<a href="lib/BridgeVersion.java.txt">lib/BridgeVersion.java.txt</a>.
|
|
To avoid updating <code>Version.java</code> whenever
|
|
<code>build-properties.xml</code> changes, a task
|
|
<a href="src/org/aspectj/internal/tools/ant/taskdefs/VersionUptodate.java">
|
|
src/org/aspectj/internal/tools/ant/taskdefs/VersionUptodate.java</a>
|
|
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.
|
|
|
|
<h4>Temporary aj-{name} and persistant aspectj-{name}</h4>
|
|
<p>
|
|
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.
|
|
|
|
<h3>Debugging build problems</h3>
|
|
<h4>Running under Eclipse</h4>
|
|
When running Ant from eclipse,
|
|
do not use the default Eclipse Ant classpath; remove those jars and
|
|
add all the libraries in <a href="../lib/ant/lib">../lib/ant/lib</a>
|
|
as well as in <a href="../lib/junit">../lib/junit</a>.
|
|
<p>
|
|
|
|
<h4>Why new or changed modules might not work</h4>
|
|
The BuildModule taskdef makes some assumptions about the naming,
|
|
position, and contents of module directories and files.
|
|
Understand those (documented in
|
|
<a href="src/org/aspectj/internal/tools/ant/taskdefs/BuildModule.java">
|
|
BuildModule.java</a>) before using non-standard module directories.
|
|
|
|
<h4>Silent classpath and build failures</h4>
|
|
<u>warning</u>: 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.
|
|
<p>
|
|
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.
|
|
|
|
<p>
|
|
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*)
|
|
|
|
<p>
|
|
</body>
|
|
</html>
|