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: Adding a Custom Toolchain 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

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

Output Arguments

expand all

`h` — Object handle
variable

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

Example: tool

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:

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 Adding a Custom Toolchain 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: Adding a Custom Toolchain 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

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

addPostbuildToolToToolchainInfo.m

Documentation

coder.make.BuildTool class

Description

Construction

Input Arguments

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

Output Arguments

`h` — Object handle
variable

Properties

`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

Methods

Copy Semantics

Example

Get a Default Build Tool and Set Its Properties

Create a Non-Default BuildTool

Add Prebuild and Postbuild Tools to Toolchain

See Also

Topics

MATLAB Coder Documentation

Support

Documentation

coder.make.BuildTool class

Description

Construction

Input Arguments

bldtl_name — Build tool name character vector | string scalar

Output Arguments

h — Object handle variable

Properties

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

Methods

Copy Semantics

Example

Get a Default Build Tool and Set Its Properties

Create a Non-Default BuildTool

Add Prebuild and Postbuild Tools to Toolchain

See Also

Topics

MATLAB Coder Documentation

Support

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

`h` — Object handle
variable

`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