Rename '*GuideDB' directories to their actual HTML site target names

Signed-off-by: Alexander Kriegisch <Alexander@Kriegisch.name>

1 files changed, 127 insertions, 0 deletions

diff --git a/docs/devguide/tools-intro.adoc b/docs/devguide/tools-intro.adoc
new file mode 100644
index 000000000..329378b2a
--- /dev/null
+++ b/docs/devguide/tools-intro.adoc
@@ -0,0 +1,127 @@
+[[tools-intro]]
+== Introduction to the AspectJ tools
+
+[[eclipse-aspectj]]
+=== The Eclipse AspectJ implementation
+
+The xref:../progguide/index.html[AspectJ Programming Guide] describes
+the AspectJ language. This guide describes the AspectJ tools produced by
+the AspectJ team on https://eclipse.org/aspectj. The AspectJ tools
+include - ajc, the compiler/weaver; ajdoc, a documentation tool;
+ajbrowser, a crosscutting code viewer; Ant support for ajc; and
+load-time weaving support. These tools are delivered in the library
+folder of the AspectJ tools installation, mainly in `aspectjtools.jar`
+(tools) and `aspectjrt.jar` (runtime). This guide does not describe the
+Eclipse AspectJ development tools (AJDT). That is produced by another
+team (sharing some members) on
+https://eclipse.org/aspectj[https://eclipse.org/ajdt]. AJDT is delivered
+as an Eclipse plugin, incorporating the classes in the AspectJ tools
+libraries along with the Eclipse plugin interface classes.
+
+Since AspectJ 1.1, the tools have implemented the AspectJ language using
+bytecode weaving, which combines aspects and classes to produce .class
+files that run in a Java VM. There are other ways to implement the
+language (e.g., compiler preprocessor, VM support); the AspectJ team has
+always tried to distinguish the language and the implementation so other
+groups could build alternative implementations of AspectJ. To that end,
+xref:../progguide/implementation.html[The AspectJ Programming Guide,
+Implementation Notes] describes how the Java bytecode form affects
+language semantics. VM- or source-based implementations may be free of
+these limits or impose limits of their own, but most should be fairly
+close to what's possible in Java bytecode.
+
+Please be careful not to confuse any description of weaving or of this
+implementation of the AspectJ language with the AspectJ language
+semantics. If you do, you might find yourself writing code that doesn't
+work as expected when you compile or run it on other systems. More
+importantly, if you think about aspects in terms of weaving or of
+inserting or merging code, then you can lose many of the design benefits
+of thinking about an aspect as a single crosscutting module. When the
+text below introduces an implementation detail, it will warn if users
+make mistakes by applying it in lieu of the language semantics.
+
+[[bytecode-concepts]]
+=== Bytecode weaving, incremental compilation, and memory usage
+
+Bytecode weaving takes classes and aspects in .class form and weaves
+them together to produce binary-compatible .class files that run in any
+Java VM and implement the AspectJ semantics. This process supports not
+only the compiler but also IDE's. The compiler, given an aspect in
+source form, produces a binary aspect and runs the weaver. IDE's can get
+information about crosscutting in the program by subscribing to
+information produced by weaver as a side-effect of weaving.
+
+Incremental compilation involves recompiling only what is necessary to
+bring the binary form of a program up-to-date with the source form in
+the shortest time possible. Incremental weaving supports this by weaving
+on a per-class basis. (Some implementations of AOP (including AspectJ
+1.0) make use of whole-program analysis that can't be done in
+incremental mode.) Weaving per-class means that if the source for a pure
+Java class is updated, only that class needs to be produced. However, if
+some crosscutting specification may have been updated, then all code
+potentially affected by it may need to be woven. The AspectJ tools are
+getting better at minimizing this effect, but it is to some degree
+unavoidable due to the crosscutting semantics.
+
+Memory usage can seem higher with AspectJ tools. Some aspects are
+written to potentially affect many classes, so each class must be
+checked during the process of weaving. Programmers can minimize this by
+writing the crosscutting specifications as narrowly as possible while
+maintaining correctness. (While it may seem like more memory, the proper
+comparison would with with a Java program that had the same
+crosscutting, with changes made to each code segment. That would likely
+require more memory and more time to recompile than the corresponding
+AspectJ program.)
+
+[[classpathInpathAndAspectpath]]
+==== Classpath, inpath, and aspectpath
+
+AspectJ introduces two new paths for the binary input to the weaver
+which you'll find referenced in xref:ajc.adoc[`ajc`, the AspectJ compiler/weaver],
+xref:ajbrowser.adoc#ajbrowser[AspectJ Browser], xref:antsupport.adoc[AspectJ Ant Tasks], and xref:ltw.adoc#ltw[Load-Time Weaving].
+
+As in Java, the `classpath` is where the AspectJ tools resolve types
+specified in the program. When running an AspectJ program, the classpath
+should contain the classes and aspects along with the AspectJ runtime
+library, `aspectjrt.jar`.
+
+In AspectJ tools, the `aspectpath` is where to find binary aspects. Like
+the classpath, it can include archives (.jar and .zip files) and
+directories containing .class files in a package layout (since binary
+aspects are in .class files). These aspects affect other classes in
+exactly the same way as source-level aspects, but are themselves not
+affected. When deploying programs, the original aspects must be included
+on the runtime classpath.
+
+In AspectJ tools, the `inpath` is where to find binary input - aspects
+and classes that weave and may be woven. Like the classpath, it can
+include archives and class directories. Like the aspectpath, it can
+include aspects that affect other classes and aspects. However, unlike
+the aspectpath, an aspect on the inpath may itself be affected by
+aspects, as if the source were all compiled together. When deploying
+aspects that were put on the inpath, only the woven output should be on
+the runtime classpath.
+
+Although types in the inpath and the aspectpath need to be resolved by
+the AspectJ tools, you usually do not need to place them on the
+classpath because this is done automatically by the compiler/weaver. But
+when using the `WeavingURLClassLoader`, your code must explicitly add
+the aspects to the classpath so they can be resolved (as you'll see in
+the sample code and the `aj.bat` script).
+
+The most common mistake is failing to add `aspectjrt.jar` to the
+classpath. Also, when weaving with binary aspects, users forget to
+deploy the aspect itself along with any classes it requires. A more
+subtle mistake is putting a binary aspect (BA) on the inpath instead of
+the aspectpath. In this case the aspect BA might be affected by an
+aspect, even itself; this can cause the program to fail, e.g., when an
+aspect uses exclusion to avoid infinite recursion but fails to exclude
+advice in aspect BA.
+
+The latter is one of many ways that mistakes in the build process can
+affect aspects that are written poorly. Aspects should never rely on the
+boundaries of the build specification to narrow the scope of their
+crosscutting, since the build can be changed without notice to the
+aspect developer. Careful users might even avoid relying on the
+implementation scope, to ensure their AspectJ code will run on other
+implementations.