[makeログから抽出] において、Imagix 4Dはビルドシステムがソースコードをコンパイルする際に実行されるコマンドライン呼び出しのログから情報を取得します。コンパイラへのコマンドのサブセット、特にソースファイルの名前とそれに関連する -I、-D、および -U の引数は、Imagix 4Dのソースアナライザによってコードを解析するために使用されます。

Imagix 4Dには、Microsoft Visual StudioおよびMicrosoft Buildツールと連携するための専門的なサポートがいくつか組み込まれています。このサポートに特有の手順は、以下でMSBuildフラグで示されています。

このようなログファイルを作成するにあたり、以下、2種類の方法が用意されています。

コマンド・キャプチャ: ビルドプロセスの一部として直接ログファイルを生成することができるかもしれません。例えば、makeシステムを実行する際に、それがエコーするコマンドをログファイルにリダイレクトすることができます。または、コンパイラを冗長モードで実行し、エコーされたコンパイラコマンドをログファイルにキャプチャするように設定することもできます。一部のビルドシステムは、例えば JSON Compilation Database のように、コンパイルのディレクティブを記録する自動的な仕組みを提供しています。

コンパイラ・モニタ: あるいは、Imagix 4Dのimagix-cc-monitorユーティリティを使用して、コンパイラの呼び出しを記録することができます。このユーティリティはシステムレベルのプロセスを監視します。ソースコードと共に使用しているコンパイラをユーティリティに識別させることで、すべてのコンパイラ呼び出しを認識し、ログファイルにキャプチャすることができます。詳細については、imagix-cc-monitorの実行を参照してください。

[makeログから抽出] の設定を適切に構成し、ビルドログを正常に処理すると、処理結果が保存され、Imagix 4Dに対してこれらの抽出結果を使用してソースコードを解析するよう指示できます。

2a. コンパイラコマンドを含むログファイルを生成する

注意: このステップ2aは、コマンドキャプチャの代替手法を使用する場合に適用されます。コンパイラモニタの代替手法については、imagix-cc-monitorユーティリティの実行に関する詳細が記載された付録Cを参照してください。結果のログファイルにはすべての必要なデータが含まれます。

MSBuild: コードをビルドする際に必要なmakelogを生成する詳細な手順については、Microsoft Buildログファイルを参照してください。結果のログファイルにはすべての必要なデータが含まれます。

[makeログから抽出] のアプローチでは、ソースコードのコンパイル中にビルドシステムが実行するコマンドが記録されたログファイルが必要です。これらのコマンドの中で最も重要なものは、コンパイラに対して実行されるものです。また、ディレクトリの変更を引き起こすコマンドも必要です。これにより、コンパイラに渡された相対パスから正確な絶対パスが計算できます。

このようなログファイルを作成するための具体的なプロセスは、ビルド環境によって大きく異なります。一部のビルド環境では、JSON Compilation DatabaseやNinjaビルドログの特定の形式など、特定のビルドレコードを明示的に作成します。[makeログから抽出] には、これらに対処するフィルタがあります。

それ以外の場合、コンパイルコマンドをキャプチャする具体的な手法が大きく異なるため、ここでは理論のみが提示されます。makeが実行されると、ビルドに必要な各コマンドラインが標準出力にエコーされ、それが実行されます。ログファイルを生成するための一般的なアプローチは、コードをコンパイルするmakeを呼び出し、エコーされたコマンドをファイルにキャプチャまたはリダイレクトすることです。現在、makeを -silent または -quiet タイプのオプションで実行している場合は、それらを無効にしてmakeコマンドがエコーされ、ログに記録できるようにする必要があります。ビルドシステムが実行しているコマンドをエコーするようにするために追加のオプションが必要な場合があります。

ログファイルの作成が完了した時点で、Imagix 4D のコード解析に必須となる要素がすべて、ログファイルに格納されていることを確認してください。ログファイルには、コンパイル対象のソースファイルを、すべて指定する必要があります。各コンパイル・コマンドが使用する、インクルード・ディレクトリおよびマクロ定義も明示しなければなりません。

ビルドログのコンパイルコマンドに必要な基本要素の簡略版を以下に示します。

