Code Generation for Entry-Point Classes

R2026b

Since R2026a

Note

Using a MATLAB^® class as an entry point for code generation is a tech preview. This feature is in active development and might change between the tech preview and the general release. To enable the feature, enter enableCodegenForEntryPointClasses at the command line before launching the MATLAB Coder™ app, calling the codegen function, or creating a coder.Type object. To provide feedback, email the development team or participate in a survey.

You can use a MATLAB value class or handle class as an entry point for code generation. An entry-point class is a C or C++ class that you want to access directly from your custom C or C++ code. When you generate code for a MATLAB class that you do not specify as an entry point, the code generator might optimize the code by eliminating, inlining, or restructuring the class and its methods. Specify a class as an entry point to direct the code generator to preserve the signatures of the class and its methods. You can use entry-point classes and entry-point class methods as stable interfaces to the generated code.

To see an example that demonstrates how to generate code for an entry-point class at the command line, see Generate Standalone C++ Code for Entry-Point Class at the Command Line. To see an example that demonstrates how to generate code for an entry-point class by using the MATLAB Coder app, see Generate Standalone C++ Code for Entry-Point Class Using MATLAB Coder App.

Create Class Signature Objects

To specify an entry-point class for code generation, create a coder.ClassSignature object. For example, consider the Rectangle class:

classdef Rectangle
    properties
        Length
        Width
    end
    methods
        function obj = Rectangle(length,width)
            obj.Length = length;
            obj.Width = width;
        end
        function area = getArea(obj)
            area = obj.Length*obj.Width;
        end
        function out = isEqualArea(obj1,obj2)
            out = isequal(getArea(obj1),getArea(obj2));
        end
    end
end

To create a class signature object for the Rectangle class, use this command:

classSig = coder.ClassSignature("Rectangle");

When you create a class signature object by using the class name, the class signature object does not include the specifications of the class properties. The code generator infers the properties of the class from the class constructor during code generation.

Usage Notes and Limitations for Class Signature Object Specification

When you create a class signature object from a MATLAB class:

• If a property of an entry-point class is a handle class, that property must be private or protected.

• You cannot use coder.Constant to directly assign a constant value to a property of a class signature object. To define a property of an entry-point class as a constant, use the Constant attribute in the MATLAB class definition.

• Class methods must accept an instance of the enclosing class as the first argument.

• Code generation does not support these types of classes as entry points:

  • Abstract classes

  • Classes contained in aggregate data types, such as structures, cells, and other classes

  • Classes that inherit from the matlab.mixin.Copyable class

Add Methods to Class Signature Objects

Add the methods that you want to access from the custom C or C++ code to the class signature object by using the addMethod object function. You must add the class constructor method. If the MATLAB class does not define a constructor, add the default constructor. See Default Constructor.

To add the Rectangle class constructor method to the classSig object that represents the Rectangle class, use this command:

addMethod(classSig,"Rectangle",{0,0});

The class constructor method must define all properties of the class, including all structure fields, cell array elements, and properties of contained classes.

To add the getArea and isEqualArea methods to the class signature object, use these commands:

addMethod(classSig,"getArea",{classSig});
addMethod(classSig,"isEqualArea",{classSig,classSig});

When you specify a class method that takes an instance of the enclosing class as an input argument, use the coder.ClassSignature object that represents the enclosing class.

Usage Notes and Limitations for Method Specification

When you add a method to a class signature object:

• You can add only public methods to the class signature object. The code generator infers private and protected method definitions from the MATLAB code.

• Code generation does not support the function coder.getArgTypes for entry-point classes. This means that you cannot call coder.getArgTypes on a test bench to determine the input argument types for an entry-point class method.

• If the entry-point class is a System object™, you must add the System object step method to the class signature object. Because step supports a variable number of outputs, you must specify the number of output arguments when you add the method. For an example, see Generate C++ Executable for Entry-Point System Object in a Namespace.

• To generate C code for a polymorphic method, you must specify the InterfaceName argument.

• You can use coder.OutputType to specify an input argument for an entry-point class method. However, you cannot use coder.OutputType to represent the type of an output of an entry-point class method.

• You cannot add these types of methods to a class signature object:

  • Static methods

  • Abstract methods

  • Private methods

  • Protected methods

  • Methods that overload the MATLAB functions disp, empty, isa, class, subsref, and subsasgn.

Check for Issues by Using MEX Functions

Since R2026b

To check for issues in the generated class, generate and run a MEX function. When you produce a MEX function from a class signature object, the generated MEX function contains the class and method definitions. You can use the function to create an instance of the generated class, and then test its methods. As a best practice, generate a MEX function because you can use the MEX class to detect run-time errors that are more difficult to diagnose in standalone code.

Adhere to the same limitations when you generate a MEX function as when you generate standalone code. See Generate Standalone C or C++ Code.

