Main Content

coder.make.ToolchainInfo class

Package: coder.make

Represent custom toolchain

Description

Use coder.make.ToolchainInfo to define and register a new set of software build tools (toolchain) with MathWorks® code generation products.

To get toolchain information about defined toolchains, use coder.make.getDefaultToolchain and coder.make.getToolchainInfoFromRegistry.

A coder.make.ToolchainInfo object contains:

  • coder.make.BuildTool objects that can describe each build tool

  • coder.make.BuildConfiguration objects that can apply sets of options to the build tools

Construction

h = coder.make.ToolchainInfo creates a default ToolchainInfo object and assigns it to a handle, h.

The default ToolchainInfo object includes BuildTool objects and configurations for C, C++, and gmake:

  • The default value of SupportedLanguages, C/C++, adds BuildTool and BuildConfiguration objects for C and C++ compilers to ToolchainInfo.

  • The default value of BuildArtifact, gmake, adds a BuildTool object for gmake to ToolchainInfo.BuilderApplication.

You can use the input arguments (name-value pairs) to override these defaults when you create the ToolchainInfo object. Each property is optional. Each property requires a corresponding value. This example overrides the SupportedLanguages or BuildArtifact defaults.

h = coder.make.ToolchainInfo('SupportedLanguages',vLanguages,'BuildArtifact',vArtifact)

The default property values for SupportedLanguages or BuildArtifact can be overridden only during the creation of the toolchain information object. These properties are read-only after object creation.

Input Arguments

expand all

The property name. For more information, see the Properties description for BuildArtifact.

Values for the BuildArtifact property, specified as a character vector.

The property name. For more information, see the Properties description for Name.

Unique name for the toolchain definition, specified as a character vector. The default value is empty.

The property name. For more information, see the Properties description for Platform.

The supported platform, specified as a character vector. The default value is the current platform.

The property name. For more information, see the Properties description for Revision.

Revision number for ToolchainInfo, specified as a character vector.

The property name. For more information, see the Properties description for SupportedLanguages.

Supported language or languages, specified as a character vector.

The property name. For more information, see the Properties description for SupportedVersion.

Version of software build tools that ToolchainInfo supports, specified as a character vector. The default value is empty

Output Arguments

expand all

A coder.make.ToolchainInfo object, specified using an object handle, such as h. To create h, enter h = coder.make.ToolchainInfo in a MATLAB® Command Window.

Properties

expand all

Custom attributes of the toolchain

Add custom attributes required by the toolchain and specify their default values.

By default, the list of custom attributes is empty.

Attributes returns a coder.make.util.UnorderedList.

For example, the intel_tc.m file from Adding a Custom Toolchain, defines the following custom attributes:

tc.addAttribute('TransformPathsWithSpaces');
tc.addAttribute('RequiresCommandFile');
tc.addAttribute('RequiresBatchFile');

To display the Attributes list from that example in a MATLAB Command Window, enter:

h = intel_tc;
h.Attributes
ans = 


# -------------------
# "Attributes" List
# -------------------
RequiresBatchFile        = true
RequiresCommandFile      = true
TransformPathsWithSpaces = true

Use the following methods with Attributes:

Attributes:

GetAccesspublic
SetAccesspublic

The type of makefile (build artifact) MATLAB Coder™ uses during the software build process.

Initialize this property when you create coder.make.ToolchainInfo. Use the default value, gmake makefile, or override the default value using a name-value pair argument, as described in Construction.

For example:

h = coder.make.ToolchainInfo('BuildArtifact','nmake');
The values can be:

  • 'gmake' or 'gmake makefile' — The GNU make utility

  • 'nmake' or 'nmake makefile' — The Windows® make utility

For example, to display the value of BuildArtifact in a MATLAB Command Window, enter:

h = coder.make.ToolchainInfo;
h.BuildArtifact 
ans  = 

gmake makefile

ToolchainInfo uses the value of the BuildArtifact property to create a BuildTool object for the build artifact in coder.make.ToolchainInfo.BuilderApplication.

