123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368 |
- <html>
- <title>Build and Test AspectJ</title>
- <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
- JUnit and the harness used for compiler tests.
-
- 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>.
-
- <ol>
- <li>Quick start</li>
- <li>Requirements</li>
- <li>Standard builds</li>
- <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>
- <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>
- <li>Build Problems</li>
- </ol>
-
- <h3>Quick start</h3>
- This is a minimal introduction to building and testing AspectJ.
-
- <p>Command-line users use CVS to check out something like this:
- <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
- <code>org.aspectj/modules</code> as Java projects.
- Skip modules <code>aspectj-attic</code> and (unless running
- compiler tests) <code>tests</code> and most <code>testing*</code>
- modules. Do not skip <code>testing-utils</code>,
- which is used by other modules.
-
- <p>Build an AspectJ distribution:
- <pre>
- cd org.aspectj/modules/build
- ../lib/ant/bin/ant -f build.xml</pre>
-
- To speed the build, Eclipse users can adopt the Eclipse-produced .class files:
- <pre> ../lib/ant/bin/ant -f build.xml -Dbuild.config=useEclipseCompiles</pre>
-
- Install the distribution (e.g., into build/../aspectj-install):
-
- <pre> java -jar ../aj-build/dist/aspectj-DEVELOPMENT.jar</pre>
-
- 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>
-
- Test it by running the build script in the examples directory:
-
- <pre> cd ../aspectj-install/doc/examples
- ../../ant/bin/ant</pre>
-
- This should build and run the spacewar example.
-
- <h3>Requirements</h3>
- To build requires only the AspectJ project modules.
- All necessary libraries and tools are in the
- <a href="../lib/">lib</a> directory. For command-line users,
- that usually means checking out the modules directory:
- <pre>
- export CVS_ROOT=":pserver:anonymous@dev.eclipse.org:/home/technology"
- cvs co org.aspectj/modules
- </pre>
- Eclipse users should check out subdirectories of
- <code>org.aspectj/modules</code> as a Java project.
-
- <p>Not all modules are required.
- The <code>aspectj-attic</code> module only has old code,
- and the <code>tests</code> and <code>testing-*</code> modules
- are only needed to run tests.
-
- <h3>Standard builds</h3>
- <h4>Building using Ant</h4>
- To do a build, use Ant to run <a href="build.xml">build.xml</a>
- from this <a href=".">build</a> directory.
- To run Ant, use the project's <a href="../lib/ant">../lib/ant</a>
- scripts and libraries, not your own.
- The default target builds the AspectJ distribution;
- see the <a href="build.xml">build.xml</a> for other targets.
-
- Consider defining the following flag properties:
- <p>
- <table cellpadding="1" border="1">
- <tr><th>Property</th><th>Meaning</th>
- </tr>
- <tr><td>module.name
- </td><td>To build any module (esp. those not directly supported
- by a target), use the "any-module" target and define
- the module name.
- </td></tr>
- <tr><td>check.build.jar
- </td><td>any value cause build to fail if
- <code>lib/build/build.jar</code> is out of date. (This is a
- built archive of the build module to avoid bootstrapping.)
- </td></tr>
- <tr><td>build.config
- </td><td>override default configuration in build.xml.
- Significant values include "verbose" for more output
- and "useEclipseCompiles" to assume that Eclipse has
- compiled modules into their bin directories, and just
- assemble those classes.
- </td></tr>
- </table>
-
- <p>
- For example, to build everything into a release bundle,
- with verbose logging
- <pre>
- cd modules/build
- ../lib/ant/bin/ant
- </pre>
-
- To build only the asm module (and any modules it requires):
- <pre>
- cd modules/build
- ../lib/ant/bin/ant -f build.xml any-module -Dmodule.name=asm
- </pre>
-
- To build the test harness into
- <code>../aj-build/jars/testing-drivers-all.jar</code>:
- <pre>
- cd modules/build
- ../lib/ant/bin/ant -f build.xml build-testing-drivers
- </pre>
-
- <h4>Building with Eclipse</h4>
- As mentioned above, the modules are Eclipse Java projects, so
- once checked out, they should build as-is. That will enable you
- to run the compiler or test harness from within Eclipse (see below),
- but it will not build the AspectJ release as Ant does.
-
- <h4>Running the Ant build scripts from Eclipse</h4>
- When running Ant from Eclipse, be sure to replace the Eclipse Ant
- 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.)
- <p>
- 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>
- Assuming Eclipse is compiling the AspectJ modules successfully,
- you can use Ant to assemble the eclipse-build .class files into a
- product by including <code>useEclipseCompiles</code> in the
- <code>build.config</code>
- variable as described above. That reduces the build process
- to product assembly, which can be completed in a couple minutes.
- (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>.
-
- <p>To run the compiler from the command-line, use the <code>ajbrowser</code> jar file:
- <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:
- <p>
-
- <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>
- 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>).
-
- <p>The AspectJ project also has <i>additional</i> custom tests in the
- <a href="../tests">tests module</a>,
- mainly the compiler tests run by the harness in
- <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>
- </p>
- <h4>Running JUnit tests in Eclipse</h4>
- JUnit tests may be run under eclipse by selecting any JUnit source file
- and creating a run configuration for it.
- To run all the JUnit tests, use Ant to "build"
- <a href="../tests/junitModules.xml">../tests/junitModules.xml</a>.
- This file uses the eclipse module bin directories as its classpath,
- so it will not work for someone not compiling with Eclipse.
-
- <h4>Running JUnit tests from the command-line without Eclipse</h4>
- The AspectJ project committers do not do this, but it should work fine.
- The trick is to build the modules with their associated test code
- (which happens by default)
- and put the resulting jars on the classpath with the JUnit harness.
-
- <h4>Running JUnit tests from Ant without Eclipse</h4>
- This entails editing
- <a href="../tests/junitModules.xml">../tests/junitModules.xml</a>
- to use a classpath containing the built module jars as described above.
- [todo: update junitModules.xml with non-eclipse variant]
-
- <h4>Using the test harness to run compiler tests</h4>
- The <code>build-testing-drivers</code> target builds a single jar with
- 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>.
- <p>
- <hr>
- <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.
-
- Release builds differ only in running
- from a clean, up-to-date tree and with correct build version values
- in <a href="build-properties.xml">build-properties.xml</a>, which
- will update <code>org.aspectj.bridge.Version</code>.
- Do not run using the <code>build.config</code> value
- <code>useEclipseCompiles</code>,
- because this will include testing classes in the release libraries.
- See <a href="#version">Version synchronization</a> below
- for more details on how the version is updated.
-
- <h4>Release preconditions and testing</h4>
- <p>
- Normally, we do releases only after fixing all high-priority
- (P1 and P2) bugs in the bug database
- (<a href="http://bugs.eclipse.org/bugs/buglist.cgi?product=AspectJ&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&priority=P1&priority=P2">
- All open AspectJ bugs with P1 and P2</a>).
- For bug fixes, associated tests in
- <code>tests/ajcTestsFailing.xml</code> are fixed and moved to
- <code>tests/ajcTests.xml</code>.
-
-
- <p>Before a release, run the release tests as described in
- <a href="../tests/readme-release-tests.html">
- ../tests/readme-release-tests.html</a>
- (deprecated? using:
- <a href="../build/release-checklist.txt">
- ../build/release-checklist.txt</a>).
-
-
- <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>
- <p>
- Pushing the release out to the web involves manually updating
- <code>aspectj-home/</code> with the release files
- (and documentation, if it is not a preview release),
- verifying the downloads and pages,
- and sending any release notifications.
- Save the release installer, test results, and any notes
- about deferred bugs or tests in
- <code>org.aspectj/releases/aspectj-{version}/</code>.
-
- <p>
- <hr>
- <h3>Build problems</h3>
- Some build problems and fixes encountered in the past:
- <ul>
- <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>
- <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>
- <ul>
-
- </body>
- </html>
|