diff options
Diffstat (limited to 'build/readme-build-and-test-aspectj.html')
| -rw-r--r-- | build/readme-build-and-test-aspectj.html | 604 |
1 files changed, 0 insertions, 604 deletions
diff --git a/build/readme-build-and-test-aspectj.html b/build/readme-build-and-test-aspectj.html deleted file mode 100644 index 4019a3f9d..000000000 --- a/build/readme-build-and-test-aspectj.html +++ /dev/null @@ -1,604 +0,0 @@ -<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="https://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> -<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> -<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> |