coder.make.BuildTool class

Package: coder.make

Represent build tool

Description

Use coder.make.BuildTool to get and define an existing default coder.make.BuildTool object, or to create a coder.make.BuildTool object.

To work with default BuildTool objects, use the get and define approach from the ToolchainInfo properties:

• coder.make.ToolchainInfo.BuildTools

• coder.make.ToolchainInfo.PostbuildTools

Examples showing the get and define approach are:

• Toolchain Definition File with Commentary

• Tutorial example: Add Custom Toolchains to MATLAB® Coder™ Build Process tutorial

An alternative to the get and define approach is the create new approach. An example showing the create new approach appears in Create a Non-Default BuildTool.

The illustration shows the relationship between the default BuildTool objects and ToolchainInfo. When you examine the PHONY TARGETS section of the generated makefile, the difference between the BuildTools, PostbuildTools, and PrebuildTools becomes clearer.

• prebuild – runs only the prebuild tool.

• build – runs the build tools after running prebuild. The build generates the build PRODUCT.

• postbuild – runs the postbuild tool after running build.

• all – runs prebuild, build, and postbuild. The build process uses this rule on a Ctrl+B build.

• clean – cleans up all output file extensions and derived file extensions of all the tools in the toolchain.

• info – expands and prints all macros used in the makefile.

Construction

h = coder.make.BuildTool(bldtl_name) creates a coder.make.BuildTool object and sets its Name property.

Input Arguments

bldtl_name — Build tool name

character vector | string scalar

Build tool name, specified as a character vector or string scalar.

Data Types: char | string

Output Arguments

h — Object handle

variable

Object handle for a coder.make.BuildTool object, specified as a variable.

Example: tool

Properties

Command — Build tool command or command macro

Represents the build tool command using:

• An optional macro name, such as: CC.

• The system call (command) that starts the build tool, such as: gcc.

The macro name and system call appear together in the generated makefile. For example: CC = gcc

Assigning a value to this property is optional.

You can use the following methods with Command:

• getCommand

• setCommand

Attributes:

GetAccess	public
SetAccess	public

Directives — Tool-specific directives

Defines any tool-specific directives, such as -D for preprocessor defines. Assigning a value to this property is optional.

You can use the following methods with Directives:

• addDirective

• getDirective

• setDirective

Attributes:

GetAccess	public
SetAccess	public

FileExtensions — Tool-specific file extensions

Defines any tool-specific file extensions. This value is optional.

You can use the following methods with FileExtensions:

• addFileExtension

• getFileExtension

• setFileExtension

Attributes:

GetAccess	public
SetAccess	public

Name — Name of build tool

Defines the name of the build tool.

You can use the following methods with Name.

• getName

• setName

Attributes:

GetAccess	public
SetAccess	public

Path — Tool-specific paths

Defines any tool-specific paths. If the command is on the system path, this value is optional.

You can use the following methods with Path:

• getPath

• setPath

Attributes:

GetAccess	public
SetAccess	public

SupportedOutputs — Tool-specific output formats

Defines any tool-specific output formats. If the tool supports all available formats, this value is optional.

The default value is {'*'}, which indicates support for all available formats.

The datatype is cell array. The contents of the cell array must be either coder.make.BuildOutput enumeration values, or '*'.

This property does not have any associated methods. Assign the value directly to the SupportedOutputs. See the addPrebuildToolToToolchainInfo.m example or the addPostbuildToolToToolchainInfo.m example. Valid enumeration values are:

coder.make.BuildOutput.STATIC_LIBRARY	applies for pre-build tools, build tools, and post-build tools
coder.make.BuildOutput.SHARED_LIBRARY	applies for build tools and post-build tools; requires Embedded Coder® license
coder.make.BuildOutput.EXECUTABLE	applies for build tools and post-build tools

Attributes:

GetAccess	public
SetAccess	public

Methods

