ajc(1)

General Commands Manual

ajc(1)

NAME
ajc compiler and bytecode weaver for the AspectJ and Java languages
SYNOPSIS
ajc [Options] [file... | @file... | -argfile file... ]
Description
The ajc 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 b
ytecode weaving and supports
incremental builds; you can also weave bytecode at run-time using "" >.
The arguments after the options specify the source file(s) to compile. T
o specify source classes, use
-inpath (below). Files may be listed directly on the command line or in
a file. The -argfile file
and @file forms are equivalent, and are interpreted as meaning all the a
rguments listed in the speci
fied file.
Note: You must explicitly pass ajc all necessary sources. Be sure to inc
lude the source not only for
the aspects or pointcuts but also for any affected types. Specif
ying 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 The AspectJ Programming Guide, Imp
lementation Appendix ../prog
guide/implementation.html) .
To specify sources, you can list source files as arguments or use the opt
ions -sourceroots or -inpath.
If there are multiple sources for any type, the result is undefined sinc
e 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.)
Options
-injars JarList
deprecated: since 1.2, use -inpath, which also takes directorie
s.
-inpath Path
Accept as source bytecode any .class files in the The outpu
t will include these classes,
possibly as woven with any applicable aspects. Path is a singl
e argument containing a list
of paths to zip files or directories, delimited by the platform

-specific path delimiter.

-aspectpath Path
Weave binary aspects from jar files and directories on path i
nto all sources. The aspects
should have been output by the same version of the compiler.
When running the output
classes, the run classpath should contain all aspectpath entri
es. Path, like classpath, is
a single argument containing a list of paths to jar files, deli
mited by the platform- spe
cific classpath delimiter.
-argfile File
The file contains a line-delimited list of arguments. Each li
ne 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 // and extend to the end of th
e line. Options specified in
argument files may override rather than extending existing opti
on values, so avoid specify
ing options like -classpath
in argument files unlike
the argument file is the only
build specification. The form @file is the same as specifying
-argfile file.
-outjar output.jar
Put output classes in zip file output.jar.
-outxml

Generate aop.xml file for load-time weaving with default name.

-outxmlfile custom/aop.xml
Generate aop.xml file for load-time weaving with custom name.
-incremental
Run the compiler continuously. After the initial compilation,
the compiler will wait to
recompile until it reads a newline from the standard input,
and will quit when it reads a
'q'. It will only recompile necessary components, so a recompi
le should be much faster than
doing a second compile. This requires -sourceroots.
-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 lis
t of paths to directories,

delimited by the platform- specific classpath delimiter. Requi

red by -incremental.
-crossrefs
Generate a build .ajsym file into the output directory. Used
for viewing crosscutting ref
erences by tools like the AspectJ Browser.
-emacssym Generate .ajesym symbol files for emacs support (deprecated).
-Xlint

Same as -Xlint:warning (enabled by default)

-Xlint:{level}
Set default level for messages about potential programming mist
akes in crosscutting code.
{level}
may
be
ignore,
warning, or error.
Th
is overrides entries in
org/aspectj/weaver/XlintDefault.properties from aspectjtools.ja
r, but does not override lev
els set using the -Xlintfile option.
-Xlintfile PropertyFile
Specify properties file to set levels for specific crosscutting
messages. PropertyFile is a
path to a Java .properties file that takes the same pro
perty names and values as
org/aspectj/weaver/XlintDefault.properties from aspectjtools.ja
r, which it also overrides.
-help

Emit information on compiler options and usage

-version Emit the version of the AspectJ compiler

-classpath Path
Specify where to find user class files. Path is a single
argument containing a list of
paths to zip files or directories, delimited by the platform-sp
ecific path delimiter.
-bootclasspath Path
Override location of VM's bootclasspath for purposes of evalua
ting types when compiling.
Path is a single argument containing a list of paths to zip fi
les or directories, delimited
by the platform-specific path delimiter.
-extdirs Path
Override location of VM's extension directories for purposes of
evaluating types when com
piling. Path is a single argument containing a list of paths

