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 フックファイルを作成するには、次の例のファイルをコピーして編集します。

grt_make_rtw_hook.m

function grt_make_rtw_hook(hookMethod, ...
                           modelName, ...
                           rtwroot, ...
                           templateMakefile, ...
                           buildOpts, ...
                           buildArgs, ...
                           buildInfo) %#ok<INUSL,INUSD> 
% GRT_MAKE_RTW_HOOK - This is an example GRT hook file for the build
% process (make_rtw).
%
% This hook file (i.e., file that implements various codegen callbacks) is
% called for system target file grt.tlc.  The file leverages
% strategic points of the build process.  A brief synopsis of the callback
% API is as follows:
%
% grt_make_rtw_hook(hookMethod, modelName, rtwroot, templateMakefile,
%                   buildOpts, buildArgs, buildInfo)
%
% hookMethod:
%   Specifies the stage of the build process.  Possible values are
%   entry, before_tlc, after_tlc, before_make, after_make and exit, etc.
%
% modelName:
%   Name of model.  Valid for all stages.
%
% rtwroot:
%   Reserved.
%
% templateMakefile:
%   Name of template makefile.  Valid for stages 'before_make' and 'exit'.
%
% buildOpts:
%   Valid for stages 'before_make' and 'exit', a MATLAB structure
%   containing fields
%
%   modules:
%     Char array specifying list of generated C files: model.c, model_data.c,
%     etc.
%
%   codeFormat:
%     Char array containing code format: 'RealTime', 'RealTimeMalloc',
%     'Embedded-C', and 'S-Function'
%
%   noninlinedSFcns:
%     Cell array specifying list of non-inlined S-Functions.
%
% buildArgs:
%   Char array containing the argument to make_rtw.  When pressing the build
%   button through the Configuration Parameter Dialog, buildArgs is taken
%   verbatim from whatever follows make_rtw in the make command edit field.
%   From MATLAB, it is whatever is passed into make_rtw.  For example, its
%   'optimized_fixed_point=1' for make_rtw('optimized_fixed_point=1').
%
% buildInfo: 
%   An RTW.BuildInfo object containing information for compiling and 
%   linking generated code. Available for the 'after_tlc', 'before_make', 
%   'after_make', and 'exit' stages only.
%
% Copyright 2024 The MathWorks, Inc.
  
  switch hookMethod
   case 'error'
    % Called if an error occurs anywhere during the build.  If no error occurs
    % during the build, then this hook will not be called.  Valid arguments
    % at this stage are hookMethod and modelName. This enables cleaning up
    % any static or global data used by this hook file.
    
   case 'entry'
    % Called at start of code generation process (before anything happens.)
    % Valid arguments at this stage are hookMethod, modelName, and buildArgs.    
    
   case 'before_tlc'
    % Called just prior to invoking TLC Compiler (actual code generation.)
    % Valid arguments at this stage are hookMethod, modelName, and
    % buildArgs
    
   case 'after_tlc'
    % Called just after to invoking TLC Compiler (actual code generation.)
    % Valid arguments at this stage are hookMethod, modelName, and
    % buildArgs
   case 'before_make'
    % Called after code generation is complete, and just prior to kicking
    % off make process (assuming code generation only is not selected.)  All
    % arguments are valid at this stage.
   case 'after_make'
    % Called after make process is complete. All arguments are valid at 
    % this stage.
    
   case 'exit'
    % Called at the end of the build process.  All arguments are valid
    % at this stage.
    
  end

以下の手順に従います。

grt_make_rtw_hook.m を MATLAB パス上のフォルダーにコピーします。STF_make_rtw_hook ファイルの使用に関する規則で説明する命名規則に従ってファイル名を変更します。
ファイル内で grt_make_rtw_hook.m 関数の名前を変更して、ファイル名と一致させます。
switch hookMethod ステートメント内の case ステートメントにコードを追加することにより、必要なフックを実装します。

フックメソッド `after_tlc`

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

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

参考

トピック

sl_customization.m によるビルドプロセスのカスタマイズ