Documentation

Code Generation Report Overview

At code generation time, MATLAB^® Coder™ produces a report. The report helps you to verify that your MATLAB code is suitable for code generation and to debug code generation issues in your code.

The report provides links to your MATLAB code and C/C++ code files. It also provides compile-time type information for the variables and expressions in your MATLAB code. This information helps you to find sources of error messages and to understand type propagation rules.

Here is an example of a code generation report.

The report provides:

• MATLAB code information, including a list of functions and classes.

• Call stack information, providing information on the nesting of function calls.

• Links to generated C/C++ code files.

• Summary of build results, including type of target and number of warnings or errors.

• List of error and warning messages.

• List of variables in your MATLAB code.

• Target build log of compilation and linking activities

Generating and Opening Reports

• Using the MATLAB Coder app:

  After code generation, on the Generate Code page, the MATLAB Coder app generates a code generation report and provides a link to the report. If the code generation report is enabled, or build errors occur, the Target Build Log tab also provides a link to the report. To view the report, click the report link.

• Using the codegen command:

  If the code generation report is enabled, or build errors occur, MATLAB Coder generates a code generation report and provides a link to the report. To open the report, click the report link. If you specify the LaunchReport option when you generate code, MATLAB Coder opens the report.

Names and Locations of Reports

MATLAB Coder produces code generation reports in the following locations. The top-level HTML file at each location is index.html.

• For MEX functions:

  output_folder/mex/primary_function_name/html

• For C/C++ executables:

  output_folder/exe/primary_function_name/html

• For C/C++ libraries:

  output_folder/lib/primary_function_name/html

Note:   The default output folder is codegen, but you can specify a different folder. For more information, see Configure Build Settings.

MATLAB Code in a Report

To view your MATLAB code, click the MATLAB code tab. The code generation report displays the code for the function or class highlighted in the list.

The MATLAB code tab provides:

• A list of the MATLAB functions and classes. Depending on the build results, the report displays icons next to each function or class name:

  • Errors in function or class.

  • Warnings in function or class.

  • Completed build, no errors or warnings.

• A filter control. You can use Filter functions and methods to sort functions and methods by:

  • Size

  • Complexity

  • Class

• An optional highlight control to highlight potential data type issues in the generated C/C++ code. This option requires an Embedded Coder^® license. See Highlight Potential Data Type Issues in a Report.

Local Functions

In the function list on the MATLAB code tab, the code generation report annotates the local function with the name of the parent function.

For example, if the MATLAB function fcn1 contains the local function local_fcn1, and fcn2 contains the local function local_fcn2, the report displays:

fcn1 > local_fcn1
fcn2 > local_fcn2

Specializations

If your MATLAB function calls the same function with different types of inputs, the code generation report numbers these specializations in the function list on the MATLAB code tab.

For example, if the function fcn calls the function subfcn with different types of inputs:

function y = fcn(u) %#codegen
% Specializations
y = y + subfcn(single(u));
y = y + subfcn(double(u));

fcn > subfcn > 1
fcn > subfcn > 2

Extrinsic Functions

The report highlights the extrinsic functions that are supported only within the MATLAB environment.

Call Stack Information in a Report

The code generation report provides call stack information:

• On the Call stack tab.

• In the list of Calls at the top right of the report.

  This list shows the calls from and to the function or method. If more than one function calls a function, this list provides details of each call-site. Otherwise, the list is disabled.

Call Stack Information on the Call stack Tab

To view call stack information, click the Call stack tab.

The call stack lists the functions and methods in the order that the top-level function calls them. It also lists the local functions that each function calls.

The call stack displays a separate tree for each entry point function. You can easily distinguish between shared and entry-point specific functions. If you click a shared function, the report highlights instances of this function. If you click an entry-point specific function, the report highlights only that instance.

For example, in the following call stack, ezep1 and ezep2 are entry-point functions. identity is an entry-point specific function, called only by ezep1. Functions ezep3 and shared are shared functions.

The Calls List

If more than one function calls a function, or if the functions calls other functions, the Calls list provides details of each call site. To navigate between call sites, select a call site from the Calls list. If the function is not called more than once, this list is disabled.

If you select the entry-point function ezep2 in the call stack, the Calls list displays the other call site in ezep1.

Generated C/C++ Code in a Report

To view a list of the generated C or C++ files, click the C code tab. The code generation report displays a list of the generated files in the Target Source Files pane. To view the code for a file, click the file.

