What is this shadows thing all about?

This module is 99% identical to the official jdt.core codebase from eclipse.org. The main line of this code should always be identical to the main line of the jdt.core development. Several changes are required to this module in order to make it work for aspectj. These changes are all captured as a branch from some tagged jdt.core release. At the time of this writing, the most recent jdt.core version is v_312. The needed changes for aspectj are captured in the branch aj_v_312.

If you need to make small changes to jdt.core to support aspectj you should do that by working in the most recent aj_tag branch. Once you've made your changes, follow the steps under build the compiled jar and move it into modules so that your changes will be available to the build process and other developers.

The reason for this weird structure is to achieve the following desired properties:

• Most people working with AspectJ should treat this code as a black box that can't be changed. Exposing it only as a .jar helps achieve this (we also include a src zip for debugging purposes).
• This code needs to periodically go through a difficult 3-way merge process. After exploring many options, I found that the most effective way to achieve this was with a cvs structure where the HEAD follows the "official" jdt core work from eclipse, and the AspectJ changes are represented as branches. This makes moving to a new eclipse release as easy as possible. The instructions for doing this are captured below.
• "experts" should be able to check out the currently active branch of org.eclipse.jdt.core from shadows into their eclipse workspace instead of the static .jar from modules. The current arrangement makes this possible without updating the dependencies.Most people working with AspectJ should treat this code as a black box that can't be changed. Exposing it only as a .jar helps achieve this (we also include a src zip for debugging purposes).

Moving to a new version of JDT Core

The following instructions are for updating to a new version of the official JDT from eclipse.org. We assume that new version is labeled as TAG. You should expect this process to take from 4-24 hours depending on the degree of changes that have occurred in the official JDT system since the last time this synchronization was performed.

General advice. Set team properties to ignore whitespace and to compare actual contents of files.

Add the new TAG to the HEAD of org.aspectj/shadows

1. Check out org.aspectj/shadows from HEAD
2. Use ant get.tag -Dtag=TAG in this directory to overwrite contents with the desired new TAG
3. Commit those changes to head using synchronize and examining changes for plausibility
4. Tag this tree with TAG -- matching the official JDT tree exactly
5. Make a branch in the tree called aj_TAG off of HEAD

Merge the AspectJ changes into the new version of jdt.core

This task is where the hard work happens. The other two tasks are just book-keeping.

1. Check out this new branch into an active AspectJ set of modules instead of the pre-compiled version in modules.
2. HARD: Working in this new branch, merge in the changes from the previous version. This will take some careful work by hand.
3. Use the build.xml file with the makeJdtDepends task found in this branch of org.jdt.core to replace the jdtDepends.jar and jdtDepends-src.zip with the latest versions of the eclipse core classes from a matching eclipse binary release.
4. Rerun the parser generator to make sure you have the right tables and symbol values. This should be done with the python script in org.aspectj.ajdt.core/scripts/make_parser.py.
5. HARD: Fix compile errors, and then run the full test suite and fix any problems that arise.

Build the compiled jar and move it into modules

1. Commit these working changes to the new branch
2. Build jdtcore-for-aspectj.jar and jdtcore-for-aspectj-src.zip using the build.xml found in this branch of org.jdt.core. These files will be put in the directory above the org.eclipse.jdt.core project so they won't be deleted by the next step.
3. Delete the org.eclipse.jdt.core project from your workspace (be sure you've committed)
4. Check out the org.eclipse.jdt.core project from modules
5. Replace the jar and zip files in this project with the ones you made above.
6. Run the tests one more time, and if nothing went wrong you're done.