Alcantarea - A Visual Studio Add-In for Runtime C++ Code Editing

Introduction

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.

The name "Alcantarea" is came from my favorite plants.
Alcantarea は C++ ソースの変更を実行中のプログラムに反映させる Visual Studio 用アドインです。 これにより、ソース編集 -> ビルド -> テスト のサイクルを劇的に速めることができ、また、C++ プログラミングがより楽しくなります。

Visual Studio には Edit and Continue という類似機能がありますが、Alcantarea にはいくつかの利点と欠点があります。
主な利点:
  • x64 のネイティブコードでも機能する
  • 最適化が有効なコードに対しても機能する (/ZI オプションを必要としない)
主な欠点:
  • 編集後はソースコードデバッグができなくなる
  • マネージドコードでは機能しない
やや厳しい欠点があるものの、この 2 つの利点は特にゲーム開発者には重宝するはずです。

"Alcantarea" という名前は私のお気に入りの植物にちなみます。

demo ( watch in full size )

How To Use

  • Alcantarea supports Visual Studio 2010, 2012, 2013 (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.menu
  • 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().
  • Alcantarea は Visual Studio 2010, 2012, 2013 に対応しており、64 bit の Widnows 7 と 8.1 で動作を確認しています。
  • Alcantarea を使う際はプロジェクト側の /Zi ( デバッグ情報の生成) と /MAP (.map ファイル生成) オプションを有効にする必要があります (詳細は後述)。
  • インストール後、右図のようなメニューが追加されます。menu
  • 基本的な使用方法は "Alcantarea"->"Start Debugging" でプログラムを起動し、ソースを編集し、"Alcantarea"->"Apply Changes" で変更を適用するだけです。
  • 変更が適用されるのは、デフォルトでは VisualStudio のエディタの現在のカーソル位置の関数、および過去に変更を適用した関数です。 しかし、稀にエディタの現在のカーソル位置の関数をうまく取得できないことがあります (マクロで包まれていてうまくパースできない、何らかの要因で .sdf ファイルを読めていない など)。このような場合シンボルフィルタによる手動設定が必要になります。
  • シンボルフィルタ "Alcantarea"->"Symbol Filter" を使うと、関数の 更新する/しない などを個別に設定することができます。また、ロード/アンロード時 (変更を反映する前後) に自動的に呼ばれるハンドラ関数の設定もできます。無関係なシンボルが多数表示されて煩わしい場合、オプション ("Alcantarea"->"Options") の "Symbol Filter" の項目でパターンを定義することで、それにマッチするシンボルを表示しないようにできます。デフォルトでコンパイラが暗黙に生成するシンボル群と std:: のシンボルを非表示にするパターンが設定されています。
  • 通常の "デバッグ開始 (F5)" でプログラムを起動した場合でも、"Alcantarea"->"Attach to Debugged Process" で変更を適用できるようになります。しかしこちらは失敗することがあります。"Alcantarea"->"Start Debugging" で起動する方を推奨します。
  • Edit and Continue と違い、Alcantarea はデバッガでプログラムを止めてる間は変更を適用できません。止めてから変更を適用したい場合、"Alcantarea"->"Suspend/Resume Process" コマンドを使います。このコマンドは対象プロセスの Alcantarea の通信スレッド以外のスレッドを全て suspend/resume させます。
  • "Alcantarea"->"Load Obj Files" を使うと、任意の .obj ファイルを読み込んでそれに含まれる関数を適用することができます。これにより、コンパイラが .obj ファイルを生成する言語であれば C/C++ 以外でも実行時に変更を適用することができます。(例: Intel ISPC。スピード狂にお勧めの言語です)
  • "Alcantarea"->"Load Symbols" は .pdb, .map ファイルからシンボル情報を読み込みます。通常は自動的に読み込むのでこれを使う必要はありません。 これが必要になるのは、オプション "Hook LoadLibrary()" を切っている状態で、変更適用に LoadLibrary() でロードしたモジュールのシンボルが必要になる時です。

How It Works

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)
以下に Alcantarea が内部でどのようなことをやっているかを解説します。
遺憾ながら、このアドインを使う上で内部処理を知っておくことはトラブルを避けるために重要です。

Alcantarea は以下のような手順で実行時に変更を適用しています:
  1. プログラムを起動し、アドインと通信するための dll を注入する
  2. "Apply Changes" が実行されると、アドイン側で C++ ソースをコンパイルし、プログラム側に .obj ファイルをロードするリクエストを送る
  3. プログラム側は .obj ファイルを自力でロード&リンクし、.obj ファイルの中の関数で元の関数を更新する (元の関数の先頭を新しい関数への jmp に書き換える)

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.
  • Antivirus software may detect Alcantarea as a threat because injecting dlls and changing binary code are similar characteristics to viruses. And firewall software may warn to you when start the program because Alcantarea uses TCP connection to communicate with program.
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.