compiler -I../dir1 -Dmacrodef sourcefile.c

次の簡単な例には（実際にログファイルに出力されることがあるかもしれませんが）重要な各要素が記されています。

make[2]: Entering directory `/home/fredn/projects/uclib/armv-gnueabi/drivers/power'
/usr/bin/gcc -g -Os -fno-strict-aliasing -fno-common -ffixed-r8 -msoft-float
    -D__KERNEL__ -DTEXT_BASE=0x80e80000 -I/home/fredn/armv-gnueabi/u-boot/include
    -isystem /home/fredn/armv-gnueabi/toolchain/lib/gcc/armv-gnueabi/4.4.5/include
    -fno-builtin -nostdinc -DCONFIG_ARM -D__ARM__ -march=armv5 -mno-thumb-interwork
    -Wall -Wstrict-prototypes -fno-stack-protector -o iex_power.o iex_power.c -c
make[2]: Leaving directory `/home/fredn/projects/uclib/armv-gnueabi/drivers/power'

上の例には、あらゆる必須項目が記述されており、数多くの追加オプションの中に挿入された要素を見て取ることができます。2行目の冒頭に表記された /usr/bin/gcc で、実際に存在するコンパイラ・コマンドが分かります。別の行ではソースファイルである iex_power.c が指定されており、-I インクルード・ディレクトリ・オプションと -D マクロ定義オプションも同様に指定されています。

最初と三番目の行も重要です。これらはソースファイルの場所を示しています。コンパイルコマンドがソースファイルまたはインクルードディレクトリのいずれかに絶対パスではなく相対パスを使用する場合、実際のディレクトリの場所を導出するために現在の作業ディレクトリの情報が必要です。

通常、キャプチャされたログファイルにはmakeシステムによって生成された多くのコマンドが含まれています。以下の [makeログから抽出] プロセスはフィルタとして機能し、ソースファイルとそれに関連するオプション、およびディレクトリのコンテキストに関する情報を抽出します。この抽出の結果はファイルに保存され、Imagix 4Dのソースアナライザが後でソースコードを解析する際に参照されます。

2b. 新しいデータソースの追加を指定

[データソース] ダイアログを開きます。既存のデータソースの設定を変更するのではなく、新しいデータソースをプロジェクトに追加したい場合は、ダイアログの左側にあるデータソースセレクタの下で [+ データソースを追加] を選択します。

2c. ビルドログからの抽出アプローチを選択

ステップ2の残りの部分では、[データソース] ダイアログの右側で作業します。上部で、[データソースの種類を選択] とラベル付けされたメニューボタンでから選択します。

MSBuildの場合: 代わりに [C/C++ソースファイル][Microsoft Visual Studio][MSBuildログ] から選択します。

2d. ログファイルの名前と開始ディレクトリを指定

[Makeログ] タブの [Makeログファイル] フィールドに、ログファイルのフルパス/ファイル名を入力します。

Makeログを処理する際、Imagix 4Dはこれらのパスがどのディレクトリに対して相対的であるかを知る必要があります。システムによって最初にMakeログが生成されたとき、パスは通常、Makeログの元の場所を基準にしています。ただし、そうでない場合や、Makeログを移動させた可能性があります。したがって、[開始ディレクトリ] フィールドを使用して相対パス名の初期ディレクトリを指定できます。

MSBuildの場合: Microsoftソリューション内の各プロジェクトに対してログファイルを指定する必要があります。これらのログファイルは通常、同じディレクトリに書き込まれます。これらのログファイルを簡単に指定できるようにするために、ディレクトリとログファイル自体を指定するための別々のフィールドがあります。[ログファイル] フィールドでは、複数のファイル名を入力し、ファイル名のグロブスタイルの一致に * 文字を使用できます。

2e. 追加のコンパイラ・オプションとソースアナライザ・オプションの指定

通常、[オプション] フィールドは空欄のままにします。ログファイルに記述される -I、-D、-U のコンパイラ・オプションは、すべて自動的に抽出されます。ただし、Imagix 4D でソースコードの解析時に求められるコンパイラ・オプションの一部が、ログファイルに記されていない場合には、ここでそれらのオプションを追記することが可能です。また、適用が必要な Imagix 4D ソースアナライザ・オプションも、追加できます（詳細は「アナライザの構文とオプション」のページを参照）。

