Access Code Generation Report Information Programmatically

You can export information about code generation to a variable in your base MATLAB® workspace. This variable contains a coder.ReportInfo object whose properties contain this information:

  • A code generation summary that includes information about code generation success, date and time, path of the output file, processor, version of MATLAB Coder™, toolbox licenses checked out during code generation, toolchain, and build configuration.

  • The code generation configuration object.

  • The text, path, and extension of the input files.

  • The text, path, and extension of the generated files.

  • For all MATLAB functions and methods involved in code generation: name, specialization, file, start index, and end index.

  • Code generation error, warning, and information messages.

  • Code insights indicating potential issues with the generated code.

  • Build logs produced during code generation.

See coder.ReportInfo Properties.

You can use the report information object to programmatically access this information about code generation. For example, you can display the code generation messages at the MATLAB command line. To perform this action, in your build script, access the property that contains these messages.

Create Report Information Object

Suppose that you want to export the code generation report information to the variable info in your base MATLAB workspace. Do one of the following:

  • In the Code Generation Settings dialog box, in the Export report information to variable box, type info.

  • At the command line, use the codegen command with the -reportinfo option. Specify the variable name after the -reportinfo option.

    codegen myFunction -reportinfo info

  • At the command line, set the code configuration object property ReportInfoVarName to the character vector 'info'.

  • Generate and open the code generation report. Click Export Report Information. In the dialog box, specify the variable name info.

Example: Create Report Information Object for Successful Code Generation

Create a report information object for a successful code generation process. Inspect the properties of this object.

  1. Define the MATLAB function foo:

    function b = foo(a)
c = svd(a,0);
b = sum(c);
end

    Generate a MEX function for foo. Specify the input a as a variable-size matrix whose first dimension has an upper bound of 3 and second dimension has an upper bound of 5. Export the code generation report information to the variable info in your base MATLAB workspace.

    codegen -config:mex foo -args {coder.typeof(ones(1,1),[3 5],[1 1])} -reportinfo info

    The code generator produces the MEX function foo_mex. The code generator also creates the report information object info in the base MATLAB workspace.

  2. Inspect the structure of the report information object. The object has eight properties that contain information about code generation.

      ReportInfo with properties:

           Summary: [1×1 coder.Summary]
            Config: [1×1 coder.MexCodeConfig]
        InputFiles: [1×1 coder.CodeFile]
    GeneratedFiles: [21×1 coder.CodeFile]
         Functions: [1×1 coder.Function]
          Messages: [0×1 coder.Message]
      CodeInsights: [1×1 coder.Message]
         BuildLogs: [1×1 coder.BuildLog]

  3. Inspect each property of info separately.

    • info.Summary is a coder.Summary object whose properties contain information about code generation success, code generation date and time, path of the output file, processor, toolbox licenses checked out during code generation, and version of MATLAB Coder.

        Summary with properties:

            Success: true
               Date: '08-May-2020 09:15:07'
         OutputFile: 'C:\coder\R2020b\License discovery\foo_mex.mexw64'
          Processor: 'Generic->MATLAB Host Computer'
            Version: 'MATLAB Coder 5.1 (R2020b)'
    ToolboxLicenses: [1×0 string]

      If you generate standalone code, info.Summary also contains information about toolchain and build configuration.

    • info.Config is the code configuration object. In this example, because you generated a MEX function for foo, it is a coder.MexCodeConfig object.

    • info.InputFiles is an array of coder.CodeFile objects. Each element of the array contains the text, path, and extension of a code generation input file. In this example, the array has just one element because there is only one input file foo.m.

        CodeFile with properties:

         Text: 'function b = foo(a)←↵b = svd(a,0);←↵end←↵'
         Path: 'C:\coder\R2019a\Report Info Object\foo.m'
    Extension: '.m'

    • info.GeneratedFiles is an array of coder.CodeFile objects. Each element of the array contains the text, path, and extension of a generated file. In this example, it is a 21-by-1 array because there are 25 generated files.

        21×1 CodeFile array with properties:

    Text
    Path
    Extension

    • info.Functions is an array of coder.Function objects. Each element of the array contains the following information about a MATLAB function or method:

      • Name and specialization.

      • The coder.CodeFile object for the input file that contains the function or method. This object is also contained in info.InputFiles.

      • The start and end index of the function or the method in the text of the file.

      In this example, info.Functions has one element because there is only one MATLAB function in the input file foo.m.

        Function with properties:

              Name: 'foo'
    Specialization: 0
              File: [1×1 coder.CodeFile]
        StartIndex: 1
          EndIndex: 52

    • info.Messages is an array of coder.Message objects that contain the code generation error, warning, and information messages. In this example, there are no such messages. So, this property is an empty array.

        0×1 Message array with properties:

    Identifier
    Type
    Text
    File
    StartIndex
    EndIndex

    • info.CodeInsights is an array of coder.Message objects that contain the code insights. These insights are messages about potential issues in the generated code such as potential differences from MATLAB code and potential row-major array layout issues. These messages also appear in the code generation report Code Insights tab. Each element of the array contains the following information about one code insight:

      • The identifier and the type of the message.

      • The text of the message.

      • The category and the subcategory that the message belongs to.

      • The coder.File or coder.CodeFile object for the input file that produced the message.

      • The start and end index of the part of the file text that produced the message.

      In this example, there is one code insight.

        Message with properties:

    Identifier: 'Coder:potentialDifferences:autoDimIncompatibility'
          Type: 'Info'
          Text: 'In the generated code, the dimension to operate along is selected automatically, and might be different from MATLAB. Consider specifying the working dimension explicitly as a constant value.'
      Category: 'PotentialDifferencesFromMATLAB'
          File: [1×1 coder.CodeFile]
    StartIndex: 41
      EndIndex: 46

      To index into the text of the file, use the StartIndex and EndIndex properties.

      info.CodeInsights.File.Text(41:46)
      This command displays the part of the file text that produced the code insight.
      'sum(c)'

    • info.BuildLogs is an array of coder.BuildLog objects that contain the build logs produced during code generation. The build logs contain compilation and linking errors and warnings. The same build logs also appear in the code generation report Build Logs tab. Each element of the array contains the type and the text of one build log. In this example, there is one build log of type 'Target'.