to directories, delimited by
the platform-specific path delimiter.
-d Directory
Specify where to place generated .class files. If not specifie
d, Directory defaults to the
current working dir.
-target [1.1 to 1.5]
Specify classfile target setting (1.1 to 1.5, default is 1.2)
-1.3

Set compliance level to 1.3 This implies -source 1.3 and -targe

t 1.1.
-1.4
Set compliance level to 1.4 (default) This implies -source 1.4
and -target 1.2.
-1.5
get 1.5.

Set compliance level to 1.5. This implies -source 1.5 and -tar

-source [1.3|1.4|1.5]
Toggle assertions (1.3, 1.4, or 1.5 - default is 1.4). When u
sing -source 1.3, an assert()
statement valid under Java 1.4 will result in a compiler error.
When using -source 1.4,
treat assert as a keyword and implement assertions according to
the 1.4 language spec. When
using -source 1.5, Java 5 language features are permitted.
-nowarn Emit no warnings (equivalent to '-warn:none') This does not sup
press messages generated by
declare warning or Xlint.
-warn: items
Emit warnings for any instances of the comma-delimited
list of questionable code (eg
'-warn:unusedLocals,deprecation'):
constructorName
packageDefaultMethod
deprecation
maskedCatchBlocks
unusedLocals
unusedArguments
unusedImports
none

method with constructor name

attempt to override package-default method
usage of deprecated type or member
hidden catch block
local variable never read
method argument never read
import statement not used by code in file
suppress all compiler warnings

-warn:none does not suppress messages generated by declare warning or Xli

nt.

-deprecation
Same as -warn:deprecation
-noImportError
Emit no errors for unresolved imports
-proceedOnError
Keep compiling after error, dumping class files with problem me
thods
-g:[lines,vars,source]
debug attributes level, that may take three forms:
-g
all debug info ('-g:lines,vars,source')
-g:none
no debug info
-g:{items} debug info for any/all of [lines, vars, source], e.g.,
-g:lines,source
-preserveAllLocals
Preserve all local variables during code generation (to facilit
ate debugging).
-referenceInfo
Compute reference information.
-encoding format
Specify default source encoding format. Specify custom encodin
g on a per file basis by suf
fixing each input source file/folder name with '[encoding]'.
-verbose Emit messages about accessed/processed compilation units
-showWeaveInfo
Emit messages about weaving
-log file Specify a log file for compiler messages.
-progress Show progress (requires -log mode).

or)

-time

Display speed information.

-noExit