2f. コンパイラ設定ファイルの選択

[コンパイラおよびターゲット] コンボ・ボックスにおいて、ステップ 1 でセットアップしたコンパイラ設定ファイルを選択します。ソフトウェアのコンパイラおよびターゲット・プラットフォーム用のコンパイラ設定ファイルを作成していない場合は、ここでその作業を行うことを強くお奨めします。

ステップ2gでは、複数のコンパイラのためのコンパイラディレクティブを抽出できることがわかります。複数のコンパイラを指定する場合、指定する名前がgccとg++のように同じコンパイラの異なる名前である可能性があります。この場合、1つのコンパイラ設定ファイルで読み込んでいるすべてのソースファイルをサポートできます。複数のコンパイラを指定していないか、もしくは指定しているコンパイラが同等で同じコンパイラ設定ファイルでサポートされている場合、この時点でステップ2fは完了しています。

ただし、お使いのソフトウェアビルドには複数の異なるコンパイラが組み込まれている可能性があり、したがって、ビルド内の異なるソースファイルに対しては異なるコンパイラ設定ファイルが適しているかもしれません。これに対処する方法は2つあります。

1つめの方法は、複数の [makeログから抽出] データソースを追加することです。各データソースについて、同じログファイルを使用し、異なるコンパイラとその適切なコンパイラ設定ファイルを指定します。その結果、プロジェクトは指定した各コンパイラ/データソースによってコンパイルされたすべてのソースファイルを対象とします。

2つめのアプローチは、#includeディレクティブを使用して適切な基本となる設定ファイルにリダイレクトする、マルチコンパイラ構成ファイルを作成することです。ログファイルを処理する際、Makeログデータからの抽出プロセスは、特定のソースファイルをコンパイルする際に使用された -D フラグを記録します。複数のコンパイラが指定されている場合、Makeログデータからの抽出プロセスはまた、そのソースファイルに使用されたコンパイラを示す追加の -D フラグも生成します。定義されるマクロは __IMGXCOMPILER_compiler_id の形式を取り、compiler_id は [コンパイラコマンド] フィールドで指定された特定のコンパイラの名前に基づいています。compiler_id 文字列は、コンパイラの名前の先頭を小文字にし、コンパイラの名前に含まれる非英数字文字をアンダースコア (_)に置き換えることで生成されます。

これらの -D フラグを使用して、マルチコンパイラのシンプルな構成ファイルを定義できます。以下の例は、GNU g++/gcc および Microsoft cl コンパイラの両方を使用するソフトウェアビルドをサポートするために作成できる、新しいコンパイラ構成ファイルの全内容を示しています。作成され、ここで指定された .inc ファイル（ステップ1を参照）は、少ない行で構成され、コンパイラ固有の .inc ファイルにリダイレクトされます。

#if defined(__IMGXCOMPILER_gcc) || defined(__IMGXCOMPILER_g__)
    #include "gnu_mingw32.inc"
#elif defined(__IMGXCOMPILER_cl)
    #include "msvc_win.inc"
#endif

2g. 処理ルールのレビューと修正

[処理ルール] タブには、ログファイルの解析方法と情報の抽出方法を制御する、一連のルールが表示されます。ルールをログファイルと突き合わせて見直すことにより、ログファイルのフォーマットに適合するルール設定を指定することができます。

MSBuildの場合: [処理ルール] タブの設定のほとんどは自動的に設定され、表示されるのはごく一部です。

これは反復プロセスの始まりであることに注意してください。ステップ2iでは、これらのルールを使用してログファイルを処理した結果を確認し、その後、ルールを改良するためにこのステップに戻ります。満足のいく結果が得られるまで、これを繰り返すことができます。

[処理ルール] タブは、さまざまなセクションに分割されています。

コンパイラ・コマンドが処理されるたび、指定された拡張子の1つで終了するコマンドラインにあるそれらの字句は、ソースファイルの名前の可能性があると見なされます。Imagix 4D は、コンパイラのようにソースファイルを解析し、その後、該当のソースファイルそのものによってインクルードされる、あらゆるヘッダファイルを取得します。このため、ヘッダファイルの拡張子を指定する必要はありません。

