--------------------------------------------------------------------------------
                         EDIT-AND-CONTINUE (EnC) README.TXT
--------------------------------------------------------------------------------
Created: 3/25/05
Updated: 3/28/05

Overview
--------
This distribution includes:

Multi-Language Edit-and-Continue (EnC) - Allows you to modify the source code of a
	running application.  Changes are re-compiled in the background and the
	running application is patched on-the-fly.  See "Docs\Edit & Continue\
	enc-csharp-eaddy-2005.doc" for details, however, the current version of EnC
	doesn't just support C#.  It also supports VB.NET, and JScript.NET as well as
	any managed language that supports CodeDomProvider.

Requirements
------------
o Windows XP
o Microsoft .NET Framework 1.1.4322     (required to run EnC)
o Microsoft Visual Studio .NET 2003     (required to build EnC)

Anti-Requirements
-----------------
EnC will probably not work if you have installed any of the following:

o Windows Longhorn
o Microsoft .NET Framework 2.0
o Microsoft Visual Studio .NET 2005

Installation
------------
1. Extract EnC package (using WinZip or tar xzf EnC.tar.gz)
2. Add <INSTALL DIR>\Common to your PATH (in System Properties->Advanced->
   Environment Variables)
3. Run INSTALL.BAT

Package Contents
----------------
\Goblin

	PACKLIST_ENC.TXT - List of files in package

	\Patcher - EnC Patcher source code (Unmanaged C++ COM object)

		README.TXT - Patcher readme
		INSTALL.BAT - Registers Patcher.dll
		TEST.BAT - Simple demonstration of Edit-and-Continue.  Starts
             Hello_CS.exe and opens Hello.cs in Notepad to allow
             the user to modify the source and observe the effects.
		ENABLE.BAT - (see below)
		DISABLE.BAT - (see below)
		ENABLE_BREAK.BAT - (see below)
		DISABLE_BREAK.BAT - (see below)
		BUILD.BAT - Builds Hello.* files and creates the bugreport files
             needed for EnC.
		Hello.cs  - Simple console app (C#)
		Hello.vb  - Simple console app (VB.NET)
		Hello.js  - Simple console app (JScript.NET)
		Hello.jsl - Simple console app (J#)
		Hello.cpp - Simple console app (Managed C++)
		IlxLogSettings.xml - Log settings configuration file
		Patcher.log - Patcher log file (created when Goblin is run with
             EnC enabled)
		Watcher.log - Watcher log file (created when Goblin is run with
             EnC enabled)

		\DEBUG

			Patcher.dll - Patcher DLL

	\Watcher - EnC Watcher source code (C#)

		Watcher.exe - Watcher application

		Watcher.exe.config - All the CodeDomProviders we've ever heard of. This
             determines which languages EnC supports. We've only verified support
             for C#, VB.NET, and JScript.NET.

\Common - Helper classes

	\ILXLog - Logging COM object

	\ILXCrashFinder - Obtains stack trace from C++ exception

NOTE: Helper classes and projects under the "Common" directory are copyright
ILX Systems/Thomson Financial.  Redistribution of source code or binaries is
not permitted.

--------------------------------------------------------------------------------

Testing EnC
-----------
1. Run <INSTALL DIR>\PATCHER\TEST.BAT from a Command Prompt.  This will start
   the Hello_CS.exe console app, which is a simple C# app that prints a message
   in an infinite loop.  TEST.BAT also opens Hello.cs in Notepad.
2. In Notepad, change the Joe() or Jack() methods by changing the WriteLine()
   string, for example.
4. Save your changes (CTRL+S).

In under a second, you should see the effects in the console window (e.g., the
output string is different).

Enabling/Disabling EnC
----------------------
EnC is enabled by setting some environment variables.  You should do this
from a Command Prompt instead of setting them in System Properties or
else EnC will be enabled for all managed/.NET processes on your machine.

Enabling:
1. Run Patcher\ENABLE.BAT

Disabling:
1. Run Patcher\DISABLE.BAT

Calling ENABLE_BREAK.BAT causes Patcher to invoke the Just-In-Time Debugger
via DebugBreak().  You can then put breakpoints in Patcher and debug.

Enabling debugging:
1. Run Patcher\ENABLE_BREAK.BAT

Disabling debugging
1. Run Patcher\DISABLE_BREAK.BAT

Building the Projects
---------------------
1. Open Goblin.sln in Visual Studio .NET 2003. You may see some error prompts
   which you should be able to safely ignore.
2. In Visual Studio .NET 2003, add the following directory to Tools->
   Options...->Projects->VC++ Directories->Executable files:

	<INSTALL DIR>\Common
3. Right click on Solution and select "Rebuild All"

Troubleshooting
---------------
Check Patcher.log and Watcher.log for errors.  If you make a change to a source
file that causes a compile error you'll see the error in Watcher.log.  If you
made a change that is not supported by Edit-and-Continue you'll see errors in 
Patcher.log.

--------------------------------------------------------------------------------

FAQ
---
Q. Patcher is not able to find any source files for my module.  I get the message:

   "INFO: Incremental build file 'App.exe.incr' and bug report file 'App.exe.bugreport'
    not found. Did you forget to specify '/incremental' or '/bugreport'?"

A. Make sure you specify the "/bugreport:App.exe.bugreport" compiler flag so that the
   App.exe.bugreport file gets created.  This is used by Patcher to determine the module
   source files, referenced assemblies, and other compilation options.

Q. Sometimes I get an assertion that says "Failed to rename log file. Backup Failed."

A. Watcher.exe is still running.  This can happen if you start and stop the target
   application quickly before Patcher has had a chance to initialize communication
   with Watcher.  Kill Watcher.exe in Task Manager. Also kill any vsjit.exe processes.

Q. Sometimes when a patch is applied I get an exception.

A. Did you specify /incremental as a compile option?  If so, you must first
   make sure you del the previous .incr file.  For some reason, the presence
   of this file has a strange effect on the subsequent compilations which
   can cause the exception.  Actually, we expect /incremental to enable
   incremental compilation.  However, it seems that the subsequent incremental
   compilations cause the problem.  need to investigate further.

Q. Patching fails and Patcher.log shows that many strings were updated even though
   I didn't change them.

A. If the strings are only used in System.Debug.Assert() calls, verify that /D:DEBUG is
   in the compiler command-line in bugreport file.  If it isn't, you must specify this
   flag when compiling from the command-line.  If the strings are only used in
   System.Trace.WriteXXX() calls, verify that /D:TRACE is used.  It appears that the
   command-line compiler doesn't specify these flags by default, but the CodeDOM compiler
   does.
   
Q. I get an assertion ("methodDef") and a bunch of exceptions when a patch is
   applied.
   
A. Make sure build.bat (the custom command-line build batch file) has been run
   for the application.

BUGS
----
1. The following design changes cause issues

	a. Adding a method - Causes the method tokens to change which causes
	   Patcher to update methods that refer to those tokens. However,
	   the new method is never added to the original assembly so when
	   the effected functions are Re-JIT'd you'll get an InvalidProgramException.

Debugging with Rotor
--------------------
1. Build Rotor (I use "checked" instead of "fastchecked")
2. Obtain "gset" from the BIN directory in the following:

http://download.microsoft.com/download/c/0/b/c0b7c8fa-58f1-4815-aae7-ed18a4dc3f08/NetProfilerAPI.exe

3. Open Command Prompt
4. Change to Rotor directory
5. Run env.bat (I modified to use "checked" instead of "fastchecked")
6. Run devenv.exe (from same Command Prompt)
7. Use Task Manager to find Process ID for devenv.exe
8. In VSNET, specify the following debug project options:

Command: clix.exe
Command Args: <your app name>.exe
Working Dir: <your app directory>

Now you should be able to put breakpoints anywhere in your code and step into
the Rotor source code for any .NET function!  Try it out on SetFunctionReJIT!

==> To debug Patcher:

Debugging Patcher also requires that you run Watcher from a separate DOS window
since Watcher fails to start/connect when Patcher is run via clix.

9. Open a separate Command Prompt
10. Run "Watcher 3456"						(3456 is the port Patcher expects)
11. From VSNET, start Patcher (F5)

You should be able to put a breakpoint in Patcher and step into Rotor function
calls (e.g., IMetaDataEmit::Merge).

==> To debug how the Rotor C# compiler (CSC) parses the Goblin
    incremental build file:

1. Start VSNET 2003
2. Make sure your Solution only has the Patcher project
3. Specify the following debug project options:

Command: C:\PROJECTS\sharedsourcecli\clr\bin\rotor_x86\checked\csc.exe
Command Args: /nologo /unsafe /target:exe /noconfig /nostdlib /out:bin\Debug\Goblin.exe /debug /incremental /reference:C:\WINDOWS\assembly\GAC\Microsoft.DirectX\1.0.2902.0__31bf3856ad364e35\Microsoft.DirectX.dll /reference:C:\WINDOWS\assembly\GAC\Microsoft.DirectX.Direct3D\1.0.2902.0__31bf3856ad364e35\Microsoft.DirectX.Direct3D.dll /reference:C:\WINDOWS\assembly\GAC\Microsoft.DirectX.Direct3DX\1.0.2903.0__31bf3856ad364e35\Microsoft.DirectX.Direct3DX.dll /reference:c:\WINDOWS\Microsoft.NET\Framework\v1.1.4322\System.dll /reference:c:\WINDOWS\Microsoft.NET\Framework\v1.1.4322\System.Windows.Forms.dll /reference:c:\WINDOWS\Microsoft.NET\Framework\v1.1.4322\System.Drawing.dll /reference:C:\PROJECTS\sharedsourcecli\clr\bin\rotor_x86\checked\mscorlib.dll /resource:Goblin.ico /recurse:*.cs
Working Dir: C:\PROJECTS\Goblin\Engine

4. Set a breakpoint in the csc source file: incbuild.cpp

- You may need to run env.bat first and launch devenv.exe from the command-line so
that the env variables for Rotor are set.

5. Run. You should hit the breakpoint.

TODO
----
o Detect unsupported updates
o Test multi-language apps
o Test updating dynamically loaded assemblies
o Optimizations
o Support arbitrary patching
o Write CS Tech Report
o Support adding fields, methods, classes
o Test calling Watcher directly from Patcher
o Support parsing project files and makefiles
o Create EnC multi-language dynamically updatable "interpreter"
o Write MSDN article
o Web site
o Automate measuring the update latency
o Fix support for J#

o Test Property aspects
o Test Field aspects

--------------------------------------------------------------------------------

Credits
-------
Marc Eaddy (eaddy@cs.columbia.edu)

IlxLog and IlxCrashFinder are copyrighted by ILX Systems.

--------------------------------------------------------------------------------
