Toolchain Definition File with Commentary

Steps Involved in Writing a Toolchain Definition File

This example shows how to create a toolchain definition file and explains each of the steps involved. The example is based on the definition file used in Add Custom Toolchains to MATLAB® Coder™ Build Process. For more information about the workflow, see Typical Workflow.

Write a Function That Creates a ToolchainInfo Object

function tc = intel_tc
% INTEL_TC Creates an Intel v12.1 ToolchainInfo object.
% This can be used as a template to add other toolchains on Windows.

tc = coder.make.ToolchainInfo('BuildArtifact','nmake makefile');
tc.Name             = 'Intel v12.1 | nmake makefile (64-bit Windows)';
tc.Platform         = 'win64';
tc.SupportedVersion = '12.1';

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

The preceding code:

  • Defines a function, intel_tc, that creates a coder.make.ToolchainInfo object and assigns it to a handle, tc.

  • Overrides the BuildArtifact property to create a makefile for nmake instead of for gmake.

  • Assigns values to the Name, Platform, and SupportedVersion properties for informational and display purposes.

  • Adds three custom attributes to Attributes property that are required by this toolchain.

  • 'TransformPathsWithSpaces' converts paths that contain spaces to short Windows® paths.

  • 'RequiresCommandFile' generates a linker command file that calls the linker. This avoids problems with calls that exceed the command line limit of 256 characters.

  • 'RequiresBatchFile' creates a .bat file that calls the builder application.

Setup

% ------------------------------
% 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';

The preceding code:

  • Assigns a system call to the ShellSetup property.

  • The coder.make.ToolchainInfo.setup method runs these system calls before it runs tools specified by PrebuildTools property.

  • Calls compilervars.bat, which is shipped with the Intel® compilers, to get the set of environment variables for Intel compiler and linkers.

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

The preceding code:

  • Uses coder.make.ToolchainInfo.addMacro method to define macros and assign values to them.

  • Uses coder.make.ToolchainInfo.addIntrinsicMacros to define macros whose values are specified by the toolchain, outside the scope of your MathWorks® software.

C Compiler

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

The preceding code:

  • Creates a build tool object for the C compiler

  • Assigns values to the build tool object properties

  • Creates directives and file extensions using name-value pairs

  • Sets a command pattern.

  • You can use setCommandPattern method to control the use of space characters in commands. For example, the two bars in OUTPUT_FLAG<||>OUTPUT do not permit a space character between the output flag and the output.

C++ Compiler

% ------------------------------
% 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','.cpp');
tool.setFileExtension('Header','.hpp');
tool.setFileExtension('Object','.obj');

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

The preceding code:

  • Creates a build tool object for the C++ compiler

  • Is very similar to the build tool object for the C compiler

Linker

% ------------------------------
% Linker
% ------------------------------

tool = tc.getBuildTool('Linker');

tool.setName('Intel C/C++ Linker');
tool.setCommand('xilink');
tool.setPath('');

tool.setDirective('Library','-L');
tool.setDirective('LibrarySearchPath','-I');
tool.setDirective('OutputFlag','-out:');
tool.setDirective('Debug','');

tool.setFileExtension('Executable','.exe');
tool.setFileExtension('Shared Library','.dll');

tool.DerivedFileExtensions = horzcat(tool.DerivedFileExtensions,{ ...
                                            ['_' tc.Platform '.lib'],...
                                            ['_' tc.Platform '.exp']});

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

The preceding code:

  • Creates a build tool object for the linker

  • Assigns values to the coder.make.BuildTool.DerivedFileExtensions

Archiver

% ------------------------------
% Archiver
% ------------------------------

tool = tc.getBuildTool('Archiver');

tool.setName('Intel C/C++ Archiver');
tool.setCommand('xilib');
tool.setPath('');

tool.setDirective('OutputFlag','-out:');

tool.setFileExtension('Static Library','.lib');

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

The preceding code:

  • Creates a build tool object for the archiver.

Builder

% ------------------------------
% Builder
% ------------------------------

tc.setBuilderApplication(tc.Platform);

The preceding code:

  • Gives the value of coder.make.ToolchainInfo.Platform as the argument for setting the value of BuilderApplication. This sets the default values of the builder application based on the platform. For example, when Platform is win64, this line sets the delete command to 'del'; the display command to 'echo', the file separator to '\', and the include directive to '!include'.

Build Configurations

% --------------------------------------------
% BUILD CONFIGURATIONS
% --------------------------------------------

optimsOffOpts = {'/c /Od'};
optimsOnOpts = {'/c /O2'};
cCompilerOpts    = '$(cflags) $(CVARSFLAG) $(CFLAGS_ADDITIONAL)';
cppCompilerOpts  = '$(cflags) $(CVARSFLAG) $(CPPFLAGS_ADDITIONAL)';
linkerOpts       = {'$(ldebug) $(conflags) $(LIBS_TOOLCHAIN)'};
sharedLinkerOpts = horzcat(linkerOpts,'-dll -def:$(DEF_FILE)');
archiverOpts     = {'/nologo'};

% Get the debug flag per build tool
debugFlag.CCompiler   = '$(CDEBUG)';   
debugFlag.CppCompiler = '$(CPPDEBUG)';
debugFlag.Linker      = '$(LDDEBUG)';  
debugFlag.Archiver    = '$(ARDEBUG)';  

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

The preceding code:

  • Creates each build configuration object.

  • Sets the value of each option for a given build configuration object.