Build Integrated Code Within the Simulink Environment

Workflow

To build executable programs that integrate generated code and external C or C++ code, iterate through the tasks in this table.

Task	Action	More Information
1	Choose a build approach.	Approaches for Building Code Generated from Simulink Models For an example, see Build Process Workflow for Real-Time Systems.
2	Configure build process support for your external code.	Configure Parameters for Integrated Code Build Process
3	If you integrated your external code through S-Functions, configure S-Function build support for your external code.	Build Support for S-Functions Use makecfg to Customize Generated Makefiles for S-Functions For example, see Call Reusable Hardware-Independent External Code for Simulation and Code Generation.
4	Configure build process to find the external code source, library, and header files.	Manage Build Process File Dependencies Control Library Location and Naming During Build
5	Set up custom build processing required for your external code integration.	For the build process customization workflow, see Customize Post-Code-Generation Build Processing. To automate applying build customizations to a toolchain approach build, see Customize Build Process with sl_customization.m. To automate applying build customizations to a template makefile approach build, see Customize Build Process with STF_make_rtw_hook File.

Configure Parameters for Integrated Code Build Process

The table provides a guide to model configuration parameters on Code Generation > Custom Code pane of the Model Configuration Parameters dialog box that support the build process for external code integration. For information about folders for your external code, see Manage Build Process Folders. If you choose to place your external code in the Code generation folder, see Preserve External Code Files in Build Folder.

To	Select
Add include folders, which contain header files, to the build process	Code information > Include directories, and enter the absolute or relative paths to the folders. If you specify relative paths, the paths must be relative to the folder containing your model files, not relative to the build folder. The order in which you specify the folders is the order in which they are searched for header, source, and library files.
Add source files to be compiled and linked	Code information > Source files, and enter the full paths or just the file names for the files. Enter just the file name if the file is in the current MATLAB^® folder or in one of the include folders. For each additional source that you specify, the build process expands a generic rule in the template makefile for the folder in which the source file is located. For example, if a source file is located in folder `inc`, the build process adds a rule similar to the following: %.obj: buildir\inc\%.c $(CC) -c -Fo$(@F) $(CFLAGS) $< The build process adds the rules in the order that you list the source files.
Add libraries to be linked	Code information > Libraries, and enter the full paths or just the file names for the libraries. Enter just the file name if the library is located in the current MATLAB folder or in one of the include folders.
Use the same custom code settings as those specified for simulation of MATLAB Function blocks, Stateflow^® charts, and Truth Table blocks	Use the same custom code settings as Simulation Target This parameter refers to the Simulation Target pane in the Configuration Parameters dialog box.
Enable a library model to use custom code settings unique from the parent model to which the library is linked	Use local custom code settings (do not inherit from main model) This parameter is available only for library models that contain MATLAB Function blocks, Stateflow charts, or Truth Table blocks.

Preserve External Code Files in Build Folder

By default, the build process deletes foreign source files. You can preserve foreign source files by following these guidelines.

If you put a .c/.cpp or .h source file in a build folder, and you want to prevent the code generator from deleting it during the TLC code generation process, insert the text target specific file in the first line of the .c/.cpp or .h file. For example:

/*  COMPANY-NAME target specific file
 *
 *   This file is created for use with the 
 *   COMPANY-NAME target.
 *   It is used for ...
 */
...

Make sure that you spell the text “target specific file” as shown in the preceding example, and that the text is in the first line of the source file. Other text can appear before or after this text.

Flagging user files in this manner prevents postprocessing these files to indent them with generated source files. Auto-indenting occurred in previous releases to build folder files with names having the pattern model_*.c/.cpp (where * was text). The indenting is harmless, but can cause differences detected by source control software that can potentially trigger unnecessary updates.

Build Support for S-Functions

User-written S-Function blocks provide a powerful way to incorporate external code into the Simulink^® development environment. In most cases, you use S-functions to integrate existing external code with generated code. Several approaches to writing S-functions are available:

S-functions also provide the most flexible and capable way of including build information for legacy and custom code files in the build process.

