Customize Template Makefiles - MATLAB & Simulink (original) (raw)

To configure or customize a template makefile (TMF), you should be familiar with how themake 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 you use.

Template Makefiles and Tokens

A template makefile contains tokens. The build process expands the tokens and creates makefiles:

• _`model`_.mk –– Compiles and links code generated from model components.
• rtwshared.mk –– Compiles generated shared utility code.

The makefiles (_`modelorsharedutils`_.mk) use commands that are specific to your development computer.

Template Makefile Tokens

The make_rtw command (or a different command provided with some targets) directs the process of generating_`modelorsharedutils`_.mk. Themake_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 expansions.

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,-DINTEGER_CODE=1.

Template Makefile Tokens Expanded by make_rtw

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

expands to:

In addition to the above, make_rtw expands tokens from other sources:

• Target-specific tokens defined in the target options of the Configuration Parameters dialog box
• Structures in the rtwoptions section of the system target file. Structures in the rtwoptions structure array that contain the fieldmakevariable are expanded.

The following example is extracted from_`matlabroot`_/rtw/c/grt/[grt.tlc](https://mdsite.deno.dev/matlab:edit%28fullfile%28matlabroot,'/rtw/c/grt/grt.tlc'%29%29). The section starting withBEGIN_RTW_OPTIONS contains MATLAB code that sets up rtwoptions. The following directive causes the |>EXT_MODE<| token to be expanded to1 (on) or 0 (off), depending on how you set the external mode options.

rtwoptions(2).makevariable = 'EXT_MODE'

Invoke the make Utility

• make Command
• make Utility Versions

make Command

After creating _`modelorsharedutils`_.mk from your TMF, the build process invokes a make command. To invokemake, the build process issues this command.

makecommand -f modelorsharedutils.mk

_`makecommand`_ is defined by theMAKECMD macro in your system target file TMF (see Structure of the Template Makefile). You can specify additional options tomake 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 following make command.

makecommand -f modelorsharedutils.mk OPT_OPTS=-O2

A comment at the top of the TMF specifies the available make 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 modelorsharedutils.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_`matlabroot`_/toolbox/coder/compile/tmf:

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 ".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_rtw section — Defines macros that tellmake_rtw how to process the TMF. Here is a representativeMacros read by make_rtw section from the GRT TMFs in_`matlabroot`_/toolbox/coder/compile/tmf:

#------------------------ 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 MAKECMD =mymake, then the make command invoked is
  mymake -f _`modelorsharedutils`_.mk
• HOST — Specifies the platform targeted by this TMF. This can be PC, UNIX,_`computername`_ (see the MATLABcomputer command), orANY.
• BUILD — Instructs make_rtw whether or not it should invoke make from the build procedure. Specifyyes or no.
• SYS_TARGET_FILE — Specifies the name of the system target file or the value any. This is used for consistency checking by make_rtw to 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 theBUILD_SUCCESS string as defined, for example, by this rule inert_vcx64.tmf:
  (PRODUCT):(PRODUCT) : (PRODUCT):(OBJS) (LIBS)(LIBS) (LIBS)(MODELREF_LINK_LIBS)
  @cmd /C "echo ### Linking ..."
  (LD)(LD) (LD)(LDFLAGS) $(LIBS) \
  @$(CMD_FILE) @$(MODELREF_LINK_RSPFILE) -dll -def:$(MODEL).def -out:$@
  @cmd /C "echo (BUILDSUCCESS)dynamicallylinkedlibrary(BUILD_SUCCESS) dynamically linked library (BUILDS​UCCESS)dynamicallylinkedlibrary(PRODUCT)"
  When the build process finds theBUILD_SUCCESS string, 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 findBUILD_SUCCESS in 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_rtw section — Defines the tokens that make_rtw expands. Here is a brief excerpt from a representativeTokens expanded by make_rtw section from the ERT TMFs in_`matlabroot`_/toolbox/coder/compile/tmf/:

#---------------------- 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 .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, External mode,Tool Specifications or Tool Definitions,Include Path, C Flags, Additional Libraries, and Source Files.
• Rules section — 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 Rules section might be followed by related sections such as Dependencies.

Customize and Create Template Makefiles

• Introduction
• Setting Up a Template Makefile
• Using Macros and Pattern Matching Expressions in a Template Makefile
• Customizing Generated Makefiles with rtwmakecfg
• Supporting Continuous Time in Custom Targets
• Model Reference Considerations
• Timeout Error When Building Shared Utility Code with Custom Template Makefile

Introduction

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_matlabroot_/toolbox/coder/compile/tmf.

Place the copy in the same folder as the associated system target file. Usually, this is the 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 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 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_`modelorsharedutils`_.mk.

The make utility processes_`modelorsharedutils`_.mk and generates a set of commands based upon dependency rules defined in_`modelorsharedutils`_.mk. Aftermake generates the set of commands for building or rebuildingtest, make executes them.

For example, to build a program called test,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, file1.c and file2.c. Using 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

make sees that to build test, it needs to buildfile1.o and file2.o. To buildfile1.o, make processes the rule

If file1.o doesn't exist, or if file1.o is older than file1.c, make compilesfile1.c.

The format of TMFs follows the above example. Our TMFs use additional features ofmake such as macros and file-pattern-matching expressions. In most versions of make, a macro is defined with

References to macros are made with $(MACRO_NAME). Whenmake sees this form of expression, it substitutes_value_ for $(MACRO_NAME).

You can use pattern matching expressions to make the dependency rules more general. For example, using GNU3 Make, you could replace the two “file1.o: file1.c” and “file2.o: file2.c” rules with the single rule

Note that $< in the previous example is a special macro that equates to the dependency file (that is, file1.c orfile2.c). Thus, using macros and the "%" pattern 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 test.

This example generates the list of objects (OBJS) from the list of sources (SRCS) by using the text substitution feature for macro expansion. It replaces the source file extension (for example, .c) with the object file extension (.o). This example also generalized the build rule for the program, test, to use the special "$@" macro.

Customizing Generated Makefiles with rtwmakecfg

TMFs provide tokens that let you add the following items to generated makefiles:

• Source folders
• Include folders
• Run-time library names
• Run-time module objects

S-functions can add this information to the makefile by using anrtwmakecfg.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 driver blocks.

To add information pertaining to an S-function to the makefile,

1. Create the function rtwmakecfg in filertwmakecfg.m. The code generator associates this file with your S-function based on its folder location.
2. Modify your target's TMF such that it supports macro expansion for the information returned by rtwmakecfg functions.

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 thertwmakecfg 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 theNUMST token expansion, as follows:

NUMST = |>NUMST<| NCSTATES = |>NCSTATES<|

In addition, add NCSTATES to theCPP_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 NUMST directly.

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 takeTID01EQ into account, as follows:

1. Before NUMST is 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 2. Replace instances of NUMST in the file byDISC_NUMST.

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.

Note

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, addMODELREFS 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 GenCodeOnly is'off'.
• The BUILD_SUCCESS message is output during themake call to rtwshared.mk.
• The make call to rtwshared.mk does not update the final product (typically rtwshared.lib).

To avoid the error, update the custom template makefile so that themake call generates the BUILD_SUCCESS message only when the final product is generated (as identified by the make variablePRODUCT). Alternatively, if the build process does not use the generated makefile, disable makefile generation by setting the configuration parameterGenerateMakefile to 'off'.

See Also

Topics

• Custom Targets
• Customize System Target Files
• Custom Target Optional Features
• Support Toolchain Approach with Custom Target

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.