[aspectj-dev] weaver jar, publishing api, rollout

[Wes Isberg <wes@xxxxxxxxxxxxxx>]

One option for the rollout is to deliver an executable
lib/aspectjweaver.jar with the weaver, the weaving class
loader, and a main class that ran it.  Either way,
we should consolidate the public API and put the
embedding docs in there.

Benefits:
- For users just running it, you just run it, even in 1.3
- For developers wanting to embed the weaver, it's clear
which set of classes to use and where the docs are.
- For testing we can update the harness to support
weave steps

Here's the command-line syntax:

  java -jar aspectjweaver.jar {classname} {options}

where the required {options} are

  -aspectpath {paths}
  -classpath {paths}    # aka -inpath

and anything else is passed to {classname}.main(..).

The weaver main method creates a weaving class loader with
the specified aspectpath and classpath (read: inpath),
loads {classname} using the weaving class loader, and runs it.
(Since we do that in util module classloader, perhaps we should
combine rather than supporting two.)

Instructions are below for setting up the build.  This works
in my local tree, but I didn't actually see the weaving
class loader or scripts checked in, so I didn't build it out.

It seems like we might also want to segregate the public API's
in org.aspectj.tools.weaver rather than putting them in
org.aspectj.weaver. That makes it really clear which API's
we are supporting (and makes javadoc easier).  Also docs for
embedding the weaver (whether in a weaving class loader or
in some other tool) could go into the javadoc.

With a resulting roll-out steps:

- mention embedded/ltw weaving in release message
  and changes/readme, linking to the devguide section
- devguide section
  - running the demo ltw [ant, java -jar, scripts..]
    - linkto doc/examples/build.xml for ant
    - linkto doc/examples/ltw/...?
  - embedding the weaver
    - requirements
    - demo classloader
    - xref weaver-api javadoc
- segregate and doc API's
- doc/weaver-api built, linked from doc/index.html

Wes

Setting up the build to add aspectjweaver.jar:

- create weaver/src/org/aspectj/tools/weaver/Main.java
- create weaver/weaver.mf.txt with the manifest, specifying
  the Main class
- create empty file
  build/products/tools/dist/lib/aspectjweaver.jar
- update build/../Builder.moduleAliasFor() to alias
  "weaver-all.jar" for "aspectjweaver.jar"
  (rebuild module and install in lib/build/build.jar)

If things are working as hoped, when you do a build it will
create the executable lib/aspectjweaver.jar in the distribution.

We can update the harness to support launching the weaver
using this main method, so we can write tests for it.