123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557 |
- [[ajc]]
- = `ajc`, the AspectJ compiler/weaver
-
- == Name
-
- `ajc` - compiler and bytecode weaver for the AspectJ and Java languages
-
- == Synopsis
-
- [subs=+quotes]
- ajc [_option_...] [_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 bytecode weaving and supports incremental
- builds; you can also weave bytecode at run-time using xref:ltw.adoc#ltw[Load-Time Weaving].
-
- The arguments after the options specify the source file(s) to compile.
- To 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
- arguments listed in the specified file.
-
- `Note:` You must explicitly pass `ajc` 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
- xref:../progguide/implementation.adoc[The AspectJ Programming Guide,
- Implementation Appendix].)
-
- To specify sources, you can list source files as arguments or use the
- options `-sourceroots` or `-inpath`. 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.)
-
- [[ajc_options]]
- === Options
-
- `-injars <JarList>`::
- deprecated: since 1.2, use `-inpath`, which also takes directories.
- `-inpath <Path>`::
- Accept as source bytecode any .class files in the .jar files or
- directories on Path. The output will include these classes, possibly
- as woven with any applicable aspects. Path is a single 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 into 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 entries. Path, like classpath, is a
- single argument containing a list of paths to jar files, delimited by
- the platform-specific classpath delimiter.
- `-argfile <File>`::
- 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 `//` 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 `-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 recompile 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 list of paths to directories, delimited by the platform-specific
- classpath delimiter. Required by `-incremental`.
-
- `-xmlConfigured <files>`::
- +
- --
- Configure the compile-time weaving (CTW) 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.OneAspect" scope="org.acme.app.B"/>
- <!-- Only weave classes in package org.acme and its sub-packages -->
- <aspect name="c.d.TwoAspect" scope="org.acme..*"/>
- <!-- Weave all classes, unless globally excluded -->
- <aspect name="e.f.ThreeAspect"/>
- <!-- Weave all classes below org.acme.service, but not in the audit sub-package -->
- <aspect name="e.f.FourAspect" scope="org.acme.service..* AND !*..audit.*"/>
- <!-- Weave all controllers and services -->
- <aspect name="e.f.FiveAspect" scope="*..*Controller || *..*Service"/>
- </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` works similarly to load-time weaving (LTW) configuration with _aop.xml_, but not 100%
- identically:
-
- * There is **no magical file name** like _aop.xml_ for LTW, i.e. an XML configuration file for CTW needs to be
- specified on the command line explicitly.
- * In the `<weaver>` section, `<include within="..."/>` is ignored (see example above), because in CTW mode all
- classes the compiler can see are implicitly included in weaving, unless explicitly excluded.
-
- Limitations which apply to both LTW and CTW modes include:
-
- * Scopes and excludes only affect regular pointcuts (e.g. method interception), not ITDs. The latter will always be
- applied and are unaffected by XML configuration.
- * When using logical operators, you cannot write `&&` in XML. Instead, use `AND` as a replacement. The operators `||`
- and `!` can be used normally. Complex expressions like `(A||B||C) AND !D` are also permitted.
- * 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.
- `-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 mistakes in
- crosscutting code. `\{level}` may be `ignore`, `warning`, or `error`. This
- overrides entries in _org/aspectj/weaver/XlintDefault.properties_ from
- aspectjtools.jar, but does not override levels 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 property names and values as
- _org/aspectj/weaver/XlintDefault.properties_ from aspectjtools.jar,
- 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-specific path delimiter.
- `-bootclasspath <Path>`::
- Override location of VM's bootclasspath for purposes of evaluating
- types when compiling. Path is a single argument containing a list of
- paths to zip files or directories, delimited by the platform-specific
- path delimiter.
- `-extdirs <Path>`::
- Override location of VM's extension directories for purposes of
- evaluating types when compiling. 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 specified,
- <Directory> defaults to the current working dir.
-
- // AspectJ_JDK_Update: increment max. version and, if necessary, min. version
- `-source <[1.3 to 21]>`::
- Set source file Java language level
- `-target <[1.3 to 21]>`::
- Set classfile Java bytecode level
- `-<[1.3 to 21]>`::
- Set compiler compliance level. Implies identical `-source` and `-target` levels.
- E.g., `-11` implies `-source 11` and `-target 11`.
-
- `-nowarn`::
- Emit no warnings (equivalent to `-warn:none`) This does not suppress
- messages generated by `declare warning` or `Xlint`.
- `-warn: <items>`::
- Emit warnings for any instances of the comma-delimited list of
- questionable code (e.g. `-warn:unusedLocals,deprecation`):
- +
- [source, text]
- ....
- constructorName method with constructor name
- packageDefaultMethod attempt to override package-default method
- deprecation usage of deprecated type or member
- maskedCatchBlocks hidden catch block
- unusedLocals local variable never read
- unusedArguments method argument never read
- unusedImports import statement not used by code in file
- none suppress all compiler warnings
- ....
- +
- `-warn:none` does not suppress messages generated by `declare warning`
- or `Xlint`.
- `-deprecation`::
- Same as `-warn:deprecation`
- `-noImportError`::
- Emit no errors for unresolved imports
- `-proceedOnError`::
- Keep compiling after error, dumping class files with problem methods
- `-g<:[lines,vars,source]>`::
- debug attributes level, that may take three forms:
- +
- [source, text]
- ....
- -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 facilitate
- debugging).
- `-referenceInfo`::
- Compute reference information.
- `-encoding <format>`::
- Specify default source encoding format. Specify custom encoding on a
- per-file basis by suffixing 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).
- `-time`::
- Display speed information.
- `-noExit`::
- Do not call `System.exit(n)` at end of compilation (n=0 if no error)
- `-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 field to
- any type implementing Serializable that is affected by an aspect. The
- field is calculated based on the class before weaving has taken place.
- `-Xreweavable[:compress]`::
- (Experimental - deprecated as now default) Runs weaver in reweavable
- mode which causes it to create woven classes that can be rewoven,
- subject to the restriction that on attempting a reweave all the types
- that advised the woven type must be accessible.
- `-XnoInline`::
- (Experimental) do not inline around advice
- `-XincrementalFile <file>`::
- (Experimental) This works like incremental mode, but using a file
- rather than standard input to control the compiler. It will recompile
- each time file is changed and and halt when file is deleted.
- `-XserializableAspects`::
- (Experimental) Normally it is an error to declare aspects
- Serializable. This option removes that restriction.
- `-XnotReweavable`::
- (Experimental) Create class files that can't be subsequently rewoven
- by AspectJ.
- `-Xajruntimelevel:1.2, ajruntimelevel:1.5`::
- (Experimental) Allows code to be generated that targets a 1.2 or a 1.5
- level AspectJ runtime (default 1.5)
-
- === File names
-
- ajc accepts source files with either the `.java` extension or the `.aj`
- extension. We normally use `.java` for all of our files in an AspectJ
- system -- files that contain aspects as well as files that contain
- classes. However, if you have a need to mechanically distinguish 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
- naming conventions or sub-packages in favor of the `.aj` extension.
-
- * Filename conventions are hard to enforce and lead to awkward names for
- your aspects. Instead of `TracingAspect.java` we recommend using
- `Tracing.aj` (or just `Tracing.java`) instead.
- * Sub-packages move aspects out of their natural place in a system and
- 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 packages instead.
-
- === Compatibility
-
- AspectJ is a compatible extension to the Java programming language. The
- AspectJ compiler adheres to the
- https://java.sun.com/docs/books/jls/index.html[The Java Language
- Specification, Second Edition] and to the
- https://java.sun.com/docs/books/vmspec/index.html[The Java Virtual
- Machine Specification, Second Edition] and runs on any Java 2 compatible
- platform. The code it generates runs on any Java 1.1 or later compatible
- platform. For more information on compatibility with Java and with
- previous releases of AspectJ, see xref:compatibility.adoc#versionCompatibility[Version Compatibility].
-
- === Examples
-
- Compile two files:
-
- [source, text]
- ....
- ajc HelloWorld.java Trace.java
- ....
-
- 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, and may include other argfiles by @-reference.
- The following file `sources.lst` contains absolute and relative files
- and @-references:
-
- [source, text]
- ....
- 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:
-
- [source, text]
- ....
- ajc -argfile sources.lst
- ajc @sources.lst
- ....
-
- Argfiles are also supported by jikes and javac, so you can use the files
- 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.
-
- 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 -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
- read-only libraries containing aspects. Like input jars, they affect all
- input; unlike input jars, they 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
- environment; it creates a read-only aspect library, compiles some
- classes for use as input bytecode, and compiles the classes and other
- sources with the aspect library.
-
- The tracing example is in the AspectJ distribution
- (\{aspectj}/doc/examples/tracing). This uses the following files:
-
- [source, text]
- ....
- 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:
-
- [source, text]
- ....
- cd examples
- export ajrt=../lib/aspectjrt.jar
- export CLASSPATH="$ajrt"
- export PATH="../bin:$PATH"
- ....
-
- Build a read-only tracing library:
-
- [source, text]
- ....
- ajc -argfile tracing/tracelib.lst -outjar tracelib.jar
- ....
-
- Build the application with tracing in one step:
-
- [source, text]
- ....
- ajc -aspectpath tracelib.jar -argfile tracing/notrace.lst -outjar tracedapp.jar
- ....
-
- Run the application with tracing:
-
- [source, text]
- ....
- 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 sake):
- +
- [source, text]
- ....
- mkdir classes
- javac -d classes tracing/*.java
- jar cfM app.jar -C classes .
- ....
- * (b) Build the application with tracing:
- +
- [source, text]
- ....
- ajc -inpath app.jar -aspectpath tracelib.jar -outjar tracedapp.jar
- ....
-
- Run the application with tracing (same as above):
-
- [source, text]
- ....
- java -classpath "$ajrt;tracedapp.jar;tracelib.jar" tracing.ExampleMain
- ....
-
- Run the application without tracing:
-
- [source, text]
- ....
- java -classpath "app.jar" tracing.ExampleMain
- ....
-
- === The AspectJ compiler API
-
- The AspectJ compiler is implemented completely in Java and can be called
- 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
- arguments. This means that an alternative way to run the compiler is
-
- [subs=+quotes]
- java org.aspectj.tools.ajc.Main [_option_...] [_file_...]
-
- To access compiler messages programmatically, use the methods
- `setHolder(IMessageHolder holder)` and/or
- `run(String[] args, IMessageHolder holder)`. `ajc` reports each message
- to the holder using `IMessageHolder.handleMessage(..)`. If you just want
- to collect the messages, use `MessageHandler` as your `IMessageHolder`.
- For example, compile and run the following with `aspectjtools.jar` on
- the classpath:
-
- [source, java]
- ....
- 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
- cases generate classfiles from multiple source files. Unfortunately, the
- original Java class file format 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, but 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
- traces, where you may encounter traces of the format
-
- [source, text]
- ....
- java.lang.NullPointerException
- at Main.new$constructor_call37(Main.java;SynchAspect.java[1k]:1030)
- ....
-
- where instead of the usual
-
- [source, text]
- ....
- File:LineNumber
- ....
-
- format, you see
-
- [source, text]
- ....
- File0;File1[Number1];File2[Number2] ... :LineNumber
- ....
-
- In this case, LineNumber is the usual offset in lines plus the "start
- line" 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" for 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 line 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 line number. That is the file where the source
- location can actually be found. Then, subtract that "start 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.
|