Main Content

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:

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

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

Data Types: char | string

Properties

expand all

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

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

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

You can use the following methods with FileExtensions:

Attributes

GetAccess
public
SetAccess
public

Defines the name of the build tool.

You can use the following methods with Name.

Attributes

GetAccess
public
SetAccess
public

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

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_LIBRARYapplies for pre-build tools, build tools, and post-build tools
coder.make.BuildOutput.SHARED_LIBRARYapplies for build tools and post-build tools; requires Embedded Coder® license
coder.make.BuildOutput.EXECUTABLEapplies for build tools and post-build tools

Attributes

GetAccess
public
SetAccess
public

Methods

expand all

Examples

collapse all

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:

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'

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