Configure Toolchain (ToolchainInfo) or Template Makefile Build Process

Configure Toolchain (`ToolchainInfo`) or Template Makefile Build Process

Specify the toolchain (ToolchainInfo) or template makefile approach for building code generated from a model.

If you set the System target file configuration parameter to grt.tlc, ert.tlc, ert_shrlib.tlc, or another toolchain-compliant system target file, the build process uses the toolchain approach. If you set the parameter to a non-toolchain-compliant system target file, the build process uses the template makefile approach (Embedded Coder).

You can switch from the toolchain approach to the template makefile approach by using this command:

set_param(model, 'MakeCommand', 'make_rtw TMF=1')

Toolchain Approach

Toolchain settings appear under Build process when you set System target file to:

grt.tlc — Generic Real-Time Target
ert.tlc — Embedded Coder
ert_shrlib.tlc — Embedded Coder (host-based shared library target)
A toolchain-compliant system target file

For more information about toolchain-compliant system target files, see Support Toolchain Approach with Custom Target.

The Toolchain settings include these configuration parameters:

Toolchain –– Specifies the collection of third-party software tools that builds the generated code. A toolchain can include a compiler, linker, and archiver, and other prebuild or postbuild tools.
The default value of Toolchain is Automatically locate an installed toolchain. The Toolchain parameter displays name of the located toolchain just below Automatically locate an installed toolchain.
To check that the toolchain is present and validate that the code generator has the information required to use the toolchain, in the Advanced Parameters section, click Validate Toolchain. The resulting Validation Report gives a pass/fail value for the selected toolchain, and shows issues that require resolution.
Build configuration –– Specifies the optimization settings. By default, Build Configuration is set to Faster Builds. You can also select Faster Runs, Debug, and Specify. If you select Specify, you can customize the options for the toolchain. When you click Apply, the custom toolchain settings apply to the current model.

Note

The following system target files, which use the template makefile approach, have the same names but different descriptions from system target files that use the toolchain approach:

ert.tlc — Create Visual C/C++ Solution File for Embedded Coder
grt.tlc — Create Visual C/C++ Solution File for Simulink Coder

To avoid confusion, click Browse to select the system target file and look at the description of each file.

Upgrade Model to Use Toolchain Approach

When you open a model created before R2013b that uses the following system target files, the software tries to upgrade the model. The upgrade changes the configuration from using template makefile settings to using the toolchain settings:

ert.tlc — Embedded Coder
ert_shrlib.tlc — Embedded Coder (host-based shared library target)
grt.tlc — Generic Real-Time Target

Note

To upgrade models using a custom system target file to use the toolchain approach, see Support Toolchain Approach with Custom Target.

Some model configuration parameter values prevent the software from upgrading a model to use toolchain settings. The following instructions show you ways to complete the upgrade process.

Consider upgrading your models and use the toolchain build approach. Doing so is not required. You can continue generating code from a model that has not been upgraded.

Note

The software does not upgrade models that use the following system target files:

ert.tlc — Create Visual C/C++ Solution File for Embedded Coder
grt.tlc — Create Visual C/C++ Solution File for Simulink Coder

To see if a model has been upgraded:

If the Toolchain and Build configuration configuration parameters are specified, the model has been upgraded.
If makefile configuration parameters such as Generate makefile, Make command, and Template makefile are specified, the model has not been upgraded.

Start by creating a working copy of the model using File > Save As. This action preserves the original model and configuration parameters for reference.

Try to upgrade the model using Upgrade Advisor:

On the Modeling tab, in the Evaluate & Manage section, select Upgrade Advisor.
In Upgrade Advisor, select Check and update model to use toolchain approach to build generated code and click Run This Check.
Perform the suggested actions and/or click Update Model.

When you cannot upgrade the model using Upgrade Advisor, one or more of the following parameters is not set to its default value, shown here:

Compiler optimization level — Optimizations off (faster builds)
Generate makefile — Enabled
Template makefile — System target file-specific template makefile
Make command — make_rtw without arguments

Sometimes, a model cannot be upgraded. Try the following procedure:

