coder.make.BuildTool Class

Namespace: 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.

The coder.make.BuildTool class is a handle class.

Creation

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

Input Arguments

expand all

`bldtl_name` — Build tool name
character vector | string scalar

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

Data Types: char | string

Properties

expand all

`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:

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:

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:

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.

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:

`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

expand all

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

Examples

collapse all

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:

Create a file that defines a BuildTool object, such as createBuildTool_1.m or createBuildTool_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.
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')

Version History

Introduced in R2013a

coder.make.BuildTool Class

Description

Creation

Input Arguments

`bldtl_name` — Build tool name
character vector | string scalar

Properties

`Command` — Build tool command or command macro

Attributes:

`Directives` — Tool-specific directives

Attributes

`FileExtensions` — Tool-specific file extensions

Attributes

`Name` — Name of build tool

Attributes

`Path` — Tool-specific paths

`SupportedOutputs` — Tool-specific output formats

Attributes

Methods

Public Methods

Examples

Get a Default Build Tool and Set Its Properties

Create a Non-Default BuildTool

Add Prebuild and Postbuild Tools to Toolchain

Version History

See Also

Topics

coder.make.BuildTool Class

Description

Creation

Input Arguments

bldtl_name — Build tool name character vector | string scalar

Properties

Command — Build tool command or command macro

Attributes:

Directives — Tool-specific directives

Attributes

FileExtensions — Tool-specific file extensions

Attributes

Name — Name of build tool

Attributes

Path — Tool-specific paths

SupportedOutputs — Tool-specific output formats

Attributes

Methods

Public Methods

Examples

Get a Default Build Tool and Set Its Properties

Create a Non-Default BuildTool

Add Prebuild and Postbuild Tools to Toolchain

Version History

See Also

Topics

`bldtl_name` — Build tool name
character vector | string scalar

`Command` — Build tool command or command macro

`Directives` — Tool-specific directives

`FileExtensions` — Tool-specific file extensions

`Name` — Name of build tool

`Path` — Tool-specific paths

`SupportedOutputs` — Tool-specific output formats