addDirective	Add directive to Directives
addFileExtension	Add new file extension entry to FileExtensions
getCommand	Get build tool command
getDirective	Get value of named directive from Directives
getFileExtension	Get file extension for named file type in FileExtensions
getName	Get build tool name
getPath	Get path and macro of build tool in Path
info	Display build tool properties and values
setCommand	Set build tool command
setCommandPattern	Set pattern of commands for build tools
setCompilerOptionMap	Set C/C++ language standard and compiler options for selected build tool (compiler)
setDirective	Set value of directive in Directives
setFileExtension	Set file extension for named file type in FileExtensions
setName	Set build tool name
setPath	Set path and macro of build tool in Path
validate	Validate build tool properties

Copy Semantics

Handle. To learn how handle classes affect copy operations, see Copying Objects.

Example

• Get a Default Build Tool and Set Its Properties

• Create a Non-Default BuildTool

• Add Prebuild and Postbuild Tools to Toolchain

Get a Default Build Tool and Set Its Properties

The intel_tc.m file from Add Custom Toolchains to MATLAB® Coder™ Build Process uses the following lines to get a default build tool, C Compiler, from a ToolchainInfo object called tc, and then sets its properties.

% ------------------------------
% 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 following examples show the same “get and define” approach in more detail:

• Toolchain Definition File with Commentary

• Tutorial example: Add Custom Toolchains to MATLAB® Coder™ Build Process tutorial

Create a Non-Default BuildTool

To create a build tool:

1. Create a file that defines a BuildTool object, such as createBuildTool_1.m or createBuildTool_2.

2. Create a file like addBuildToolToToolchainInfo.m, that:

   • Creates a ToolchainInfo object, or uses an existing one.

   • Creates a BuildTool object from createBuildTool_1.m or createBuildTool_2.

   • Adds the BuildTool object to the ToolchainInfo object.

3. Run addBuildToolToToolchainInfo.m.

Refer to the following examples of addBuildToolToToolchainInfo.m, createBuildTool_1.m, and createBuildTool_2.m.

 addBuildToolToToolchainInfo.m

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Adding a build tool to ToolchainInfo
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

% Create a toolchain object
h = coder.make.ToolchainInfo();

% User function for creating and populating a build tool
tool = createBuildTool_1();
% or tool = createBuildTool_2();

% Add the build tool to ToolchainInfo
h.addBuildTool('My C Compiler',tool);

 createBuildTool_1.m

function buildToolObj = createBuildTool_1()

toolinfo.Name                       = 'My GNU C Compiler';
toolinfo.Language                   = 'C';

toolinfo.Command.Macro              = 'CC';
toolinfo.Command.Value              = 'gcc';

toolinfo.Path.Macro                 = 'CC_PATH';
toolinfo.Path.Value                 = '';

toolinfo.OptionsRegistry            = {'My C Compiler','MY_CFLAGS'};

% Key name of this directive
toolinfo.Directives(1).Key          = 'IncludeSearchPath';

% Macro of this directive (directives can have empty macros)
toolinfo.Directives(1).Macro        = '';                   

% Value of this directive
toolinfo.Directives(1).Value        = '-I';                 

toolinfo.Directives(2).Key          = 'PreprocessorDefine';
toolinfo.Directives(2).Macro        = '';
toolinfo.Directives(2).Value        = '-D';

toolinfo.Directives(3).Key          = 'Debug';
toolinfo.Directives(3).Macro        = 'CDEBUG';
toolinfo.Directives(3).Value        = '-g';

toolinfo.Directives(4).Key          = 'OutputFlag';
toolinfo.Directives(4).Macro        = 'C_OUTPUT_FLAG';
toolinfo.Directives(4).Value        = '-o';

% Key name of this file extension
toolinfo.FileExtensions(1).Key      = 'Source';  

% Macro of this file extension
toolinfo.FileExtensions(1).Macro    = 'C_EXT';   

% Value of this file extension
toolinfo.FileExtensions(1).Value    = '.c';      

toolinfo.FileExtensions(2).Key      = 'Header';
toolinfo.FileExtensions(2).Macro    = 'H_EXT';
toolinfo.FileExtensions(2).Value    = '.h';

toolinfo.FileExtensions(3).Key      = 'Object';
toolinfo.FileExtensions(3).Macro    = 'OBJ_EXT';
toolinfo.FileExtensions(3).Value    = '.obj';