The intel_tc.m file from the Adding a Custom Toolchain example uses the following line to set the value of BuildArtifact:

tc = coder.make.ToolchainInfo('BuildArtifact','nmake makefile');

There are no methods to use with BuildArtifact.

Attributes:

GetAccesspublic
SetAccessprotected

List of build configurations

Each entry in this list is a coder.make.BuildConfiguration object.

For example, the intel_tc.m file from Adding a Custom Toolchain, uses the following lines to define the build configurations:

cfg = tc.getBuildConfiguration('Faster Builds');
cfg.setOption('C Compiler',horzcat(cCompilerOpts,optimsOffOpts));
cfg.setOption('C++ Compiler',horzcat(cppCompilerOpts,optimsOffOpts));
cfg.setOption('Linker',linkerOpts);
cfg.setOption('Shared Library Linker',sharedLinkerOpts);
cfg.setOption('Archiver',archiverOpts);

cfg = tc.getBuildConfiguration('Faster Runs');
cfg.setOption('C Compiler',horzcat(cCompilerOpts,optimsOnOpts));
cfg.setOption('C++ Compiler',horzcat(cppCompilerOpts,optimsOnOpts));
cfg.setOption('Linker',linkerOpts);
cfg.setOption('Shared Library Linker',sharedLinkerOpts);
cfg.setOption('Archiver',archiverOpts);

cfg = tc.getBuildConfiguration('Debug');
cfg.setOption('C Compiler',horzcat(cCompilerOpts,optimsOffOpts,debugFlag.CCompiler));
cfg.setOption('C++ Compiler',horzcat(cppCompilerOpts,optimsOffOpts,debugFlag.CppCompiler));
cfg.setOption('Linker',horzcat(linkerOpts,debugFlag.Linker));
cfg.setOption('Shared Library Linker',horzcat(sharedLinkerOpts,debugFlag.Linker));
cfg.setOption('Archiver',horzcat(archiverOpts,debugFlag.Archiver));

tc.setBuildConfigurationOption('all','Make Tool','-f $(MAKEFILE)');

To display the BuildConfigurations list from that example in a MATLAB Command Window, enter:

h = intel_tc;
h.BuildConfigurations
ans = 


# ----------------------------
# "BuildConfigurations" List
# ----------------------------
Debug         = <coder.make.BuildConfiguration>
Faster Builds = <coder.make.BuildConfiguration>
Faster Runs   = <coder.make.BuildConfiguration>

Use the following methods with BuildConfigurations:

Attributes:

GetAccesspublic
SetAccesspublic

The list of build tools in the toolchain.

Each entry in this list is a coder.make.BuildTool object.

When you initialize ToolchainInfo, the SupportedLanguages property determines which build tools are created in BuildTools. For more information, see SupportedLanguages or Construction.

The BuildTool objects ToolchainInfo can create based on the SupportedLanguages are:

  • Assembler

  • C Compiler

  • C++ Compiler

  • Linker

  • Archiver

For example, the intel_tc.m file from Adding a Custom Toolchain, uses the following lines to get and update one of the BuildTool objects:

% ------------------------------
% C Compiler
% ------------------------------
 
tool = tc.getBuildTool('C Compiler');

tool.setName('Intel C Compiler');
tool.setCommand('icl');
tool.setPath('');

tool.setDirective('IncludeSearchPath','-I');
tool.setDirective('PreprocessorDefine','-D');
tool.setDirective('OutputFlag','-Fo');
tool.setDirective('Debug','-Zi');

tool.setFileExtension('Source','.c');
tool.setFileExtension('Header','.h');
tool.setFileExtension('Object','.obj');

tool.setCommandPattern('|>TOOL<| |>TOOL_OPTIONS<| |>OUTPUT_FLAG<||>OUTPUT<|');

To display the BuildTools list from that example in a MATLAB Command Window, enter:

h = intel_tc;
h.BuildTools
ans = 


