Customize Build Process with STF_make_rtw_hook File

The build process lets you supply optional custom code in hook methods that are executed at specified points in the code generation and make process. You can use hook methods to add target-specific actions to the build process.

STF_make_rtw_hook File

You can modify hook methods in a file generically referred to as STF_make_rtw_hook.m, where STF is the name of a system target file, such as ert or mytarget. This file implements a function, STF_make_rtw_hook, that dispatches to a specific action, depending on the hookMethod argument passed in.

The build process calls STF_make_rtw_hook, passing in the hookMethod argument and other arguments. You implement only those hook methods that your build process requires.

If your model contains reference models, you can implement an STF_make_rtw_hook.m for each reference model as required. The build process calls each STF_make_rtw_hook for reference models, processing these files recursively (in dependency order).

Conventions for Using the STF_make_rtw_hook File

For the build process to call the STF_make_rtw_hook, check that the following conditions are met:

The STF_make_rtw_hook.m file is on the MATLAB^® path.
The file name is the name of your system target file (STF), appended to the text _make_rtw_hook.m. For example, if you generate code with a custom system target file mytarget.tlc, name your hook file mytarget_make_rtw_hook.m, and name the hook function implemented within the file mytarget_make_rtw_hook.
The hook function implemented in the file uses the function prototype described in STF_make_rtw_hook.m Function Prototype and Arguments.

STF_make_rtw_hook.m Function Prototype and Arguments

The function prototype for STF_make_rtw_hook is:

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

The arguments are defined as:

hookMethod: Character vector specifying the stage of build process from which the STF_make_rtw_hook function is called. The following flow chart summarizes the build process, highlighting the hook points. Valid values for hookMethod are 'entry', 'before_tlc', 'after_tlc', 'before_make', 'after_make', 'exit', and 'error'. The STF_make_rtw_hook function dispatches to the relevant code with a switch statement.

modelName: Character vector specifying the name of the model. Valid at all stages of the build process.
rtwRoot: Reserved.
templateMakefile: Name of template makefile.
buildOpts: A MATLAB structure that contains the Boolean field codeWasUpToDate. Valid for the 'before_make', 'after_make', and 'exit' stages only.
buildArgs: Character vector containing the argument to make_rtw. When you invoke the build process, buildArgs is copied from the argument following "make_rtw" in the Configuration Parameters + Code Generation + Make command field.
For example, the following make arguments from the Make command field
```
make_rtw VAR1=0 VAR2=4
```
generate the following:
```
% make -f untitled.mk VAR1=0 VAR2=4
```
The buildArgs argument does not apply for toolchain approach builds because these builds do not allow adding make arguments to the make_rtw call. On the compiler command line, to provide custom definitions (for example, VAR1=0 VAR2=4) that apply for both TMF approach and toolchain approach builds, use the Configuration Parameters > Code Generation > Custom Code > Defines field.
buildInfo: The RTW.BuildInfo object that contains information for compiling and linking generated code. Available only for the 'after_tlc', 'before_make', 'after_make', and 'exit' stages. The information in the object at the end of the 'after_tlc' stage might not be complete. In later stages, the 'before_make' and 'after_make' hook methods can also add information to the object. For more information about using the RTW.BuildInfo object, see Code Compilation Customization.

Applications for STF_make_rtw_hook.m

This section shows how you can use the STF_make_rtw_hook.m hook methods.

In general, use the 'entry' hook to initialize the build process, for example, to change or validate settings before code is generated. One application for the 'entry' hook is to rerun the auto-configuration script that initially ran at target selection time to compare model parameters before and after the script executes, for validation purposes.

The other hook points, 'before_tlc', 'after_tlc', 'before_make', 'after_make', 'exit', and 'error' are useful for interfacing with external tool chains, source control tools, and other environment tools.

For example, you can use the STF_make_rtw_hook.m file at a stage after 'entry' to obtain the path to the build folder. At the 'exit' stage, you can then locate generated code files within the build folder and check them into your version control system. You can use 'error' to clean up static or global data used by the hook function when an error occurs during code generation or the build process.

Note

The build process temporarily changes the MATLAB working folder to the build folder for stages 'before_make', 'after_make', 'exit', and 'error'. Your STF_make_rtw_hook.m file must not make incorrect assumptions about the location of the build folder. At a point after the 'entry' stage, you can obtain the path to the build folder. In the following MATLAB code example, the build folder path is returned as a character vector to the variable buildDirPath.

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

Note

Do not use the STF_make_rtw_hook.m file to:

Change the model configuration. For example, do not use a hook method to:
- Switch between model variants.
- Call the set_param function.
Changing the model configuration might produce unexpected code generation results.
Run commands that compile the model. Compiling the model might produce unexpected behavior.

Control Code Regeneration Using STF_make_rtw_hook.m

When you rebuild a model, by default, the build process performs checks to determine whether changes to the model or relevant settings require regeneration of the top model code. (For details on the criteria, see Control Regeneration of Top Model Code.) If the checks determine that top model code generation is required, the build process fully regenerates and compiles the model code. If the checks indicate that the top model generated code is current with respect to the model, and model settings do not require full regeneration, the build process omits regeneration of the top model code.

Regardless of whether the top model code is regenerated, the build process subsequently calls the build process hooks, including STF_make_rtw_hook functions and the post code generation command. The following mechanisms allow you to perform actions related to code regeneration in the STF_make_rtw_hook functions:

To force code regeneration, use the following function call from the 'entry' hook:
```
rtw.targetNeedsCodeGen('set', true);
```
In hooks from 'before_tlc' through 'exit', the buildOpts structure passed to the hook has a Boolean field codeWasUpToDate. The field is set to true if model code was up to date and code was not regenerated, or false if code was not up to date and code was regenerated. You can customize hook actions based on the value of this field. For example:
```
...
case 'before_tlc'
    if buildOpts.codeWasUpToDate
        %Perform hook actions for up to date model
    else
        %Perform hook actions for full code generation
    end
...
```

Use `STF_make_rtw_hook.m` for Your Build Procedure

To create a custom STF_make_rtw_hook hook file for your build procedure, copy and edit this example file:

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

Use these steps:

Copy grt_make_rtw_hook.m to a folder on the MATLAB path. Rename the file in accordance with the naming conventions described in Conventions for Using the STF_make_rtw_hook File.
Rename the grt_make_rtw_hook.m function within the file to match the file name.
Implement the hooks that you require by adding code to case statements within the switch hookMethod statement.

Hook Method `after_tlc`

The after_tlc hook method is available solely for backwards compatibility.

The format of the generated code during the after_tlc stage is not the final format.