toolinfo.DerivedFileExtensions      = {'$(OBJ_EXT)'};
% '*' means all outputs are supported
toolinfo.SupportedOutputs           = {'*'}; 


% put actual extension (e.g. '.c') or keyname if already registered
% under 'FileExtensions'
toolinfo.InputFileExtensions        = {'Source'}; 
toolinfo.OutputFileExtensions       = {'Object'}; 

% Create a build tool object and populate it with the above data
buildToolObj = createAndpopulateBuildTool(toolinfo);

function buildToolObj = createAndpopulateBuildTool(toolinfo)

% -------------------------
% Construct a BuildTool
% -------------------------
buildToolObj = coder.make.BuildTool();

% -------------------------
% Set general properties
% -------------------------
buildToolObj.Name              = toolinfo.Name;
buildToolObj.Language          = toolinfo.Language;
buildToolObj.Command           = coder.make.BuildItem ...
    (toolinfo.Command.Macro,toolinfo.Command.Value);
buildToolObj.Path              = coder.make.BuildItem ...
    (toolinfo.Path.Macro,toolinfo.Path.Value);
buildToolObj.OptionsRegistry   = toolinfo.OptionsRegistry;
buildToolObj.SupportedOutputs  = toolinfo.SupportedOutputs;

% -------------------------
% Directives
% -------------------------
for i = 1:numel(toolinfo.Directives)
    directiveBuildItem = coder.make.BuildItem(...
        toolinfo.Directives(i).Macro,toolinfo.Directives(i).Value);
    buildToolObj.addDirective(toolinfo.Directives(i).Key,directiveBuildItem);
end

% -------------------------
% File extensions
% -------------------------
for i = 1:numel(toolinfo.FileExtensions)
    fileExtBuildItem = coder.make.BuildItem(...
        toolinfo.FileExtensions(i).Macro,toolinfo.FileExtensions(i).Value);
    buildToolObj.addFileExtension(toolinfo.FileExtensions(i).Key,fileExtBuildItem);
end

% -------------------------
% Derived file extensions
% -------------------------
for i = 1:numel(toolinfo.DerivedFileExtensions)
    if buildToolObj.FileExtensions.isKey(toolinfo.DerivedFileExtensions{i})
        buildToolObj.DerivedFileExtensions{end+1} = ...
        ['$(' buildToolObj.getFileExtension
        (toolinfo.DerivedFileExtensions{i}) ')'];
    else
        buildToolObj.DerivedFileExtensions{end+1} = toolinfo.DerivedFileExtensions{i};
    end
end

% -------------------------
% Command pattern
% -------------------------
if isfield(toolinfo,'CommandPattern')
    buildToolObj.CommandPattern = toolinfo.CommandPattern;
end

% --------------------------------
% [Input/Output]FileExtensions
% --------------------------------
if isfield(toolinfo,'InputFileExtensions')
    buildToolObj.InputFileExtensions = toolinfo.InputFileExtensions;
end
if isfield(toolinfo,'OutputFileExtensions')
    buildToolObj.OutputFileExtensions = toolinfo.OutputFileExtensions;
end

 createBuildTool_2.m

function buildToolObj = createBuildTool_2()

% -------------------------
% Construct a BuildTool
% -------------------------
buildToolObj = coder.make.BuildTool();

% -------------------------
% Set general properties
% -------------------------
buildToolObj.Name               = 'My GNU C Compiler';
buildToolObj.Language           = 'C';
buildToolObj.Command            = coder.make.BuildItem('CC','gcc');
buildToolObj.Path               = coder.make.BuildItem('CC_PATH','');
buildToolObj.OptionsRegistry    = {'My C Compiler','MY_CFLAGS'};
buildToolObj.SupportedOutputs   = {'*'}; % '*' means all outputs are supported

% -------------------------
% Directives
% -------------------------

directiveBuildItem = coder.make.BuildItem('','-I');
buildToolObj.addDirective('IncludeSearchPath',directiveBuildItem);

directiveBuildItem = coder.make.BuildItem('','-D');
buildToolObj.addDirective('PreprocessorDefine',directiveBuildItem);

