Generate Custom File and Function Banners

Using code generation template (CGT) files, you can specify custom file banners and function banners for the generated code files. File banners are comment sections in the header and trailer sections of a generated file. Function banners are comment sections for each function in the generated code. Use these banners to add a company copyright statement, specify a special version symbol for your configuration management system, remove time stamps, and for many other purposes. These banners can contain characters, which propagate to the generated code.

To specify banners, create a custom CGT file with customized banner sections. The build process creates an executable TLC file from the CGT file. The code generation process then invokes the TLC file.

You do not need to be familiar with TLC programming to generate custom banners. You can modify example files that are supplied with the ERT target.

Note

Prior releases supported direct use of customized TLC files as banner templates. You specified these with the Source file (.c) banner template and Header file (.h) banner template options of the ERT target. You can still use a custom TLC file banner template, however, you can now use CGT files instead.

ERT template options on the Code Generation > Templates pane of a configuration set, in the Code templates section, support banner generation.

The options for function and file banner generation are:

Code templates: Source file (*.c) template: CGT file to use when generating source (.c or .cpp) files. Place this file on the MATLAB^® path.
Code templates: Header file (*.h) template: CGT file to use when generating header (.h) files. You must place this file on the MATLAB path. This file can be the same template specified in the Code templates: Source file (*.c) template field, in which case identical banners are generated in source and header files.
By default, the template for both source and header files is matlabroot/toolbox/rtw/targets/ecoder/ert_code_template.cgt.
In each of these fields, click Browse to navigate to and select an existing CGT file for use as a template. Click Edit to open the specified file into the MATLAB editor, where you can customize it.

Create a Custom File and Function Banner Template

To customize a CGT file for custom banner generation, make a local copy of the default code template and edit it, as follows:

Activate the configuration set that you want to work with.
Open the Code Generation pane of the active configuration set.
Click the Templates tab.
By default, the code template specified in the Code templates: Source file (*.c) template and Code templates: Header file (*.h) template fields is matlabroot/toolbox/rtw/targets/ecoder/ert_code_template.cgt.
If you want to use a different template as your starting point, click Browse to locate and select a CGT file.
Click Edit button to open the CGT file into the MATLAB editor.
Save a local copy of the CGT file. Store the copy in a folder that is outside of the MATLAB folder structure, but on the MATLAB path. If required, add the folder to the MATLAB path.
If you intend to use the CGT file with a custom target, locate the CGT file in a folder under your target root folder.
Rename your local copy of the CGT file. When you rename the CGT file, update the associated Code templates: Source file (*.c) template or Code templates: Header file (*.h) template field to match the new file name.
Edit and customize the local copy of the CGT file for banner generation, using the information provided in Customize a Code Generation Template (CGT) File for File and Function Banner Generation.
Save your changes to the CGT file.
Click Apply to update the configuration set.
Save your model.
Generate code. Examine the generated source and header files to confirm that they contain the banners specified by the template or templates.

Customize a Code Generation Template (CGT) File for File and Function Banner Generation

This section describes how to edit a CGT file for custom file and function banner generation. For a description of CGT files, see Code Generation Template (CGT) Files.

Components of the File and Function Banner Sections in the CGT file

In a CGT file, you can modify the following sections: file banner, function banner, shared utility function banner, and file trailer. Each section is defined by open and close tags. The tags specific to each section are shown in the following table.

CGT File Section	Open Tag	Close Tag
File Banner	`<FileBanner>`	`</FileBanner>`
Function Banner	`<FunctionBanner>`	`</FunctionBanner>`
Shared-utility Banner	`<SharedUtilityBanner>`	`</SharedUtilityBanner>`
File Trailer	`<FileTrailer>`	`</FileTrailer>`

You can customize your banners by including tokens and comments between the open and close tag for each section. Tokens are typically TLC variables, for example <ModelVersion>, which are replaced with values in the generated code.

Note

Including C comment indicators, '/*' or a '*/', in the contents of your banner might introduce an error in the generated code.

An open tag includes tag attributes. Enclose the value of the attribute in double quotes. The attributes available for an open tag are:

width: specifies the width of the file or function banner comments in the generated code. The default value is 80.
style: specifies the boundary for the file or function banner comments in the generated code.

The open tag syntax is as follows:

<OpenTag style = “style_value” width = “num_width”>

Note

If the Configuration Parameters > Code Generation > Language parameter is set to C++, to select a comment style that uses C comment notation (/*...*/), you must also set the Configuration Parameters > Comments > Comment style parameter to Multi-line.

The built-in style options for the style attribute are:

classic

/* single line comments */
/*
 * multiple line comments
 * second line
 */

classic_cpp

// single line comments
//
// multiple line comments
// second line
//

box

/**********************************************************/
/* banner contents                                        */
/**********************************************************/

box_cpp

////////////////////////////////////////////////////////////
// banner contents                                        //
////////////////////////////////////////////////////////////

open_box

/**********************************************************
 * banner contents
 **********************************************************/

open_box_cpp

////////////////////////////////////////////////////////////
// banner contents
////////////////////////////////////////////////////////////