# -------------------
# "BuildTools" List
# -------------------
C Compiler   = <coder.make.BuildTool>
C++ Compiler = <coder.make.BuildTool>
Archiver     = <coder.make.BuildTool>
Linker       = <coder.make.BuildTool>
MEX Tool     = <coder.make.BuildTool>

Use the following methods with BuildTools:

Attributes:

GetAccesspublic
SetAccesspublic

Properties of the build tool that runs the makefile or build artifact

ToolchainInfo uses the value of the BuildArtifact property to create a BuildTool object for coder.make.ToolchainInfo.BuilderApplication, as described in Construction.

For example, the intel_tc.m file from Adding a Custom Toolchain, uses the following lines to set the BuildArtifact and update BuilderApplication objects:

h = coder.make.ToolchainInfo('BuildArtifact','nmake');

To display the value of BuilderApplication from that example in a MATLAB Command Window, enter:

h.BuilderApplication
ans = 

##############################################
# Build Tool: NMAKE Utility
##############################################

Language              : ''
OptionsRegistry       : {'Make Tool','MAKE_FLAGS'}
InputFileExtensions   : {}
OutputFileExtensions  : {}
DerivedFileExtensions : {}
SupportedOutputs      : {'*'}
CommandPattern        : '|>TOOL<| |>TOOL_OPTIONS<|'

# ---------
# Command
# ---------
MAKE = nmake
MAKE_PATH  = 

# ------------
# Directives
# ------------
Comment                = #
DeleteCommand          = @del
DisplayCommand         = @echo
FileSeparator          = \
ImpliedFirstDependency = $<
ImpliedTarget          = $@
IncludeFile            = !include
LineContinuation       = \
MoveCommand            = @mv
ReferencePattern       = \$\($1\)
RunScriptCommand       = @cmd /C

# -----------------
# File Extensions
# -----------------
Makefile = .mk

Use the setBuilderApplication method with BuilderApplication.

Attributes:

GetAccesspublic
SetAccesspublic

Commands the toolchain needs to inline within the generated makefile

Specify inlined commands to insert verbatim into the makefile. The default value is empty.

The datatype is character vector.

For example, to display and then update the value of the InlinedCommands property, use the MATLAB Command Window to enter:

h.InlinedCommands
ans  = 

     ''
h.InlinedCommands =  '!include <ntwin32.mak>';
h.InlinedCommands
!include <ntwin32.mak>

The Adding a Custom Toolchain example does not include the InlinedCommands property.

There are no methods to use with InlinedCommands.

Attributes:

GetAccesspublic
SetAccesspublic

MATLAB cleanup commands

Specify MATLAB commands or scripts to perform cleanup routines specific to this toolchain. Use commands or scripts that can be invoked from the MATLAB Command Window. The default value is empty.

The datatype is a cell array of character vectors.

For example, to display and then update the value of the MATLABSetup and MATLABCleanup properties, use the MATLAB Command Window to enter:

h = coder.make.ToolchainInfo;
h.MATLABSetup;
h.MATLABCleanup;
h.MATLABSetup{1}    = sprintf('if ispc \n origTMP=getenv(''TMP''); \n setenv(''TMP'',''C:\\TEMP'');\nend');
h.MATLABCleanup{1}  = sprintf('if ispc \n setenv(''TMP'',origTMP); \nend');

The following list illustrates where this property fits in the sequence of operations :

  1. MATLAB Setup

  2. Shell Setup

  3. Prebuild

  4. Build (assembler, compilers, linker, archiver)

  5. Postbuild

  6. Shell Cleanup

  7. MATLAB Cleanup

The Adding a Custom Toolchain example does not include the MATLABCleanup property.

There are no methods to use with MATLABCleanup.

Attributes:

GetAccesspublic
SetAccesspublic

MATLAB setup commands

Specify MATLAB commands or scripts to perform setup routines specific to this toolchain. Use commands or scripts that can be invoked from the MATLAB Command Window. The default value is empty.

The datatype is a cell array of character vectors.