ログファイルを処理する際に、フィルタはコンパイラ・コマンドを参照している行を識別する必要があります。上図のように設定することで、ステップ 2a で示した参考例の2行目を、コンパイラ・コマンドとして認識します。これは参考例の2行目の冒頭に記述されている /usr/bin/gcc （パスを無視）が、ここで指定したコンパイラ・コマンドの中の１つに、一致するためです。

ログファイル内のコンパイラ名にcl.exeのようなサフィックスがある場合は、ここにリストされたコンパイラコマンドにそのサフィックスを含める必要があります。二つの設定オプションは、より複雑なログファイル内のコンパイラコマンドラインを識別するための追加サポートを提供します。複数のコンパイラを有効にする場合、ステップ2fに与える影響に注意してください。

コンパイラ・コマンドの実際のフォーマットは、使用する makeシステムや呼び出すコンパイラにより、非常にさまざまなものが存在します。コンパイラ・コマンドとして認識された時点で、フィルタによるログファイルの解析方法を決定する、数多くの設定が提供されています。

Windows 用コンパイラの多くは、"-Idirectory" や "-Dmacro" ではなく、"/I directory" や "/D macro" 形式のオプションを使用します。[コンパイラオプションの形式] の 2番目の設定を選択すると、そのようなコンパイラ・コマンドをログファイルから抽出し、Imagix 4D のオプションとして処理できるように変換することが可能です。

フィルタはコンパイラ・コマンドラインの字句それぞれを処理します。引数を取るオプションを認識することにより、フィルタは無意味な引数をスキップし、追加オプションなのかソースファイルの名前なのかを判断する余分なステップの実行を回避することができます。

また makeシステムとコンパイラでは、 -D マクロ定義の値におけるクォーテーション・マークの解釈および情報交換の方法にも、相違点があります。Imagix 4D ソースアナライザは文字列の代入の一部として、= の右側にあるクォーテーション・マークで囲われた値をすべてインクルードします。これが不適切な場合は、余分なクォーテーション・マークを削除することが可能です。

注: [ログファイルの処理] の設定は、[コマンド・キャプチャ] の方法を使用している場合に、適用されます。ログファイルのフォーマットを識別した上で、[コンパイラ・モニタ] を使用してログファイルを生成した場合、ディレクトリ先が記録されるため設定は無視されます。

追加の設定は、さまざまなビルドシステムによって生成される独自の形式をサポートするために、ログファイルの一般的な処理に対して利用可能です。

最も重要な設定は、指定されている場合のMakelogの前処理用フィルタです。利用可能な選択肢は、../imagix/user/data_srcsディレクトリに存在する.fltファイルを指します。例えば、JSON-Bear_CompDatabase.fltは、JSONコンパイルデータベースからのコンパイラコマンドをImagix 4DのMakelogアナライザがサポートする形式に変換します。これには、個々のマクロ定義、インクルードディレクトリ、およびソースファイルエントリをImagix 4Dアナライザが必要とする単一行に結合することが含まれます。また、Ninja-Soong_Buildlog.fltは、Android Open Source Project (AOSP)で使用されるSoongビルドシステムのコマンドライン出力をサポートし、AOSPディレクトリのどれをImagix 4Dプロジェクトにロードするかを制限するオプションが含まれています。

これらの前処理フィルタは、実際には中間ファイルを生成し、次にImagix 4Dプロセッサがそれを解析します。これらの中間ファイルは../project.4D/datasourcesディレクトリに書き込まれ、そこで確認できます。詳細は../imagix/user/data_srcs/data_srcs_inventory.txtを参照してください。

ログファイル処理セクションの残りの設定は、Imagix 4Dプロセッサがログファイルを直接解析する方法を設定するために使用されます。

特定のトークンで始まる行全体をスキップすることができます。改行によって分割された長い行を含むログファイルでは、手動の介入なしに分割された行を再結合することができます。「&&」で結合された2つ以上の論理行からなる単一の物理行を持つログファイルでは、処理中にそれらの論理行を別々の行として解析することができます。

