target.Toolchain Class

Namespace: target

Capture high-level information about toolchain

Since R2022b

Description

Use a target.Toolchain object to capture high-level information about a toolchain.

To create a target.Toolchain object, use the target.create function. Create the object in a single step.

toolchainObject = target.create('Toolchain', ...
                                nameOfToolchain, ...
                                parameterXName, parameterXValue, ...
                                parameterYName, parameterYValue, ...
                                parameterZName, parameterZValue)

nameOfToolchain is the name of the target.Toolchain object that you want to create. parameterXName is the name of either a property or a referenced object property –– see tables below.

Properties

Id — Object identifier

string

Unique ID of object in internal database.

Attributes:

GetAccess	public
SetAccess	private

Name — Toolchain name

string

Name of the toolchain, in a form that you want workflows to display.

Example: 'CMake/Ninja for all hosts'

Attributes:

GetAccess	public
SetAccess	public

SupportedHardware — Supported target devices

target.HardwareComponentSupport object array

Optional. Target devices for which the toolchain can build code.

Attributes:

GetAccess	public
SetAccess	public

HostOperatingSystemSupport — Operating system support

target.HostOperatingSystemSupport object

Development computer operating systems that the toolchain can run on.

Attributes:

GetAccess	public
SetAccess	public

Tools — Toolchain tools

target.Tool object array

Tools in the toolchain.

If you use name-value arguments to create a target.Toolchain object, for the Tools property, specify these arguments.

Name	Description
'Family'	Provides an initial list of tools through a default set of target.BuildTool objects configured for the specified family. Example: 'Family', 'GNU'
'Assembler'	Optional. In the list of tools, specify the assembler through a target.BuildTool object. The argument sets: Name of BuildToolType property (a target.BuildToolType object) to 'Assembler'. String and Arguments of Command property (a target.Command object) using specified value. Example: 'Assembler', 'as'
'CCompiler'	Optional. In the list of tools, specify the C compiler through a target.BuildTool object. The argument sets: Name of BuildToolType property (a target.BuildToolType object) to 'C Compiler'. String and Arguments of Command property (a target.Command object) using specified value. Example: 'CCompiler', 'gcc'
'CppCompiler'	Optional. In the list of tools, specify the C++ compiler through a target.BuildTool object. The argument sets: Name of BuildToolType property (a target.BuildToolType object) to 'C++ Compiler'. String and Arguments of Command property (a target.Command object) using specified value. Example: 'CppCompiler', 'g++'
'Linker'	Optional. In the list of tools, specify the linker through a target.BuildTool object. The argument sets: Name of BuildToolType property (a target.BuildToolType object) to 'Linker'. String and Arguments of Command property (a target.Command object) using specified value. Example: 'Linker', 'gcc'
'CppLinker'	Optional. In the list of tools, specify the C++ linker through a target.BuildTool object. The argument sets: Name of BuildToolType property (a target.BuildToolType object) to 'C++ Linker'. String and Arguments of Command property (a target.Command object) using specified value. Example: 'CppLinker', 'g++'
'Archiver'	Optional. In the list of tools, specify the archiver through a target.BuildTool object. The argument sets: Name of BuildToolType property (a target.BuildToolType object) to 'Archiver'. String and Arguments of Command property (a target.Command object) using specified value. Example: 'Archiver', 'ar ruvs'
'MakeTool'	Optional. In the list of tools, specify the make tool through a target.BuildTool object. The argument sets: Name of BuildToolType property (a target.BuildToolType object) to 'Make Tool'. String and Arguments of Command property (a target.Command object) using specified value. Example: 'MakeTool', 'mingw32-gmake -j$(NUM_CORES)'
'CommandFile'	Optional. For each tool that supports a command file directive, specify the directive through the corresponding target.BuildTool object. The argument sets: Name of Directive property (a target.Directive object) to 'CommandFile'. String of Directive property to specified value. Example: 'CommandFile', '@'
'ObjectExtension'	Optional. Specify the file extension that the tools (target.BuildTool objects) use for object files. Example: 'ObjectExtension', '.obj'
'ExecutableExtension'	Optional. Specify the file extension that the tools (target.BuildTool objects) use for executable files. Example: 'ExecutableExtension', '.exe'
'SharedLibraryExtension'	Optional. Specify the file extension that the tools (target.BuildTool objects) use for shared library files. Example: 'SharedLibraryExtension', '.dll'
'StaticLibraryExtension'	Optional. Specify the file extension that the tools (target.BuildTool objects) use for static library files. Example: 'StaticLibraryExtension', '.a'
'FileSep'	Optional. Specify the file separator that the tools (target.BuildTool objects) use. Example: 'FileSep', '\'
'ToolPrefix'	Optional when 'Family' name-value argument is used. Specify prefix for default command names in target.BuildTool objects created for the family. Example: 'ToolPrefix', 'arm-none-eabi-'

Attributes:

GetAccess	public
SetAccess	public

Builder — Builder configuration