For example, to display and then update the value of the MATLABSetup and MATLABCleanup properties, use the MATLAB Command Window to enter:

h = coder.make.ToolchainInfo;
h.MATLABSetup;
h.MATLABCleanup;
h.MATLABSetup{1}    = sprintf('if ispc \n origTMP=getenv(''TMP''); \n setenv(''TMP'',''C:\\TEMP'');\nend');
h.MATLABCleanup{1}  = sprintf('if ispc \n setenv(''TMP'',origTMP); \nend');

The following list illustrates where this property fits in the sequence of operations :

  1. MATLAB Setup

  2. Shell Setup

  3. Prebuild

  4. Build (assembler, compilers, linker, archiver)

  5. Postbuild

  6. Shell Cleanup

  7. MATLAB Cleanup

The Adding a Custom Toolchain example does not include the MATLABSetup property.

There are no methods to use with MATLABCleanup.

Attributes:

GetAccesspublic
SetAccesspublic

List of custom macros that contains macro names and values

The list is a coder.make.util.OrderedList of coder.make.BuildItem objects.

By default this list is empty. For example:

h = coder.make.ToolchainInfo;
h.Macros
ans = 


# ---------------
# "Macros" List
# ---------------
(empty)

ToolchainInfo uses macros in two ways:

  • It writes macros that are used by the current build to the makefile as variables. For example:

    TI_INSTALL 	 =  C:\Program Files\CCSv4
    TI_C2000_TOOLS 	 =  $(TI_INSTALL)\tools\compiler\c2000\bin

  • When the custom toolchain has been registered, validate expands the complete path provided by a macro, including macros contained within macros. For example, when ToolchainInfo validates the path in the following compiler information, it expands both TI_C2000_TOOLS and TI_INSTALL:

    Command = 'cl2000'
    Path = '$(TI_C2000_TOOLS)'

The default value of Macros is an empty list.

The datatype is coder.make.util.OrderedList of coder.make.BuildItem objects.

For example, the intel_tc.m file from Adding a Custom Toolchain uses the following lines to add macros to Macros:

