Customize Build Process with STF_make_rtw

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 the example ert_make_rtw_hook.m file, which is located in the foldermatlabroot/toolbox/coder/embeddedcoder (open), as follows:

Copy ert_make_rtw_hook.m to a folder in the MATLAB path. Rename it in accordance with the naming conventions described in Conventions for Using the STF_make_rtw_hook File. For example, to use it with the GRT target grt.tlc, rename it to grt_make_rtw_hook.m.
Rename the ert_make_rtw_hook 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.