If Generate makefile is disabled, this case cannot be upgradable. However, you can try enabling it and try upgrading the model using Upgrade Advisor.
If Compiler optimization level is set to Optimizations on (faster runs):
1. Set Compiler optimization level is to Optimizations off (faster builds).
2. Upgrade the model using Upgrade Advisor.
3. Set Build configuration to Faster Runs.
If Compiler optimization level is set to Custom:
1. Copy the Custom compiler optimization flags to a text file.
2. Set Compiler optimization level to Optimizations off (faster builds).
3. Upgrade the model using Upgrade Advisor.
4. Set Build configuration to Specify.
5. To perform the same optimizations, edit the compiler options.
If Template makefile uses a customized template makefile, this case cannot be upgradable. However, you can try the following:
1. Update Template makefile to use the default makefile for the system target file.
  
  Note
  To get the default makefile name, change the System target file, click Apply, change it back, and click Apply again.
2. Upgrade the model using Upgrade Advisor.
3. If the template makefile contains build tool options, such as compiler optimization flags, set Build configuration to Specify and update the options.
4. If the template makefile uses custom build tools, create and register a custom toolchain, as described in Custom Toolchain Registration. Then, set the Toolchain parameter to use the custom toolchain.
  Note
  After registering the custom toolchain, update Toolchain to use the custom toolchain.
5. If the template makefile contains custom rules and logic, these customizations cannot be applied to the upgraded model.

Template Makefile Approach

When the System target file is set to a tlc file that uses the template makefile approach, the software displays Compiler optimization level, Generate makefile, Make command, and Template makefile parameters.

Specify Whether to Generate a Makefile

The Generate makefile option specifies whether the build process is to generate a makefile for a model. By default, the build process generates a makefile. Suppress generation of a makefile, for example in support of custom build processing that is not based on makefiles, by clearing Generate makefile. When you clear this parameter:

The Make command and Template makefile options are unavailable.
Set up post code generation build processing using a user-defined command, as explained in Customize Post-Code-Generation Build Processing.

Specify a Make Command

Each template makefile-based system target file has an associated make command. The code generator uses this internal MATLAB^® command to control the build process. The command appears in the Make command field and runs when you start a build.

Most system target files use the default command, make_rtw. Third-party system target files could supply another make command. See the documentation from the vendor.

In addition to the name of the make command, you can supply makefile options in the Make command field. These options could include compiler-specific options, include paths, and other parameters. When the build process invokes the make utility, these options are passed on the make command line, which adds them to the overall flags passed to the compiler.

Template Makefiles and Make Options lists the Make command options you can use with each supported compiler.

Specify the Template Makefile

The Template makefile field has these functions:

If you selected a system target file with the System Target File Browser, this field displays the name of a MATLAB language file that selects a template makefile for your development environment. For example, in Model Configuration Parameters: Code Generation, the Template makefile field displays grt_default_tmf, indicating that the build process invokes grt_default_tmf.m.
Template Makefiles and Make Options gives a detailed description of the logic by which the build process selects a template makefile.
Alternatively, you can explicitly enter the name of a specific template makefile (including the extension) or a MATLAB language file that returns a template makefile in this field. Use this approach if you are using a system target file that does not appear in the System Target File Browser. For example, use this approach if you have written your own template makefile for a custom system target file.

If you specify your own template makefile, be sure to include the file name extension. If you omit the extension, the build process attempts to find and execute a file with the extension .m (that is, a MATLAB language file). The template make file (or a MATLAB language file that returns a template make file) must be on the MATLAB path. To determine whether the file is on the MATLAB path, enter the following command in the MATLAB Command Window:

which tmf_filename

Associate the Template Makefile with a Toolchain

Specify a toolchain for the template makefile build process. This example provides a definition for a minimal toolchain and shows how you can associate the toolchain with a template makefile that is a copy of ert_unix.tmf or ert_vcx64.tmf.

Use a copy of ert_unix.tmf or ert_vcx64.tmf as the template makefile.