多くのケースにおいて、ログファイルに出力されるソースファイルや -I インクルード・ディレクトリ・オプションには、相対パスが使用されます。そのような場合には、ログファイルの解析で各コンパイラ・コマンドに関連するディレクトリ先を、追跡する必要があります。フィルタは、 "Entering directory"、"Leaving directory"、"START"、"END" が記述されたログファイルの行を、ディレクトリの移動を示すものとして処理します。また、ディレクトリの移動を指示するコマンドを追加指定することも可能です。上図では "cd" が追加で指定されいます。また、それらのディレクトリの移動コマンドの処理方法を制御することもできます。

ディレクトリ先を追跡する際に、ログファイルが格納されているディレクトリは、相対パスの開始ディレクトリとして認識されます。相対パスの開始ディレクトリを明示させるためログファイルの冒頭に、例えば "Entering directory c:\starting\dir" のように、ディレクトリの移動コマンドを手動で追記することも可能です。

認識していないオプションに直面すると、Imagix 4D のソースアナライザは、そのオプションをマクロ定義に変換します。例えば、オプション "-opt" は "-D__IMGX_opt__" に変換されます。変換されたマクロ定義は、コンパイラ設定ファイルでロジックを制御するために使用されます。フィルタ設定により、このような認識されないオプションをソースアナライザに渡すか否かを、管理することが可能です。

Makelogには同じソースファイルに対する複数のエントリが含まれている場合がありますが、Imagix 4Dプロジェクトでは通常、各ソースファイルを一度だけ解析します。しかし、単一のソースファイルが異なるマクロ定義で複数回コンパイルされ、その各フラグセットでの解析をプロジェクトに反映させたい場合があります。プロセッサをこのように設定することができ、その場合、通常は [オプション] タブで [採用されたすべての条件付き取り込みのパスデータを生成] を有効にします。この設定は、サンプリングアプローチの結果として重複エントリが予期されるimagix-cc-monitorのログファイルを使用している場合は無視されます。

別のコンピュータや別のオペレーティングシステムでログファイルを生成した場合でも、Imagix 4Dのパス置換を使用してディレクトリパスを修正し、現在の環境に存在するソースファイルやインクルードディレクトリにマッピングすることができます。有効にすると、以前に定義されたディレクトリマッピングの置換が適用されます。

2h. ログファイルの処理

以上により、ログファイルを処理する準備が整いました。ダイアログの下部にある [Makeログを処理] をクリックしてください。

2i. ログファイルの出力結果のレビューと処理ルールの改善

Imagix 4D には、ログファイルの処理結果のレビューに使用するフィードバック用のソースが、いくつか用意されています。

最初に表示されるのは、処理中に識別されたソースファイルの数を、ファイルシステム内で見つかったものと見つからなかったものに分けてリストするダイアログです。このダイアログでは、プロジェクト設定を生成することができます。生成を選択すると、このデータソースに対して以前に生成された設定は、新しい処理から派生した設定に置き換えられます。

特に有用なのは、[データソース] ダイアログの右側に表示される [ステータス] タブからログファイル処理を呼び出した場合に生成される抽出ログです。これらのログは、Imagix 4Dプロジェクトのdatasourcesディレクトリ（ステップ4a）にあるextract_xxx.logというタイトルの一連のファイルです。個別のログには、コンパイラアクション、コンパイラの詳細、ディレクトリ変更アクション、プロセス警告が含まれています。これらのログは [ステータス] タブからアクセスできます。

ログファイルの出力結果のレビューとルールの修正は、反復的な処理となります。これにはユーザによる解析と、論理的な結論を導き出すことが要求されるのです。そこで、この作業をより容易にする方法を、以下に示します。

ソースファイルの特定

まず始めに、ログファイルで参照されるソースファイルを特定することに焦点を置きます。

ソースファイルが見つからない場合は、[コンパイラ] ログを参照してください。このログには、コンパイラの起動コマンドとして認識された、ログファイルの各行が示されています。それでもコンパイラの起動コマンドが見つからない場合は、ログファイルを調べてください。ここで手動によりコンパイラの起動コマンドを特定できない場合は、ログファイルの再生成が必要となることがあります（ステップ 2a を参照）。コンパイラの起動行が存在するものの、[コンパイラ] ログに従いその行が特定されていない際は、[コンパイラの呼出し] ルールをチェックしてください。指定したコンパイラ・コマンドが、ログファイルに出力されたコマンドと一致していることを確認します。また、[行頭の無視すべきコマンド] ルールの修正が必要となることもあります。

