README.html - aspectj/org.aspectj.shadows - Git at Google

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