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 whether to use the toolchain approach or template makefile approach build process. | Choose Build Approach and Configure Build Process For an example, see Build Process Workflow for Real-Time Systems. |
2 | Configure build process support for your external code. | |
3 | Configure S-Function build support for your external code. | Use makecfg to Customize Generated Makefiles for S-Functions For examples, see Call External C Code from Model and Generated Code and Call Reusable External Algorithm Code for Simulation and Code Generation. |
4 | Configure build process to find the external code source, library, and header files. | |
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. |
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 | Additional build 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 | Additional build 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
%.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 | Additional build 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. |
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.
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.
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.hsfcnname.mexext
If the file sfcnname.csfcnname.cpp
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.cppsfcnname.cppsfcnname.c
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.
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.
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).
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.
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) | |||
|---|---|---|---|---|---|
| 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_lcc64.tmf | lcc | _rtwsfcn_lcc | _int_ert_lcc | _ert_lcc | .lib |
| ert_vcx64.tmf | vcx64 | _rtwsfcn_vcx64 | _int_ert_vcx64 | _ert_vcx64 | .lib |
| ert_unix.tmf | unix | _rtwsfcn | _int_ert | _ert | .a |
| grt_lcc64.tmf | lcc | n/a | n/a | _lcc | .lib |
| 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 |
|---|---|
A cell array of character vectors that name the folders
containing Note: The specified model must contain blocks
that use precompiled libraries specified by the | |
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. | |
| 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. | |
A character vector that specifies an option to be included in the
rtwMake command line. | |
A cell array of structures that specify libraries to
be built that are not specified by an
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);