Choosing C++ Deployment Option

MATLAB^® Compiler SDK™ provides two ways to deploy MATLAB functions within C++ applications:

Deploy to C++ Applications using MATLAB Data API (C++11)
Deploy to C++ Applications using mwArray API (C++03)

Since MATLAB Compiler SDK provides two C++ application APIs to interact with deployed MATLAB functions, the two deployment options are distinguished based on the APIs used for exchanging data between the C++ application and the deployed MATLAB functions.

Choosing a C++ deployment option comes down to understanding the capabilities of each option and recognizing how those capabilities line up with your development requirements. Both options provide a comprehensive set of APIs for handling both application management and data manipulation.

Advantages of MATLAB Data API for .NET over `MWArray` API

MathWorks^® recommends deploying to C++ applications using the more modern MATLAB Data API over the mwArray API. The advantages of using the MATLAB Data API over the mwArray API are:

Data copy operations are minimized.
You do not need to explicitly manage the life-cycle of the MATLAB Runtime instance and library of MATLAB functions in the archive since the C++ API provides a fail-safe way to terminate them.
The runtime instance can run either in-process or out-of-process with respect to the C++ application, and deployed MATLAB functions can be executed either synchronously or asynchronously.
Support for C++11 functionality, type-safety, and multi-thread-safety.
Support for strong types in MATLAB code.
Complex data is stored in the same interleaved format used by MATLAB internally since R2018a and by the C++ language. This eliminates the need for internal conversion.

Difference in Generated Artifacts

When you feed a MATLAB function or class to the compiler.build.cppSharedLibrary function or the Library Compiler app, the main products generated are different for the two deployment options.

Assuming you have a MATLAB function called calculateDistance stored in a file named calculateDistance.m, and you want to deploy in a C++ application, let's examine the resulting outcomes of the two deployment alternatives:

function distance = calculateDistance(p1, p2)
    % This function calculates the Euclidean distance between two points
    % Inputs:
    %   p1 - a two-element vector [x, y]
    %   p2 - a two-element vector [x, y]
    % Output:
    %   distance - the Euclidean distance between p1 and p2
    
    % Use arguments block to map C++ type to corresponding MATLAB type
    % std::vector<int32_t> <--> (1,2) int32 {mustBeReal}
    
    arguments (Input)
        p1 (1,2) int32 {mustBeReal}
        p2 (1,2) int32 {mustBeReal}
    end

    arguments (Output)
        distance (1,1) int32 {mustBeReal}
    end
    
    % Calculte Euclidean distance
    diff = p1 - p2;
    diffSq = diff.^2;
    sumSq = sum(diffSq);
    distance = sqrt(sumSq);
end

When you pass the calculateDistance.m file into the compiler.build.cppSharedLibrary function, the MATLAB Data API is the default choice. To use the mwArray API, you need to explicitly specify the interface type using the name-value pair Interface="mwarray".

results = compiler.build.cppSharedLibrary("calculateDistance.m",...
    OutputDir="calcDistMDArray", Verbose="on")

results = compiler.build.cppSharedLibrary("calculateDistance.m",...
    Interface="mwarray", OutputDir="calcDistmwArray", Verbose="on")

The function generates corresponding files for the two APIs in the specified folder:

P:\MATLAB\WORK\CALCDISTMDARRAY
│   GettingStarted.html
│   includedSupportPackages.txt
│   mccExcludedFiles.log
│   readme.txt
│   requiredMCRProducts.txt
│   unresolvedSymbols.txt
│
└───v2
    └───generic_interface
            calculateDistance.ctf
            calculateDistancev2.hpp
            readme.txt

P:\MATLAB\WORK\CALCDISTMWARRAY
    calculateDistance.cpp
    calculateDistance.def
    calculateDistance.dll
    calculateDistance.exp
    calculateDistance.exports
    calculateDistance.h
    calculateDistance.lib
    GettingStarted.html
    includedSupportPackages.txt
    mccExcludedFiles.log
    readme.txt
    requiredMCRProducts.txt
    unresolvedSymbols.txt

No subfolders exist

When using the MATLAB Data API to incorporate MATLAB code into a C++ application, MATLAB Compiler SDK does not output a C++ shared library file. When you pass a MATLAB function or class to the compiler.build.cppSharedLibrary function or the Library Compiler app, the main products generated are a code archive (.ctf file) and a header (.hpp file). This design offers a more streamlined interface for C++ developers.

To generate a C++ shared library file from MATLAB code with MATLAB Compiler SDK, you must use the mwArray API. Yet, this API operates on the older C++03 standard and lacks many of the sophisticated features provided by the MATLAB Data API. In addition, it transfers data less efficiently.

Support for Strong Types Using MATLAB Data API

You have the flexibility to dictate how MATLAB interprets and handles C++ data types.

If you are deploying a MATLAB class use a properties block and arguments block within the MATLAB class.

MATLAB Function

For example, should your C++ application utilize an int32 data type to signify input types for the MATLAB function, you can employ a MATLAB arguments block to designate the corresponding type. The resulting MATLAB code, the associated header file (.hpp), and the C++ application code are consequently generated as follows:

% .m file
arguments
        p1 (1,2) int32 {mustBeReal}
        p2 (1,2) int32 {mustBeReal}
    end

// .hpp file
   
std::vector<int32_t> p1, 
std::vector<int32_t> p2)

// .cpp file
  
std::vector<int32_t> p1 = { 0, 0 };
std::vector<int32_t> p2 = { 3, 4 };

MATLAB Class

If you are deploying a MATLAB class, use a properties block and arguments block within the MATLAB class.

Data types of MATLAB class properties map to specific C++ data types.
MATLAB package directories map to C++ namespaces with matching names.
MATLAB classes map to C++ classes with matching names.
public methods of MATLAB classes map to public C++ methods with matching names. Since the method names are unchanged, they can be used as is in the C++ application code. These aligned names eliminate the need for intermediate layer top-level functions that call the class methods through an feval function execution.
C++ get and set methods are generated for public properties of MATLAB classes. The property names of MATLAB classes are prepended with get or set. For example, if the property name in a MATLAB class is UpperLeft, the corresponding C++ method names are getUpperLeft and setUpperLeft.