target.CMakeBuilder object | target.MakefileBuilder object

An object that describes the configuration of a build automation tool. For a CMake-based toolchain, use a target.CMakeBuilder object. For a makefile-based toolchain, use a target.MakefileBuilder object.

If you use name-value arguments to create a target.Toolchain object, for the Builder property, specify this argument.

Name	Description
'MakeToolType'	Required. MakeToolType property of target.MakefileBuilder object. Value must be 'GMake', 'NMake', or 'CMake'. Example: 'MakeToolType', 'GMake'
'Generator'	Optional. Generator property of target.CMakeBuilder object. Example: 'Generator', 'Unix Makefiles'
'ToolchainFile'	Optional. ToolchainFile property of target.CMakeBuilder object. Example: 'ToolchainFile', 'pathToFolder/cmake/myPlatform.cmake'

Attributes:

GetAccess	public
SetAccess	public

BuildRequirements — Build dependencies

target.BuildDependencies object

C and C++ build dependencies that you must associate with the toolchain. For example, specific preprocessor directives or libraries. When you specify this property, every build that uses the toolchain includes the dependencies.

If you use name-value arguments to create a target.Toolchain object, for the BuildRequirements property, specify these arguments.

Name	Description
'SharedLibraries'	Optional. SharedLibraries property of target.BuildDependencies object. Example: 'SharedLibraries', {'m', 'ws2_32'}
'CompilerFlags'	Optional. CompilerFlags property of target.BuildDependencies object. Example: 'CompilerFlags', {'-fwrapv', '-fPIC'}
'LinkerFlags'	Optional. LinkerFlags property of target.BuildDependencies object. Example: 'LinkerFlags', {'/DEBUG'}

Attributes:

GetAccess	public
SetAccess	public

EnvironmentConfiguration — Environment configuration

target.EnvironmentConfiguration object array

An array of objects that provide system environment setup commands and paths that are required for the use of the toolchain. For example, vendor-supplied setup scripts. Use only one object for each operating system of a development computer.

If you use name-value arguments to create a target.Toolchain object, for the EnvironmentConfiguration property, specify this argument.

Name	Description
'SystemPaths'	Optional. SystemPaths property of target.EnvironmentConfiguration object. Example: 'SystemPaths', {'$(MW_MINGW64_LOC)/bin'}

Attributes:

GetAccess	public
SetAccess	public

runsOn — Remote build connection

'' (default) | SSHExecutionContext object

Optional. For the build process, specify the use of a remote toolchain through a connection with the remote build computer. You can specify an SSH connection by using the SSHExecutionContext object that is produced when you run target.ExecutionContext.SSH(). For example:

tc.RunsOn = target.ExecutionContext.SSH();

Attributes:

GetAccess	public
SetAccess	public

Examples

Use target.Toolchain to Configure CMake Build

This code snippet from Create Custom CMake Toolchain Definition shows how you can create a target.Toolchain object and use it to configure the way CMake builds generated code.

tc = target.create('Toolchain', 'Name', 'Example Custom CMake Toolchain'); 
tc.Builder = target.create('CMakeBuilder');
tc.Builder.Generator = 'Ninja';
tc.Builder.ToolchainFile = 'pathTo/ExampleCMakeToolchain.cmake';

Or, create the object in a single step.

tc = target.create('Toolchain', ...
                   'Name', 'Example Custom CMake Toolchain', ...
                   'MakeToolType', 'CMake', ...
                   'Generator', 'Ninja', ...
                   'ToolchainFile', 'pathTo/ExampleCMakeToolchain.cmake')

Use target.Toolchain Object to Configure Makefile Build

This command creates an object for a GNU^®-based toolchain by using several name-value arguments.

mingwtc = target.create('Toolchain', ...
                        'MakeToolType', 'GMake', ...
                        'Name', 'ARM Toolchain', ...
                        'SystemPaths', {'$(ARM_TOOLS_LOCATION)/bin'}, ...
                        'CCompiler', 'arm-none-eabi-gcc', ...
                        'CppCompiler', 'arm-none-eabi-g++', ...
                        'Linker', 'arm-none-eabi-gcc', ...
                        'CppLinker', 'arm-none-eabi-g++', ...
                        'CompilerFlags', {'-fwrapv', '-fPIC'});

Using the Family and ToolPrefix name-value arguments, you can create the same object.

target.create('Toolchain', ...
              'Family', 'GNU', ...
              'Name', 'ARM Toolchain', ...
              'ToolPrefix', 'arm-none-eabi-');

To capture information about a more customized toolchain, you can use additional name-value arguments. For example:

target.create('Toolchain', ...
              'Family', 'GNU', ...
              'Name', 'ARM Toolchain', ...
              'ToolPrefix', 'arm-none-eabi-', ...
              'SystemPaths', {'$(ARM_TOOLS_LOCATION)/bin'}, ...
              'CompilerFlags', {'-fwrapv', '-fPIC'});;

Version History

Introduced in R2022b