Do not call System.exit(n) at end of compilation (n=0 if no err

-repeat N Repeat compilation process N times (typically to do performance

analysis).
-XterminateAfterCompilation
Causes compiler to terminate before weaving
-XaddSerialVersionUID
Causes the compiler to calculate and add the SerialVersionUID f
ield to any type implementing
Serializable that is affected by an aspect. The field is calc
ulated based on the class
before weaving has taken place.
-Xreweavable[:compress]
(Experimental - deprecated as now default) Runs weaver in rewea
vable mode which causes it to
create woven classes that can be rewoven, subject to the restri
ction that on attempting a
reweave all the types that advised the woven type must be acces
sible.
-XnoInline
(Experimental) do not inline around advice
-XincrementalFile file
(Experimental) This works like incremental mode, but using a fi
le rather than standard input
to control the compiler. It will recompile each time file is c
hanged and and halt when file
is deleted.
-XserializableAspects
(Experimental) Normally it is an error to declare aspects Seria
lizable. This option removes
that restriction.
-XnotReweavable
(Experimental) Create class files that can't be subsequently re
woven by AspectJ.
-Xajruntimelevel:1.2, ajruntimelevel:1.5
(Experimental) Allows code to be generated that targets a 1.2 o
r a 1.5 level AspectJ runtime
(default 1.5)
File names
ajc accepts source files with either the .java
extension or the .a
j extension. We normally use
.java for all of our files in an AspectJ system -- files that contain asp
ects as well as files that
contain classes. However, if you have a need to mechanically disting

uish files that use AspectJ's

additional functionality from those that are pure Java we recommend using
the .aj extension for those
files.
We'd like to discourage other means of mechanical distinction such as na
ming conventions or sub-pack
ages in favor of the .aj
extension.
Filename conventions are hard to enforce and lead to awkward names fo
r your aspects. Instead of
TracingAspect.java we recommend using Tracing.aj (or just Tracing.j
ava) instead.
Sub-packages move aspects out of their natural place in a system a
nd can create an artificial
need for privileged aspects. Instead of adding a sub-package like
aspects we recommend using
the .aj extension and including these files in your existing packag
es instead.
Compatibility
AspectJ is a compatible extension to the Java programming language. Th
e AspectJ compiler adheres to
the
The
Java
Language
Specfication,
Second
Edition
(BOOK)
http://java.sun.com/docs/books/jls/index.html and to the The Java Virtua
l Machine Specification, Sec
ond Edition (BOOK) http://java.sun.com/docs/books/vmspec/index.html and
runs on any Java 2 compatible
platform. The code it generates runs on any Java 1.1 or later compatible
platform. For more informa
tion on compatibility with Java and with previous releases of AspectJ, se
e "" >.
Examples
A simple example
Compile two files:
ajc HelloWorld.java Trace.java
An example using -argfile/@
To avoid specifying file names on the command line, list source files
in a line-delimited text
argfile. Source file paths may be absolute or relative to the argfile, a
nd may include other argfiles
by @-reference. The following file sources.lst
contains absolu
te and relative files and
@-references:
Gui.java
/home/user/src/Library.java
data/Repository.java
data/Access.java
@../../common/common.lst

@/home/user/src/lib.lst
view/body/ArrayView.java
Compile the files using either the -argfile or @ form:
ajc -argfile sources.lst
ajc @sources.lst
Argfiles are also supported by jikes and javac, so you can use the file
s in hybrid builds. However,
the support varies:
Only ajc accepts command-line options
Jikes and Javac do not accept internal @argfile references.
Jikes and Javac only accept the @file form on the command line.
An example using -inpath and -aspectpath
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 sourc
e 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 cour
se, ajc. Aspects included in
-inpath will be woven into like other .class files, and they will affect
other types as usual.
Aspect libraries using -aspectpath: AspectJ 1.1 supports weaving from rea
d-only libraries containing
aspects. Like input jars, they affect all input; unlike input jars, the
y themselves are not affected
or emitted as output. Sources compiled with aspect libraries must be
run with the same aspect
libraries on their classpath.
The following example builds the tracing example in a command-line enviro
nment; it creates a read-only
aspect library, compiles some classes for use as input bytecode, and comp
iles the classes and other
sources with the aspect library.
The tracing example is in the AspectJ distribution ({aspectj}/doc/exam
ples/tracing). This uses the
following files:
aspectj1.1/
bin/
ajc
lib/
aspectjrt.jar

examples/
tracing/
Circle.java
ExampleMain.java
lib/
AbstractTrace.java
TraceMyClasses.java
notrace.lst
Square.java
tracelib.lst
tracev3.lst
TwoDShape.java
version3/
Trace.java
TraceMyClasses.java
Below, the path separator is taken as ";", but file separators are "/".
All commands are on one line.
Adjust paths and commands to your environment as needed.
Setup the path, classpath, and current directory:
cd examples
export ajrt=../lib/aspectjrt.jar
export CLASSPATH="$ajrt"
export PATH="../bin:$PATH"
Build a read-only tracing library:
ajc -argfile tracing/tracelib.lst -outjar tracelib.jar
Build the application with tracing in one step:
ajc -aspectpath tracelib.jar -argfile tracing/notrace.lst -outjar traceda
pp.jar
Run the application with tracing:
java -classpath "$ajrt;tracedapp.jar;tracelib.jar" tracing.ExampleMain
Build the application with tracing from binaries in two steps:
(a) Build the application classes (using javac for demonstration's sa
ke):
mkdir classes
javac -d classes tracing/*.java
jar cfM app.jar -C classes .
(b) Build the application with tracing:
ajc -inpath app.jar -aspectpath tracelib.jar -outjar tracedapp.jar

Run the application with tracing (same as above):

java -classpath "$ajrt;tracedapp.jar;tracelib.jar" tracing.ExampleMain
Run the application without tracing:
java -classpath "app.jar" tracing.ExampleMain
The AspectJ compiler API
The AspectJ compiler is implemented completely in Java and can be call
ed as a Java class. The only
interface that should be considered public are the public methods in
org.aspectj.tools.ajc.Main.
E.g., main(String[] args) takes the the standard ajc command line a
rguments. This means that an
alternative way to run the compiler is
java org.aspectj.tools.ajc.Main [option...] [file...]
To access compiler messages programmatically, use the methods setHolder(I
MessageHolder holder) and/or
run(String[] args, IMessageHolder holder). ajc reports each message
to the holder using IMessage
Holder.handleMessage(..). If you just want to collect the messag
es, use MessageHandler as
your
IMessageHolder. For example, compile and run the following
with aspectjtools.jar on the
classpath:
import org.aspectj.bridge.*;
import org.aspectj.tools.ajc.Main;
import java.util.Arrays;
public class WrapAjc {
public static void main(String[] args) {
Main compiler = new Main();
MessageHandler m = new MessageHandler();
compiler.run(args, m);
IMessage[] ms = m.getMessages(null, true);
System.out.println("messages: " + Arrays.asList(ms));
}
}
Stack Traces and the SourceFile attribute
Unlike traditional java compilers, the AspectJ compiler may in certain ca
ses generate classfiles from
multiple source files. Unfortunately, the original Java class file for
mat does not support multiple
SourceFile attributes. In order to make sure all source file information
is available, the AspectJ
compiler may in some cases encode multiple filenames in the SourceFile
attribute. When the Java VM
generates stack traces, it uses this attribute to specify the source file
.

(The AspectJ 1.0 compiler also supports the .class file extensions of JSR
-45. These permit compliant
debuggers (such as jdb in Java 1.4.1) to identify the right file and line
even given many source files
for a single class. JSR-45 support is planned for ajc in AspectJ 1.1, b
ut is not in the initial
release. To get fully debuggable .class files, use the -XnoInline option
.)
Probably the only time you may see this format is when you view stack tr
aces, where you may encounter
traces of the format
java.lang.NullPointerException
at Main.new$constructor_call37(Main.java;SynchAspect.java[1k]:1030)
where instead of the usual
File:LineNumber
format, you see
File0;File1[Number1];File2[Number2] ... :LineNumber
In this case, LineNumber is the usual offset in lines plus the "start lin
e" of the actual source file.
That means you use LineNumber both to identify the source file and to
find the line at issue. The
number in [brackets] after each file tells you the virtual "start line" f
or that file (the first file
has a start of 0).
In our example from the null pointer exception trace, the virtual start
line is 1030. Since the file
SynchAspect.java "starts" at line 1000 [1k], the LineNumber points to lin
e 30 of SynchAspect.java.
So, when faced with such stack traces, the way to find the actual source
location is to look through
the list of "start line" numbers to find the one just under the shown l
ine number. That is the file
where the source location can actually be found. Then, subtract that "st
art line" from the shown line
number to find the actual line number within that file.
In a class file that comes from only a single source file, the AspectJ
compiler generates SourceFile
attributes consistent with traditional Java compilers.

ajc(1)