Main Content

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 whether to use the toolchain approach or template makefile approach build process.

Choose Build Approach and Configure Build Process (Embedded Coder)

For an example, see Build Process Workflow for Real-Time Systems (Embedded Coder).

2

Configure build process support for your external code.

Configure Parameters for Integrated Code Build Process (Embedded Coder)

3

Configure S-Function build support for your external code.

Build Support for S-Functions (Embedded Coder)

Use makecfg to Customize Generated Makefiles for S-Functions (Embedded Coder)

For examples, see Call External C Code from Model and Generated Code (Embedded Coder) and Call Reusable External Algorithm Code for Simulation and Code Generation (Embedded Coder).

4

Configure build process to find the external code source, library, and header files.

Manage Build Process File Dependencies (Embedded Coder)

Control Library Location and Naming During Build (Embedded Coder)

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 (Embedded Coder).

To automate applying build customizations to a toolchain approach build, see Customize Build Process with sl_customization.m (Embedded Coder).

To automate applying build customizations to a template makefile approach build, see Customize Build Process with STF_make_rtw_hook File (Embedded Coder).

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 (Embedded Coder). If you choose to place your external code in the Code generation folder, see Preserve External Code Files in Build Folder (Embedded Coder).

ToSelect

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

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.

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).

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.

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:

  1. 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 FileCOMPILER _TOOL_CHAIN ValuePrecompiler 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.tmflcc_rtwsfcn_lcc_int_ert_lcc_ert_lcc.lib
    ert_vcx64.tmfvcx64_rtwsfcn_vcx64_int_ert_vcx64_ert_vcx64.lib
    ert_unix.tmfunix_rtwsfcn_int_ert_ert.a
    grt_lcc64.tmflccn/an/a_lcc.lib
    grt_vcx64.tmfvcx64n/an/a_vcx64.lib
    grt_unix.tmfunixn/an/a_std.a
  2. Set the precompiled library folder.

    Use one of the following methods to set the precompiled library folder:

    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.

  3. 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.

    FieldDescription

    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')};
  4. 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);

Related Topics