しかしながら、コンパイラの起動コマンドが検出されたのにもかかわらず、まだソースファイルが見つからない場合には、「ソースファイルの接尾語」ルールと起動コマンドの拡張子を比較してください。

コンパイラ・オプションの識別

ソースファイルの特定が適切になされた上で、コンパイラ・オプションの抽出箇所をレビューします。

この際 [コンパイラの詳細] ログを調べることが、特に効果的な方法と言えます。ログファイルの実際の行を、そこから派生したオプションと比較することが可能です。オプションが不足していたり、オプションのフォーマットが希望するものと異なったりする場合には、[コンパイラオプション] ルールを修正してください。

また、[警告] ログも、有効に活用できることがあります。コンパイラ行に「unrecognized arg」のリストが表示されている場合、オプションのフォーマットを変更する必要があるか、一部のオプションが [引数を取るコンパイラオプション] ルールに登録されていない可能性があります。

パスの調整

最後の手順として、パスをレビューし解決します。

ソースファイルの名前と、それに関連付けられた -I、-D、-U オプションを特定する以外に、抽出処理ではディレクトリ先が追跡されるため、ソースファイルとインクルード・ディレクトリの双方に対する相対パスを解決することが可能です。Compiler Monitor を使用しているケースでは、ディレクトリの場所は自動的に記録されますが、[コマンド・キャプチャ] を適用している場合には、[ログファイルの処理] セクションの設定を、変更する必要が生じることがあります。

CD ログからは、今後の相対ディレクトリの計算に使用されるベースを変更するものとして特定された、ログファイルの行を把握することができます。cd を呼び出す行が存在しない場合には、[ディレクトリ変更コマンド] ルールを確認してください。cd の呼び出し行に相対パスが含まれている時は、適切なパスを割り出すため [相対パス付きのディレクトリ変更コマンドを処理] ルールを選択します。

Summary of build ログの処理において、ファイルシステムでの検出を差し置き、他のソースファイルを特定中であることを未だに示す際は [警告] ログを参照し、ファイルシステム内で検出できないファイルを特定します。次に、検出できない原因が、実際にファイルが存在しないのか、あるいは処理中にファイルパスが適切に解決されなかったのかを、判断する必要があります。後者の場合は、[ディレクトリ変更] ルールを修正してください。

両方の代替案に関する最後の注意点として、パスについて述べます。Imagix 4Dによる解析のためのソースコードが、ログファイルを生成した時点とは異なる場所にある可能性があります。これは、解析に使用するプラットフォームがコンパイルに使用するプラットフォームと異なる場合など、さまざまな理由で発生する可能性があります。ログファイルに絶対パスではなく相対パスが含まれている場合、ステップ2dで異なる開始ディレクトリを指定することで成功する可能性があります。また、ログファイルに絶対パスが含まれている場合、[ファイル] > [オプション] ダイアログの [データ収集] セクションで [ディレクトリマッピング] 設定を使用してパスの置換を行うことができます。

2j. 解析プロセスの開始

ログファイルの出力結果のレビューとルールの修正は、反復的な処理となります。ルールを修正し（ステップ 2g）ログファイルを処理（ステップ 2h）するたびに、レビューを実施するため新しい出力結果を生成します。最初のうちは、レビューにより再度ルールの改善と、ログファイルの（再）処理の必要性を決定づける、十分な根拠が提示されます。

ある時点で、処理ルールが十分に改善されていると判断し、出力結果となるダイアログ・ベースの（C / C++）データソース定義によって、どの程度適切にソースコードが解析されるのかを確認する必要が生じることがあります。これは何度でも実行できるステップです。後で 2g あるいは 2a に戻り、ステップ 2 固有の繰り返し処理を継続することが可能です。

コードを解析するために生成された [ダイアログベース (C/C++)] データソース定義を適用する準備ができたら、ダイアログの下部にある [データソースを読み込み] クリックします。