% ------------------------------
% Macros
% ------------------------------
tc.addMacro('MW_EXTERNLIB_DIR',['$(MATLAB_ROOT)\extern\lib\' tc.Platform '\microsoft']);
tc.addMacro('MW_LIB_DIR',['$(MATLAB_ROOT)\lib\' tc.Platform]);
tc.addMacro('CFLAGS_ADDITIONAL','-D_CRT_SECURE_NO_WARNINGS');
tc.addMacro('CPPFLAGS_ADDITIONAL','-EHs -D_CRT_SECURE_NO_WARNINGS');
tc.addMacro('LIBS_TOOLCHAIN','$(conlibs)');
tc.addMacro('CVARSFLAG','');

tc.addIntrinsicMacros({'ldebug','conflags','cflags'});

With that example, to see the corresponding property values in a MATLAB command window, enter:

h = intel_tc;
h.Macros
ans = 


# ---------------
# "Macros" List
# ---------------
MW_EXTERNLIB_DIR    = $(MATLAB_ROOT)\extern\lib\win64\microsoft
MW_LIB_DIR          = $(MATLAB_ROOT)\lib\win64
CFLAGS_ADDITIONAL   = -D_CRT_SECURE_NO_WARNINGS
CPPFLAGS_ADDITIONAL = -EHs -D_CRT_SECURE_NO_WARNINGS
LIBS_TOOLCHAIN      = $(conlibs)
CVARSFLAG           = 
ldebug              = 
conflags            = 
cflags              = 

Use the following methods with this property:

Attributes:

GetAccesspublic
SetAccesspublic

Unique name for the toolchain definition

Specify the full name of the toolchain. This name also appears as one of the Toolchain parameter options on the Hardware tab of the project build settings. The default value is empty. The recommended format is:

name version | build artifact (platform)

The data type is character vector.

For example, the intel_tc.m file from Adding a Custom Toolchain provides a line that defines the value of Name. To see the property value, in the Command Window, enter:

h = intel_tc;
h.Name

Attributes:

GetAccesspublic
SetAccesspublic

Specify the supported platform

Specify the platform upon which the toolchain will be used. The default value is the current platform. Supported values are win32, win64, maci64, and glnxa64.

Create a separate ToolchainInfo for each platform.

The datatype is character vector.

This property does not have any associated methods. Assign the value directly to the Platform.

For example, the intel_tc.m file from Adding a Custom Toolchain uses the following line to define the value of Platform:

tc.Platform         = 'win64';

With that example, to see the corresponding property values in a MATLAB Command Window, enter:

h = intel_tc;
h.Platform
ans  = 

win64

Attributes:

GetAccesspublic
SetAccesspublic

The list of tools used after the linker/archiver are invoked.

The list is a coder.make.util.OrderedList of coder.make.BuildTool objects.

To see the corresponding property values in the MATLAB Command Window, enter:

h = coder.make.ToolchainInfo;
h.PostbuildTools

The Adding a Custom Toolchain example does not include the PostbuildTools property.

Use the following methods with this property:

The list of tools used before compiling the source files into object files.

The list is a coder.make.util.OrderedList of coder.make.BuildTool objects.

By default this list is empty. For example:

h.PrebuildTools
ans = 


# ----------------------
# "PrebuildTools" List
# ----------------------
(empty)

The Adding a Custom Toolchain example does not include the PrebuildTools property.

Use the following methods with this property:

Attributes:

GetAccesspublic
SetAccesspublic

Assign revision number to ToolchainInfo

The author of the toolchain definition file can use this information to differentiate one version of the file from another. The default value is 1.0.

The datatype is character vector.

This property does not have any associated methods. Assign the value directly to the Revision.

For example:

h.Revision
ans  = 

1.0

h.Revision = '2.0';
h.Revision
ans  = 

2.0

Attributes:

GetAccesspublic
SetAccesspublic

Shell scripts that clean up the toolchain

Specify shell commands or scripts to perform cleanup routines specific to this toolchain. Use commands or scripts that can be invoked from the system command environment. The default value is empty.

The datatype is a cell array of character vectors. Each character vector is a shell cleanup command.

If ToolchainInfo invokes a setup routine, you can use a corresponding set of cleanup routines to restore the system environment to its original settings. For example, if a setup routine added environment variables and folders to the system path, you can use a cleanup routine to remove them.

For example:

>> h.ShellCleanup

ans  = 

     []

>> h.ShellCleanup = 'call "cleanup_mssdk71.bat"';

>> h.ShellCleanup

ans = 

    'call "cleanup_mssdk71.bat"'

The following list illustrates where this property fits in the sequence of operations :

  1. MATLAB Setup

  2. Shell Setup

  3. Prebuild

  4. Build (assembler, compilers, linker, archiver)

  5. Postbuild

  6. Shell Cleanup

  7. MATLAB Cleanup

The Adding a Custom Toolchain example does not include the ShellCleanup property.

Attributes:

GetAccesspublic
SetAccesspublic

Shell scripts that set up the toolchain

Specify shell commands or scripts to perform setup routines specific to this toolchain. Use commands or scripts that can be invoked from the system command environment. The default value is empty.

The datatype is a cell array of character vectors. Each character vector is a shell setup command.

If ToolchainInfo invokes a setup routine, you can use a corresponding set of cleanup routines to restore the system environment to its original settings. For example, if a setup routine added environment variables and folders to the system path, you can use a cleanup routine to remove them.

For example:

>> h.ShellSetup

ans  = 

     []

>> h.ShellSetup = 'call "setup_mssdk71.bat"';

>> h.ShellSetup

ans = 

    'call "setup_mssdk71.bat"'

The intel_tc.m file in Adding a Custom Toolchain uses the following lines to set the value of ShellSetup:

% ------------------------------
% Setup
% ------------------------------
% Below we are using %ICPP_COMPILER12% as root folder where Intel Compiler is
% installed. You can either set an environment variable or give full path to the
% compilervars.bat file
tc.ShellSetup{1} = 'call %ICPP_COMPILER12%\bin\compilervars.bat intel64';

With that example, to see the corresponding property values in the MATLAB Command Window, enter:

h = intel_tc;
h.ShellSetup
ans = 

    'call %ICPP_COMPILER12%\bin\compilervars.bat intel64'

The following list illustrates where this property fits in the sequence of operations :

  1. MATLAB Setup

  2. Shell Setup

  3. Prebuild

  4. Build (assembler, compilers, linker, archiver)

  5. Postbuild

  6. Shell Cleanup

  7. MATLAB Cleanup

Attributes:

GetAccesspublic
SetAccesspublic

Create BuildTool objects for specific languages

Initializing ToolchainInfo creates BuildTool objects for the language or set of languages specified by SupportedLanguages.

If you do not specify a value for SupportedLanguages, the default value is 'C/C++'. This adds BuildTool objects for a C compiler and a C++ compiler to the other BuildTool objects in ToolchainInfo.

To override the default, use a name-value pair to specify a value for SupportedLanguages when you initialize ToolchainInfo. For example:

h = coder.make.ToolchainInfo('SupportedLanguages','C');
The value can be: 'C', 'C++', 'C/C++', 'Asm/C', 'Asm/C++', or 'Asm/C/C++'.

The SupportedLanguages property does not have any related methods.

The Adding a Custom Toolchain example does not include the SupportedLanguages property.

Attributes:

GetAccesspublic
SetAccessprotected

The version of the software build tools ToolchainInfo supports.

The default value is empty.

The datatype is character vector.

This property does not have any associated methods. Assign the value directly to the SupportedVersion.

With the Adding a Custom Toolchain example, the value of SupportedVersion is defined in the intel_tc.m toolchain definition file:

tc.SupportedVersion = '12.1';

With that example, to see the corresponding property values in the MATLAB command window, enter:

h = intel_tc;
h.SupportedVersion
ans  = 

12.1

Attributes:

GetAccesspublic
SetAccesspublic

Methods

addAttributeAdd custom attribute to Attributes
addBuildConfigurationAdd build configuration
addBuildToolAdd BuildTool object to BuildTools
addIntrinsicMacrosAdd intrinsic macro to Macros
addMacroAdd macro to Macros
addPostDownloadToolAdd post-download tool to PostDownloadTool
addPostExecuteToolAdd post-execute tool to PostbuildTools
addPostbuildToolAdd postbuild tool to PostbuildTools
addPrebuildToolAdd prebuild tool to PrebuildTools
cleanupRun cleanup commands
getAttributeGet value of attribute
getAttributesGet list of attribute names
getBuildConfigurationGet handle for build configuration object
getBuildToolGet BuildTool object
getMacroGet value of macro
getPostbuildToolGet postbuild BuildTool object
getPrebuildToolGet prebuild BuildTool object
getSupportedLanguagesGet list of supported languages
isAttributeDetermine if attribute exists
removeAttributeRemove attribute
removeBuildConfigurationRemove build configuration
removeBuildToolRemove BuildTool object from BuildTools
removeIntrinsicMacrosRemove intrinsic macro
removeMacroRemove macro from Macros
removePostbuildToolRemove postbuild build tool
removePrebuildToolRemove prebuild build tool
setBuildConfigurationSet value of specified build configuration
setBuildConfigurationOptionSets value of build tool options for build configuration
setBuildToolAssign BuildTool object to named build tool in BuildTools
setBuilderApplicationUpdate builder application to work on specific platform
setMacroSet value of macro
setPostbuildToolAssign BuildTool object to PostbuildTool tool in PostbuildTools
setPrebuildToolAssign BuildTool object to named PrebuildTool in PrebuildTools
setupInvoke toolchain setup commands specified by MATLABSetup and ShellSetup
validateValidate toolchain