There are different ways of adding S-functions to the build process.

Implicit Build Support

When building models with S-functions, the build process adds rules, include paths, and source file names to the generated makefile. The source files (.h, .c, and .cpp) for the S-function must be in the same folder as the S-function MEX-file. Whether using the toolchain approach or template makefile approach for builds, the build process propagates this information through the toolchain or template makefile.

If the file sfcnname.h exists in the same folder as the S-function MEX-file (for example, sfcnname.mexext), the folder is added to the include path.
If the file sfcnname.c or sfcnname.cpp exists in the same folder as the S-function MEX-file, the build process adds a makefile rule for compiling files from that folder.
When an S-function is not inlined with a TLC file, the build process must compile the S-function source file. To determine the name of the source file to add to the list of files to compile, the build process searches for sfcnname.cpp on the MATLAB path. If the source file is found, the build process adds the source file name to the makefile. If sfcnname.cpp is not found on the path, the build process adds the file name sfcnname.c to the makefile, whether or not it is on the MATLAB path.
Note
For the Simulink engine to find the MEX-file for simulation and code generation, it must exist on the MATLAB path or exist in our current MATLAB working folder.

Specify Additional Source Files for an S-Function

If your S-function has additional source file dependencies, you must add the names of the additional modules to the build process. Specify the file names:

In the S-function modules field in the S-Function block parameter dialog box
With the SFunctionModules parameter in a call to the set_param function

For example, suppose you build your S-function with multiple modules.

mex sfun_main.c sfun_module1.c sfun_module2.c

You can then add the modules to the build process by doing one of the following:

In the S-function block dialog box, specify sfun_main, sfun_module1, and sfun_module2 in the S-function modules field.

At the MATLAB command prompt, enter:

set_param(sfun_block,'SFunctionModules','sfun_module1 sfun_module2')

Alternatively, you can define a variable to represent the parameter value.

modules = 'sfun_module1 sfun_module2'
          set_param(sfun_block,'SFunctionModules', modules)

The S-function modules field and SFunctionModules parameter do not support complete source file path specifications. To use the parameter, the code generator must find the additional source files when executing the makefile. For the code generator to locate the additional files, place them in the same folder as the S-function MEX-file. You can then leverage the implicit build support described in Implicit Build Support.

When you are ready to generate code, force the code generator to rebuild the top model, as described in Control Regeneration of Top Model Code.

For more complicated S-function file dependencies, such as specifying source files in other locations or specifying libraries or object files, use the rtwmakecfg.m API, as described in Use rtwmakecfg.m API to Customize Generated Makefiles.

Use TLC Library Functions

If you inline your S-function by writing a TLC file, you can add source file names to the build process by using the TLC library function LibAddToModelSources. For details, see LibAddSourceFileCustomSection(file, builtInSection, newSection).

Note

This function does not support complete source file path specifications. The function assumes that the code generator can find the additional source files when executing the makefile.

Another useful TLC library function is LibAddToCommonIncludes. Use this function in a #include statement to include S-function header files in the generated model.h header file. For details, see LibAddToCommonIncludes(incFileName).

Precompile S-Function Libraries

You can precompile new or updated S-function libraries (MEX-files) for a model by using the MATLAB language function rtw_precompile_libs. Using a specified model and a library build specification, this function builds and places the libraries in a precompiled library folder.

By precompiling S-function libraries, you can optimize system builds. Once your precompiled libraries exist, the build process can omit library compilation from subsequent builds. For models that use numerous libraries, the time savings for build processing can be significant.

To use rtw_precompile_libs:

Set the library file suffix, including the file type extension, based on your system platform.

Consider determining the type of platform, and then use the TargetLibSuffix parameter to set the library suffix accordingly. For example, when applying a suffix for a GRT target, you can set the suffix to _std.a for a UNIX^® platform and _vcx64.lib for a Windows^® platform.

  if isunix
    suffix = '_std.a';
  else
    suffix = '_vcx64.lib';
  end

set_param(my_model,'TargetLibSuffix', suffix);

