[aspectj-dev] RE: ajde implementation plans

["Mik Kersten" <mik@xxxxxxxxxxxxxx>]

> -----Original Message-----
> From: Mik Kersten [mailto:mik@xxxxxxxxxxxxxx]
...
> 2. BUILD OPTIONS
> 
> The following build options need to work: -injars, -aspectpath, and -
> outjar.
> In addition the "Xlint" option settings should be supported.  I believe
> that
> the best documentation for these options is in the 1.1 readme.

I just found some very nice documentation on these options that Wes wrote
(message attached).

Mik

--- Begin Message ---

• From: "Isberg, Wes <isberg@xxxxxxxx>"
• Date: Tue, 26 Nov 2002 19:04:11 -0800
• Importance: Normal

Title: Using 1.1b1 for aspect libraries and bytecode weaving

This email introduces two features new to 1.1, bytecode weaving
and aspect libraries, by describing and demonstrating them. 
It requires the 1.1b1 release and the 1.0 tracing example. 
(Later this will be included the Development Environment Guide.)

---- Description

-- bytecode weaving:  ajc -injars "{jar1};{jar2}"
AspectJ 1.1 supports weaving from input zip or jar files containing
class files.  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 (only if they are unwoven -- see below).

-- aspect libraries: ajc -aspectjpath "{jar1};{jar2}"
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.  (Aspect libraries must
already be woven -- see below.)

-- woven or not: ajc -noweave
By default, ajc produces "woven" classes, integrated as necessary
with any aspects. But bytecode may be woven only once.  In cases
where ajc is producing binaries to be used as input to bytecode
weaving via -injars, the -noweave option specifies that the output
classes should not (yet) be woven.  These classes may only be used
as input jars for the ajc -injars option; they cannot be run in
any VM or used by any other compiler.

-- summary

The relevant new 1.1 options:

  -noweave        create unwoven source binaries for -injars
  -injars         take input binaries from specified jars
  -aspectpath     aspects to include as read-only sources
  -outjar {path}  output a zip file with all classes produced

Usage rules:
o -noweave produces input for -injar ONLY
o if ajc creates -injars classes, -noweave is required
o -aspectpath aspect libraries cannot be created with -noweave

---- Demonstration
This build 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.

Install the tracing example from the 1.0 documentation distribution
(http://aspectj.org/dl) in the AspectJ distribution installed from
aspectj-tools-1.1b1.jar (http://aspectj.org/dl-11).  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 ajc:

    ajc -noweave -argfile tracing/notrace.lst -outjar appInput.jar

- -or- using javac:

    mkdir classes
    javac -d classes tracing/*.java
    jar cfM app.jar -C classes .

(b) Build the application with tracing:

    ajc -injars appInput.jar -aspectpath tracelib.jar -outjar tracedapp.jar

  -or-

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

--- End Message ---