aboutsummaryrefslogtreecommitdiffstats
path: root/docs
diff options
context:
space:
mode:
authorAlexander Kriegisch <Alexander@Kriegisch.name>2024-02-22 10:20:45 +0700
committerAlexander Kriegisch <Alexander@Kriegisch.name>2024-02-22 10:28:03 +0700
commit38e175b1575649d690a95994e1b5b812cec1cdda (patch)
treeab383cf1e87ea5ecfc7ad0c0a6b9fdd16ffdfa1b /docs
parentfac5d8cb222719cddfc169d5285d918557b786c5 (diff)
downloadaspectj-38e175b1575649d690a95994e1b5b812cec1cdda.tar.gz
aspectj-38e175b1575649d690a95994e1b5b812cec1cdda.zip
Document AJC option '-xmlConfigured'
- Add short description to AJC usage message via messages_aspectj.properties - Add longer description to ajc.adoc in the AspectJ Development Environment Guide Closes https://bugs.eclipse.org/bugs/show_bug.cgi?id=455014. Signed-off-by: Alexander Kriegisch <Alexander@Kriegisch.name>
Diffstat (limited to 'docs')
-rw-r--r--docs/devguide/ajc.adoc43
1 files changed, 41 insertions, 2 deletions
diff --git a/docs/devguide/ajc.adoc b/docs/devguide/ajc.adoc
index 5e47018e1..ea482aed6 100644
--- a/docs/devguide/ajc.adoc
+++ b/docs/devguide/ajc.adoc
@@ -82,8 +82,47 @@ destination directory on the inpath and rebuild.)
`-sourceroots <DirPaths>`::
Find and build all .java or .aj source files under any directory
listed in DirPaths. DirPaths, like classpath, is a single argument
- containing a list of paths to directories, delimited by the platform-
- specific classpath delimiter. Required by -incremental.
+ containing a list of paths to directories, delimited by the platform-specific
+ classpath delimiter. Required by `-incremental`.
+`-xmlConfig <files>`::
+ Configure the weaving process, if you wish to impose non-standard limitations, e.g.
+ a list of aspects to use (if not all), global and per-aspect scopes for the weaver
+ (target packages and classes to exclude or include). This option also needs an .xml
+ file on the command line, optionally multiple ones to be logically merged into one
+ weaver configuration. Example:
++
+[source, xml]
+....
+<aspectj>
+ <!-- From all aspects found, only use the ones listed here -->
+ <aspects>
+ <!-- Only weave class org.acme.app.B -->
+ <aspect name="a.b.FooAspect" scope="org.acme.app.B"/>
+ <!-- Only weave classes in package orc.acme and its sub-packages -->
+ <aspect name="c.d.BarAspect" scope="orc.acme..*"/>
+ <!-- Weave all classes, unless globally excluded -->
+ <aspect name="e.f.ZotAspect"/>
+ </aspects>
+ <weaver>
+ <!-- Globally exclude classes in package org.acme.internal and its sub-packages from weaving -->
+ <exclude within="org.acme.internal..*"/>
+ <!-- This has **no effect**, use per-aspect scopes instead -->
+ <include within="com.xyz..*"/>
+ </weaver>
+</aspectj>
+....
+Please note that `-xmlConfigured` only supports a subset of options available to
+load-time weaving configuration by _aop.xml_. Current limitations include:
+ * There is **no magical file name** like _aop.xml_ for the load-time weaver,
+ i.e. an XML configuration file for the compiler needs to be listed explicitly
+ on the command line.
+ * Scopes and excludes only affect method interception pointcuts, not ITDs.
+ The latter will always be applied and are unaffected by XML configuration.
+ * There is no global `<include within="..."/>` (see example above).
+ * Lists in aspect scope expressions are not supported, i.e. an expression like
+ `scope="A,B,C"` will be treated like `scope="A"`, using only the first element.
+ * If you want to apply a scope to an aspect extending an abstract base aspect,
+ you need to list and scope both aspects in the XML file.
`-crossrefs`::
Generate a build .ajsym file into the output directory. Used for
viewing crosscutting references by tools like the AspectJ Browser.