mirror of
https://github.com/eclipse-aspectj/aspectj.git
synced 2024-09-01 17:56:00 +02:00
149 lines
7.5 KiB
HTML
149 lines
7.5 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
|
|
<html> <head>
|
|
<title>The BCEL-builder module</title>
|
|
</head>
|
|
|
|
<body>
|
|
<h1>The BCEL-builder module</h1>
|
|
|
|
This module includes a modified form of BCEL - with some fixes in *and* support for Java5.
|
|
|
|
<hr>
|
|
|
|
<h3>Java 5 support</h3>
|
|
<p>The best way to see how it works is look in the testcases. The only feature that
|
|
is definetly not implemented yet is package level annotations. What is working is:</p>
|
|
|
|
<ul>
|
|
<li>You can ask a type: are you an annotation type? are you an enum type?</li>
|
|
<li>You can ask a method: were you defined with varargs? Are you a bridge method?</li>
|
|
<li>All annotation values types are supported (primitive, string, array, enum, annotation, class).</li>
|
|
<li>Runtime visible and invisible annotations are supported.</li>
|
|
<li>Annotations are accessible on types, methods, fields.</li>
|
|
<li>Parameter annotations are accessible on methods.</li>
|
|
<li>You can programmatically construct annotations and attach them to types, methods, fields.</li>
|
|
<li>You can construct parameter annotations and add them to methods.</li>
|
|
<li>The EnclosingMethod attribute is supported (it is used to let you know the containing method for local/anonymous types)</li>
|
|
<li>The LocalVariableTypeTable attribute is supported (used for generics to tell you the original variable signature)</li>
|
|
</ul>
|
|
<p>All this is implemented without using any Java 5 APIs.</p>
|
|
<p>There are a number of new TODO type tags in the code that may prove useful:</p>
|
|
<ul>
|
|
<li>J5SUPPORT: Marks places where BCEL has been changed for 1.5 (might have missed a couple...)</li>
|
|
<li>BCELBUG: Marks things that might be BCEL problems that I came across</li>
|
|
<li>J5TODO: Marks either a missing bit of implementation (hopefully corner case) or an optimization we could make</li>
|
|
</ul>
|
|
<hr>
|
|
<p> The contents of this directory are:
|
|
</p>
|
|
|
|
<ul>
|
|
<li>This file</li>
|
|
<li>src -- contains the source for BCEL, a modified variant of BCEL 5.1 that includes bug fixes and Java 5 support</li>
|
|
<li>testsrc -- JUnit test cases for the Java 5 support</li>
|
|
<li>testdata -- Java5 testcode that can be built using the build.xml script in the testdata directory (see note on this below)</li>
|
|
<li>build.xml -- an ant script for manipulating the src folder, possibly useful if ever merging a base BCEL version</li>
|
|
</ul>
|
|
|
|
<hr>
|
|
<h3>Development Process</h3>
|
|
<p>
|
|
We can now follow normal TDD for this. Add a JUnit testcase to the testsrc folder, plus any
|
|
associated test materials into the testdata directory. Then change BCEL to get your test passing,
|
|
when you are happy with the result (i.e. all the tests in the bcel-builder module are passing), you
|
|
should execute the build.xml script whose default target will package up bcel (and bcel src) and
|
|
deliver it into the lib module, the rest of AspectJ is driven off the version of bcel in the lib/bcel
|
|
folder - it is *not* driven off the bcel-builder code (we could choose to change that sometime later).
|
|
<p>
|
|
Once you have done this execute all the tests for AspectJ, if they all pass you can check in your
|
|
mods for bcel-builder and to the lib project.
|
|
|
|
<hr>
|
|
<h3>testdata</h3>
|
|
The testdata folder includes a load of Java5 code, it needs to be built with a Java5 compiler. There
|
|
is an ant script in there (build.xml) that builds all the source code into a testcode.jar which is
|
|
then used by the testcases - so if you do change the testdata code then you should run build.xml
|
|
to rebuild testcode.jar.
|
|
|
|
<hr>
|
|
<h3>The old stuff...</h3>
|
|
Before the Java 5 support was added we maintained this module as basically a patch to apply against
|
|
a particular download of BCEL. Changes to BCEL are occurring more frequently than we integrate
|
|
a new version of BCEL so it made sense to make the patching process easier, so we have checked in
|
|
the modified source for BCEL.
|
|
The original instructions for patching BCEL in the old way are below...
|
|
|
|
<p> And pretty much nothing else. Well, then, what do you do with
|
|
this directory? Well, the whole point is to generate bcel/bcel.jar in
|
|
the lib package. To do so, first stick
|
|
<strong>bcel-5.1-src.zip</strong> in this directory, then run ant.
|
|
(at one point, this was available at
|
|
<a href="http://archive.apache.org/dist/jakarta/bcel/source/bcel-5.1-src.zip">
|
|
http://archive.apache.org/dist/jakarta/bcel/source/bcel-5.1-src.zip</a>)
|
|
After much unzipping, patching, and compiling, you should get an
|
|
appropriate bcel.jar file. Now put it in the appropriate place. </p>
|
|
|
|
<p> If there's something <em>wrong</em> with the bcel.jar in the lib
|
|
project, well, then you've got some development to do. You'll need
|
|
to know some more ant targets. But before anything, get that
|
|
<strong>bcel-5.1-src.zip</strong> and stick it in this directory.
|
|
<b>NOTE: You should be working on BCEL when the package names are org.aspectj.apache.bcel,
|
|
and *not* when the package names are org.apache.bcel. If you run the extractAndPatch task
|
|
below, you will be left with a src folder in the correct state for further development.</b>
|
|
</p>
|
|
|
|
<p> There are five top-level ant targets apart from the usual "clean":</p>
|
|
|
|
<ul>
|
|
<li>ant extractAndPatchAndJar -- this is just the composition of the extract,
|
|
jar and srcjar targets, and is the default. It extracts the source from bcel-5.1-src.zip,
|
|
patches it, renames the files to start org.aspectj.apache rather than org.apache then
|
|
compiles the patched version into a jar and drops the new archives:
|
|
bcel.jar and bcel-src.zip, into the project root. This is the default task, mainly used
|
|
to sanity check the building and make sure we're generating something.
|
|
The bcel.jar and bcel-src.zip generated should be the same as that in ..\lib\bcel\.
|
|
</li>
|
|
|
|
<li>ant extractAndPatch -- this extracts the source from bcel-5.1-src.zip,
|
|
patches it, renames the files to start org.aspectj.apache rather than org.apache then
|
|
copies the patched source into the project src directory,
|
|
there to be visible by eclipse for people to do development on it.
|
|
For the patch file to be applied you need to have a patch.exe on your path,
|
|
this bcel building process was tested with the version from cygwin.
|
|
</li>
|
|
|
|
<li>ant jar -- this copies the edited source from the project source
|
|
directory and jars it up into bcel.jar, there to be tested.
|
|
</li>
|
|
|
|
<li>ant srcjar -- this copies the edited source from the project source
|
|
directory and jars up the source code into bcel-src.zip.
|
|
</li>
|
|
|
|
<li>ant push -- this pushes the new bcel.jar and bcel-src.zip into ..\lib\bcel\.
|
|
- ready to be used by the greater compiler.</li>
|
|
|
|
<li>ant diff -- this creates the patch.txt file, composed of the differences
|
|
between the project src directory and the original bcel-5.1 source.
|
|
In order to create the patch, we transform the packages back to org.apache from
|
|
org.aspectj.apache. To continue working on BCEL once you have done this, you might
|
|
need to run the transformToAJ task to switch the packages back to the AJ prefix.
|
|
For the patch file to be built successfully you need to have a diff.exe on your path,
|
|
this bcel building process was tested with the version from cygwin.
|
|
</li>
|
|
|
|
<li>ant transformToAJ - this changes the packages for the BCEL classes to
|
|
org.aspectj.apache from org.apache. This is used by the extractAndPatch task above.
|
|
</li>
|
|
|
|
<li>ant transformFromAJ - this changes the packages for the BCEL classes to
|
|
org.apache from org.aspectj.apache. This is used by the diff task.
|
|
</li>
|
|
</ul>
|
|
|
|
<p> All of the tasks are destructive, so don't do "ant extract", for example,
|
|
if you have anything in the project source directory you care about.
|
|
</p>
|
|
|
|
</body> </html>
|