Alcantarea - A Visual Studio Extension for Runtime C++ Code Editing

Alcantarea is an add-in for Visual Studio that allow you to apply C++ code changes to running programs. This functionality makes development iteration cycle drastically faster, and makes C++ programming more fun.

Visual Studio has similar functionality called Edit and Continue. Alcantarea has some advantages and disadvantages.
Notable advantages:

• Alcantarea supports x64 native code
• Alcantarea works with optimized code (/ZI option is not required)

Notable disadvantages:

• Source code debugging will not work after applying changes
• Alcantarea does not support managed code

Although these disadvantages are serious, these advantages are very helpful especially for game developers.

• Alcantarea supports Visual Studio 2010 - 2015 preview (Tested on 64-bit Windows 7 and 8.1).
• Alcantarea requires /Zi (generate debug information), /MAP (generate map files) options (detailed in next section).
• After the installation complete, the menu (right image) will appear.
• The basic usage is: start program by "Alcantarea"->"Start Debugging", edit source, and "Alcantarea"->"Apply Changes".
• By default, Alcantarea updates the cursor's current position function, and the functions updated in the past. But in some special case, Visual Studio cannot get cursor's current position function (the function is wrapped by macro, the .sdf file could not load, etc). In this case, you need to use Symbol Filter to choose functions to update.
• By using Symbol Filter ("Alcantarea"->"Symbol Filter"), you can choose functions to update, and set on load/unload handler (functions called on applying changes). You can set ignore pattern in "Symbol Filter" tab on "Alcantarea"->"Optins". Symbols that match these patterns are not shown in Symbol Filter.
• "Alcantarea"->"Attach to Debugged Process" command makes programs that are started by normel "Debug"->"Start Debugging (F5)" able to apply changes. But it sometimes fails. Using "Alcantarea"->"Start Debugging" is recommended.
• Unlike Edit and Continue, Alcantarea cannot apply changes in break mode. If you want to stop the program before applying changes, you can use "Alcantarea"->"Suspend/Resume Process". This command suspends/resumes all threads except Alcantarea's communicator thread in target process.
• You can load any .obj files and apply functions in it by using "Alcantarea"->"Load Obj Files". This means, you can apply any languages' code changes if the language's compiler generates .obj files. (e.g. Intel ISPC. This is good for high performance programming)
• "Alcantarea"->"Load Symbols" loads symbol information from .pdb and .map files. By default, symbols are loaded automatically and you do not need to use this command. You need this command only when "Hook LoadLibrary()" option is disabled and runtime-linker requires symbols in DLLs loaded by LoadLibrary().

This section describes how Alcantarea applying code changes.
Unfortunately, understanding it is important to avoid troubles.

What Alcantarea do is:

1. Start program and inject a dll that communicate with the add-in.
2. Compile C++ sources and request the program to load .obj files when "Apply Changes" is executed.
3. Load & link .obj files, and replace existing functions with new ones in .obj files. (Emit jmp instructions on the head of old functions to redirect to new ones)

This approach works quite well. But there are some limitations and pitfalls.

• Symbol information is required to runtime linking. So one of /Zi (generate debug information) and /MAP (generate map files) options is required. Practically, both of them are required. /Zi is for debug. /MAP is for speed. Searching symbols from debug information is painfully slow when the program is large. By using .map files, it will be much faster.
• Source code debugging will not work after applying changes. Adding debug information from .obj files at runtime is difficult to implement and currently in investigation.
• Updating functions that have function-static objects can be dangerous. Function-static objects in before-updated functions and after-updated functions are different instances. Mixing them will cause problems.
• Runtime-edited code cannot catch exceptions. Catching exception is difficult to implement and there is no plan.
• Alcantarea will not work if /LTCG (link time code generation) option is enabled. /LTCG makes .obj files unloadable.
• Changing data structure is difficult to handle and should be avoided. Applying code changes does not change existing data's structure. So the program needs to can use both before-changed data structures and after-changed ones properly.
• Runtime-edited code cannot use functions in external libraries that are not contained in host program. It will cause link error because runtime linker cannot find these symbols. (Link errors simply cancel applying code changes. The program can continue running)
• Adding or removing virtual functions cannot be applied properly because vftable cannot be modified.
• Inlined functions cannot be updated. Nothing can be done about it.

In conclusion, Alcantarea is fit for small program changes such like changing algorithms in functions. And is not fit for large program changes such like changing data structure or adding new classes.

Runtime loader & linker is DynamicPatcher with some improvements. DynamicPatcher is my previous work. And it is distributed under CC BY license. If you want to use this functionality in your program, you can use it freely. DynamicPatcher was used by Riot Games.