Real-Time Workshop® Embedded Coder™

Customizing the Target Build Process with the STF_make_rtw Hook File

Overview

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

This section describes an important M-file hook, 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 hook file implements a function, STF_make_rtw_hook, that dispatches to a specific action, depending on the hookMethod argument passed in.

The build process automatically calls STF_make_rtw_hook, passing in the correct hookMethod argument (as well as other arguments described below). You need to implement only those hook methods that your build process requires.

Back to Top

File and Function Naming Conventions

To ensure that STF_make_rtw_hook is called correctly by the build process, you must ensure that the following conditions are met:

• The STF_make_rtw_hook.m file is on the MATLAB path.

• The filename is the name of your system target file (STF), appended to the string _make_rtw_hook.m. For example, if you were generating code with a custom system target file mytarget.tlc, you would name your STF_make_rtw_hook.m file to mytarget_make_rtw_hook.m. Likewise, the hook function implemented within the file should follow the same naming convention.

• The hook function implemented in the file follows the function prototype described in the next section.

Back to Top

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)

The arguments are defined as:

• hookMethod: String specifying the stage of build process from which the STF_make_rtw_hook function is called. The flowchart below 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: String 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 containing the fields described in the list below. Valid for the 'before_make', 'after_make', and 'exit' stages only. The buildOpts fields are

  • modules: Character array specifying a list of additional files that need to be compiled.

  • codeFormat: Character array containing code format specified for the target. (ERT-based targets must use the 'Embedded-C' code format.)

  • noninlinedSFcns: Cell array specifying list of noninlined S-functions in the model.

  • compilerEnvVal: String specifying compiler environment variable value (for example, C:\Applications\Microsoft Visual).

• buildArgs: Character array containing the argument to make_rtw. When you invoke the build process, buildArgs is copied from the argument string (if any) following "make_rtw" in the Make command field of the Real-Time Workshop pane of the Configuration Parameters dialog box.

  

The make arguments from the Make command field in the figure above, for example, generate the following:

% make -f untitled.mk VAR1=0 VAR2=4

Back to Top

Applications for STF_make_rtw_hook.m

An enumeration of all possible uses for STF_make_rtw_hook.m is beyond the scope of this document. However, this section provides some suggestions of how you might apply the available hooks.

In general, you can use the 'entry' hook to initialize the build process before any code is generated, for example to change or validate settings. 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 could use the STF_make_rtw_hook.m file at any stage after 'entry' to obtain the path to the build directory. At the 'exit' stage, you could then locate generated code files within the build directory and check them into your version control system. You might 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 that the build process temporarily changes the MATLAB working directory to the build directory for stages 'before_make', 'after_make', 'exit', and 'error'. Your STF_make_rtw_hook.m file should not make incorrect assumptions about the location of the build directory. You can obtain the path to the build directory anytime after the 'entry' stage. In the following code example, the build directory pathname is returned as a string to the variable buildDirPath.

makertwObj = get_param(gcs, 'MakeRTWSettingsObject');
buildDirPath = getfield(makertwObj, 'BuildDirectory');

Back to Top

Using 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 (located in the matlabroot/toolbox/rtw/targets/ecoder directory) as follows:

1. Copy ert_make_rtw_hook.m to a directory in the MATLAB path, and rename it in accordance with the naming conventions described in File and Function Naming Conventions. For example, to use it with the GRT target grt.tlc, rename it to grt_make_rtw_hook.m.

2. Rename the ert_make_rtw_hook function within the file to match the filename.

3. Implement the hooks that you require by adding code to the appropriate case statements within the switch hookMethod statement. See Auto-Configuring Models for Code Generation for an example.

Back to Top

Code Generation with User-Defined Data Types

Customizing the Target Build Process with sl_customization.m