Customize Build Process with sl_customization.m
The Simulink® customization file sl_customization.m
is a mechanism
that allows you to use MATLAB® to customize the build process interface. The Simulink software reads the sl_customization.m
file, if present
on the MATLAB path, when it starts and the customizations specified in the file are
applied to the Simulink session. For more information on the sl_customization.m
customization file, see Register Customizations with Simulink.
The sl_customization.m File
The sl_customization.m
file can be used to register
installation-specific hook functions to be invoked during the build process. The
hook functions that you register through sl_customization.m
complement System Target File (STF) hooks (described in Customize Build Process with STF_make_rtw_hook File)
and post-code generation commands (described in Customize Post-Code-Generation Build Processing).
The following figure shows the relationship between installation-level hooks and the other available mechanisms for customizing the build process.
Register Build Process Hook Functions Using sl_customization.m
To register installation-level hook functions that are invoked during the build
process, you create a MATLAB function called sl_customization.m
and include it
on the MATLAB path of the Simulink installation that you want to customize. The
sl_customization
function accepts one argument: a handle to a
customization manager object. For example,
function sl_customization(cm)
As a starting point for your customizations, the
sl_customization
function must first get the default
(factory) customizations, using the following assignment statement:
hObj = cm.RTWBuildCustomizer;
You then invoke methods to register your customizations. The customization manager object includes the following method for registering build process hook customizations:
addUserHook(hObj, hookType, hook)
Registers the MATLAB hook script or function specified by
hook
for the build process stage represented byhookType
. The valid values forhookType
are'entry'
,'before_tlc'
,'after_tlc'
,'before_make'
,'after_make'
, and'exit'
.
Use this method to register installation-specific hook functions in your instance
of the sl_customization
function.
The Simulink software reads the sl_customization.m
file when it
starts. If you subsequently change the file, you must restart the Simulink session or enter the following command in the Command Window to enable
the changes:
sl_refresh_customizations
Note
Do not use the addUserHook
method to:
Change the model configuration. For example, do not use the 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.
Variables Available for sl_customization.m Hook Functions
The following variables are available for sl_customization.m
hook functions to use:
modelName
— The name of the Simulink model (valid for all stages)dependencyObject
— An object containing the dependencies of the generated code (valid only for the'after_make'
stage)
A hook script can directly access the valid variables. A hook function can pass the valid variables as arguments to the function. For example:
hObj.addUserHook('after_make', 'afterMakeFunction(modelName,dependencyObject);');
Example of Build Process Customization with sl_customization.m
The sl_customization.m
file shown in the example, sl_customization.m for Build Process Customizations, uses
the addUserHook
method to specify installation-specific build
process hooks to be invoked at the 'entry'
and
'after_tlc'
stages of the build process. For the hook
function source code, see the CustomRTWEntryHook.m
and CustomRTWPostProcessHook.m examples.
function sl_customization(cm) % Register user customizations % Get default (factory) customizations hObj = cm.RTWBuildCustomizer; % Register build process hooks hObj.addUserHook('entry', 'CustomRTWEntryHook(modelName);'); hObj.addUserHook('after_tlc', 'CustomRTWPostProcessHook(modelName);'); end
function [str, status] = CustomRTWEntryHook(modelName) str =sprintf('Custom entry hook for model ''%s.''',modelName); disp(str) status =1;
function [str, status] = CustomRTWPostProcessHook(modelName) str =sprintf('Custom post process hook for model ''%s.''',modelName); disp(str) status =1;
If you include the above three files on the MATLAB path of the Simulink installation that you want to customize, the coded hook function
messages appear in the displayed output for builds. For example, if you open the
ERT-based model UserDefinedDataTypes
, open the Code
Generation pane of the Configuration Parameters dialog box, and press
Ctrl+B to initiate a build, the following messages are
displayed:
>> UserDefinedDataTypes ### Starting build procedure for model: UserDefinedDataTypes Custom entry hook for model 'UserDefinedDataTypes.' Custom post process hook for model 'UserDefinedDataTypes.' ### Successful completion of build procedure for model: UserDefinedDataTypes >>
Use addUserHook Method to Customize Build Process
This example shows how you can customize the build process by using the addUserHook
method to register build hooks. The example model uses a custom hardware board. By running a custom hook method at the 'after_tlc'
build stage, the build process links a custom main file.
Register New Hardware Device Using Target Framework
If you already have hardware settings for your model, you can skip this section.
Create a target.Board
object that provides MATLAB with a description of your hardware device.
myProcessor = target.get('Processor', ... 'Intel-x86-64 (Windows64)'); myBoard = target.create('Board', ... 'Name', 'My Board with Custom Main File Linked', ... 'Processors', myProcessor);
Add the target object to an internal database.
boardObj = target.add(myBoard);
"target.add" summary: Objects added to internal database for current MATLAB session: target.Board "My Board with Custom Main File Linked" Objects not added because they already exist: target.Processor "Intel-x86-64 (Windows64)"
Specify Hardware Board for Model and Build Code
Specify the hardware board for your model and disable the GenerateSampleERTMain
option.
model = 'CustomBuildCounter'; open_system(model); set_param(model, 'HardwareBoard', myBoard.Name); set_param(model, 'IncludeMdlTerminateFcn', 'on'); set_param(model, 'GenerateSampleERTMain', 'off');
The software automatically selects relevant configuration parameters for the toolchain and processor associated with the specified hardware board.
Without customization, the build process uses the static rt_main.c
file from the matlabroot/rtw/c/src/common
folder.
slbuild(model);
### Starting build procedure for: CustomBuildCounter ### Successful completion of build procedure for: CustomBuildCounter Build Summary Top model targets: Model Build Reason Status Build Duration ===================================================================================================================== CustomBuildCounter Information cache folder or artifacts were missing. Code generated and compiled. 0h 0m 16.071s 1 of 1 models built (0 models already up to date) Build duration: 0h 0m 18.067s
The RTW.BuildInfo
object contains names of source files used by the build process, including rt_main.c
.
bi = load(fullfile([model '_ert_rtw'], 'buildInfo.mat')); srcfiles = getSourceFiles(bi.buildInfo, true, false)'
srcfiles = 2x1 cell
{'$(START_DIR)/CustomBuildCounter_ert_rtw/CustomBuildCounter.c'}
{'$(MATLAB_ROOT)/rtw/c/src/common/rt_main.c' }
Customize Build Process
Using a custom hook method, you can register a custom main file instead of using the default rt_main.c
.
Each custom hook method must check that it is compatible with the model settings. For example, in registerCustomMain.m
, the function checks that the hook method applies only for a specific hardware board.
edit(fullfile(pwd, 'myHooks', 'registerCustomMain.m'))
Register the custom hook method via sl_refresh_customization.
addpath('myHooks');
sl_refresh_customizations
Before generating code, remove the previous code generation folders and model cache.
rmdir(fullfile(pwd, [model '_ert_rtw']), 's'); rmdir(fullfile(pwd, 'slprj'), 's'); delete([model '.slxc']);
Build the model.
slbuild(model);
### Starting build procedure for: CustomBuildCounter Custom after_tlc hook to register custom main file for model 'CustomBuildCounter.' ### Successful completion of build procedure for: CustomBuildCounter Build Summary Top model targets: Model Build Reason Status Build Duration ===================================================================================================================== CustomBuildCounter Information cache folder or artifacts were missing. Code generated and compiled. 0h 0m 12.419s 1 of 1 models built (0 models already up to date) Build duration: 0h 0m 14.833s
Check that the build process uses myMainFile.c
.
bi = load(fullfile([model '_ert_rtw'], 'buildInfo.mat')); srcfiles = getSourceFiles(bi.buildInfo, true, false)'
srcfiles = 2x1 cell
{'$(START_DIR)/CustomBuildCounter_ert_rtw/CustomBuildCounter.c'}
{'$(START_DIR)/myMainFile.c' }
Clean Up
Close the model, remove target objects from the internal database, and deregister custom hook methods.
close_system(model, 0); target.remove(boardObj);
"target.remove" summary: Objects removed from internal database: target.Board "My Board with Custom Main File Linked"
rmpath('myHooks');
sl_refresh_customizations
Clear the variables added to the workspace.
clear INC K LIMIT RESET model bi srcfiles myBoard myProcessor boardObj