mirrors
/
org.aspectj
mirror of https://github.com/eclipse/org.aspectj.git


			
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134
							<html>
<title>Incremental test of AjcTask Ant task</title>
<body>
<h2>Incremental test of AjcTask Ant task</h2>
This directory contains files for manually testing 
two AjcTask Ant task facilities:
<ul>
<li>incremental builds, using tag file or input stream
    (supported directly by the compiler)
   </li>
<li>resource copying using input jars or source roots
    and output jar or directory
    (only supported in the Ant task).
   </li>
</ul>

<a href="incTest.xml">incTest.xml</a>
is an Ant script which builds two input jars
and runs an incremental test using a tag file.
<p>
The results must be verified by hand manually at present;
This test should be updated to run using JUnit like
<a href="../../testsrc/org/aspectj/tools/ant/taskdefs/AjcTaskTest.java">
         AjcTaskTest.java</a>.


<h3>Sample procedure</h3>
This shows how to set up the test and check whether
the incremental tag file and resource-copying features work.
Throughout, <code>{ant}</code> is assumed to be
<code>../../../lib/ant/bin/ant</code> and the directory
is assumed to be this directory, with the Ant build script
<a href="incTest.xml">incTest.xml</a>.
The script uses the eclipse classpath rather than aspectjtools.jar,
so that updates to the sources can be tested without
rebuilding the distribution.

<ol>
<li>Set up the output jars
<pre>  {ant} -f incTest.xml setup</pre>
    This should produce <code>one.jar</code> and <code>two.jar</code>
    in the directory <a href="injars">injars/</a>.
    <p>
    </li>
    
<li>Start the run with the default settings 
  (use <code>output/tagfile.txt</code> as the tag file
  and to include the non-.class contents of the input jars
  in the output jar):
<pre>  {ant} -f incTest.xml test</pre>
The task will do an initial compilation and silently wait.
    <p>
    </li>
<li>In another shell, test the classes in the generated output jar:
<pre>  export CLASSPATH="../../../lib/test/aspectjrt.jar;output/outjar.jar"
  java packageOne.Main</pre>
	Inspect the files in the <a href="src">src/</a> and 
	<a href="injarSrc">injarSrc/</a> directories to find other
	main classes and to determine the expected result of the aspect.
	As of this writing,  
    the aspect <a href="src/TraceMains.java">src/TraceMains.java</a>
	should emit messages before and after
	the execution of any static main(String[]) method.
    <p>
    </li>
<li>Check that the output jar got the injar and src files:

<pre>  jar tf output/outjar.jar</pre>
    <p>
    The output should list the 
    non-.class files in <a href="injarSrc">injarSrc/</a>
    and the non CVS/.java files in the <a href="src">src/</a> dir.
	<p>
    </li>
<li>To test incremental compiles,
    edit the aspect <a href="src/TraceMains.java">src/TraceMains.java</a>
    to modify the behavior.  You can also modify the input jars or
    source files.
    Then touch or edit <a href="output/tagfile.txt">output/tagfile.txt</a>
    to provoke recompilation.
    <p>
    </li>
<li>Test the generated output jar again
    to see if the changes are reflected in the runtime behavior
    and if files are being copied correctly.
    <p>
    </li>
<li>Repeat this process until satisfied.  Delete the tagfile to quit:
<pre>  rm output/tagfile.txt</pre>
    <p>
    </li>
<li>Also run the targets <code>test-all</code>
and <code>test-both</code>.
    <p>
    </li>
</ol>

Many combination of the option variants are possible.
Test the relevant ones by editing the 
<a href="incTest.xml">incTest.xml</a> script 
and redoing the test.
<p>
<table cellpadding="1" border="1">
<tr><th>Option</th><th>Variants</th></tr>
<tr><td>incremental</td><td>none, -incremental, -tagFile</td></tr>
<tr><td>output</td><td>none (default "."), destDir, output jar</td></tr>
<tr><td>injars</td><td>none, one, two</td></tr>
<tr><td>injar copying</td><td>off (default), on</td></tr>
<tr><td>source resource copying</td><td>off (default), various patterns</td></tr>
</table>

<p>

<h3>Clean-up</h3>
Take care to preserve CVS state after running this test.
It calls on you to edit checked-in files and generates files
to local repository directories.  The best thing is to delete
the <code>output</code> and <code>injars</code> directories
(using the <code>clean</code> task)
and revert to repository forms for sources (unless fixing them).

<h3>Upgrade</h3>
This needs to be upgraded to run automatically.
There is a file/tree-comparison utility to revive from the
aspectj-attic which can be used to compare expected and actual
results of the jar files.  Setting up the tasks to run incrementally
might be done using the parallel task, but...
<p>
In any case, the nested options tested here should move
to non-incremental JUnit tests.
<p>
<hr>
</body>
</html>