Main Content

Define MATLAB Interface for C++ Library

Complete Definitions

After creating the library definition file definelibName.mlx using clibgen.generateLibraryDefinition, you might have to modify the contents to include functionality in the interface. Use the Live Editor to modify the file. For more information, see Define Missing Information for MATLAB Signatures.

Auto-Define Arguments

You can direct MATLAB to auto-define the type and shape of specific argument types using clibgen.generateLibraryDefinition and clibgen.buildInterface name-value pair arguments. The options are:

However, when you validate the library definition, you might get errors about duplicate MATLAB® signatures. To resolve these errors, see Reconcile MATLAB Signature Conflicts.

Reconcile MATLAB Signature Conflicts

After generating and editing a library definition file, there might be two or more functions or other constructs with identical MATLAB signatures. To check for this conflict, validate the definition file. For example, for the definition file definelibname, type:

definelibname

If there is a conflict, MATLAB displays an error with a link to the code in the definition file. To resolve the conflict, choose one of the following:

  • Revise the defineArgument or defineOutput arguments to create a unique MATLAB signature. The conflict occurs when there are multiple overloaded functions and you specify the same argument parameters. See Define Missing Information for MATLAB Signatures.

  • Remove one of the functions by commenting out the definition of the construct. The conflict might occur when you use one of the clibgen.generateLibraryDefinition name-value pair arguments to automatically convert all cases of a particular type. You also can remove an overloaded function.

After modifying the definition file, rerun the file to validate your edits.

Customize Content

Review the renaming scheme used by MATLAB to replace invalid names. For more information, see C++ Names That Are Invalid in MATLAB.

Review auto-generated help. MATLAB automatically copies some C++ comments into Description and DetailedDescription arguments. You can modify or replace this content, which is the basis of the doc command for end-users.

Customize Function Template Names

Review the unique function names generated from function templates in the library definition file. For example, class A in this header file defines a function template show and provides instantiations for types int, double, and const A.

class A{}; // User type
template<typename T> void show(T a) {}
template void show<int>(int);
template void show<double>(double);
template<> void show<const A &>(const A& a){}

If you build an interface A to this library, MATLAB creates overloaded functions with signatures for these instantiations.

summary(defineA)
MATLAB Interface to libname Library

Class clib.libname.A

  Constructors:
    clib.libname.A(clib.libname.A)
    clib.libname.A()

  No Methods defined

  No Properties defined

Functions
clib.libname.show(int32)
clib.libname.show(double)
clib.libname.show(clib.libname.A)

The C++ interface also generates unique function names based on the signature types. To view the unique names, use the TemplateUniqueName property.

d = defineA;
d.Functions(1:3).TemplateUniqueName
ans = "clib.libname.show_int_"
ans = "clib.libname.show_double_"
ans = "clib.libname.show_AConst__"

You can customize these name in the library definition file. For example, change the name of the function for the class object, clib.libname.show_AConst__. Restart MATLAB and edit defineA.mlx. Locate the addFunction statement for the show_AConst__ function and change the "TemplateUniqueName" name-value pair argument. Replace show_AConst__ with a new name, for example showObjectA. Update the "Description" name-value pair argument by replacing clib.libname.show with the new name clib.libname.showObjectA and modifying the help text to read Representation of C++ function show for class A.

"Description", "clib.libname.showObjectA    Representation of C++ function show for class A.");
help clib.libname.showObjectA
 clib.libname.showObjectA    Representation of C++ function show for class A.

    Inputs
      a              read-only clib.libname.A  

    No outputs

For more information, see Use Function and Member Function Templates.

See Also

|

Related Topics