STF_make_rtw_hook ファイルによるビルドプロセスのカスタマイズ

ビルドプロセスでは、コード生成と make プロセスの特定の時点で実行されるフックメソッドに、オプションのカスタムコードを追加できます。フックメソッドを使用してターゲット固有の行動をビルドプロセスに追加することができます。

STF_make_rtw_hook ファイル

一般に STF_make_rtw_hook.m と呼ばれるファイル内のフックメソッドは変更できます。この STF はシステムターゲットファイルの名前です (たとえば、ert や mytarget など)。このファイルは関数 STF_make_rtw_hook を実装します。この関数は渡された hookMethod 引数に依存し、特定の行動を送信します。

ビルドプロセスは STF_make_rtw_hook を呼び出し、引数 hookMethod などの引数を渡します。ビルドプロセスに必要なフックメソッドのみを実装してください。

モデルに参照モデルが含まれている場合は、必要に応じて参照モデルごとに STF_make_rtw_hook.m を実装できます。ビルドプロセスは参照モデルごとにそれぞれ STF_make_rtw_hook を呼び出し、これらのファイルを (依存関係の順に) 再帰的に処理します。

STF_make_rtw_hook ファイルの使用に関する規則

ビルドプロセスが必ず STF_make_rtw_hook を呼び出すように、以下の条件が満たされていることを確認します。

STF_make_rtw_hook.m ファイルが MATLAB^® パス上にあること。
ファイル名がシステムターゲットファイル (STF) の名前であり、テキスト _make_rtw_hook.m に付加されていること。たとえば、カスタムのシステムターゲットファイル mytarget.tlc でコードを生成する場合、フックファイルの名前は mytarget_make_rtw_hook.m とし、そのファイル内で実装されたフック関数の名前は mytarget_make_rtw_hook とします。
ファイル内で実装されたフック関数が関数プロトタイプ STF_make_rtw_hook.m と引数で説明する関数プロトタイプを使用すること。

関数プロトタイプ STF_make_rtw_hook.m と引数

STF_make_rtw_hook 用の関数プロトタイプは、次のとおりです。

function STF_make_rtw_hook(hookMethod, modelName, rtwRoot, templateMakefile,
buildOpts, buildArgs, buildInfo)

引数は、次のように定義されます。

hookMethod:関数 STF_make_rtw_hook が呼び出されるビルドプロセスの段階を指定する文字ベクトル。以下のフローチャートはビルドプロセスをまとめたもので、フック点を強調表示しています。hookMethod 用の有効値は、'entry'、'before_tlc'、'after_tlc'、'before_make'、'after_make'、'exit'、'error' です。関数 STF_make_rtw_hook は switch ステートメントで関連コードへ送信します。

modelName:モデルの名前を指定する文字ベクトル。ビルドプロセスのすべての段階で有効です。
rtwRoot:予備。
templateMakefile:テンプレート makefile の名前。
buildOpts:Boolean のフィールド codeWasUpToDate が含まれている MATLAB 構造体。'before_make'、'after_make'、'exit' 段階のみで有効です。
buildArgs:make_rtw への引数が含まれる文字ベクトル。ビルドプロセスを呼び出すと、buildArgs は [コンフィギュレーションパラメーター] + [コード生成] + [make コマンド] フィールド内で "make_rtw" に続く引数からコピーされます。
たとえば、次の [make コマンド] フィールドの make 引数
```
make_rtw VAR1=0 VAR2=4
```
は、以下を生成します。
```
% make -f untitled.mk VAR1=0 VAR2=4
```
buildArgs 引数がツールチェーンアプローチのビルドに適用されないのは、これらのビルドが make_rtw 呼び出しに make 引数を追加することができないためです。コンパイラコマンドラインで、TMF アプローチのビルドとツールチェーンアプローチのビルドの両方に適用されるカスタム定義 (たとえば、VAR1=0 VAR2=4) を指定するには、[コンフィギュレーションパラメーター] 、 [コード生成] 、 [カスタムコード] 、 [定義] フィールドを使用します。
buildInfo:生成されたコードのコンパイルとリンクに関する情報を格納する RTW.BuildInfo オブジェクト。'after_tlc'、'before_make'、'after_make'、'exit' 段階のみで有効です。'after_tlc' 段階の終了時、このオブジェクト内の情報は完了していない可能性があります。さらに後の段階では、'before_make' および 'after_make' フックメソッドもオブジェクトに情報を追加できます。RTW.BuildInfo オブジェクトの使用方法の詳細については、コードコンパイルのカスタマイズを参照してください。

STF_make_rtw_hook.m の応用

この節では、STF_make_rtw_hook.m フックメソッドを使用する方法を説明します。

