Main Content

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 by hookType. The valid values for hookType 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.

Example 1. sl_customization.m for Build Process Customizations
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
Example 2. CustomRTWEntryHook.m
function [str, status] = CustomRTWEntryHook(modelName)
str =sprintf('Custom entry hook for model ''%s.''',modelName);
disp(str)
status =1;
Example 3. CustomRTWPostProcessHook.m
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

Open Live Script

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.075s 

1 of 1 models built (0 models already up to date)
Build duration: 0h 0m 18.931s

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 14.668s 

1 of 1 models built (0 models already up to date)
Build duration: 0h 0m 17.914s

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

See Also

Related Topics