2003-02-27 01:39:30 +01:00
|
|
|
<html>
|
2005-02-11 06:04:07 +01:00
|
|
|
<head>
|
|
|
|
|
<title>Build and Test AspectJ</title>
|
|
|
|
|
</head>
|
2003-02-27 01:39:30 +01:00
|
|
|
<body>
|
|
|
|
|
<h1>Build and Test AspectJ</h1>
|
|
|
|
|
|
|
|
|
|
This describes how to build and test AspectJ
|
|
|
|
|
for developers working on source code for AspectJ.
|
|
|
|
|
It covers building with Ant or Eclipse and testing with
|
2003-03-08 17:37:49 +01:00
|
|
|
JUnit and the harness used for compiler tests.
|
2003-02-27 01:39:30 +01:00
|
|
|
|
2003-03-06 23:17:13 +01:00
|
|
|
For information on how the build works and how to
|
|
|
|
|
debug failed builds, see
|
|
|
|
|
<a href="readme-build-module.html">
|
|
|
|
|
readme-build-module.html</a>.
|
|
|
|
|
|
2003-02-27 01:39:30 +01:00
|
|
|
<ol>
|
|
|
|
|
<li>Quick start</li>
|
|
|
|
|
<li>Requirements</li>
|
2005-02-11 06:04:07 +01:00
|
|
|
<li>Standard builds
|
2003-02-27 01:39:30 +01:00
|
|
|
<ol>
|
|
|
|
|
<li>Building using Ant</li>
|
|
|
|
|
<li>Building with Eclipse</li>
|
|
|
|
|
<li>Running the Ant build scripts from Eclipse</li>
|
|
|
|
|
<li>Using Eclipse to compile but Ant to assemble</li>
|
|
|
|
|
</ol>
|
2005-02-11 06:04:07 +01:00
|
|
|
</li>
|
2003-02-27 01:39:30 +01:00
|
|
|
<li>Running build products
|
|
|
|
|
<ol>
|
|
|
|
|
<li>Running the compiler, browser, or harness from the command-line</li>
|
|
|
|
|
<li>Running the compiler, browser, or harness from Eclipse</li>
|
|
|
|
|
<li>Running Ant-built jars from Eclipse</li>
|
|
|
|
|
</ol>
|
|
|
|
|
</li>
|
|
|
|
|
<li>Testing AspectJ
|
|
|
|
|
<ol>
|
|
|
|
|
<li>Running JUnit tests in Eclipse</li>
|
|
|
|
|
<li>Running JUnit tests from the command-line without Eclipse</li>
|
|
|
|
|
<li>Running JUnit tests from Ant without Eclipse</li>
|
|
|
|
|
<li>Using the test harness to run compiler tests</li>
|
|
|
|
|
</ol>
|
|
|
|
|
</li>
|
|
|
|
|
<li>Releases
|
|
|
|
|
<ol>
|
|
|
|
|
<li>Release builds</li>
|
|
|
|
|
<li>Release preconditions and testing</li>
|
|
|
|
|
<li>Release completion</li>
|
|
|
|
|
</ol>
|
|
|
|
|
</li>
|
2005-05-11 10:13:00 +02:00
|
|
|
<li>New modules, Java 5, and Ant-only build problems</li>
|
2003-03-06 23:17:13 +01:00
|
|
|
<li>Build Problems</li>
|
2003-02-27 01:39:30 +01:00
|
|
|
</ol>
|
|
|
|
|
|
|
|
|
|
<h3>Quick start</h3>
|
|
|
|
|
This is a minimal introduction to building and testing AspectJ.
|
|
|
|
|
|
2005-02-11 06:04:07 +01:00
|
|
|
<p/>Command-line users use CVS to check out something like this:
|
2003-02-27 01:39:30 +01:00
|
|
|
<pre>
|
|
|
|
|
export CVS_ROOT=":pserver:anonymous@dev.eclipse.org:/home/technology"
|
|
|
|
|
cvs co org.aspectj/modules</pre>
|
|
|
|
|
If using Eclipse, check out the subdirectories of
|
2005-05-19 06:58:05 +02:00
|
|
|
<code>org.aspectj/modules</code> as Eclipse projects.
|
2005-06-09 02:05:40 +02:00
|
|
|
Skip the <code>aspectj-attic</code> module.
|
2003-02-27 01:39:30 +01:00
|
|
|
|
2005-02-11 06:04:07 +01:00
|
|
|
<p/>Build an AspectJ distribution:
|
2003-02-27 01:39:30 +01:00
|
|
|
<pre>
|
|
|
|
|
cd org.aspectj/modules/build
|
2005-06-09 02:05:40 +02:00
|
|
|
../lib/ant/bin/ant</pre>
|
2003-02-27 01:39:30 +01:00
|
|
|
|
2003-03-06 23:17:13 +01:00
|
|
|
Install the distribution (e.g., into build/../aspectj-install):
|
2003-02-27 01:39:30 +01:00
|
|
|
|
|
|
|
|
<pre> java -jar ../aj-build/dist/aspectj-DEVELOPMENT.jar</pre>
|
|
|
|
|
|
2003-03-06 23:17:13 +01:00
|
|
|
You can skip the GUI by specifying an existing, empty writable
|
|
|
|
|
target directory using <code>-to {targDir}</code>:
|
|
|
|
|
|
|
|
|
|
<pre> java -jar ../aj-build/dist/aspectj-DEVELOPMENT.jar -to .</pre>
|
|
|
|
|
|
2003-02-27 01:39:30 +01:00
|
|
|
Test it by running the build script in the examples directory:
|
|
|
|
|
|
2003-03-06 23:17:13 +01:00
|
|
|
<pre> cd ../aspectj-install/doc/examples
|
2005-06-09 02:05:40 +02:00
|
|
|
../../lib/ant/bin/ant</pre>
|
2003-02-27 01:39:30 +01:00
|
|
|
|
|
|
|
|
This should build and run the spacewar example.
|
|
|
|
|
|
2005-06-09 02:05:40 +02:00
|
|
|
<h3>Required sources, libraries, and tools</h3>
|
|
|
|
|
<p>
|
|
|
|
|
|
|
|
|
|
To build requires only the AspectJ project modules and Java VM's.
|
2003-02-27 01:39:30 +01:00
|
|
|
All necessary libraries and tools are in the
|
2005-06-09 02:05:40 +02:00
|
|
|
<a href="../lib/">lib</a> directory, including Ant.
|
|
|
|
|
</p>
|
|
|
|
|
<p>To get the source, check out from CVS. E.g., from the command line,
|
|
|
|
|
</p>
|
|
|
|
|
|
2003-02-27 01:39:30 +01:00
|
|
|
<pre>
|
|
|
|
|
export CVS_ROOT=":pserver:anonymous@dev.eclipse.org:/home/technology"
|
|
|
|
|
cvs co org.aspectj/modules
|
|
|
|
|
</pre>
|
2005-05-11 10:13:00 +02:00
|
|
|
<p>
|
2005-06-09 02:05:40 +02:00
|
|
|
Eclipse users should check out each relevant subdirectory of
|
|
|
|
|
<code>org.aspectj/modules</code> as a project
|
|
|
|
|
(most have .project files).
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
2005-05-11 10:13:00 +02:00
|
|
|
Not all modules are required.
|
2005-06-09 02:05:40 +02:00
|
|
|
The <code>aspectj-attic</code> module only has old code.
|
2005-05-11 10:13:00 +02:00
|
|
|
</p>
|
2003-02-27 01:39:30 +01:00
|
|
|
|
|
|
|
|
<h3>Standard builds</h3>
|
2005-06-09 02:05:40 +02:00
|
|
|
<h4>Overview</h4>
|
|
|
|
|
The build system is designed to work standalone and support
|
|
|
|
|
Eclipse and Ant.
|
|
|
|
|
Each module is an Eclipse project, and all required libraries
|
|
|
|
|
are in lib/.
|
|
|
|
|
All build dependencies are read from Eclipse .classpath files
|
|
|
|
|
and managed using an Ant builder task,
|
|
|
|
|
so no Ant build scripts need to change when dependencies change.
|
|
|
|
|
However, that means the modules (read: Eclipse projects) can only
|
|
|
|
|
do what the builder task understands. Currently it expects
|
|
|
|
|
release source files in <code>src</code> (or <code>java5-src</code>
|
|
|
|
|
for Java 5 code) and test source files in
|
|
|
|
|
<code>testsrc</code> (or <code>java5-testsrc</code>),
|
|
|
|
|
and can handle Java and AspectJ projects.
|
|
|
|
|
For more information on the build infrastructure and setup, see
|
|
|
|
|
<a href="readme-build-module.html">readme-build-module.html</a>
|
|
|
|
|
and <a href="#antInvariants">below</a>.
|
|
|
|
|
|
2003-02-27 01:39:30 +01:00
|
|
|
<h4>Building using Ant</h4>
|
2005-06-09 02:05:40 +02:00
|
|
|
<p>
|
|
|
|
|
You should use the Ant in ../lib/ant. Currently this is a vanilla
|
|
|
|
|
distribution of Ant 1.6.3, but that might change.
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
2005-05-19 06:58:05 +02:00
|
|
|
This <a href=".">build</a> directory has a master
|
|
|
|
|
<a href="build.xml">build.xml</a> script, and the modules have
|
|
|
|
|
satellite <code>build.xml</code> which support building only that
|
|
|
|
|
module.
|
2005-06-09 02:05:40 +02:00
|
|
|
The <a href="release">release</a> directory has scripts for doing
|
|
|
|
|
release builds (in multiple VM's, with testing). These are run by
|
|
|
|
|
automated build and before any AspectJ distribution.
|
|
|
|
|
Custom <code>build.xml</code> files are in
|
|
|
|
|
The <a href="../docs/build.xml">../docs/build.xml</a>,
|
|
|
|
|
<a href="../org.aspectj.lib/build-aspectjlib.xml">org.aspectj.lib/build-aspectjlib.xml</a>,
|
|
|
|
|
and <a href="../eclipse.plugin/build.xml">../eclipse.plugin/build.xml</a>.
|
|
|
|
|
These are invoked by the master
|
|
|
|
|
<a href="build.xml">build.xml</a> as needed.
|
|
|
|
|
Other modules have generic <code>build.xml</code>'s that just
|
|
|
|
|
use the master build file to run targets <code>compile</code> and
|
|
|
|
|
<code>test</code> for that module.
|
|
|
|
|
(If you do <code>clean</code>, all binaries for all
|
|
|
|
|
modules are cleaned.)
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
The master <a href="build.xml">build.xml</a>
|
2005-05-19 06:58:05 +02:00
|
|
|
creates an AspectJ distribution in
|
|
|
|
|
<a href="../aj-build/dist/aspectj-DEVELOPMENT.jar">
|
|
|
|
|
../aj-build/dist/aspectj-DEVELOPMENT.jar
|
|
|
|
|
</a>;
|
2005-06-09 02:05:40 +02:00
|
|
|
You'll notice module jar results are put in
|
|
|
|
|
<a href="../aj-build/jars">../aj-build/jars</a>,
|
|
|
|
|
including <code>{module}.jar</code> and <code>{module}-test.jar</code>
|
|
|
|
|
(for the release and test classes) and
|
|
|
|
|
<code>{module}-all.jar</code>, and
|
|
|
|
|
<code>{module}-test-all.jar</code>
|
|
|
|
|
(including all antecedant classes and libraries).
|
|
|
|
|
See <a href="build.xml">build.xml</a> for other targets.
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
For any build, you should create your own version of
|
|
|
|
|
<a href="local.properties">local.properties</a>, using
|
|
|
|
|
<a href="sample.local.properties">sample.local.properties</a>
|
|
|
|
|
as a template.
|
2005-05-19 06:58:05 +02:00
|
|
|
When using the master <code>build.xml</code>,
|
2005-06-09 02:05:40 +02:00
|
|
|
consider defining "build.config" to pass flags to the Ant
|
|
|
|
|
builder. E.g., to reuse Eclipse classes and log verbosely,
|
2005-02-11 06:04:07 +01:00
|
|
|
<p/>
|
2005-06-09 02:05:40 +02:00
|
|
|
<pre>
|
|
|
|
|
ant -Dbuild.config=useEclipseCompiles,verbose
|
|
|
|
|
</pre>
|
|
|
|
|
<p>
|
|
|
|
|
(<code>useEclipseCompiles</code> is incompatible with release builds
|
|
|
|
|
since it mixes testing and release classes.)
|
2005-05-11 10:13:00 +02:00
|
|
|
<p/>
|
2005-06-09 02:05:40 +02:00
|
|
|
<h4>Example builds</h4>
|
2005-05-11 10:13:00 +02:00
|
|
|
<p>
|
2003-02-27 01:39:30 +01:00
|
|
|
For example, to build everything into a release bundle,
|
2005-05-19 06:58:05 +02:00
|
|
|
with verbose logging:
|
|
|
|
|
</p>
|
2003-02-27 01:39:30 +01:00
|
|
|
<pre>
|
|
|
|
|
cd modules/build
|
|
|
|
|
../lib/ant/bin/ant
|
|
|
|
|
</pre>
|
|
|
|
|
|
2005-05-19 06:58:05 +02:00
|
|
|
<p>
|
2005-05-11 10:13:00 +02:00
|
|
|
To build only the asm module (and any modules it requires) using
|
|
|
|
|
<code>modules/build</code>:
|
2005-05-19 06:58:05 +02:00
|
|
|
</p>
|
2003-02-27 01:39:30 +01:00
|
|
|
<pre>
|
|
|
|
|
cd modules/build
|
|
|
|
|
../lib/ant/bin/ant -f build.xml any-module -Dmodule.name=asm
|
|
|
|
|
</pre>
|
2005-05-19 06:58:05 +02:00
|
|
|
<p>
|
|
|
|
|
To build and test the asm module from that module:
|
|
|
|
|
</p>
|
2005-05-11 10:13:00 +02:00
|
|
|
<pre>
|
2005-05-19 06:58:05 +02:00
|
|
|
cd modules/asm
|
2005-05-11 10:13:00 +02:00
|
|
|
../lib/ant/bin/ant test
|
|
|
|
|
</pre>
|
|
|
|
|
|
2005-05-19 06:58:05 +02:00
|
|
|
<p>
|
2003-02-27 01:39:30 +01:00
|
|
|
To build the test harness into
|
|
|
|
|
<code>../aj-build/jars/testing-drivers-all.jar</code>:
|
2005-05-19 06:58:05 +02:00
|
|
|
</p>
|
2003-02-27 01:39:30 +01:00
|
|
|
<pre>
|
|
|
|
|
cd modules/build
|
2005-06-09 02:05:40 +02:00
|
|
|
../lib/ant/bin/ant build-harness-jar
|
2003-02-27 01:39:30 +01:00
|
|
|
</pre>
|
|
|
|
|
|
|
|
|
|
<h4>Building with Eclipse</h4>
|
2005-05-19 06:58:05 +02:00
|
|
|
<p>
|
|
|
|
|
As mentioned above, the modules are Eclipse projects, so
|
2005-06-09 02:05:40 +02:00
|
|
|
once checked out, they should build as-is.
|
|
|
|
|
(You will need to be using a version of Eclipse that can
|
|
|
|
|
handle the .project and .classpath files in the modules/projects.)
|
|
|
|
|
That will enable you
|
2003-02-27 01:39:30 +01:00
|
|
|
to run the compiler or test harness from within Eclipse (see below),
|
|
|
|
|
but it will not build the AspectJ release as Ant does.
|
2005-05-19 06:58:05 +02:00
|
|
|
If you are making changes in Eclipse, you should set your default JRE
|
|
|
|
|
to the minimum supported by the AspectJ tools (currently JDK 1.3)
|
|
|
|
|
to avoid using later API's.
|
|
|
|
|
You'll need to set some variables in your Eclipse environment;
|
|
|
|
|
currently these are:
|
|
|
|
|
</p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><u>JAVA_HOME</u>: used to access <code>JAVA_HOME/lib/tools.jar</code>
|
|
|
|
|
</li>
|
|
|
|
|
<li><u>JRE15_LIB</u>: used to access Java 5 libraries.
|
|
|
|
|
Some modules/projects use Java 5 API's. These have
|
|
|
|
|
per-project compiler settings for 5.0 compliance, but cannot
|
|
|
|
|
be built with the default pre-1.5 VM libraries.
|
|
|
|
|
Until the minimum VM required by the tools is 1.5,
|
|
|
|
|
we'll need to define this variable.
|
|
|
|
|
</li>
|
|
|
|
|
</ul>
|
2003-02-27 01:39:30 +01:00
|
|
|
|
|
|
|
|
<h4>Running the Ant build scripts from Eclipse</h4>
|
2005-05-19 06:58:05 +02:00
|
|
|
When running Ant from older versions of Eclipse,
|
|
|
|
|
be sure to replace the Eclipse Ant
|
2003-02-27 01:39:30 +01:00
|
|
|
libraries with ours. In the Ant configuration, remove all jars
|
|
|
|
|
specified by Eclipse 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>.
|
|
|
|
|
(Do not add <code>../lib/build/build.jar</code>, which is
|
|
|
|
|
added via a taskdef declaration.)
|
2005-02-11 06:04:07 +01:00
|
|
|
<p/>
|
2003-02-27 01:39:30 +01:00
|
|
|
If you find on rebuilding that the build products are not
|
|
|
|
|
being regenerated, you may need to manually delete them
|
|
|
|
|
or restart eclipse (the files are not being closed); see
|
|
|
|
|
<a href="readme-build-module.html">readme-build-module.html</a>
|
|
|
|
|
for more information.
|
|
|
|
|
|
|
|
|
|
<h4>Using Eclipse to compile but Ant to assemble</h4>
|
2005-06-09 02:05:40 +02:00
|
|
|
As mentioned above,
|
|
|
|
|
assuming Eclipse is compiling the AspectJ modules successfully,
|
|
|
|
|
you can use Ant to assemble the Eclipse-built .class files into a
|
2003-02-27 01:39:30 +01:00
|
|
|
product by including <code>useEclipseCompiles</code> in the
|
2005-06-09 02:05:40 +02:00
|
|
|
<code>build.config</code>. That reduces the build process
|
|
|
|
|
to product assembly.
|
2003-02-27 01:39:30 +01:00
|
|
|
(And of course you can run Ant from Eclipse as described above.)
|
|
|
|
|
|
|
|
|
|
<h4>Running the compiler, browser, or harness from the command-line</h4>
|
|
|
|
|
The build produces jar files in
|
|
|
|
|
<a href="../aj-build/jars/">../aj-build/jars/</a>,
|
|
|
|
|
some of which have manifests specifying the main class, so they
|
|
|
|
|
can be run using <code>java -jar {file} {arguments}</code>.
|
|
|
|
|
|
2005-02-11 06:04:07 +01:00
|
|
|
<p/>To run the compiler from the command-line, use the <code>ajbrowser</code> jar file:
|
2003-02-27 01:39:30 +01:00
|
|
|
<pre>
|
|
|
|
|
java -jar aj-build/jars/ajbrowser-all.jar {compile arguments}
|
|
|
|
|
</pre>
|
|
|
|
|
This will run <code>ajbrowser</code> if you provide no arguments or
|
|
|
|
|
only (unflagged) .lst file arguments. To run the test harness,
|
|
|
|
|
use the <code>testing-drivers</code> jar file:
|
|
|
|
|
<pre>
|
|
|
|
|
java -jar aj-build/jars/testing-drivers-all.jar tests/ajcTests.xml ...
|
|
|
|
|
</pre>
|
|
|
|
|
|
|
|
|
|
<h4>Running the compiler, browser, or harness from Eclipse</h4>
|
|
|
|
|
To run things within Eclipse, create a run configuration from the
|
|
|
|
|
defining module using the main class:
|
2005-02-11 06:04:07 +01:00
|
|
|
<p/>
|
2003-02-27 01:39:30 +01:00
|
|
|
|
|
|
|
|
<table border="1" cellpadding="1">
|
|
|
|
|
<tr><th>Program</th><th>Module</th><th>Main</th></tr>
|
|
|
|
|
<tr><td>AspectJ compiler</td><td>org.aspectj.ajdt.core</td><td>org.aspectj.tools.ajc.Main</td></tr>
|
|
|
|
|
<tr><td>AspectJ browser</td><td>ajbrowser</td><td>org.aspectj.tools.ajbrowser.Main</td></tr>
|
|
|
|
|
<tr><td>Test harness</td><td>testing-drivers</td><td>org.aspectj.testing.drivers.Harness</td></tr>
|
|
|
|
|
</table>
|
|
|
|
|
|
|
|
|
|
<h4>Running Ant-built jars from Eclipse</h4>
|
|
|
|
|
You can run build products (built jars) from Eclipse in two ways:
|
|
|
|
|
<ul>
|
|
|
|
|
<li>Put them on the classpath of some run configuration</li>
|
|
|
|
|
<li>Select the jar files and right-click to "open with default editor"
|
|
|
|
|
(assuming your system is configured to run .jar files)</li>
|
|
|
|
|
</ul>
|
|
|
|
|
You might do this to run the installer or test the browser as built.
|
|
|
|
|
However, doing so might prevent those jar files from being recreated
|
|
|
|
|
in the next build.
|
|
|
|
|
It appears that sometimes these jar files are not close during the
|
|
|
|
|
Eclipse session, which means they cannot be overwritten in new builds,
|
|
|
|
|
even those run from a different Ant process.
|
|
|
|
|
If you find that builds are silently failing, try deleting the
|
|
|
|
|
build products.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<h3>Testing AspectJ</h3>
|
2005-05-19 06:58:05 +02:00
|
|
|
<p>
|
2003-02-27 01:39:30 +01:00
|
|
|
Each module has a tree of JUnit tests in the <code>testsrc</code> directory.
|
|
|
|
|
These parallel the <code>src</code> directories and contain roll-up suites
|
|
|
|
|
for each package
|
|
|
|
|
(<code>{module}/testsrc/{packagePath}/{package}Tests.java</code>) and
|
|
|
|
|
for the module as a whole
|
|
|
|
|
(<code>{module}/testsrc/{module}ModuleTests.java</code>).
|
2005-05-19 06:58:05 +02:00
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
The AspectJ project also has <i>additional</i> custom tests in the
|
|
|
|
|
<a href="../tests">tests module</a>,
|
2003-02-27 01:39:30 +01:00
|
|
|
mainly the compiler tests run by the harness in
|
2003-03-08 17:37:49 +01:00
|
|
|
<a href="../tests/ajcTests.xml">ajcTests.xml</a>. <u>It is important
|
|
|
|
|
to run these additional compiler tests (not covered by the JUnit
|
|
|
|
|
suite) before and after any change to the compiler.</u>
|
2005-05-19 06:58:05 +02:00
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
The module <a href="../run-all-junit-tests">run-all-junit-tests</a>
|
|
|
|
|
refers to all the other modules and the compiler tests adapted through
|
|
|
|
|
the <a href="../tests/src">../tests/src</a>. So the easiest way to
|
|
|
|
|
run the JUnit and compiler tests is to run the top-level suite
|
|
|
|
|
<a href="../run-all-junit-tests/testsrc/RunTheseBeforeYouCommitTests.java">
|
|
|
|
|
RunTheseBeforeYouCommitTests</a>.
|
|
|
|
|
</p>
|
2005-02-11 06:04:07 +01:00
|
|
|
|
2003-02-27 01:39:30 +01:00
|
|
|
<h4>Running JUnit tests in Eclipse</h4>
|
|
|
|
|
JUnit tests may be run under eclipse by selecting any JUnit source file
|
2005-06-09 02:05:40 +02:00
|
|
|
and creating a run configuration for it, including the roll-up
|
|
|
|
|
root test
|
|
|
|
|
<a href="../run-all-junit-tests/testsrc/RunTheseBeforeYouCommitTests.java">
|
|
|
|
|
RunTheseBeforeYouCommitTests</a>.
|
|
|
|
|
|
|
|
|
|
<h4>Running JUnit tests in Ant from the command line</h4>
|
|
|
|
|
To run the JUnit tests for any module, just go there and
|
|
|
|
|
<pre>../lib/ant/bin/ant tests</pre>.
|
2003-02-27 01:39:30 +01:00
|
|
|
|
2005-05-19 06:58:05 +02:00
|
|
|
<h4>Running JUnit tests from the command-line without Eclipse or Ant</h4>
|
|
|
|
|
<p>
|
2005-06-09 02:05:40 +02:00
|
|
|
To run JUnit directly, put JUnit and the {module}-test-all.jar file
|
|
|
|
|
on the classpath:
|
2005-05-19 06:58:05 +02:00
|
|
|
</p>
|
|
|
|
|
<pre>
|
2005-06-09 02:05:40 +02:00
|
|
|
set cp="lib/junit/junit.jar;aj-build/jars/util-test-all.jar"
|
|
|
|
|
java -classpath "$cp" junit.textui.TestRunner UtilModuleTests
|
2005-05-19 06:58:05 +02:00
|
|
|
</pre>
|
2005-06-09 02:05:40 +02:00
|
|
|
<p>
|
|
|
|
|
The assembled (<code>-all</code>) jar files include all antecedants,
|
|
|
|
|
except for those "skipped" (like Ant and JUnit).
|
|
|
|
|
(For more on skipped libraries, see
|
|
|
|
|
<a href="readme-build-module.html">readme-build-module.html</a>).
|
|
|
|
|
</p>
|
2003-02-27 01:39:30 +01:00
|
|
|
|
|
|
|
|
<h4>Using the test harness to run compiler tests</h4>
|
2005-05-19 06:58:05 +02:00
|
|
|
<p>
|
|
|
|
|
|
2005-06-09 02:05:40 +02:00
|
|
|
The <a href="build.xml">build.xml</a> <code>build-harness-jar</code>
|
|
|
|
|
target builds a single jar with
|
2003-02-27 01:39:30 +01:00
|
|
|
the AspectJ binaries and a test harness as the main class.
|
|
|
|
|
It reads test suite files like
|
|
|
|
|
<a href="../tests/ajcTests.xml">../tests/ajcTests.xml</a>;
|
|
|
|
|
use the -help flag to see available options.
|
|
|
|
|
For more information, see
|
|
|
|
|
<a href="../tests/readme-tests-module.html">
|
|
|
|
|
../tests/readme-tests-module.html</a>.
|
2005-05-19 06:58:05 +02:00
|
|
|
</p>
|
2005-02-11 06:04:07 +01:00
|
|
|
<hr/>
|
2003-02-27 01:39:30 +01:00
|
|
|
<h3><a name="releases"></a>Releases</h3>
|
|
|
|
|
<h4>Release builds</h4>
|
|
|
|
|
Committers do official release builds to create the distribution
|
|
|
|
|
released in binary form from the web site.
|
|
|
|
|
|
2005-06-09 02:05:40 +02:00
|
|
|
Release builds differ mainly in running
|
2003-02-27 01:39:30 +01:00
|
|
|
from a clean, up-to-date tree and with correct build version values
|
2005-06-09 02:05:40 +02:00
|
|
|
in <a href="local.properties">local.properties</a>, which
|
2003-02-27 01:39:30 +01:00
|
|
|
will update <code>org.aspectj.bridge.Version</code>.
|
2003-03-06 23:17:13 +01:00
|
|
|
Do not run using the <code>build.config</code> value
|
|
|
|
|
<code>useEclipseCompiles</code>,
|
|
|
|
|
because this will include testing classes in the release libraries.
|
2003-02-27 01:39:30 +01:00
|
|
|
See <a href="#version">Version synchronization</a> below
|
|
|
|
|
for more details on how the version is updated.
|
|
|
|
|
|
|
|
|
|
<h4>Release preconditions and testing</h4>
|
2005-02-11 06:04:07 +01:00
|
|
|
<p/>
|
2003-02-27 01:39:30 +01:00
|
|
|
Normally, we do releases only after fixing all high-priority
|
|
|
|
|
(P1 and P2) bugs in the bug database
|
2005-02-11 06:04:07 +01:00
|
|
|
(<a href="http://bugs.eclipse.org/bugs/buglist.cgi?product=AspectJ&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&priority=P1&priority=P2">
|
2003-03-06 23:17:13 +01:00
|
|
|
All open AspectJ bugs with P1 and P2</a>).
|
2003-02-27 01:39:30 +01:00
|
|
|
For bug fixes, associated tests in
|
|
|
|
|
<code>tests/ajcTestsFailing.xml</code> are fixed and moved to
|
|
|
|
|
<code>tests/ajcTests.xml</code>.
|
|
|
|
|
|
|
|
|
|
|
2005-02-11 06:04:07 +01:00
|
|
|
<p/>Before a release, run the release tests as described in
|
2003-04-26 23:15:23 +02:00
|
|
|
<a href="../tests/readme-release-tests.html">
|
2003-05-06 07:03:38 +02:00
|
|
|
../tests/readme-release-tests.html</a>
|
|
|
|
|
(deprecated? using:
|
|
|
|
|
<a href="../build/release-checklist.txt">
|
|
|
|
|
../build/release-checklist.txt</a>).
|
|
|
|
|
|
|
|
|
|
|
2003-02-27 01:39:30 +01:00
|
|
|
<h4>Release completion</h4>
|
|
|
|
|
When the release build is accepted,
|
|
|
|
|
tag the tree with the release version
|
|
|
|
|
so others can do diffs or create patches
|
|
|
|
|
based on the release code. E.g., from the command line:
|
|
|
|
|
<pre>
|
|
|
|
|
cd org.aspectj/
|
|
|
|
|
cvs tag -R -c v1_1_0
|
|
|
|
|
</pre>
|
2005-02-11 06:04:07 +01:00
|
|
|
<p/>
|
2003-02-27 01:39:30 +01:00
|
|
|
Pushing the release out to the web involves manually updating
|
2005-06-09 02:05:40 +02:00
|
|
|
the web with the release files and documentation,
|
2003-02-27 01:39:30 +01:00
|
|
|
verifying the downloads and pages,
|
|
|
|
|
and sending any release notifications.
|
2003-03-06 23:17:13 +01:00
|
|
|
Save the release installer, test results, and any notes
|
|
|
|
|
about deferred bugs or tests in
|
|
|
|
|
<code>org.aspectj/releases/aspectj-{version}/</code>.
|
|
|
|
|
|
2005-02-11 06:04:07 +01:00
|
|
|
<p/>
|
|
|
|
|
<hr/>
|
2005-05-11 10:13:00 +02:00
|
|
|
<a name="antInvariants"/>
|
|
|
|
|
<h3>New modules, Java 5, and Ant-only build problems</h3>
|
|
|
|
|
<p>
|
2005-06-09 02:05:40 +02:00
|
|
|
To reiterate (and as described more fully in
|
|
|
|
|
<a href="readme-build-module.html">readme-build-module.html</a>),
|
2005-05-11 10:13:00 +02:00
|
|
|
the build system introspects on module and the .classpath file
|
|
|
|
|
to determine how to build. Further, it enforces stricter build
|
|
|
|
|
invariants than the Eclipse projects do; when your code works
|
|
|
|
|
in Eclipse but fails in the Ant, it's your responsibility to fix it
|
|
|
|
|
by following the build invariants below.
|
|
|
|
|
</p>
|
2006-08-03 18:03:35 +02:00
|
|
|
<p>
|
|
|
|
|
<p>What to do when adding a new module (i.e., eclipse project):
|
|
|
|
|
</p>
|
|
|
|
|
<ol>
|
|
|
|
|
<li>Setup like the other modules, following the invariants below, esp.
|
|
|
|
|
<ol>
|
|
|
|
|
<li>same directory level</li>
|
|
|
|
|
<li>same naming conventions for source folders</li>
|
|
|
|
|
<li>same use of known classpath variables/entries</li>
|
|
|
|
|
</ol>
|
|
|
|
|
</li>
|
|
|
|
|
<li>Add module to those checked for copyright/license in
|
|
|
|
|
<a href="testsrc/org/aspectj/build/BuildModuleTests.java">
|
|
|
|
|
testsrc/org/aspectj/build/BuildModuleTests.java
|
|
|
|
|
</a>
|
|
|
|
|
</li>
|
|
|
|
|
<li>Add module to module dependency tree as usual in Eclipse project properties</li>
|
|
|
|
|
<li>If the module is to produce a jar visible in {AspectJ}/lib,
|
|
|
|
|
then add a zero-length file of the correct name to
|
|
|
|
|
<a href="products/tools/dist/lib">products/tools/dist/lib</a>
|
|
|
|
|
and an alias to that file from the module name in
|
|
|
|
|
<a href="src/org/aspectj/internal/tools/build/Builder.properties">
|
|
|
|
|
Builder.properties</a>
|
|
|
|
|
</li>
|
|
|
|
|
<li>To make the JUnit tests visible to the Ant builder, include a
|
|
|
|
|
top-level Ant suite titled {Module}ModuleTests.java
|
|
|
|
|
</li>
|
|
|
|
|
<li>Test the build in Eclipse/JUnit using
|
|
|
|
|
<a href="testsrc/org/aspectj/internal/build/BuildModuleTest.java">
|
|
|
|
|
testsrc/org/aspectj/internal/build/BuildModuleTest.java
|
|
|
|
|
</a>
|
|
|
|
|
</li>
|
|
|
|
|
</ol>
|
2005-05-11 10:13:00 +02:00
|
|
|
<p>
|
|
|
|
|
How the build system introspects, and the build invariants that
|
|
|
|
|
are enforced by the Ant build:
|
|
|
|
|
</p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li>A given module is identified by its directory name.
|
|
|
|
|
</li>
|
|
|
|
|
<li>Most modules are Eclipse Java projects; some are AspectJ projects.
|
|
|
|
|
Eclipse is not required to build.
|
|
|
|
|
</li>
|
|
|
|
|
<li>The file <code>{module.name}/.classpath</code> is read to determine
|
|
|
|
|
the source directories and required projects and libraries.
|
|
|
|
|
</li>
|
|
|
|
|
<li>Normal Java source files are in <code>src</code> and <code>testsrc</code>
|
|
|
|
|
directories.
|
|
|
|
|
</li>
|
|
|
|
|
<li>Java 5 source files are in <code>java5-src</code> and <code>java5-testsrc</code>
|
|
|
|
|
directories.
|
|
|
|
|
</li>
|
|
|
|
|
<li>Neither <code>testsrc</code> directory is used in production builds.
|
|
|
|
|
</li>
|
|
|
|
|
<li>
|
|
|
|
|
This only requires what's in the
|
|
|
|
|
<a href="../lib">../lib</a> directory and the usual Java VM's.
|
|
|
|
|
That means modules can only depend on each other and the libraries
|
|
|
|
|
in <a href="../lib">../lib</a>.
|
|
|
|
|
</li>
|
|
|
|
|
<li>Modules are built into jar files. <code>{module.name}.jar</code>
|
|
|
|
|
includes only the module classes, and <code>{module.name}-all.jar</code>
|
|
|
|
|
includes the module classes plus any antecendant modules and any
|
|
|
|
|
required libraries not skipped (see below).
|
|
|
|
|
</li>
|
|
|
|
|
<li>A file <code>{module.name}/{module.name}.mf.txt</code>, if available,
|
|
|
|
|
will be used as the jar file manifest, after replacing certain
|
|
|
|
|
variables in the <code>.mf.txt</code> file.
|
|
|
|
|
</li>
|
|
|
|
|
<li>All required libraries are included in the production jars, except
|
|
|
|
|
for testing libraries and those "skipped" in
|
|
|
|
|
<a href="src/org/aspectj/internal/tools/build/Builder.properties">
|
|
|
|
|
Builder.properties</a>
|
|
|
|
|
(Ant, JUnit, etc.).
|
|
|
|
|
</li>
|
|
|
|
|
<li>Test classes are excluded from the compile process for production builds.
|
|
|
|
|
These result in the same jar files; there is no way to
|
|
|
|
|
tell externally whether the test classes were stripped from a jar.
|
|
|
|
|
</li>
|
|
|
|
|
<li>ONLY resources specified as <code>resource.pattern</code> in
|
|
|
|
|
<a href="src/org/aspectj/internal/tools/build/Builder.properties">
|
|
|
|
|
Builder.properties</a>
|
|
|
|
|
are included with assembled jars.
|
|
|
|
|
</li>
|
|
|
|
|
<li>No <code>testing-*</code> module is used in production builds,
|
|
|
|
|
directly or indirectly.
|
|
|
|
|
</li>
|
|
|
|
|
<li>It is an error for any code to depend on any <code>testsrc</code> code,
|
|
|
|
|
whether in the same or another module.
|
|
|
|
|
</li>
|
|
|
|
|
<li>AspectJ projects are built in Ant using
|
|
|
|
|
<a href="../lib/aspectj">../lib/aspectj</a>.
|
|
|
|
|
</li>
|
|
|
|
|
<li>Java 5 code is not supported in AspectJ (yet).
|
|
|
|
|
</li>
|
|
|
|
|
<li>Java 5 code is built in Ant only if JAVA_HOME points to Java 5 (or later).
|
|
|
|
|
</li>
|
|
|
|
|
<li>No normal code can depend on any Java 5 code.
|
|
|
|
|
The build system checks by building everything using the
|
|
|
|
|
lowest VM supported by the tools.
|
|
|
|
|
</li>
|
|
|
|
|
</ul>
|
|
|
|
|
<p>That means there are a number of legal Eclipse projects and code
|
|
|
|
|
arrangements which are not valid AspectJ modules.
|
|
|
|
|
When you add modules, libraries, or dependencies, you must build
|
|
|
|
|
with Ant to verify these invariants are not broken.
|
|
|
|
|
</p>
|
2003-02-28 08:46:14 +01:00
|
|
|
<h3>Build problems</h3>
|
|
|
|
|
Some build problems and fixes encountered in the past:
|
|
|
|
|
<ul>
|
2005-05-11 10:13:00 +02:00
|
|
|
<li>If the build works in Eclipse, but fails in Ant,
|
|
|
|
|
do not assume the build scripts are broken.
|
|
|
|
|
See <a href="#antInvariants">Invariants enforced only in Ant</a>.
|
|
|
|
|
</li>
|
2003-02-28 08:46:14 +01:00
|
|
|
<li>If your compiles fail because Ant cannot find <code>javac</code>,
|
|
|
|
|
put the JDK bin directory on your PATH and/or define
|
|
|
|
|
the JAVA_HOME environment variable.
|
|
|
|
|
Ant requires the path to the <code>javac</code> executable
|
|
|
|
|
when the <code>BuildModule</code> taskdef runs. I think it either
|
|
|
|
|
gets it from <code>$JAVA_HOME</code> or if the <code>bin</code>
|
|
|
|
|
directory is on the <code>PATH</code>.
|
|
|
|
|
</li>
|
2003-03-08 17:37:49 +01:00
|
|
|
<li>If using an IBM JDK at version 1.4 or higher within Eclipse,
|
|
|
|
|
then the default value of JRE_LIB will point to the jar file
|
|
|
|
|
"core.jar." Unlike the Sun JDK, IBM does not package the full
|
|
|
|
|
runtime into a single jar ("rt.jar"), but instead has multiple
|
|
|
|
|
jar files. Since core.jar does not contain the graphics libraries,
|
|
|
|
|
several of the AspectJ projects will fail to build as checked out
|
|
|
|
|
of CVS - there are missing dependencies on AWT and swing. The
|
|
|
|
|
solution is to add graphics.jar to the project classpaths... BUT
|
|
|
|
|
if this is added as an ordinary (external jar), then the main
|
|
|
|
|
ant build script will pick up the contents of graphics.jar and
|
|
|
|
|
include it in the aspectj distribution (obvious clue, the size of
|
|
|
|
|
the built aspectjtools.jar doubles to about 10MB). Instead, from the
|
|
|
|
|
Java Build Path properties page of the project, select "Add Library"
|
|
|
|
|
and add the JDK library. You now have to remove the JRE_LIB entry
|
|
|
|
|
from the project or Eclipse complains about duplicate jar files
|
|
|
|
|
in the path.
|
|
|
|
|
</li>
|
2005-03-08 08:37:24 +01:00
|
|
|
<li>More generally, if you find extra classes in the assembled jars,
|
|
|
|
|
most likely you have added unexpected libraries to the build, e.g.,
|
|
|
|
|
when adding libraries for the IBM JRE.
|
|
|
|
|
To skip those, add them to the "skip.libraries" list in
|
|
|
|
|
<a href="src/org/aspectj/internal/tools/build/Builder.properties">
|
|
|
|
|
src/org/aspectj/internal/tools/build/Builder.properties</a>.
|
|
|
|
|
These libraries will always be skipped for any module built this way;
|
|
|
|
|
there is no way to include a library in one module but not another.
|
|
|
|
|
For more information on the properties file, see
|
|
|
|
|
<a href="readme-build-module.html">readme-build-module.html</a>.
|
|
|
|
|
</li>
|
2005-02-11 06:04:07 +01:00
|
|
|
</ul>
|
2003-02-27 01:39:30 +01:00
|
|
|
|
|
|
|
|
</body>
|
|
|
|
|
</html>
|