通常、'entry' フックを使用してビルドプロセスを初期化し、コードを生成する前に、たとえば、設定を変更したり有効にしたりすることができます。'entry' フックの応用の 1 つは、ターゲットの選択時に最初に起動した自動コンフィギュレーションスクリプトを再度実行し、スクリプトが認証を実行する前と後のモデルパラメーターを比較することです。

他のフックポイント 'before_tlc'、'after_tlc'、'before_make'、'after_make'、'exit'、'error' は、外部のツールチェーン、ソース管理ツール、および他の環境ツールとインターフェイスする際に役立ちます。

たとえば、'entry' 後の段階で STF_make_rtw_hook.m ファイルを使用し、ビルドフォルダーへのパスを取得することができます。それから 'exit' 段階で、ビルドフォルダー内で生成コードファイルを見つけ、それらをバージョン制御システム内にチェックインすることができます。コード生成中またはビルドプロセス時にエラーが発生する場合は、'error' を使用して、フック関数が使用した静的データまたはグローバルデータをクリーンアップすることができます。

メモ

ビルドプロセスは MATLAB 作業フォルダーを一時的に段階 'before_make'、'after_make'、'exit'、'error' 用のビルドフォルダーに変更します。STF_make_rtw_hook.m ファイルはビルドフォルダーの位置に関して誤った仮定をしてはなりません。'entry' 段階後、ビルドフォルダーへのパスを取得することができます。以下の MATLAB コード例では、ビルドフォルダーパスは変数 buildDirPath に文字ベクトルとして返されます。

buildDirPath = rtwprivate('get_makertwsettings',gcs,'BuildDirectory');

メモ

モデルコンフィギュレーションの変更には、STF_make_rtw_hook.m ファイルを使用しないでください。たとえば、以下にはフックメソッドを使用しないでください。

モデルバリアント間の切り替え。
関数 set_param の呼び出し。

モデルコンフィギュレーションを変更すると、予期しないコード生成結果となる可能性があります。

STF_make_rtw_hook.m を使用したコード再生成の制御

モデルをリビルドするとき、既定の設定では、ビルドプロセスはモデルまたは関連する設定の変更によって、最上位モデルの再生成が必要かどうかを判断するために、チェックを実行します。(詳細については、最上位モデルコードの再生成の制御を参照)。チェック結果が最上位モデルコードの生成が必要であることを示している場合は、ビルドプロセスはモデルコードの完全な再生成とコンパイルを実行します。チェック結果が、最上位モデルの生成コードがモデルに対して最新であり、モデル設定に完全な再生成が必要ないことを示している場合、ビルドプロセスは最上位モデルコードの再生成を省略します。

最上位モデルコードが再生成されたかどうかに関わりなく、ビルドプロセスは続けて関数 STF_make_rtw_hook やコード生成後のコマンドを含むビルドプロセスフックを呼び出します。次のメカニズムにより、関数 STF_make_rtw_hook のコード再生成に関連するアクションを実行できます。

強制的にコードを再生成するには、'entry' フックから次の関数呼び出しを使用します。
```
rtw.targetNeedsCodeGen('set', true);
```
'before_tlc' から 'exit' までのフックでは、フックに渡される buildOpts 構造体には論理値のフィールド codeWasUpToDate があります。このフィールドは、モデルコードが最新の状態であったために再生成されなかった場合に true にセットされます。コードが最新の状態ではなく再生成が必要だった場合には、false になります。このフィールドの値に基づいてフック処理をカスタマイズできます。以下に例を示します。
```
...
case 'before_tlc'
    if buildOpts.codeWasUpToDate
        %Perform hook actions for up to date model
    else
        %Perform hook actions for full code generation
    end
...
```

ビルドプロセス用に STF_make_rtw_hook.m を使用

ビルドプロセス用にカスタムの STF_make_rtw_hook フックファイルを作成するには、matlabroot/toolbox/coder/embeddedcoder (開く) フォルダーに配置されている例ファイル ert_make_rtw_hook.m を以下のようにコピーして編集します。

ert_make_rtw_hook.m を MATLAB パスのフォルダーにコピーします。STF_make_rtw_hook ファイルの使用に関する規則で説明する命名規則に従ってその名前を変更します。たとえば、GRT ターゲット grt.tlc でそれを使用する場合は、その名前を grt_make_rtw_hook.m に変更します。
ファイル内で関数 ert_make_rtw_hook の名前を変更して、ファイル名と一致させます。
switch hookMethod ステートメント内のケースステートメントにコードを追加することにより、必要なフックを実装します。

フックメソッド `after_tlc`

after_tlc フックメソッドは、下位互換性のためにのみ提供されています。

after_tlc 段階の生成コードの形式は最終的な形式ではありません。