Provided by: aspectj_1.6.12+dfsg-3_all bug

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
       bytecode  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.  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  The  AspectJ
       Programming Guide, Implementation Appendix ../progguide/implementation.html) .

       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.)

   Options
       -injars JarList
                 deprecated: since 1.2, use -inpath, which also takes directories.

       -inpath Path
                 Accept as source bytecode any .class files in the 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.

       -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.

       -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 -target 1.1.

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

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

       -source [1.3|1.4|1.5]
                 Toggle  assertions (1.3, 1.4, or 1.5 - default is 1.4).  When using -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 suppress 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        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:

       -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    The   Java   Language   Specfication,    Second    Edition    (BOOK)
       http://java.sun.com/docs/books/jls/index.html   and   to  the  The  Java  Virtual  Machine
       Specification, Second 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 information  on  compatibility  with  Java  and  with
       previous releases of AspectJ, see "" >.

   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,  and  may
       include  other argfiles by @-reference.  The following file sources.lst           contains
       absolute 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 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.

       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 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:

       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 tracedapp.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 sake):

       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 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

       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:

       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

       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 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.

                                                                                           ajc(1)