| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> |
| <html> |
| <head> |
| |
| <title>Modified JDT Core for AspectJ</title> |
| </head> |
| |
| <body> |
| <h2>What is this shadows thing all about?</h2> |
| |
| <p>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.<p> |
| |
| <p>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.</p> |
| |
| <p>The reason for this weird structure is to achieve the following |
| desired properties:</p> |
| |
| <ul> |
| <li>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). |
| </li> |
| |
| <li>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.</li> |
| |
| <li>"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). |
| </li> |
| </ul> |
| |
| |
| <h2>Moving to a new version of JDT Core</h2> |
| |
| <p>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 <b>TAG</b>. 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.</p> |
| |
| <p>General advice. Set team properties to ignore whitespace and |
| to compare actual contents of files.<p> |
| |
| <h3>Add the new <b>TAG</b> to the HEAD of org.aspectj/shadows</h3> |
| <ol> |
| <li>Check out org.aspectj/shadows from HEAD</li> |
| |
| <li>Use <code>ant get.tag -Dtag=<b>TAG</b></code> in this directory to overwrite |
| contents with the desired new <b>TAG</b></li> |
| |
| <li>Commit those changes to head using synchronize and examining changes for plausibility</li> |
| |
| <li>Tag this tree with <b>TAG</b> -- matching the official JDT tree exactly</li> |
| |
| <li>Make a branch in the tree called aj_<b>TAG</b> off of HEAD</li> |
| </ol> |
| |
| <h3>Merge the AspectJ changes into the new version of jdt.core</h3> |
| |
| <p>This task is where the hard work happens. The other two tasks are just book-keeping. |
| </p> |
| |
| <ol> |
| <li>Check out this new branch into an active AspectJ set of modules instead of the |
| pre-compiled version in modules.</li> |
| |
| <li><b>HARD:</b> Working in this new branch, merge in the changes from the previous version. This |
| will take some careful work by hand.</li> |
| |
| <li>Use the build.xml file with the <code>makeJdtDepends</code> |
| 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. |
| </li> |
| |
| <li>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. |
| </li> |
| |
| <li><b>HARD:</b> Fix compile errors, and then run the full test suite and fix any problems that arise.</li> |
| </ol> |
| |
| <h3>Build the compiled jar and move it into modules</h3> |
| <ol> |
| <li>Commit these working changes to the new branch</li> |
| |
| <li>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.</li> |
| |
| <li>Delete the org.eclipse.jdt.core project from your workspace (be sure you've committed)</li> |
| |
| <li>Check out the org.eclipse.jdt.core project from modules</li> |
| |
| <li>Replace the jar and zip files in this project with the ones you made above.</li> |
| |
| <li>Run the tests one more time, and if nothing went wrong you're done.</li> |
| </ol> |
| </body> |
| </html> |