doxygen

/** single line comments */

/**
 * multiple line comments
 * second line
 */

doxygen_cpp

/// single line comments

///
/// multiple line comments
/// second line
///

doxygen_qt

/*! single line comments */

/*!
 * multiple line comments
 * second line
 */

doxygen_qt_cpp

//! single line comments

//!
//! multiple line comments
//! second line
//!

File Banner

This section contains comments and tokens for use in generating a custom file banner. The file banner precedes C or C++ code generated by the model. If you omit the file banner section from the CGT file, then no file banner emits to the generated code.

Note

If you customize your file banner, the software does not emit the customized banner for the file const_params.c.

The following section is the file banner section provided with the default CGT file, matlabroot/toolbox/rtw/targets/ecoder/ert_code_template.cgt.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% Custom file banner section (optional)
%%
<FileBanner style="classic">
File: %<FileName>

Code generated for Simulink model %<ModelName>.

Model version                        : %<ModelVersion>
Simulink Coder version               : %<RTWFileVersion>
C/C++ source code generated on       : %<SourceGeneratedOn>
%<CodeGenSettings>
</FileBanner>

Summary of Tokens for File Banner Generation

`FileName`	Name of the generated file (for example, `"UserDefinedDataTypes.c"`).
`FileType`	Either `"source"` or `"header"`. Designates whether generated file is a `.c` or `.cpp` file or an `.h` file.
`FileTag`	Given file names `file.c` or `.cpp` and `file.h`; the file tags are `"file_c"` and `"file_h"`, respectively.
`ModelName`	Name of generating model.
`ModelVersion`	Version number of model.
`Description`	Description of the model specified in the CGT file or the text specified in the Descripton tab in Model Properties (Modeling > Model Settings). This token is not supported for referenced models in a model reference hierarchy.
`RTWFileVersion`	Version number of `model.rtw` file.
`RTWFileGeneratedOn`	Timestamp of `model.rtw` file.
`TLCVersion`	Version of Target Language Compiler.
`SourceGeneratedOn`	Timestamp of generated file.
`CodeGenSettings`	Code generation settings for model: target language, target selection, production hardware selection, test hardware selection, code generation objectives (in priority order), and Code Generation Advisor validation result.

Function Banner

This section contains comments and tokens for use in generating a custom function banner. The function banner precedes C or C++ function generated during the build process. If you omit the function banner section from the CGT file, the default function banner emits to the generated code. The following section is the default function banner section provided with the default CGT file, matlabroot/toolbox/rtw/targets/ecoder/ert_code_template.cgt.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% Custom function banner section (optional)
%%   Customize function banners by using the following predefined tokens:
%% %<ModelName>, %<FunctionName>, %<FunctionDescription>, %<Arguments>,
%% %<ReturnType>, %<GeneratedFor>, %<BlockDescription>.
%%
<FunctionBanner style="classic">
%<FunctionDescription>
%<BlockDescription>
</FunctionBanner>

Summary of Tokens for Function Banner Generation

`FunctionName`	Name of function
`Arguments`	List of function arguments
`ReturnType`	Return type of function
`ModelName`	Name of generating model
`FunctionDescription`	Short abstract about the function
`GeneratedFor`	Full block path for the generated function
`BlockDescription`	User input from the Block Description parameter of the block properties dialog box. `BlockDescription` contains an optional token attribute, `style`. The only valid value for`style` is `content_only`, which is case-sensitive and enclosed in double quotes. Use the `content_only` style when you want to include only the block description content that you entered in the block parameter dialog. The syntax for the token attribute `style` is: %<BlockDescription style = "content_only">

Shared Utility Function Banner

The shared utility function banner section contains comments and tokens for use in generating a custom shared utility function banner. The shared utility function banner precedes C or C++ shared utility function generated during the build process. If you omit the shared utility function banner section from the CGT file, the default shared utility function banner emits to the generated code. The following section is the default shared utility function banner section provided with the default CGT file, matlabroot/toolbox/rtw/targets/ecoder/ert_code_template.cgt.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% Custom shared utility function banner section (optional)
%%   Customize banners for functions generated in shared location by using the
%% following predefined tokens: %<FunctionName>, %<FunctionDescription>,
%% %<Arguments>, %<ReturnType>.
%%
<SharedUtilityBanner style="classic">
%<FunctionDescription>
</SharedUtilityBanner>

Summary of Tokens for Shared Utility Function Banner Generation

`FunctionName`	Name of function
`Arguments`	List of function arguments
`ReturnType`	Return type of function
`FunctionDescription`	Short abstract about function

File Trailer

The file trailer section contains comments for generating a custom file trailer. The file trailer follows C or C++ code generated from the model. If you omit the file trailer section from the CGT file, no file trailer emits to the generated code. The following section is the default file trailer provided in the default CGT file.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% Custom file trailer section (optional)
%%
<FileTrailer style="classic">
File trailer for generated code.

[EOF]
</FileTrailer>

Tokens available for the file banner are available for the file trailer. See Summary of Tokens for File Banner Generation.