If you generate a MEX function, a list of support files that the code generator uses appears in the Interface Source Files pane of the C code tab. By default, this list is collapsed.

When you generate an example main function, by default, the code generation report does not include the generated example main files. If you configure code generation to generate and compile an example main function, and then you generate code, example main files appear in the code generation report. A list of source and header files for the example main function appears in the Example Source Files pane of the C code tab.

Tracing Generated Code to MATLAB Source Code

You can configure codegen to generate C code that includes the MATLAB source code as comments. In these generated comments, codegen precedes each line of source code with a traceability tag that provides details about the location of the source code. See Generate Traceable Code.

For code generated using the Embedded Coder software, these traceability tags are hyperlinks. To go the relevant line in the source code in the MATLAB editor, click the tag.

Navigating to MATLAB Source Files for Generated C/C++ Code

To open the MATLAB source code file associated with a generated C/C++ function, click the link at the top of the code pane.

Navigating to Type Definitions

To see the definition for a generated C/C++ data type, click the data type in the generated C/C++ code pane.

Custom Code in a Report

The report displays custom code with color syntax highlighting. To learn what these colors mean and how to customize color settings, see Check Syntax as You Type.

Build Summary Information in a Report

To view a summary of the build results, including type of target and number of errors or warnings, click the Summary tab.

Errors and Warnings in a Report

MATLAB Coder reports errors and warnings. If errors occur during the build, MATLAB Coder does not generate code. The report lists the messages in the order that MATLAB Coder detects them. It is a best practice to address the first message in the list, because often subsequent errors and warnings are related to the first message. If the build produces warnings, but no errors, MATLAB Coder does generate code.

The code generation report:

• Lists errors and warnings on the All Messages tab. The report lists these messages in chronological order.

• Highlights errors and warnings on the MATLAB code pane.

• Records compilation and linking errors and warnings on the Target Build Log tab. If the code generator detects compilation warnings, you see a message on the All Messages tab. The code generator detects compilation warnings only for MEX output or if you use a supported compiler for other types of output. For a list of supported compilers, see Supported Compilers.

Errors and Warnings in the All Messages Tab

If errors or warnings occur during the build, click the All Messages tab to view a complete list of these messages. The code generation report marks messages as either:

	Error
	Warning

To locate the incorrect line of code for an error or warning, click the message in the list. The code generation report highlights errors in the list. It highlights MATLAB code in red and warnings in orange. To go to the error in the source file, click the line number next to the incorrect line of code in the MATLAB code pane.

Note:   You can fix errors only in the source file.

Error and Warning Information in Your MATLAB Code

If errors or warnings occur during the build, the code generation report underlines them in your MATLAB code. The report underlines errors in red and warnings in orange. To learn more about a particular error or warning, place your cursor over the underlined text.

Compilation and Linking Errors and Warnings

The code generation report highlights compilation and linking errors and warnings in red on the Target Build Log tab. For errors, the code generation report opens to the Target Build Log tab so that you can view the build log. For warnings, the report opens to the All Messages tab. A message instructs you to view the warnings on the Target Build Log tab.

MATLAB Code Variables in a Report

The report provides compile-time type information for the variables and expressions in your MATLAB code, including name, type, size, complexity, and class. It also provides type information for fixed-point data types, including word length and fraction length. You can use this type information to find the sources of error messages and to understand type propagation rules.

You can view information about the variables in your MATLAB code:

• On the Variables tab, view the list.

• In your MATLAB code, place your cursor over the variable name.

  In the MATLAB code, an orange variable name indicates a compile-time constant argument to an entry-point or a specialized function. The information for a constant argument includes the value. The information about constant arguments helps you to understand generated function signatures. It also helps you to see when code generation created function specializations for different constant argument values.

Variables on the Variables Tab

To view a list of the variables in your MATLAB function, click the Variables tab. The report displays a complete list of variables in the order that they appear in the function that you selected on the MATLAB code tab. Clicking a variable in the list highlights instances of that variable, and scrolls the MATLAB code pane so that you can view the first instance.

As applicable, the report provides the following information about each variable:

• Order

• Name

• Type

• Size

• Complexity

• Class

• DataTypeMode (DT mode) — for fixed-point data types only. For more information, see Data Type and Scaling Properties.

• Signed — sign information for built-in data types, signedness information for fixed-point data types.

• Word length (WL) — for fixed-point data types only.

• Fraction length (FL) — for fixed-point data types only.

Note:   For more information on viewing fixed-point data types, see Use Fixed-Point Code Generation Reports.