directiveBuildItem = coder.make.BuildItem('CDEBUG','-g');
buildToolObj.addDirective('Debug',directiveBuildItem);

directiveBuildItem = coder.make.BuildItem('C_OUTPUT_FLAG','-o');
buildToolObj.addDirective('OutputFlag',directiveBuildItem);

% -------------------------
% File Extensions
% -------------------------

fileExtBuildItem = coder.make.BuildItem('C_EXT','.c');
buildToolObj.addFileExtension('Source',fileExtBuildItem);

fileExtBuildItem = coder.make.BuildItem('H_EXT','.h');
buildToolObj.addFileExtension('Header',fileExtBuildItem);

fileExtBuildItem = coder.make.BuildItem('OBJ_EXT','.obj');
buildToolObj.addFileExtension('Object',fileExtBuildItem);

% -------------------------
% Others
% -------------------------

buildToolObj.DerivedFileExtensions  = {'$(OBJ_EXT)'};
buildToolObj.InputFileExtensions    = {'Source'};
% put actual extension (e.g. '.c')
% or keyname if already registered under 'FileExtensions'
buildToolObj.OutputFileExtensions   = {'Object'};
% put actual extension (e.g. '.c')
% or keyname if already registered under 'FileExtensions'

Add Prebuild and Postbuild Tools to Toolchain

The code in the addPrebuildToolToToolchainInfo.m and the addPostbuildToolToToolchainInfo.m examples show how to add prebuild and postbuild tools to a toolchain.

 addPrebuildToolToToolchainInfo.m

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Adding a pre-build tool with selected SupportedOutputs to ToolchainInfo
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

% Create a toolchain object
tc = coder.make.ToolchainInfo(coder.make.getToolchainInfoFromRegistry(coder.make.getDefaultToolchain));
% Set inlined commands for source to dependency tool
tc.InlinedCommands = ['define sourceToDep=', 10, ...
'$(foreach source, $(1), $(CC) $(CFLAGS) -E -MMD -MP -MF"$(notdir $(source:%.c=%.d))" -MT"$(notdir $(source:%.c=%.o))" $(source) )', 10, ...
'endef'];
% Set makefile includes
make = tc.BuilderApplication();
make.IncludeFiles = {'*.d'};
% Dependency File Generator for GCC-based toolchain
prebuildToolName = 'Dependency File Generator';
prebuildTool = tc.addPrebuildTool(prebuildToolName);              
% Set command macro and value
prebuildTool.setCommand('SRC2DEP', '$(call sourceToDep, $(SRCS))');
% Set tool options macro
prebuildTool.OptionsRegistry = {prebuildToolName, 'SRC2DEP_OPTS'};
% Set output type from tool
prebuildTool.SupportedOutputs = {'*'};
tc.addBuildConfigurationOption(prebuildToolName, prebuildTool);  
tc.setBuildConfigurationOption('all', prebuildToolName, ''); 

% displays pre-build tool properties
tc.getPrebuildTool('Dependency File Generator')

 addPostbuildToolToToolchainInfo.m

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Adding a post-build tool to ToolchainInfo
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

% ELF (executable and linkable format) to hexadecimal converter 
postbuildToolName = 'elf2hex converter';
% Create and populate a post-build tool
tc = coder.make.ToolchainInfo;
postbuild = tc.addPostbuildTool(postbuildToolName);              
% Set command macro and value for tool
postbuild.setCommand('OBJCOPY', 'arm-none-eabi-objcopy');
% Set path for tool
postbuild.setPath('OBJCOPYPATH','$(MW_GNU_ARM_TOOLS_PATH)');
% Set options for tool
postbuild.OptionsRegistry = {postbuildToolName, 'OBJCOPYFLAGS_HEX'};
% Set output type from tool
postbuild.SupportedOutputs = {coder.make.enum.BuildOutput.EXECUTABLE};
% Create build configuration for tool
tc.addBuildConfigurationOption(postbuildToolName, postbuild);
% Set build configuration for tool
tc.setBuildConfigurationOption('all', postbuildToolName, '-O ihex $(PRODUCT) $(PRODUCT_HEX)');

% displays post-build tool properties
tc.getPostbuildTool('elf2hex converter')