Example: Create Report Information Object for Successful Code Generation That Checks Out Toolbox Licenses

Create a report information object for a code generation process that checks out toolbox licenses. Inspect the properties of this object.

  1. Define the MATLAB function bar that calls the functions iqr (Statistics and Machine Learning Toolbox) and haart (Wavelet Toolbox). 

    function [u,v,w] = bar(x) %#codegen
u = iqr(x);
[v,w] = haart(x); 
end

    Generate C source code for bar. Specify the type of the input argument as a 1-by-100 row vector of doubles. Export the code generation report information to the variable info in your base MATLAB workspace.

    codegen -c bar -args {zeros(1,100)} -reportinfo info

  2. Code generation succeeds. Inspect the info.Summary.ToolboxLicenses property.

      1×2 string array

    "statistics_toolbox"    "wavelet_toolbox"

    This property shows that the Statistics and Machine Learning Toolbox™ and Wavelet Toolbox™ licenses were checked out during code generation.

    Note

    If you generate MEX code, these licenses are checked out again when you load the MEX function.

    If you generate static library or dynamically linked library, the toolbox licenses are checked out only during code generation. The code generator does not write license checkouts into generated standalone code.

Example: Create Report Information Object for Failed Code Generation

Create a report information object for a code generation process that fails. Inspect the properties of this object.

  1. Define the MATLAB function foo:

    function b = foo(a)
b = svd(a,0);
end

    Generate a MEX function for foo. Specify the input a as a string scalar. Export the code generation report information to the variable info in your base MATLAB workspace.

    codegen -config:mex foo -args {"A string scalar"} -reportinfo info

    Code generation fails because a string scalar is not a valid input for the MATLAB function svd. The code generator creates the report information object info in the base MATLAB workspace.

  2. Inspect the info.Summary and info.Messages properties.

    • info.Summary indicates that code generation has failed.

        Summary with properties:

            Success: false
               Date: '08-May-2020 10:20:35'
         OutputFile: 'C:\coder\R2020b\License discovery\codegen\mex\foo'
          Processor: 'Generic->MATLAB Host Computer'
            Version: 'MATLAB Coder 5.1 (R2020b)'
    ToolboxLicenses: [1×0 string]

    • info.Messages is an array of coder.Message objects that contain the code generation error, warning, and information messages. Each element of the array contains the following information about one message:

      • The identifier and the type of the message.

      • The text of the message.

      • The coder.CodeFile object for the input file that caused the message.

      • The start and end index of the part of the file text that caused the message.

      In this example, there are two error messages. So, info.Messages is a 2-by-1 array.

        2×1 Message array with properties:

    Identifier
    Type
    Text
    File
    StartIndex
    EndIndex

      View the first element of the array info.Messages(1).

        Message with properties:

    Identifier: 'Coder:toolbox:unsupportedClass'
          Type: 'Error'
          Text: 'Function 'svd' is not defined for values of class 'string'.'
          File: [1×1 coder.CodeFile]
    StartIndex: 26
      EndIndex: 33
      Use the StartIndex and EndIndex properties to index into the text of the file.
      info.Messages(1).File.Text(26:33)
      This command displays the part of the file text that caused the error message.
      'svd(a,0)'

Inspect Code Manually

To manually inspect the text of the input files, the line and column numbers corresponding to the StartIndex and EndIndex values are useful. Use the getLineColumn function to obtain this information. This function returns two structures that contain the line and column numbers corresponding to StartIndex and EndIndex respectively.

In the preceding example, to manually inspect the part of foo.m that caused the first error message, display the text of the file.

info.Messages(1).File.Text

The text of the file is displayed as:

'function b = foo(a)
 b = svd(a,0);
 end
 '

Access the line and column numbers of the part of the text that caused the first error message.

[startLoc,endLoc] = getLineColumn(info.messages(1))

The output is:

startLoc = 

  struct with fields:

      Line: 2
    Column: 5


endLoc = 

  struct with fields:

      Line: 2
    Column: 12

These locations correspond to the beginning and the end of the function call 'svd(a,0)' in the text of foo.m.

Transferring Code Configuration Objects to a New MATLAB Session

Suppose that you create a report information object info in a MATLAB session, and then use it in another MATLAB session. If info.Config is a configuration object for standalone code generation (coder.CodeConfig or coder.EmbeddedCodeConfig), the following behavior might occur:

  • If the MATLAB host computer for the second session does not have the hardware board specified in the info.Config.Hardware property installed on it, the configuration parameter info.Config.Hardware reverts to its default value. The default value is [].

  • If the MATLAB host computer for the second session does not have the toolchain specified in the info.Config.Toolchain property installed on it, the configuration parameter info.Config.Toolchain reverts to its default value. The default value is 'Automatically locate an installed toolchain'.

See Also

| | | | | | | |

Topics