Use Automated Tool to Assist Migration of Existing Toolchain to Target Framework
R2026bUse the function to assist you in upgrading coder.make.ToolchainInfo toolchains to their Target Framework equivalent. The
function generates the following MATLAB® files:
A file that assists in defining a Target Framework object equivalent to the original toolchain defined using
coder.make.ToolchainInfoA file that converts intrinsic macros in the original toolchain to MATLAB settings or environment variables, depending on the value of the
UseMATLABSettingsname-value argument
Conversions When Upgrading Toolchain
The generated files might convert some existing toolchain settings to a different
representation when you upgrade them to the Target Framework. To do
prompts appear in the generated files identifying these conversions. Address these prompts
by confirming or amending the generated toolchain definition.
Individual build configurations in the existing toolchain are replaced by directives:
The
EnableOptimizationdirective contains the flags in the "Faster Runs" build configuration but not the "Faster Builds" build configuration.The
DisableOptimizationdirective contains the flags in the "Faster Builds" build configuration but not the "Faster Runs" build configuration.The
Debugdirective derives directly from the "Debug" directive in the existing toolchain.
Build configuration options for linkers and shared library linkers in the existing toolchain are incorporated into common flags and a
Shareddirective in the upgraded toolchain. Flags that existed in the shared library linker build configuration options but not that of the linker appear in thisShareddirective.MATLAB setup commands in the existing toolchain are not directly supported in the Target Framework, and require you to amend the toolchain definition.
Shell setup commands in the existing toolchain appear in the
SetupCommandof theEnvironmentConfigurationproperty of the upgraded toolchain object.Intrinsic macros in the existing toolchain appear as MATLAB settings or environment variables, while non-intrinsic macros are recursively expanded into their values. Additionally, some macros not supported by Target Framework toolchains are ignored.
Post-build tools in the existing toolchain are converted based on their name:
Name Contains Substring (Case Sensitive) Converted Tool Type binBIN Converter hexHEX Converter srecSREC Converter executableExecutable Size sizeExecutable Size Other post-build tools not listed above require you to amend the toolchain definition.
Some predefined macros in post-build tools are modified to improve handling of spaces in paths across different platforms. For instance:
Existing Upgraded $(basename $(PRODUCT))"$(PRODUCT_BASENAME_QUOTABLE)"$(PRODUCT)"$(PRODUCT_QUOTABLE)"The Target Framework equivalent adds a trailing space to the
Outputdirective depending on the presence of a space between the|>OUTPUT_FLAG<|and|>OUTPUT<|tokens in the command pattern of the existing build tool. This conversion does not trigger aTo Doprompt.
Use Automated Tool to Assist Migration of GCC-Based Toolchain to Target Framework
This example shows how to use the coder.make.upgradeToolchain function to assist you in upgrading a GCC-Based toolchain to its Target Framework equivalent.
To run this example on Windows®, you must install the support package MATLAB Support for MinGW-w64 C/C++/Fortran Compiler.
Get Existing Toolchain
Load an existing GCC-based toolchain by running the exampleLegacyToolchain script. In other scenarios, you can also obtain your toolchain by loading it from a MAT file or by referencing it by name if you already registered it with MATLAB. See Custom Toolchain Registration for details.
tc = exampleLegacyToolchain;
Run Toolchain Upgrade Tool
Call coder.make.upgradeToolchain on the existing toolchain. Name the upgraded toolchain Example upgraded GCC based toolchain.
coder.make.upgradeToolchain(tc, ... OutputFile="getUpgradedGCCToolchain.m", ... TargetToolchainName="Example upgraded GCC based toolchain");
Inspect and Process Toolchain Upgrade File
Inspect a portion of getUpgradedGCCToolchain.m.
upgradedToolchainFile = "getUpgradedGCCToolchain.m"; coder.example.extractLines(upgradedToolchainFile, "function tc", "Linker", 1, 0);
function tc = getUpgradedGCCToolchain
% To do:
% - Open MATLAB settings file getUpgradedGCCToolchain_MATLABSettings.m, created in the current folder.
% - Remove settings that are not required.
% - Enter values of settings by replacing "|>YOUR_VALUE<|".
% - Run the MATLAB settings commands.
% Create host operating system support object
hostOS = target.create("HostOperatingSystemSupport");
hostOS.Windows = 0;
hostOS.Mac = 0;
hostOS.Linux = 1;
% Create toolchain object
tcName = "Example upgraded GCC based toolchain";
tc = target.create("Toolchain", Name=tcName, ...
HostOperatingSystemSupport=target.create("HostOperatingSystemSupport", Copy=hostOS));
% Specify make tool type
tc.Builder = target.create("MakefileBuilder", "GMake");
% C Compiler
cCompiler = target.create("BuildTool", "C Compiler", ...
"$(ExampleUpgradedGCCBasedToolchain.EXAMPLE_GCC_TOOLCHAIN_INSTALL_DIR)/gcc", ...
Name=tcName+" C Compiler", ...
HostOperatingSystemSupport=target.create("HostOperatingSystemSupport", Copy=hostOS));
cCompiler.setDirective("CompileFlag", "-c");
cCompiler.setDirective("Debug", "-g");
cCompiler.setDirective("IncludeSearchPath", "-I");
cCompiler.setDirective("OutputFlag", "-o ");
cCompiler.setDirective("PreprocessFile", "-E");
cCompiler.setDirective("PreprocessorDefine", "-D");
% To do:
% - Confirm whether optimization directives are specified correctly.
% Additional information:
% - "EnableOptimization" directive is for flags originally specified by "Faster Runs" build configuration.
% - "DisableOptimization" directive is for flags originally specified by "Faster Builds" build configuration.
% - "Debug" build configuration uses flags specified by "DisableOptimization" and "Debug" directives.
cCompiler.setDirective("EnableOptimization", "-O3 -fno-loop-optimize -fno-aggressive-loop-optimizations");
cCompiler.setDirective("DisableOptimization", "-O0");
cCompiler.setFileExtensions("Header", ".h");
cCompiler.setFileExtensions("Object", ".o");
cCompiler.setFileExtensions("Source", ".c");
cCompiler.Command.Arguments = ["-fwrapv", ...
"-fPIC"];
tc.Tools(end+1) = cCompiler;
% C++ Compiler
cppCompiler = target.create("BuildTool", "C++ Compiler", ...
"$(ExampleUpgradedGCCBasedToolchain.EXAMPLE_GCC_TOOLCHAIN_INSTALL_DIR)/g++", ...
Name=tcName+" C++ Compiler", ...
HostOperatingSystemSupport=target.create("HostOperatingSystemSupport", Copy=hostOS));
cppCompiler.setDirective("CompileFlag", "-c");
cppCompiler.setDirective("Debug", "-g");
cppCompiler.setDirective("IncludeSearchPath", "-I");
cppCompiler.setDirective("OutputFlag", "-o ");
cppCompiler.setDirective("PreprocessFile", "-E");
cppCompiler.setDirective("PreprocessorDefine", "-D");
% To do:
% - Confirm whether optimization directives are specified correctly.
% Additional information:
% - "EnableOptimization" directive is for flags originally specified by "Faster Runs" build configuration.
% - "DisableOptimization" directive is for flags originally specified by "Faster Builds" build configuration.
% - "Debug" build configuration uses flags specified by "DisableOptimization" and "Debug" directives.
cppCompiler.setDirective("EnableOptimization", "-O3 -fno-loop-optimize -fno-aggressive-loop-optimizations");
cppCompiler.setDirective("DisableOptimization", "-O0");
cppCompiler.setFileExtensions("Header", ".hpp");
cppCompiler.setFileExtensions("Object", ".o");
cppCompiler.setFileExtensions("Source", ".cpp");
cppCompiler.Command.Arguments = ["-fwrapv", ...
"-fPIC"];
tc.Tools(end+1) = cppCompiler;
Each To do prompt identifies conversions in the upgrade that might require you to amend the toolchain definition. In this example, the function identifies the following items:
Update settings in the generated settings file (see next section).
Confirm or update optimization flags for the C compiler.
Confirm or update optimization flags for the C++ compiler.
Address these items based on the requirements of your build.
Inspect and Process Settings File
Inspect getUpgradedGCCToolchain_MATLABSettings.m, which converts intrinsic macros in the toolchain to their equivalent MATLAB settings.
settingsFile = 'getUpgradedGCCToolchain_MATLABSettings.m'; coder.example.extractLines(settingsFile, "To do", "EXAMPLE_GCC_TOOLCHAIN_INSTALL_DIR.PersonalValue", 1, 1);
% To do:
% - Open MATLAB settings file getUpgradedGCCToolchain_MATLABSettings.m, created in the current folder.
% - Remove settings that are not required.
% - Enter values of settings by replacing "|>YOUR_VALUE<|".
% - Run the MATLAB settings commands.
% Settings
s = settings;
parent = s;
if ~hasGroup(parent,"ExampleUpgradedGCCBasedToolchain")
addGroup(parent, "ExampleUpgradedGCCBasedToolchain");
end
if ~hasSetting(s.ExampleUpgradedGCCBasedToolchain, "EXAMPLE_GCC_TOOLCHAIN_INSTALL_DIR")
addSetting(s.ExampleUpgradedGCCBasedToolchain, "EXAMPLE_GCC_TOOLCHAIN_INSTALL_DIR");
end
s.ExampleUpgradedGCCBasedToolchain.EXAMPLE_GCC_TOOLCHAIN_INSTALL_DIR.PersonalValue = "|>YOUR_VALUE<|";
According to the To do prompt, replace "|>YOUR_VALUE<|" with the location of the installation path. For example:
if ispc toolchainLocation = fullfile(getenv('MW_MINGW64_LOC'), 'bin'); else toolchainLocation = fullfile('/usr', 'bin'); end settingsContent = fileread(settingsFile); settingsContent = strrep(settingsContent, "|>YOUR_VALUE<|", toolchainLocation); writelines(settingsContent, settingsFile);
If you prefer a different name for the settings group or particular settings, you can update them now. In this case, you will also need to search and replace settings in the file that implements the upgraded toolchain. Alternatively, you can rerun coder.make.upgradeToolchain while specifying a different value for the SettingsGroup argument.
Upgrade Toolchain and Configure Settings
Run the generated scripts to upgrade the existing toolchain to the Target Framework equivalent.
upgradedTc = getUpgradedGCCToolchain()
upgradedTc =
Toolchain with identifier "Example upgraded GCC based toolchain" and properties:
Builder: [1×1 target.MakefileBuilder]
BuildRequirements: [1×1 target.BuildDependencies]
EnvironmentConfiguration: [1×1 target.EnvironmentConfiguration]
HostOperatingSystemSupport: [1×1 target.HostOperatingSystemSupport]
RunsOn: [0×0 target.ExecutionContext]
Tools: [1×8 target.Tool]
SupportedHardware: [0×0 target.HardwareComponentSupport]
Id: 'Example upgraded GCC based toolchain'
Name: 'Example upgraded GCC based toolchain'
IsValid: 1
Also convert macros in the toolchain to their corresponding MATLAB settings.
getUpgradedGCCToolchain_MATLABSettings()
Test Upgraded Toolchain
Test the upgraded toolchain by building a standalone executable from a main file.
Create a simple main file main.c in the build directory. Create the build directory if it does not exist.
buildDir = fullfile(pwd, "build"); if ~isfolder(buildDir) mkdir(buildDir) end writelines('int main(void) { return 0; }', fullfile(buildDir, 'main.c'));
Register main.c as a source file in the RTW.BuildInfo object.
buildInfo = RTW.BuildInfo;
buildInfo.setRootFolder(char(buildDir));
buildInfo.addSourceFiles("main.c", buildDir);Build the standalone executable.
codebuild(buildInfo, BuildMethod=upgradedTc, BuildVariant="STANDALONE_EXECUTABLE", RTWVerbose=false);Register and Apply Toolchain
Register the upgraded toolchain in the Target Framework.
registeredObjects = target.add(upgradedTc);
target.add summary:
Objects added to internal database for current MATLAB session:
target.BuildTool "Example upgraded GCC based toolchain Archiver"
target.BuildTool "Example upgraded GCC based toolchain C Compiler"
target.BuildTool "Example upgraded GCC based toolchain C++ Compiler"
target.BuildTool "Example upgraded GCC based toolchain C++ Linker"
target.BuildTool "Example upgraded GCC based toolchain Linker"
target.Toolchain "Example upgraded GCC based toolchain"
15 objects not added because they already exist.
Apply the registered toolchain to the MATLAB Coder™ or Simulink Coder™ configuration set.
% MATLAB Coder cfg = coder.config('exe'); cfg.Toolchain = upgradedTc.Name; % Simulink Coder cfg = Simulink.ConfigSet; set_param(cfg, "Toolchain", upgradedTc.Name);
In Simulink®, you can verify the name of the toolchain by opening the Configuration Parameters dialog box and navigating to Code Generation > Toolchain.
Generate and Build Code
Configure a Simulink model or MATLAB Coder with the registered toolchain. Apply the toolchain by generating and building the code.
Clean Up Settings and Unregister Toolchain
Remove the MATLAB settings and unregister the toolchain created as part of this example.
Remove the MATLAB settings group.
s = settings;
s.removeGroup("ExampleUpgradedGCCBasedToolchain");Unregister the toolchain.
target.remove(registeredObjects);
target.remove summary:
Objects removed from internal database:
target.BuildTool "Example upgraded GCC based toolchain Archiver"
target.BuildTool "Example upgraded GCC based toolchain C Compiler"
target.BuildTool "Example upgraded GCC based toolchain C++ Compiler"
target.BuildTool "Example upgraded GCC based toolchain C++ Linker"
target.BuildTool "Example upgraded GCC based toolchain Linker"
target.Toolchain "Example upgraded GCC based toolchain"