copyfile(fullfile(matlabroot, 'toolbox', 'coder', ...
                  'compile', 'tmf', 'ert_vcx64.tmf'), ...
                  'ert_copy.tmf')

In the template makefile, i.e. ert_copy.tmf, edit the TOOLCHAIN_NAME macro.
```
TOOLCHAIN_NAME = "Minimal Toolchain for TMF Build"
```
Note
The ert_unix.tmf and ert_vcx64.tmf files from the current release are simplified compared to the corresponding files from releases before R2018a. The software determines whether your template makefile uses the simplified approach by checking for the presence of the variable TOOLCHAIN_NAME. A template makefile that is based on ert_unix.tmf and ert_vcx64.tmf files from releases before R2018a does not specify the TOOLCHAIN_NAME variable.
Through the |>MODEL_MODULES<| token, the simplified approach specifies the main, model, and other source files that require compiling. The template makefile that is based on ert_unix.tmf and ert_vcx64.tmf files from releases before R2018a explicitly adds the main and model source files to the list of source files that require compiling.
To update a template makefile that originates from a release before R2018a:
1. Remove references to ert_main.c, classic_main.c or rt_main.c. For example, literal references like ert_main.c or tokenized references like ert_main.$(TARGET_LANG_EXT).
2. Remove references to $(MODEL).c or $(MODEL).$(TARGET_LANG_EXT).

Associate the toolchain with the template make file.

Create a toolchain definition file. For this example, use this code:

Toolchain Definition File

Run the toolchain definition file, which generates a ToolchainInfo object, tc.
```
tc = minimalToolchainForTMF;
```
Save the ToolchainInfo object to a MAT file.
```
save('tcMinimal','tc')
```

Place this code in an rtwTargetInfo.m file.

function rtwTargetInfo(tr)
tr.registerTargetInfo(@loc_createToolchain);
end

function config = loc_createToolchain
config(1) = coder.make.ToolchainInfoRegistry;
config(1).Name = 'Minimal Toolchain for TMF Build';
config(1).FileName = fullfile(fileparts(mfilename('fullpath')),...
    'tcMinimal.mat');
config(1).TargetHWDeviceType = {'*'};
config(1).Platform =  {computer('arch')};
end

Save the file in the current working folder or in a folder that is on the MATLAB search path.

Reset the TargetRegistry.

RTW.TargetRegistry.getInstance('reset');

Associate the template makefile with your model and build the model.
```
set_param(model, 'TemplateMakefile', 'ert_copy.tmf');
slbuild(model);
```

Specify TLC for Code Generation

Target Language Compiler (TLC) is an integral part of the code generator. It enables you to customize generated code. Through customization, you can produce platform-specific code, or you can incorporate your own algorithmic changes for execution speed, code size, or compatibility with existing methods that you prefer to maintain. For additional information, see Target Language Compiler Overview.

TLC options that you specify for code generation appear in the summary section of the generated HTML code generation report.

Note

Specifying TLC command-line options does not add flags to the make command line.

You can specify Target Language Compiler (TLC) command-line options and arguments for code generation using the model parameter TLCOptions in a set_param function call. For example,

>> set_param(gcs,'TLCOptions','-p0 -aWarnNonSaturatedBlocks=0')

Some common uses of TLC options include the following:

-aVarName=1 to declare a TLC variable and/or assign a value to it
-IC:\Work to specify an include path
-v to obtain verbose output from TLC processing (for example, when debugging)

Use of Checksums in Recompilation of Generated Code

When you build a model with GenerateMakefile set to 'on' and GenCodeOnly set to 'off', the software generates a makefile and runs the makefile to compile the generated code. When the compilation is complete, the software creates and saves checksums for source files and configuration data.

If checksums from a previous build are available when you build the model:

The software uses the checksums to determine whether the source files and configuration data are different from the previous build.
If the software detects a difference, the software:
- Regenerates the makefile.
- Recompiles the generated code.

If the build process uses a template makefile, you can disable the use of checksums by adding this text to the template makefile:

DO_NOT_USE_CHECKSUMS=1

In this case, the software uses file timestamps to determine whether it should recompile the generated code.