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).
For the build process to call the
, check that the
following conditions are met:
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
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.
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
is called. The following flow chart summarizes the build process,
highlighting the hook points. Valid values for
dispatches to the relevant code with a
modelName: Character vector specifying the name of the
model. Valid at all stages of the build
templateMakefile: Name of template makefile.
buildOpts: A MATLAB structure that contains the Boolean field
codeWasUpToDate. Valid for the
'exit' stages only. The
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
buildArgs argument does not apply for toolchain
approach builds because these builds do not allow adding make arguments to
make_rtw call. On the compiler command line, to
provide custom definitions (for example,
that apply for both TMF approach and toolchain approach builds, use the Configuration Parameters > Code Generation > Custom Code > Defines field.
buildInfo: The MATLAB structure that contains the model build information fields.
Valid for the
'exit' stages only. For information about these
fields and functions to access them, see Build Process Customization.
Here are some examples of how to apply the
In general, you can 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 could use the
file at a
'entry' to obtain the path to the build folder. At
'exit' stage, you could 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');
A change to model configuration within
(including switching Variants) might lead to unexpected results in code
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
passed to the hook has a Boolean field
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 ...
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.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
rename it to
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.