Hauptinhalt

Use Automated Tool to Assist Migration of Existing Toolchain to Target Framework

R2026b

Use 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.ToolchainInfo

  • A file that converts intrinsic macros in the original toolchain to MATLAB settings or environment variables, depending on the value of the UseMATLABSettings name-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 EnableOptimization directive contains the flags in the "Faster Runs" build configuration but not the "Faster Builds" build configuration.

    • The DisableOptimization directive contains the flags in the "Faster Builds" build configuration but not the "Faster Runs" build configuration.

    • The Debug directive 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 Shared directive in the upgraded toolchain. Flags that existed in the shared library linker build configuration options but not that of the linker appear in this Shared directive.

  • 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 SetupCommand of the EnvironmentConfiguration property 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
    bin BIN Converter
    hex HEX Converter
    srec SREC Converter
    executable Executable Size
    size Executable 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:

    ExistingUpgraded
    $(basename $(PRODUCT)) "$(PRODUCT_BASENAME_QUOTABLE)"
    $(PRODUCT) "$(PRODUCT_QUOTABLE)"

  • The Target Framework equivalent adds a trailing space to the Output directive 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 a To Do prompt.

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"

See Also

Topics