1 files changed, 58 insertions, 0 deletions
diff --git a/docs/sandbox/trails/debugging.html b/docs/sandbox/trails/debugging.html
new file mode 100644
index 000000000..3c6bbcfab
--- /dev/null
+++ b/docs/sandbox/trails/debugging.html
@@ -0,0 +1,58 @@
+<html>
+<title>Debugging AspectJ Programs
+</title>
+<body>
+<h2>Debugging AspectJ Programs
+</h2>
+<!-- @author Wes Isberg -->
+<!-- START-SAMPLE trails-debugging-aspectj10 -->
+<h3>Debugging AspectJ 1.0 Programs
+</h3>
+The AspectJ 1.0 compiler produces .class files that have the
+normal source file attribute and line information as well
+as the information specified by JSR-045 required to debug
+.class files composed of multiple source files.  
+This permits the compiler to inline advice code 
+into the .class files of the target classes; 
+the advice code in the target class can have source 
+attributes that point back to the aspect file.
+
+<p>
+Support for JSR-45 varies.
+At the time of this writing, Sun's VM supports it, 
+but not some others, which means that the Sun VM
+must be used as the runtime VM.
+
+Because the VM does all the work of associating the
+source line with the code being debugged,
+debuggers should be able to operate normally with
+AspectJ 1.0 source files even if they weren't written
+with that in mind, if they use the correct
+API's to the debugger.  Unfortunately, some debuggers
+take shortcuts based on the default case of one file
+per class in order to avoid having the VM calculate
+the file suffix or package prefix.  These debuggers
+do not support JSR-45 and thus AspectJ.
+
+<!-- END-SAMPLE trails-debugging-aspectj10 -->
+
+<!-- @author Wes Isberg -->
+<!-- START-SAMPLE trails-debugging-aspectj11 -->
+<h3>Debugging AspectJ 1.1 Programs
+</h3>
+The AspectJ 1.1 compiler usually implements advice as 
+call-backs to the aspect, which means that most
+AspectJ programs do not require JSR-45 support in
+order to be debugged.  However, it does do a limited
+amount of advice inlining; to avoid this, use the
+<code>-XnoInline</code> flag.
+<p>
+Because inlined advice can be more efficient, we
+plan to support JSR-45 as soon as feasible. 
+This will require upgrading the BCEL library we
+use to pass around the correct source attributes.
+
+<!-- END-SAMPLE trails-debugging-aspectj11 -->
+
+</body>
+</html>