Main Content

coder.make.ToolchainInfo Class

Namespace: coder.make

Represent custom toolchain

expand all in page

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

Creation

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 Add Custom Toolchains to MATLAB® Coder™ Build Process, 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:

GetAccess
public
SetAccess
public

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 Creation.

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 Add Custom Toolchains to MATLAB® Coder™ Build Process 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:

GetAccess
public
SetAccess
protected

List of build configurations

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

For example, the intel_tc.m file from Add Custom Toolchains to MATLAB® Coder™ Build Process, 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:

GetAccess
public
SetAccess
public

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 Creation.

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 Add Custom Toolchains to MATLAB® Coder™ Build Process, 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:

GetAccess
public
SetAccess
public

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 Creation.

For example, the intel_tc.m file from Add Custom Toolchains to MATLAB® Coder™ Build Process, 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:

GetAccess
public
SetAccess
public

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 Add Custom Toolchains to MATLAB® Coder™ Build Process example does not include the InlinedCommands property.

There are no methods to use with InlinedCommands.

Attributes:

GetAccess
public
SetAccess
public

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 Add Custom Toolchains to MATLAB® Coder™ Build Process example does not include the MATLABCleanup property.

There are no methods to use with MATLABCleanup.

Attributes:

GetAccess
public
SetAccess
public

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 Add Custom Toolchains to MATLAB® Coder™ Build Process example does not include the MATLABSetup property.

There are no methods to use with MATLABCleanup.

Attributes:

GetAccess
public
SetAccess
public

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 Add Custom Toolchains to MATLAB® Coder™ Build Process 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:

GetAccess
public
SetAccess
public

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 Add Custom Toolchains to MATLAB® Coder™ Build Process 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:

GetAccess
public
SetAccess
public

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, maca64, 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 Add Custom Toolchains to MATLAB® Coder™ Build Process 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:

GetAccess
public
SetAccess
public

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 Add Custom Toolchains to MATLAB® Coder™ Build Process 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 Add Custom Toolchains to MATLAB® Coder™ Build Process example does not include the PrebuildTools property.

Use the following methods with this property:

Attributes:

GetAccess
public
SetAccess
public

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:

GetAccess
public
SetAccess
public

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 Add Custom Toolchains to MATLAB® Coder™ Build Process example does not include the ShellCleanup property.

Attributes:

GetAccess
public
SetAccess
public

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 Add Custom Toolchains to MATLAB® Coder™ Build Process 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:

GetAccess
public
SetAccess
public

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 Add Custom Toolchains to MATLAB® Coder™ Build Process example does not include the SupportedLanguages property.

Attributes:

GetAccess
public
SetAccess
protected

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 Add Custom Toolchains to MATLAB® Coder™ Build Process 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:

GetAccess
public
SetAccess
public

Methods

expand all

Version History

Introduced in R2013a

See Also

| | | |

Topics