The report displays a column only if at least one variable in the code has information in that column. For example, if the code does not contain fixed-point data types, the report does not display the DT mode, WL, or FL columns.

Sorting Variables on the Variables Tab.  By default, the report lists the variables in the order that they appear in the selected function.

To sort the variables, click the column headings on the Variables tab. To sort the variables by multiple columns, hold down the Shift key when you click the column headings.

To restore the list to the original order, click the Order column heading.

Structures on the Variables Tab.  To display structure field properties, expand the structure on the Variables tab.

If you sort the variables by type, size, complexity, or class, it is possible that a structure and its fields do not appear sequentially in the list. To restore the list to the original order, click the Order column heading.

Variable-Size Arrays in the Variables Tab.  For variable-size arrays, the Size field includes information about the computed maximum size of the array. The size of each array dimension that varies is prefixed with a colon :. The size of an unbounded dimension is :?.

In the following report, variables A and B are variable-size. The second dimension of A has a maximum size of 100. The size of the second dimension of B is :?.

If you declare a variable-size array, and then fix the dimensions of this array in the code, the report appends * to the size of the variable. In the generated C code, this variable appears as a variable-size array, but the sizes of its dimensions do not change during execution.

For information about how to use the size information for variable-size arrays, see Variable-Size Data Definition for Code Generation.

Renamed Variables in the Variables Tab.  If your MATLAB function reuses a variable with a different size, type, or complexity, the code generator attempts to create separate, uniquely named variables. For more information, see Reuse the Same Variable with Different Properties. The report numbers the renamed variables in the list on the Variables tab. When you place your cursor over a renamed variable, the report highlights only the instances of this variable that share data type, size, and complexity.

For example, suppose that your code uses the variable t to hold a scalar double, and reuses it outside the for-loop to hold a vector of doubles. In the list on the Variables tab, the report displays two variables, t>1 and t>2,

Viewing Information About Variables and Expressions in Your MATLAB Function Code

To view information about a particular variable or expression in your MATLAB function code, on the MATLAB code pane, place your cursor over the variable name or expression. The report highlights variables and expressions in different colors:

Green, when the variable has data type information at this location in the code  

For variable-size arrays, the Size field includes information on the computed maximum size of the array. The size of each array dimension that varies is prefixed with a colon :.

Green with orange text, when a constant argument has data type and value information.  When the variable is a compile-time constant argument to an entry-point or a specialized function:

• The variable name is orange.

• The information for the variable includes the value.

If you export the value as a variable to the base workspace, you can use the Workspace browser to view detailed information about the variable.

To export the value to the base workspace:

1. Click the Value link.

2. In the Export Constant Value dialog box, specify the Variable name.

3. Click OK.

   The variable and its value appear in the Workspace browser.

Pink, when the variable has no data type information  

Purple, information about expressions.  You can also view information about expressions in your MATLAB code. On the MATLAB code pane, place your cursor over an expression. The report highlights expressions in purple and provides more detailed information.

Red, when there is error information  

Target Build Information in a Report

If the build completes, MATLAB Coder provides target build information on the Target Build Log tab, including:

• Build folder

  Clicking this link changes the MATLAB current folder to the build folder.

• Make wrapper

  The batch file name that MATLAB Coder used for this build.

• Build log

  If compilation or linking errors occur, the code generation report opens to the Target Build Log tab so that you can view the build log.

Keyboard Shortcuts for a Report

You can use keyboard shortcut settings to perform actions in the code generation report.

This table lists actions that you can associate with a keyboard shortcut. The keyboard shortcuts are defined in your MATLAB preferences. See Define Keyboard Shortcuts.

Alternatively, you can select these actions from a context menu. To open the context menu, right-click anywhere in the report.

This table lists keyboard shortcuts that help you navigate between panes and tabs in the code generation report. To advance through data in the selected pane, use the Tab key. These keyboard shortcuts override the keyboard shortcut settings in your MATLAB preferences. See Define Keyboard Shortcuts.

Searching in a Report

Use the keyboard shortcut associated with Find in your MATLAB preferences. For example, on a Windows platform, the default keyboard shortcut for Find is Ctrl+F.

Report Limitations

The report displays information about the variables and expressions in your MATLAB code with the following limitations:

 varargin and varargout

 Loop Unrolling

 Dead Code

 Structures

 Column Headings on the Variables Tab

 Multiline Matrices

out1 = [1 2 3; 
       4 5 6];

out1 = [1 2 3; 4 5 6];