|
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148 |
- <!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>
|