By the way, I used DynamicPatcher (with some improvements) to implement loading & linking .obj files and updating functions. 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.
このアプローチは概ねうまく機能しますが、いくつかの制限や注意すべき点があります。
  • 実行時に自力でリンクするのにシンボル情報が必要なため、 /Zi (デバッグ情報生成) か /MAP (map ファイル生成) のどちらかが必須になります。/Zi は通常有効になっていると思われますが、デバッグ情報からシンボルを探すのは大規模なプログラムでは非常に遅くなります。それと比べ、.map ファイルを使った場合は高速です。このため事実上両オプション必須に近い状態です。
  • 実行時編集後、ソースコードデバッグができなくなります。 厳しい制限なので対処したいところですが、.obj ファイルからデバッグ情報を取り出して実行中にデバッグ情報を追加するのは難しく、実装の見通しは立っていません。
  • 関数内 static オブジェクトを含む関数を更新するのは危険です。 更新前の関数の static オブジェクトと更新後のそれは別のインスタンスとして扱われます。2 つのインスタンスが混ざると高確率でよくないことが起きます。
  • 実行時編集されたコードの中では例外の catch ができません。例外の catch は実装が難しく、実装は未定です。
  • リンク時コード生成 (/LTCG) 最適化オプションが有効になっていると編集を反映できなくなります。 このオプションは .obj ファイルのフォーマットを変え、ロードできなくしてしまいます。
  • データ構造を変える変更は扱いが難しく、できるだけ避けるべきです。 プログラムを変更しても既存のデータの構造は変わらないため、プログラムは変更前と変更後両方のデータ構造を適切に扱える作りになっている必要があります。
  • 実行時編集されたコードは、ホストプログラムが含んでいない外部ライブラリの関数を使えません。 ホストプログラムにないシンボルは見つけられないため、リンクエラーになります。この場合、エラーメッセージが出て変更が反映されないだけで、クラッシュしたりはしません。
  • virtual 関数の追加や削除は正しく反映できません。vftable の構造が変えられないためです。
  • インライン展開された関数は更新できません。これは対処のしようがありません。
  • アンチウィルスソフトがこのアドインをウィルスと誤認する可能性があります。dll の注入やバイナリ書き換えなどがウィルスの特性と類似しているためです。 また、プログラム起動時にファイアウォールソフトが警告を発する可能性もあります。現在アドインとプログラムの通信に TCP コネクションを用いているためです。
総じて、Alcantarea は関数の中のアルゴリズムを変えるような小さな変更には向きますが、データ構造を変えたり class を追加したりなどの大きな変更には向きません。

余談ながら、.obj ファイルのロードや関数の更新の実装は DynamicPatcher に改良を加えたものになっています。 DynamicPatcher は私の過去の制作物であり、CC BY ライセンスでオープンソースで公開しています。この機能をご自身のプログラムに組み込みたい場合、自由にご利用いただけます。
DynamicPatcher は Riot Games に採用された実績があります。

Download Free Trial

Alcantarea-1.0.1.vsix ( ReleaseNotes ) 2014/02/10

Old Builds
Alcantarea-1.0.0.vsix (2013/12/24)


Trial version will run without limitation for 30 days.
Trial version can be upgraded to the full version by purchasing license at any time.
試用版は 30 日間、機能制限なしで動きます。
ライセンスを購入することでいつでもフルバージョンにアップグレードできます。

Purchase

A license consts $40. Includes 1 year of software updates and technical support.
The license is per-user basis. You can use a license on any computers.
1 ライセンス $40 です。1 年間のアップデートとテクニカルサポートを含みます。
所持しているユーザーが使用する限りにおいては、1 つのライセンスをどのコンピュータでもご使用いただけます。

Quantity * $40


A license key mail will arrive to your email address in paypal several minutes after purchase.
License key mails can be classified as spam with high probability. Make sure your spam filter didn't sort out the mail. Sometimes spam filters delete the mail automatically. If the mail does not arrive, please contact to support@alcantarea-cpp.com with your paypal transaction ID.

購入後、数分以内に paypal に登録されているメールアドレスにライセンスキーが届きます。
スパムフィルタに引っかかる可能性が高いです。メールがスパムフォルダに入っていないかご注意ください。
また、一部のスパムフィルタは無言でメールを削除することがあるようです。もしメールが届かない場合、お手数ですが paypal からのメールに記載されている 取引 ID を添えて support@alcantarea-cpp.com まで御一報ください。

Contact

If you need technical support, please contact to support@alcantarea-cpp.com.
If you interested in technology behind Alcantarea or other my work, feel free to follow my twitter, or visit my blog, or contact to i-saint@alcantarea-cpp.com. (Sorry, almost all of my articles are japanese.)
And feel free to use forum below. You can post a message in any topic related to Alcantarea.

Alcantarea is made and maintained by one programmer. So user support may be poor. Some bugs may not be fixed until you report it. If you like Alcantarea, please support us to make it more better. Purchase, bug reports, comments, recommend to friends, all will be welcome.
テクニカルサポートが必要な場合、support@alcantarea-cpp.com まで御一報ください。
このアドオンの実装など技術的なことに興味があれば、私の twitterblog が情報になるかもしれません。なにか個人的な要件がもしあれば i-saint@alcantarea-cpp.com までどうぞ。
また、下記フォーラムはこのアドオンに関連するトピックであればご自由にご利用いただけます。

Alcantarea は個人で制作されています。個人ゆえにユーザーサポートには限界がありますし、報告されるまで気づかないバグなどもあるかもしれません。 Alcantarea を気に入っていただけたなら、サポートしていただけると幸いです。購入、バグ報告、ご意見ご感想、知り合いに勧める、なんでも構いません。

Forum

Jump to google group