aboutsummaryrefslogtreecommitdiffstats
path: root/docs
diff options
context:
space:
mode:
authorwisberg <wisberg>2006-03-03 10:17:58 +0000
committerwisberg <wisberg>2006-03-03 10:17:58 +0000
commit741181e71756adc5cad84a09b6f55ca945171feb (patch)
treee1162653a96f4c04093ae9621954d7a20016374a /docs
parent0748a02f3e581dcff1c70f3f82e935871d2a36a9 (diff)
downloadaspectj-741181e71756adc5cad84a09b6f55ca945171feb.tar.gz
aspectj-741181e71756adc5cad84a09b6f55ca945171feb.zip
warn about duplicate sources, convert exampled to -inpath, corrected -inpath aspects and argument file descriptions, linked out to affected types and load-time weaving, deprecated -emacsym as untested/unsupported. Leaving -messageHolder undocumented (Adrian's choice, if I recall correctly - not sure why)
Diffstat (limited to 'docs')
-rw-r--r--docs/devGuideDB/ajc.xml100
1 files changed, 56 insertions, 44 deletions
diff --git a/docs/devGuideDB/ajc.xml b/docs/devGuideDB/ajc.xml
index a9d21962c..1f1623577 100644
--- a/docs/devGuideDB/ajc.xml
+++ b/docs/devGuideDB/ajc.xml
@@ -19,38 +19,40 @@
<refsect1 id="ajc" xreflabel="ajc">
<title>Description</title>
- <para>The <command>ajc</command> command compiles AspectJ and Java
- language files, weaving aspects as necessary to produce .class files
- compliant with any Java VM (1.1 or later).
- To do bytecode weaving, it also accepts input classes or aspects
- in binary form.
+ <para>The <command>ajc</command> command compiles and weaves AspectJ and
+ Java source and .class files, producing .class files compliant with any
+ Java VM (1.1 or later). It combines compilation and bytecode weaving
+ and supports incremental builds; you can also weave bytecode
+ at run-time using <xref linkend="ltw"/>.
</para>
<para> The arguments after the options specify the source file(s) to compile.
- (Specify source classes using the <parameter>-injars</parameter> or
- <parameter>-inpath</parameter> options, below.)
- Files may be listed directly on the command line, or listed in a file.
+ To specify source classes, use <parameter>-inpath</parameter> (below).
+ Files may be listed directly on the command line or in a file.
The <parameter>-argfile <replaceable>file</replaceable></parameter>
and <parameter>@<replaceable>file</replaceable></parameter> forms
- are equivalent, and are interpreted as meaning all the files listed in
- the specified file. Each line in these files should contain one option
- or filename. Comments, as in Java, start with <literal>//</literal> and
- extend to the end of the line.
+ are equivalent, and are interpreted as meaning all the arguments
+ listed in the specified file.
</para>
<para>
- <command>NB:</command>
- You must explicitly pass <command>ajc</command> all sources necessary
- for the compilation. When compiling source files containing aspects
- or pointcuts, be sure
- to include the source files for any types affected by the aspects or
- picked out by the pointcuts.
- (To exclude types from the scope affected by the aspect,
- change the corresponding pointcut or declaration.)
- This is necessary because, unlike javac, ajc does not search the
- sourcepath for classes.
- You may use the <parameter>-sourceroots</parameter> option to specify
- as source all the .aj and .java files in a set of directory trees.
+ <command>Note:</command>
+ You must explicitly pass <command>ajc</command> all necessary sources.
+ Be sure to include the source not only for the
+ aspects or pointcuts but also for any affected types.
+ Specifying all sources is necessary because, unlike javac, ajc does not
+ search the sourcepath for classes.
+ (For a discussion of what affected types might be required,
+ see <ulink url="../progguide/implementation.html">The AspectJ
+ Programming Guide, Implementation Appendix</ulink>.)
+ <para>
+ </para>
+ To specify sources, you can list source files as arguments or use the
+ options <parameter>-sourceroots</parameter> or <parameter>-inpath</parameter>.
+ If there are multiple sources for any type, the result is undefined
+ since ajc has no way to determine which source is correct. (This
+ happens most often when users include the destination directory
+ on the inpath and rebuild.)
</para>
<refsect2>
@@ -82,11 +84,11 @@
<varlistentry>
<term>-aspectpath <replaceable>Path</replaceable></term>
<listitem><para>
- Weave binary aspects from Jars and directories on path into all sources.
+ Weave binary aspects from jar files and directories on path into all sources.
The aspects should have been output by the same version
of the compiler.
- To run the output classes requires putting all the
- aspectpath entries on the run classpath.
+ When running the output classes, the run classpath should contain
+ all aspectpath entries.
Path, like classpath, is a single argument containing
a list of paths to jar files, delimited by the platform-
specific classpath delimiter.
@@ -96,9 +98,20 @@
<varlistentry>
<term>-argfile <replaceable>File</replaceable></term>
<listitem><para>
- The file is a line-delimited list of arguments.
- These arguments are inserted into the argument list.
- </para></listitem>
+ The file contains a line-delimited list of arguments.
+ Each line in the file should contain one option, filename, or
+ argument string (e.g., a classpath or inpath).
+ Arguments read from the file are inserted into the argument list
+ for the command. Relative paths in the file are calculated from
+ the directory containing the file (not the current working directory).
+ Comments, as in Java, start with <literal>//</literal> and
+ extend to the end of the line. Options specified in argument
+ files may override rather than extending existing option values,
+ so avoid specifying options like <replaceable>-classpath</replaceable>
+ in argument files unlike the argument file is the only build
+ specification. The form <replaceable>@file</replaceable> is the same
+ as specifying <replaceable>-argfile file</replaceable>.
+ </para></listitem>
</varlistentry>
<varlistentry>
@@ -155,7 +168,7 @@
<varlistentry>
<term>-emacssym</term>
<listitem><para>
- Generate .ajesym symbol files for emacs support
+ Generate .ajesym symbol files for emacs support (deprecated).
</para></listitem>
</varlistentry>
@@ -244,8 +257,8 @@
</varlistentry>
<varlistentry>
- <term>-target <replaceable>[1.1 to 1.4]</replaceable></term>
- <listitem><para>Specify classfile target setting (1.1 to 1.4, default is 1.2)
+ <term>-target <replaceable>[1.1 to 1.5]</replaceable></term>
+ <listitem><para>Specify classfile target setting (1.1 to 1.5, default is 1.2)
</para></listitem>
</varlistentry>
@@ -415,7 +428,8 @@
<varlistentry>
<term>-Xnoweave</term>
<listitem><para>(Experimental) produce unwoven class files
- for input using -injars.
+ for input using -injars. (deprecated - .class files are by
+ default reweavable and can be input using -inpath.)
</para></listitem>
</varlistentry>
@@ -580,18 +594,16 @@ ajc @sources.lst</programlisting>
</example>
<example id="examplebytecode">
- <title>An example using -injars and -aspectpath</title>
- <para>Bytecode weaving using -injars:
- AspectJ 1.1 supports weaving from input zip or jar files containing
- class files. Using input jars is like compiling the corresponding
+ <title>An example using -inpath and -aspectpath</title>
+ <para>Bytecode weaving using -inpath:
+ AspectJ 1.2 supports weaving .class files in input zip/jar files
+ and directories.
+ Using input jars is like compiling the corresponding
source files, and all binaries are emitted to output. Although
Java-compliant compilers may differ in their output, ajc should
take as input any class files produced by javac, jikes, eclipse,
- and, of course, ajc. Aspects included in -injars will be woven into
- like other .class files, but they will specify any crosscutting
- code (i.e., they will not be woven into other types). To use
- aspects in their binary form to specify crosscutting,
- see -aspectpath below.
+ and, of course, ajc. Aspects included in -inpath will be woven into
+ like other .class files, and they will affect other types as usual.
</para>
<para>Aspect libraries using -aspectpath:
AspectJ 1.1 supports weaving from read-only libraries containing
@@ -674,7 +686,7 @@ commands to your environment as needed.
<listitem><para>
(b) Build the application with tracing:</para>
<programlisting>
- ajc -injars app.jar -aspectpath tracelib.jar -outjar tracedapp.jar
+ ajc -inpath app.jar -aspectpath tracelib.jar -outjar tracedapp.jar
</programlisting>
</listitem></itemizedlist>