主要内容

使用 STF_make_rtw_hook 文件自定义编译过程

R2026b

在编译过程中,您可以在代码生成和联编过程中的指定点执行的钩子方法中提供可选的自定义代码。您可以使用钩子方法将特定于目标的操作添加到编译过程中。

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:模板联编文件的名称。

  • buildOpts:包含布尔字段 codeWasUpToDate 的 MATLAB 结构体。仅在 'before_make'、'after_make' 和 'exit' 阶段有效。

  • buildArgs:包含 make_rtw 的参量的字符向量。当您调用编译过程时,将复制配置参数 + 代码生成 + Make 命令字段中 "make_rtw" 后面的参量,以此作为 buildArgs。

    例如,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' 钩子的用途之一是重新运行最初在目标选择时间运行的自动配置脚本,从而对执行脚本前后的模型参数进行比较,以实现验证目的。

其他钩子点('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 控制代码重新生成

重新编译模型时,默认情况下编译过程将执行一些检查,以确定对模型或相关设置所做的更改是否需要重新生成顶层模型代码。(有关判定标准的详细信息,请参阅Control Regeneration of Top Model Code。)如果检查确定需要生成顶层模型代码,编译过程将重新生成并编译所有模型代码。如果检查发现为顶层模型生成的代码对模型来说是最新的代码,而且模型设置不要求完全重新生成,则编译过程将不会重新生成顶层模型代码。

无论是否重新生成顶层模型代码,编译过程随后都会调用编译过程钩子,包括 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 钩子文件,请复制并编辑此示例文件:

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

使用以下步骤:

  1. 将 grt_make_rtw_hook.m 复制到 MATLAB 路径中的一个文件夹。根据STF_make_rtw_hook 文件的使用约定中所述的命名约定重命名该文件。

  2. 重命名此文件中的 grt_make_rtw_hook.m 函数以便与文件名匹配。

  3. 通过在 switch hookMethod 语句的 case 语句中添加代码,实现您需要的钩子。

钩子方法 after_tlc

after_tlc 钩子方法仅为向后兼容而提供。

在 after_tlc 阶段生成的代码的格式不是最终格式。

另请参阅

主题