There are a number of factors that influence the precompiled library suffix and extension. The following table provides examples for typical selections of system target file, the compiler toolchain, and other options that affect your choice of suffix and extension. For more information, examine the template make files in the matlab/rtw/c/grt folder or matlab/rtw/c/ert folder.

TMF File	COMPILER _TOOL_CHAIN Value	Precompiler Libraries (PRECOMP_LIBRARIES)
TMF File	COMPILER _TOOL_CHAIN Value	Library Suffix S-Function (EXPAND _LIBRARY _NAME Value)	Library Suffix Integer- Only Code (EXPAND _LIBRARY _NAME Value)	Library Suffix Optimize for Speed (EXPAND _LIBRARY _NAME Value)	Library Extension (EXPAND _LIBRARY _NAME Value)
ert_vcx64.tmf	vcx64	_rtwsfcn_vcx64	_int_ert_vcx64	_ert_vcx64	.lib
ert_unix.tmf	unix	_rtwsfcn	_int_ert	_ert	.a
grt_vcx64.tmf	vcx64	n/a	n/a	_vcx64	.lib
grt_unix.tmf	unix	n/a	n/a	_std	.a

Set the precompiled library folder.
Use one of the following methods to set the precompiled library folder:
- Set the TargetPreCompLibLocation parameter, as described in Specify the Location of Precompiled Libraries.
- Set the makeInfo.precompile field in an rtwmakecfg.m function file. (For more information, see Use rtwmakecfg.m API to Customize Generated Makefiles.)
If you set TargetPreCompLibLocation and makeInfo.precompile, the setting for TargetPreCompLibLocation takes precedence.
The following command sets the precompiled library folder for model my_model to folder lib under the current working folder.
```
set_param(my_model,'TargetPreCompLibLocation', fullfile(pwd,'lib'));
```
Note
If you set both the target folder for the precompiled library files and a target library file suffix, the build process detects whether any precompiled library files are missing while processing builds.

Define a build specification.

Set up a structure that defines a build specification. The following table describes fields that you can define in the structure. These fields are optional, except for rtwmakecfgDirs.

Field	Description
`rtwmakecfgDirs`	A cell array of character vectors that name the folders containing `rtwmakecfg` files for libraries to be precompiled. The function uses the `Name` and `Location` elements of `makeInfo.library`, as returned by `rtwmakecfg`, to specify the name and location of the precompiled libraries. If you set the `TargetPreCompLibLocation` parameter to specify the library folder, that setting overrides the `makeInfo.library.Location` setting. Note: The specified model must contain blocks that use precompiled libraries specified by the `rtwmakecfg` files because the TMF-to-makefile conversion generates the library rules only if the build process uses the libraries.
`libSuffix`	A character vector that specifies the suffix, including the file type extension, to be appended to the name of each library (for example, `.a` or `_vc.lib`). The character vector must include a period (.). You must set the suffix with either this field or the `TargetLibSuffix` parameter. If you specify a suffix with both mechanisms, the `TargetLibSuffix` setting overrides the setting of this field.
`intOnlyBuild`	A Boolean flag. When set to true, the flag indicates the libraries are to be optimized such that they are compiled from integer code only. This field applies to ERT targets only.
`makeOpts`	A character vector that specifies an option to be included in the `rtwMake` command line.
`addLibs`	A cell array of structures that specify libraries to be built that are not specified by an `rtwmakecfg` function. Each structure must be defined with two fields that are character arrays: `libName` — the name of the library without a suffix `libLoc` — the location for the precompiled library The target makefile (TMF) can specify other libraries and how those libraries are built. Use this field to precompile those libraries.

The following commands set up build specification build_spec, which indicates that the files to be compiled are in folder src under the current working folder.

build_spec = [];
build_spec.rtwmakecfgDirs = {fullfile(pwd,'src')};

Issue a call to rtw_precompile_libs.
The call must specify the model for which you want to build the precompiled libraries and the build specification. For example:
```
rtw_precompile_libs(my_model,build_spec);
```