Main Content

target.Toolchain Class

Namespace: target

Capture high-level information about toolchain

Since R2022b

expand all in page

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

expand all

Unique ID of object in internal database.

Attributes:

GetAccess
public
SetAccess
private

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

Example: 'CMake/Ninja for all hosts'

Attributes:

GetAccess
public
SetAccess
public

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

Attributes:

GetAccess
public
SetAccess
public

Development computer operating systems that the toolchain can run on.

Attributes:

GetAccess
public
SetAccess
public

Tools in the toolchain.

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

NameDescription
'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

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.

NameDescription
'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

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.

NameDescription
'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

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.

NameDescription
'SystemPaths'

Optional. SystemPaths property of target.EnvironmentConfiguration object.

Example: 'SystemPaths', {'$(MW_MINGW64_LOC)/bin'}

Attributes:

GetAccess
public
SetAccess
public

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

collapse all

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')

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

See Also

| | | | | |

Topics