================================================================================
                               PHX.MORPH v1.1

                  Copyright (C) 2005-2006 Microsoft Corporation.
================================================================================

Created: 03/12/06
Updated: 05/26/06

Overview
--------
Phx.Morph is byte code weaver for .NET assemblies.  It is written in C# and
is built on top of Phoenix, Microsoft's back-end compiler infrastructure.

Phx.Morph supports:

+ Open Classes (aka static crosscutting, introductions, intertype declarations)
   + Add fields
   + Add methods
   + Add properties
   + Add base iface
   + Add base class
   + Replace methods

+ Aspect-Oriented Programming (AOP)
   + Advice types: before, after
   + Pointcuts: execution, call, get, set, within, withincode, this, target
   + Joinpoint context: This, Args, Annotations, SourceLocation, Signature,
     Within, Kind, Target
   + Statement Annotations

Phx.Morph is similar to AspectJ.  It supports the pointcut-advice AOP flavor.
Pointcuts are used to pick out points in the program (join points) where calls
to advice methods will be injected (woven in).  Pointcuts are specified using
AspectJ-like pointcut designators and expressions. Aspects are written in
plain-old C# (or any .NET language).  Phx.Morph relies on .NET attributes for
specifing introductions, pointcuts, and tagging advice method parameters with
the join point context parameter that should be passed in.

Requirements
------------
o Microsoft .NET 2.0
o Microsoft Phoenix RDK (http://research.microsoft.com/phoenix)
o Perl (http://www.activestate.com/Products/Download/Download.plex?id=ActivePerl)

(Note: Perl is only needed to run the regression test suite (dotest.bat)).

Installation
------------
1. Download and install Phoenix RDK
2. Make sure the RDKRoot environment variable is set to the Phoenix RDK
   root directory
3. Extract the contents of Morpher.zip to any directory
4. Make sure csc.exe is in your PATH.
5. Run <INSTALL DIR>\BUILDALL.BAT from a Command Prompt.  This will build
   Phx.Aop, Phx.Morph, MorphPlugin, and all the examples in the test suite.

Testing
-------
1. Run <INSTALL DIR>\DOTEST.BAT from a Command Prompt.  This will build Phx.Aop,
   Phx.Morph, MorphPlugin, and all the examples in the test suite, and will run
   the tests in the test suite.  You should see no failed tests in the summary
   at the end.

================================================================================

Change History
==============

1.1
---
- Withincode pointcut support
- Constructor matching support (e.g., *.new(..))
- Annotation support
	- Annotation matching in pointcut expressions
	- Annotation context exposure
	- Statement annotations
- Added Verbosity flag to control message output
- Added callback so a dynamic breakpoint weaver can do the weaving
- Added Phx.Morph.Morpher (MorphPlugin.dll) to allow clients to invoke
  weaving programmatically
- Advice now keep track of their advised join points so they don't
  weave them twice
- Can no longer specify /classToExtend and /fieldToAdd flags
- BUG FIXES
	- Aspect assembly must be in the current directory to be loaded
	- Error when passing Args context from within a static method
	- Aspect assebmly cannot be an EXE

================================================================================

Package Contents
----------------
\Morpher

	\Phx.Aop - General-purpose AOP classes (doesn't require Phoenix RDK)
	\Phx.Morph - APIs for Open Classes and AOP
	\MorphPlugin - Plugin for the Phoenix Portable Executable Rewrite (PEREW)
		and API for programmatic weaving
	\examples - Test suite

================================================================================

FAQ
---

================================================================================

KNOWN ISSUES
------------
o Some call joinpoints have no filename or linenumber
o Failed to detect pointcut expression error:

	"[PrintAttr] call(* *.*(..))"

	should be

	"call([PrintAttr] * *.*(..))"

o Binary weaving causes the line number to be incremented in the woven
  executable.  This causes the advice to be applied multiple times incorrectly.
o Rewriting Goblin.Engine.dll without changes results in Goblin failing to run
o dotest.Logging.bat binary fails with

  Unhandled Exception: System.MissingMethodException: Method not found: 'Void LogA
  ttribute..ctor(LogAspect, System.String)'.
     at SimpleDraw..ctor()
     at SimpleDraw.Main()

  unless I explicitly do a System.Type forceLoad2 = typeof(LogAspect);
o Around/proceed currently doesn't work
o Some pointcuts not supported: initialization, preinitialization,
  staticinitialization, handler, adviceexecution, cflow, cflowbelow,
  args, and if
o This, args, and target only work for execution joinpoints
o Can't import or replace methods with multiple return statements or exception
  handlers
o If the client assembly initializes fields inline we get a PEVERIFY error:

  class Person {
      string name = "joe";
       
o Sometimes a certain aspect ordering or advice method implementation
  will cause BackPatchIR to fail for instance advice.

================================================================================

TODO
----
o Support adding events
o Support adding attributes
o Support adding classes
o Support thisJoinPoint and thisJoinpointStatic
o Support aspect precedence
o Support named pointcuts
o Use msbuild to build Phx.Aop, Phx.Morph, and MorphPlugin from the command-line
o Should be able to specify a base class for context parameters that are
  references
o Verify that we don't load assemblies using Reflection unless needed
o Statement annotations need to apply at arbitrary statements, not just calls

================================================================================

Main contact
------------
Marc Eaddy (eaddy@cs.columbia.edu)

Credits
-------
Marc Eaddy (Columbia University)
Rajesh Ramakrishnan (Columbia University)
Adam Vartanian (Columbia University)
Weiping Hu (Microsoft)
Paddy McDonald (Microsoft)
Julian Burger (Microsoft)

================================================================================