123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571 |
- <html>
- <head>
- <title>Build and Test AspectJ</title>
- </head>
- <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
- <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>
- <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>New modules, Java 5, and Ant-only build problems</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 Eclipse projects.
- Skip the <code>aspectj-attic</code> module.
-
- <p/>Build an AspectJ distribution:
- <pre>
- cd org.aspectj/modules/build
- ../lib/ant/bin/ant</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
- ../../lib/ant/bin/ant</pre>
-
- This should build and run the spacewar example.
-
- <h3>Required sources, libraries, and tools</h3>
- <p>
-
- To build requires only the AspectJ project modules and Java VM's.
- All necessary libraries and tools are in the
- <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>
-
- <pre>
- export CVS_ROOT=":pserver:anonymous@dev.eclipse.org:/home/technology"
- cvs co org.aspectj/modules
- </pre>
- <p>
- Eclipse users should check out each relevant subdirectory of
- <code>org.aspectj/modules</code> as a project
- (most have .project files).
- </p>
- <p>
- Not all modules are required.
- The <code>aspectj-attic</code> module only has old code.
- </p>
-
- <h3>Standard builds</h3>
- <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>.
-
- <h4>Building using Ant</h4>
- <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>
- 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.
- 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>
- creates an AspectJ distribution in
- <a href="../aj-build/dist/aspectj-DEVELOPMENT.jar">
- ../aj-build/dist/aspectj-DEVELOPMENT.jar
- </a>;
- 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.
- When using the master <code>build.xml</code>,
- consider defining "build.config" to pass flags to the Ant
- builder. E.g., to reuse Eclipse classes and log verbosely,
- <p/>
- <pre>
- ant -Dbuild.config=useEclipseCompiles,verbose
- </pre>
- <p>
- (<code>useEclipseCompiles</code> is incompatible with release builds
- since it mixes testing and release classes.)
- <p/>
- <h4>Example builds</h4>
- <p>
- For example, to build everything into a release bundle,
- with verbose logging:
- </p>
- <pre>
- cd modules/build
- ../lib/ant/bin/ant
- </pre>
-
- <p>
- To build only the asm module (and any modules it requires) using
- <code>modules/build</code>:
- </p>
- <pre>
- cd modules/build
- ../lib/ant/bin/ant -f build.xml any-module -Dmodule.name=asm
- </pre>
- <p>
- To build and test the asm module from that module:
- </p>
- <pre>
- cd modules/asm
- ../lib/ant/bin/ant test
- </pre>
-
- <p>
- To build the test harness into
- <code>../aj-build/jars/testing-drivers-all.jar</code>:
- </p>
- <pre>
- cd modules/build
- ../lib/ant/bin/ant build-harness-jar
- </pre>
-
- <h4>Building with Eclipse</h4>
- <p>
- As mentioned above, the modules are Eclipse projects, so
- 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
- to run the compiler or test harness from within Eclipse (see below),
- but it will not build the AspectJ release as Ant does.
- 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>
-
- <h4>Running the Ant build scripts from Eclipse</h4>
- When running Ant from older versions of 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>
- As mentioned above,
- assuming Eclipse is compiling the AspectJ modules successfully,
- you can use Ant to assemble the Eclipse-built .class files into a
- product by including <code>useEclipseCompiles</code> in the
- <code>build.config</code>. That reduces the build process
- to product assembly.
- (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>
- <p>
- 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>
- <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>
- <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>
-
- <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, 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>.
-
- <h4>Running JUnit tests from the command-line without Eclipse or Ant</h4>
- <p>
- To run JUnit directly, put JUnit and the {module}-test-all.jar file
- on the classpath:
- </p>
- <pre>
- set cp="lib/junit/junit.jar;aj-build/jars/util-test-all.jar"
- java -classpath "$cp" junit.textui.TestRunner UtilModuleTests
- </pre>
- <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>
-
- <h4>Using the test harness to run compiler tests</h4>
- <p>
-
- The <a href="build.xml">build.xml</a> <code>build-harness-jar</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 mainly in running
- from a clean, up-to-date tree and with correct build version values
- in <a href="local.properties">local.properties</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
- the web with the release files and documentation,
- 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/>
- <a name="antInvariants"/>
- <h3>New modules, Java 5, and Ant-only build problems</h3>
- <p>
- To reiterate (and as described more fully in
- <a href="readme-build-module.html">readme-build-module.html</a>),
- 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>
- <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>
- <h3>Build problems</h3>
- Some build problems and fixes encountered in the past:
- <ul>
- <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>
- <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>
- <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>
- </ul>
-
- </body>
- </html>
|