Customize Template Makefiles
To configure or customize a template makefile (TMF), you should be familiar with how the
make command works and how it processes a makefile
.mk file). You should also understand makefile build rules. For
information on these topics, refer to the documentation provided with the make utility that
Template Makefiles and Tokens
A template makefile contains tokens. The build process expands the tokens and creates makefiles:
–– Compiles and links code generated from model components.
rtwshared.mk–– Compiles generated shared utility code.
) use commands that
are specific to your development computer.
Template Makefile Tokens
make_rtw command (or a different command provided with some
targets) directs the process of generating
make_rtw command processes the TMF specified on the Code
Generation pane of the Configuration Parameters dialog box.
make_rtw copies the TMF, line by line, expanding each token
encountered. Template Makefile Tokens Expanded by make_rtw lists the tokens and their
These tokens are used in several ways by the expanded makefile:
To control the conditional behavior in the makefile. The conditionals are used to control the source file lists, library names, target to be built, and other build-related information.
To provide the macro definitions for compiling the files, for example,
Template Makefile Tokens Expanded by make_rtw
Linker flags automatically added by blocks.
Alternate full pathname for the MATLAB® executable; value is different than value for
Alternate full pathname for the MATLAB installation; value is different than value for
Options passed to
True (1) when you select model configuration parameter
Single output/update function, otherwise False (0).
Used for the macro definition
Compiler flags in a group other than
Computer type. See the MATLAB
Preprocessor macro definitions in a group other than
preprocessor macro definition in
For example, some template makefiles contain these statements:
If the template makefile contains the variable/token pair
... NUMST = |>NUMST<| ... CPP_REQ_DEFINES1 = ... -DNUMST=$(NUMST) ...
The build process
produces a warning if
Location of precompiled library file. The
Library suffix. The
True (1) to enable generation of external mode support code, otherwise False (0).
Index of transport mechanism (for example,
True (1) if static memory allocation is selected for external mode. False (0) if dynamic memory allocation is selected.
Size of static memory allocation buffer for external mode.
|True (1) when model configuration parameter Create block
is set to |
True (1) when model configuration parameter Terminate
function required is selected, otherwise False (0). Used for the
True (1) when model configuration parameter Support
floating-point numbers is cleared, otherwise False (0).
|True (1) when model configuration parameter MAT-file
logging is selected, otherwise False (0). |
Location of the MATLAB executable program.
Path to where MATLAB is installed.
MEX-file extension. See the MATLAB
Additional generated source modules. For example, you can split a large
model into two files,
Object filenames (
Name of the Simulink® block diagram currently being built.
True (1) if solver mode is multitasking, otherwise False (0).
Number of continuous states.
Number of sample times in the model.
The MATLAB release version.
List of S-function libraries available for linking.
Solver source filename, for example,
Solver object (
Code generation folder at the start of the build.
True (1) if sampling rates of the continuous task and the first discrete task are equal, otherwise False (0).
S-function and build information support
For examples of the tokens in this section, see Modify the Template Makefile for rtwmakecfg.
|List of folder names to add to the include path. Additionally, the
|List of library names.|
|Library module names within
|List of precompiled library names.|
Model reference support
For examples of the tokens in this section, see Providing Model Referencing Support in the TMF.
|Name of the library file generated for the current model.|
|List of models referenced by the top model.|
|List of referenced model libraries against which the top model links.|
|Name of a response file against which the top model links. This token is
valid only for build environments that support linker response files. For an
example of its use, see
Type of target being built. Possible values are
|Relative path, from the location of the generated makefile, to the MATLAB working folder.|
These tokens are expanded by substitution of parameter values known to the build process. For example, if the source model contains blocks with two different sample times, the TMF statement
NUMST = |>NUMST<|
NUMST = 2
In addition to the above,
make_rtw expands tokens from other
Target-specific tokens defined in the target options of the Configuration Parameters dialog box
Structures in the
rtwoptionssection of the system target file. Structures in the
rtwoptionsstructure array that contain the field
The following example is extracted from
. The section starting with
BEGIN_RTW_OPTIONS contains MATLAB code that sets up
rtwoptions. The following directive
|>EXT_MODE<| token to be expanded to
1 (on) or
0 (off), depending on how you set the
external mode options.
rtwoptions(2).makevariable = 'EXT_MODE'
Invoke the make Utility
from your TMF, the build process invokes a
make command. To invoke
make, the build process issues this command.
makecommand -f model_or_sharedutils.mk
is defined by the
MAKECMD macro in your system target file TMF (see Structure of the Template Makefile). You can specify additional options to
make by using the model configuration parameter Make command. (See the sections Specify a Make Command and Template Makefiles and Make Options.)
For example, specifying
OPT_OPTS=-O2 in the Make command field causes
make_rtw to generate the
makecommand -f model_or_sharedutils.mk OPT_OPTS=-O2
A comment at the top of the TMF specifies the available
command options. If these options do not provide you with enough flexibility, you can
configure your own TMF.
make Utility Versions
The make utility lets you control nearly every aspect of building your real-time
program. There are several different versions of
make available. The
code generator provides the Free Software Foundation GNU®
make for both UNIX®1
and PC platforms in platform-specific subfolders under
It is possible to use other versions of
make with the code
generator, although GNU Make is recommended. To be compatible with the code generator, verify that
your version of
make supports the following command format.
makecommand -f model_or_sharedutils.mk
Structure of the Template Makefile
A TMF has multiple sections, including the following:
Abstract— Describes what the makefile targets. Here is a representative abstract from the ERT TMFs in
# Abstract: # Template makefile for building a Windows-based stand-alone embedded # real-time version of Simulink model using generated C code and the # Microsoft Visual C/C++ compiler for x64. # # Note that this template is automatically customized by the build # procedure to create "<model>.mk" # # The following defines can be used to modify the behavior of the # build: # OPT_OPTS - Optimization option. See DEFAULT_OPT_OPTS in # vctools.mak for default. # OPTS - User specific options. # CPP_OPTS - C++ compiler options. # USER_SRCS - Additional user sources, such as files needed by # S-functions. # USER_INCLUDES - Additional include paths # (i.e. USER_INCLUDES="-Iwhere-ever -Iwhere-ever2") # # To enable debugging: # set DEBUG_BUILD = 1, which will trigger OPTS=-Zi (may vary with # compiler version, see compiler doc) # # This template makefile is designed to be used with a system target # file that contains 'rtwgensettings.BuildDirSuffix' see ert.tlc
Macros read by make_rtwsection — Defines macros that tell
make_rtwhow to process the TMF. Here is a representative
Macros read by make_rtwsection from the GRT TMFs in
#------------------------ Macros read by make_rtw ----------------------------- # # The following macros are read by the build procedure: # # MAKECMD - This is the command used to invoke the make utility # HOST - What platform this template makefile is targeted for # (i.e. PC or UNIX) # BUILD - Invoke make from the build procedure (yes/no)? # SYS_TARGET_FILE - Name of system target file. MAKECMD = nmake HOST = PC BUILD = yes SYS_TARGET_FILE = any BUILD_SUCCESS = ^#^#^# Created # Opt in to simplified format by specifying compatible Toolchain TOOLCHAIN_NAME = [\ "Microsoft Visual C++ 2019 v16.0 | nmake (64-bit Windows)", \ "Microsoft Visual C++ 2017 v15.0 | nmake (64-bit Windows)", \ "Microsoft Visual C++ 2015 v14.0 | nmake (64-bit Windows)"]
The macros in this section might include:
MAKECMD— Specifies the command used to invoke the make utility. For example, if
mymake, then the
makecommand invoked is
HOST— Specifies the platform targeted by this TMF. This can be
(see the MATLAB
make_rtwwhether or not it should invoke
makefrom the build procedure. Specify
SYS_TARGET_FILE— Specifies the name of the system target file or the value
any. This is used for consistency checking by
make_rtwto verify the system target file specified in the Target selection panel of the Code Generation pane of the Configuration Parameters dialog box. If you specify
any, you can use the TMF with any system target file.
BUILD_SUCCESS— When the makefile creates a static library, it produces the
BUILD_SUCCESSstring as defined, for example, by this rule in
$(PRODUCT) : $(OBJS) $(LIBS) $(MODELREF_LINK_LIBS) @cmd /C "echo ### Linking ..." $(LD) $(LDFLAGS) $(LIBS) \ @$(CMD_FILE) @$(MODELREF_LINK_RSPFILE) -dll -def:$(MODEL).def -out:$@ @cmd /C "echo $(BUILD_SUCCESS) dynamically linked library $(PRODUCT)"
When the build process finds the
BUILD_SUCCESSstring, it polls for the existence of the updated static library file. The build process does not link the library file to the executable file until the build process can confirm the presence of the library file, with an updated timestamp, on the file system.
If the build process does not find
BUILD_SUCCESSin the compilation log, then the build process assumes that the updated library archive is available on the file system. If required, the build process links the library to the executable file.
Tokens expanded by make_rtwsection — Defines the tokens that
make_rtwexpands. Here is a brief excerpt from a representative
Tokens expanded by make_rtwsection from the ERT TMFs in
#---------------------- Tokens expanded by make_rtw ---------------------------- # # The following tokens, when wrapped with "|>" and "<|" are expanded by the # build procedure. # # MODEL_NAME - Name of the Simulink block diagram # MODEL_MODULES - Any additional generated source modules # MAKEFILE_NAME - Name of makefile created from template makefile <model>.mk # MATLAB_ROOT - Path to where MATLAB is installed. ... MODEL = |>MODEL_NAME<| MODULES = |>MODEL_MODULES<| PRODUCT = |>PRODUCT<| MAKEFILE = |>MAKEFILE_NAME<| MATLAB_ROOT = |>MATLAB_ROOT<| ...
For more information about TMF tokens, see Template Makefile Tokens Expanded by make_rtw.
Subsequent sections vary based on compiler, host, and target. Some common sections include
Model and reference models,
Additional Libraries, and
Rulessection — Contains the make rules used in building an executable from the generated source code. The build rules are typically specific to your version of make. The
Rulessection might be followed by related sections such as
Customize and Create Template Makefiles
This section describes the mechanics of setting up a custom template makefile (TMF) and incorporating it into the build process. It also discusses techniques for modifying a TMF and MATLAB file mechanisms associated with the TMF.
Before creating a custom TMF, you should read Folder and File Naming Conventions to understand the folder structure and MATLAB path requirements for custom targets.
Setting Up a Template Makefile
To customize or create a new TMF, copy an existing GRT or ERT TMF from
Place the copy in the same folder as the associated system target file. Usually, this
mytarget/mytarget folder within the target folder structure.
Then, rename your TMF (for example,
mytarget.tmf) and modify it.
To allow the build process to locate and select your TMF, you must provide information in the system target file file header (see System Target File Structure). For a target that implements a single TMF, the standard way to specify the TMF to be used in the build process is to use the TMF directive of the system target file file header.
Using Macros and Pattern Matching Expressions in a Template Makefile
This section shows, through an example, how to use macros and file-pattern-matching
expressions in a TMF to generate commands in
The make utility processes
and generates a
set of commands based upon dependency rules defined in
make generates the set of commands for building or rebuilding
make executes them.
For example, to build a program called
make must link the object files. However, if the object files don't
exist or are out of date,
make must compile the source code. Thus there
is a dependency between source and object files.
Each version of
make differs slightly in its features and how rules
are defined. For example, consider a program called
test that gets
created from two sources,
most versions of
make, the dependency rules would be
test: file1.o file2.o cc -o test file1.o file2.o file1.o: file1.c cc -c file1.c file2.o: file2.c cc -c file2.c
In this example, a UNIX2 environment is assumed. In a PC environment the file extensions and compile and link commands are different.
In processing the first rule
test: file1.o file2.o
make sees that to build
test, it needs to build
file2.o. To build
make processes the rule
file1.o doesn't exist, or if
file1.o is older
The format of TMFs follows the above example. Our TMFs use additional features of
make such as macros and file-pattern-matching expressions. In most
make, a macro is defined with
MACRO_NAME = value
References to macros are made with
make sees this form of expression, it substitutes
You can use pattern matching expressions to make the dependency rules more general.
For example, using GNU3
Make, you could replace the two “
file1.c” and “
file2.o: file2.c” rules
with the single rule
%.o : %.c cc -c $<
$< in the previous example is a special macro that
equates to the dependency file (that is,
file2.c). Thus, using macros and the "
matching character, the previous example can be reduced to
SRCS = file1.c file2.c OBJS = $(SRCS:.c=.o) test: $(OBJS) cc -o $@ $(OBJS) %.o : %.c cc -c $<
Note that the
$@ macro above is another special macro that equates
to the name of the current dependency target, in this case
This example generates the list of objects (
OBJS) from the list of
SRCS) by using the text substitution feature for macro
expansion. It replaces the source file extension (for example,
the object file extension (
.o). This example also generalized the build
rule for the program,
test, to use the special "
Customizing Generated Makefiles with rtwmakecfg
TMFs provide tokens that let you add the following items to generated makefiles:
Run-time library names
Run-time module objects
S-functions can add this information to the makefile by using an
rtwmakecfg.m file function. This function is particularly useful
when building a model that contains one or more of your S-Function blocks, such as device
To add information pertaining to an S-function to the makefile,
Create the function
rtwmakecfg.m. The code generator associates this file with your S-function based on its folder location.
Modify your target's TMF such that it supports macro expansion for the information returned by
After the TLC phase of the build process, when generating a makefile from the TMF, the
build process searches for an
rtwmakecfg.m file in the folder that
contains the S-function component. If it finds the file, the build process calls the
rtwmakecfg function. For more information, see Use rtwmakecfg.m API to Customize Generated Makefiles.
Supporting Continuous Time in Custom Targets
If you want your custom ERT-based target to support continuous time, you must update
your template makefile (TMF) and the static main program module (for example,
mytarget_main.c) for your target.
Template Makefile Modifications. Add the
NCSTATES token expansion after the
NUMST token expansion, as follows:
NUMST = |>NUMST<| NCSTATES = |>NCSTATES<|
In addition, add
NCSTATES to the
CPP_REQ_DEFINES macro, as in the following example:
CPP_REQ_DEFINES = -DMODEL=$(MODEL) -DNUMST=$(NUMST) -DNCSTATES=$(NCSTATES) \ -DMAT_FILE=$(MAT_FILE) -DINTEGER_CODE=$(INTEGER_CODE) \ -DONESTEPFCN=$(ONESTEPFCN) -DTERMFCN=$(TERMFCN) \ -DHAVESTDIO -DMULTI_INSTANCE_CODE=$(MULTI_INSTANCE_CODE) \
Modifications to Main Program Module. The main program module defines a static main function that manages task scheduling
for the supported tasking modes of single- and multiple-rate models.
NUMST (the number of sample times in the model) determines whether
the main function calls multirate or single-rate code. However, when a model uses
continuous time, do not rely on
When the model has continuous time and the flag
TID01EQ is true,
both continuous time and the fastest discrete time are treated as one rate in generated
code. The code associated with the fastest discrete rate is guarded by a major time step
check. When the model has only two rates, and
TID01EQ is true, the
generated code has a single-rate call interface.
To support models that have continuous time, update the static main module to take
TID01EQ into account, as follows:
NUMSTis referenced in the file, add the following code:
#if defined(TID01EQ) && TID01EQ == 1 && NCSTATES == 0 #define DISC_NUMST (NUMST - 1) #else #define DISC_NUMST NUMST #endif
Replace instances of
NUMSTin the file by
Model Reference Considerations
See Support Model Referencing for important information on TMF modifications you may need to make to support the code generator model referencing features.
If you are using a TMF without the variable
MODELREFS, the file
might have been used with a previous release of Simulink software. If you want your TMF to support model referencing, add
MODELREFS to the make file.
Timeout Error When Building Shared Utility Code with Custom Template Makefile
If the build process uses a custom template makefile to create a makefile for the shared utility code, the build process produces a timeout error when all of these conditions apply:
The configuration parameter
BUILD_SUCCESSmessage is output during the
rtwshared.mkdoes not update the final product (typically
To avoid the error, update the custom template makefile so that the
make call generates the
BUILD_SUCCESS message only
when the final product is generated (as identified by the
PRODUCT). Alternatively, if the build process does not use the
generated makefile, disable makefile generation by setting the configuration parameter
1 UNIX is a registered trademark of The Open Group in the United States and other countries.
2 UNIX is a registered trademark of The Open Group in the United States and other countries.
3 GNU is a registered trademark of the Free Software Foundation.