The function coder.runTest does not support entry-point classes. To run a test bench using the generated MEX class, you must manually modify the test script to call the MEX function. See Unit Test Generated Standalone Class.

Generate MEX Function

To generate a MEX function from an entry-point class, pass the class signature object to the codegen command by using the -class option. For example, to generate a C MEX function from the classSig object that represents the Rectangle class, use this command:

codegen -class ClassSig

The code generator creates a MEX function with the same name as the MATLAB class.

Test MEX Class

To create an instance of the generated class from the MEX function, pass the name of the class constructor to the MEX function followed by the required inputs. For example, to create an instance of the MEX Rectangle class, use this command:

myMexObj = Rectangle_mex("Rectangle",3,4)

If the entry-point class is inside a MATLAB namespace, call the constructor method by using dot notation. For an example, see Generate C++ Executable for Entry-Point System Object in a Namespace.

When you create an instance of a MEX class, the code generator creates an object that behaves like the MATLAB class but calls the MEX code. To interact with this object, use MATLAB class syntax. For example, to set the Length property of the myMexObj object to 5, use this command:

myMexObj.Length = 5;

To call the getArea method on the MyMexClass object, use this command:

getArea(myMexObj)

Generate Standalone C or C++ Code

To generate standalone code for an entry-point class, pass the class signature object to the codegen command by using the -class option and use the -config option to specify a standalone output type.

For example, to generate a C++ static library from the classSig object that represents the Rectangle class, use this command:

codegen -config:lib -lang:c++ -class classSig

Usage Notes and Limitations for Code Generation

When you generate code for an entry-point class, adhere to these guidelines:

• If an entry point takes a handle class as an input argument, you must also specify the handle class as an entry point.

• If you copy a class signature object and pass both copies of the class signature object to the codegen command, the objects must have handle equality. See Equality of Handle Objects.

• If an entry-point class contains a handle class property at any level of nesting, and the entry-point class is nested in one or more containing classes, you must also specify the top-level enclosing class as an entry point.

• The code generator does not produce an example main function. To generate an executable, you must write a main function for your application. For an example, see Generate C++ Executable for Entry-Point System Object in a Namespace.

• When you generate code for an entry-point class, you cannot:

  • Create circular dependencies among entry-point classes.

  • Produce multi-instance, reentrant code.

  • Perform numeric conversion by using the codegen options -config:single, -float2fixed, and -singleC.

  • Generate CUDA^® code by passing a CUDA MEX configuration object to the codegen command.

  • Profile the generated code by using the codegen command with the -gpuprofile option to call the GPU performance analyzer.

  • Generate HDL or High-Level Synthesis (HLS) code by passing a coder.HdlConfig (HDL Coder) object to the codegen command.

Verify Generated Classes

Since R2026b

If you have an Embedded Coder^® license, you can verify the generated class by using software-in-the-loop (SIL) and processor-in-the-loop (PIL) execution. See Unit Test Generated Standalone Class.

Examine Generated Classes

The way that the code generator represents MATLAB classes in the generated code depends on whether you generate C or C++ code. If you generate C code, the code generator represents MATLAB classes as structures. If you generate C++ code, the default behavior of the code generator is to produce C++ classes for the MATLAB classes. See Generate C++ Code for MATLAB Classes.

Entry-Point MATLAB Classes in C Code

When you generate C code for an entry-point class, the code generator represents the MATLAB class as a structure type with fields that correspond to the class properties. When you define the TypeName property of the coder.ClassSignature object, the code generator uses the TypeName to name the structure type. Otherwise, the code generator defines a structure type with the same name as the MATLAB class.

The code generator represents the class methods as functions that operate on the structure. The C function names follow the pattern ClassName_MethodName. If you generate C code for a polymorphic method, the code generator produces a C function with a name that follows the pattern ClassName_InterfaceName.

Entry-Point MATLAB Classes in C++

When you generate C++ code for an entry-point class, the code generator produces an idiomatic C++ class and class methods that have the same names as the MATLAB class and methods. The generated class might also define internal methods, such as init and the non-initializing constructor. Do not use these internal methods in your custom C++ code.

If you add a class constructor method that takes no arguments to the class signature object, the code generator produces a C++ constructor that requires a user_construct_tag_t tag argument. To create an instance of the generated C++ class by using this constructor, call the constructor and pass a user_construct_tag_t object. For an example, see Generate C++ Executable for Entry-Point System Object in a Namespace.

If you generate C++ code for a polymorphic method, the behavior of the code generator depends on whether the polymorphic method is the class constructor and whether you specify the InterfaceName argument:

• If the polymorphic method is the class constructor, the code generator produces overloaded C++ constructor methods. If you specify the InterfaceName argument, the code generator ignores it.

• If the polymorphic method is not the class constructor and you do not specify the InterfaceName argument, the code generator produces overloaded C++ methods.

• If the polymorphic method is not the class constructor and you specify the InterfaceName argument, the code generator names the generated method after the InterfaceName argument.