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.
You can modify hook methods in a file generically referred to as
is the name of a system
target file, such as
file implements a function,
, that dispatches
to a specific action, depending on the
hookMethod argument passed
The build process calls
, 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
reference model as required. The build process calls each
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
, check that the
following conditions are met:
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
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
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
function is called. The following flow chart summarizes the build process, highlighting the hook points. Valid values for
function dispatches to the relevant code with a
modelName: Character vector specifying the name of the model. Valid at all stages of the build process.
templateMakefile: Name of template makefile.
buildOpts: A MATLAB structure that contains the Boolean field
codeWasUpToDate. Valid for the
buildArgs: Character vector containing the argument to
make_rtw. When you invoke the build process,
buildArgsis 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
buildArgsargument does not apply for toolchain approach builds because these builds do not allow adding make arguments to the
make_rtwcall. 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.
RTW.BuildInfoobject that contains information for compiling and linking generated code. Available only for the
'exit'stages. The information in the object at the end of the
'after_tlc'stage might not be complete. In later stages, the
'after_make'hook methods can also add information to the object. For more information about using the
RTW.BuildInfoobject, see Code Compilation Customization.
Applications for STF_make_rtw_hook.m
This section shows how you can use the
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
The other hook points,
'error' are useful for interfacing with external tool chains,
source control tools, and other environment tools.
For example, you can use the
file at a
'entry' to obtain the path to the build folder. At
'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.
The build process temporarily changes the MATLAB working folder to the build folder for stages
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 = rtwprivate('get_makertwsettings',gcs,'BuildDirectory');
Do not use the
change the model configuration. For example, do not use a hook method to:
Switch between model variants.
Changing the model configuration might produce unexpected code generation results.
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
and the post code generation command. The following mechanisms allow you to perform
actions related to code regeneration in the
To force code regeneration, use the following function call from the
In hooks from
buildOptsstructure passed to the hook has a Boolean field
codeWasUpToDate. The field is set to
trueif model code was up to date and code was not regenerated, or
falseif 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
hook file for your build procedure, copy and edit the example
ert_make_rtw_hook.m file, which is located in the
(open), as follows:
ert_make_rtw_hook.mto 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
ert_make_rtw_hookfunction within the file to match the file name.
Implement the hooks that you require by adding code to case statements within the
after_tlc hook method is available solely for backwards
The format of the generated code during the
after_tlc stage is
not the final format.