Deploy MATLAB Function to C++ Application Using MATLAB Data API

This example shows how to package a MATLAB^® function and deploy it within a C++ application. It uses the MATLAB Data API for managing data exchange between the MATLAB function and the C++ application. The workflow is supported on Windows^®, Linux^®, and macOS.

Prerequisites

Create a new work folder that is visible to the MATLAB search path. This example uses a folder named work.
Verify that you have set up a C++ development environment. For details, see Set Up C++ Development Environment. This example uses MATLAB as a C++ development environment. Therefore, verify that you have a C++ compiler installed by typing mbuild -setup at the MATLAB command prompt.
Verify that you have met all of the MATLAB Compiler SDK™ C++ target requirements. For details, see MATLAB Compiler SDK C++ Target Requirements.
End users must have an installation of MATLAB Runtime to run the application. For details, see Download and Install MATLAB Runtime.
For testing purposes, you can use an installation of MATLAB instead of MATLAB Runtime when running the C++ application.

Create MATLAB Function

Create a MATLAB file named calculateDistance.m with the following code:

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

Established MATLAB users may find the presence of an arguments block unconventional. The arguments block lets you represent C++ data types with an equivalent MATLAB type. For instance, if your C++ application employs an int32_t data type representing a value, you can now represent that in MATLAB as an int32. This option is useful in situations where a C++ application has strict type requirements. For details, see Data Type Mappings Between C++ and Strongly Typed MATLAB Code.

In this example, an arguments block with specified type information is used to illuminate subtle nuances. However, remember that incorporating an arguments block is entirely optional. The deployment process remains unchanged even without it. Various parts of this example underscore the areas where this difference manifests. So, if data types aren't crucial, the specification of type information using an arguments block is not necessary.

Test the MATLAB function at the command prompt.

p1 = int32([0, 0])
p2 = int32([3 4])
distance = calculateDistance(p1,p2)

p1 =
  1×2 int32 row vector
   0   0
p2 =
  1×2 int32 row vector
   3   4
distance =
  int32
   5

Note

MATLAB

functions that use varargin and varargout are unsupported.

Package MATLAB Function Using `compiler.build.cppSharedLibrary`

Create a code archive (.ctf file) and header (.hpp file) from the MATLAB function using the compiler.build.cppSharedLibrary function.

buildResults = compiler.build.cppSharedLibrary("calculateDistance.m",...
    OutputDir=".\output", Verbose="on");

The function produces a suite of files, as enumerated below, and places them in the specified output directory. Among these, the key files utilized during the integration process are the code archive (.ctf file) containing the MATLAB code and the corresponding header (.hpp file). For information on the other files, see Files Generated After Packaging MATLAB Functions.

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

To finalize integration, you need the calculateDistance.ctf code archive file and the calculateDistancev2.hpp header file from the generic_interface folder. You can view the header file here:

calculateDistancev2.hpp

In the calculateDistancev2.hpp header, the MATLAB function's int32 argument specification mirrors its C++ equivalent, int32_t.

    arguments (Input)
        p1 (1,2) int32 {mustBeReal}
        p2 (1,2) int32 {mustBeReal}
    end

   
std::vector<int32_t> p1, 
std::vector<int32_t> p2)

    arguments (Output)
        distance (1,1) int32 {mustBeReal}
    end

template<>
struct return_type_calculateDistance<1> { typedef int32_t type; };
...
...
matlab::data::Array _result_mda = _matlabPtr->feval(u"calculateDistance", _args);
int32_t _result;
_result = MatlabTypesInterface::convertMDAtoScalar<int32_t>(_result_mda);

When an arguments block detailing type information is not included in your MATLAB function, it results in the production of the following header file:

calculateDistancev2.hpp (Type Agnostic)

The primary difference between the header files rests in the type specification for input and output variables. When an arguments block is used with type information specified, the inputs and outputs are categorized as std::vector<int32_t> and int32_t respectively. Conversely, when an arguments block is absent, the inputs and outputs receive a matlab::data::Array object type designation.

Note

The generated artifacts do not include MATLAB Runtime or an installer. To create an installer using the buildResults object, see compiler.package.installer.

Integrate MATLAB Code Archive into C++ Application

You can finalize the integration process in your preferred C++ development environment, including MATLAB or alternatives such as Microsoft^® Visual Studio^® on Windows. This example, however, uses MATLAB as a C++ development environment. For details, see Set Up C++ Development Environment.

To integrate the generated MATLAB code archive (.ctf file) and header (.hpp file) into a C++ application, adhere to these guidelines:

Use a #include directive to incorporate the generated header file (.hpp file) in your C++ application code.
Ensure the code archive (.ctf file) is positioned in a location that the C++ executable can access.

Completing the integration step requires proficient C++ skills for writing application code. You can use the following sample C++ application code as guide when writing your own application.

In the work folder for this example create a new file named DistanceConsoleApp.cpp with the following code.

DistanceConsoleApp.cpp

// Include header files
#include <iostream>
#include "MatlabCppSharedLib.hpp"
#include "P:\MATLAB\work\output\v2\generic_interface\calculateDistancev2.hpp"

// Start MATLAB Runtime, initialize it, and return an object to it
std::shared_ptr<matlab::cpplib::MATLABApplication> setup()
{
    auto mode = matlab::cpplib::MATLABApplicationMode::IN_PROCESS;
    std::vector<std::u16string> options = { u"-nojvm" };
    std::shared_ptr<matlab::cpplib::MATLABApplication> matlabApplication =
        matlab::cpplib::initMATLABApplication(mode, options);
    return matlabApplication;
}

// Initialize the code archive (.ctf file), specify input arguments, call the MATLAB function, 
// and print the result
int mainFunc(std::shared_ptr<matlab::cpplib::MATLABApplication> app, const int argc, const char* argv[])
{
    try {
        auto libPtr = matlab::cpplib::initMATLABLibrary(app, u"calculateDistance.ctf");
        std::shared_ptr<MATLABControllerType> matlabPtr(std::move(libPtr));

        // Specify inputs using std::vector; no need to create matlab::data::Array objects
        std::vector<int32_t> p1 = { 0, 0 };
        std::vector<int32_t> p2 = { 3, 4 };

        // Specify output type as int32_t, call MATLAB function, and print result
        int32_t distance = calculateDistance(matlabPtr, p1, p2);
        std::cout << "Euclidean distance between ["
            << p1[0] << ", " << p1[1] << "] and [" << p2[0] << ", " << p2[1] << "] is: "
            << distance << "\n";

    }
    catch (const std::exception& exc) {
        std::cerr << exc.what() << std::endl;
        return -1;
    }
    return 0;
}

// Call setup() to initialize MATLAB Runtime, use runMain() to run mainFunc(), 
// and reset MATLAB Runtime after completion
int main(const int argc, const char* argv[])
{
    int ret = 0;
    try {
        auto matlabApplication = setup();
        ret = matlab::cpplib::runMain(mainFunc, std::move(matlabApplication), argc, argv);
        matlabApplication.reset();
    }
    catch (const std::exception& exc) {
        std::cerr << exc.what() << std::endl;
        return -1;
    }
    return ret;
}

When an arguments block detailing type information is not included in your MATLAB function, your C++ application code must be written as follows:

DistanceConsoleApp.cpp (Type Agnostic)

// Include header files
#include <iostream>
#include "MatlabCppSharedLib.hpp"
#include "P:\MATLAB\work\output\v2\generic_interface\calculateDistancev2.hpp"

// Start MATLAB Runtime, initialize it, and return an object to it
std::shared_ptr<matlab::cpplib::MATLABApplication> setup()
{
    auto mode = matlab::cpplib::MATLABApplicationMode::IN_PROCESS;
    std::vector<std::u16string> options = { u"-nojvm" };
    std::shared_ptr<matlab::cpplib::MATLABApplication> matlabApplication =
        matlab::cpplib::initMATLABApplication(mode, options);
    return matlabApplication;
}

// Initialize the code archive (.ctf file), specify input arguments, call the MATLAB function, 
// and print the result
int mainFunc(std::shared_ptr<matlab::cpplib::MATLABApplication> app, const int argc, const char* argv[])
{
    try {
        auto libPtr = matlab::cpplib::initMATLABLibrary(app, u"calculateDistance.ctf");
        std::shared_ptr<MATLABControllerType> matlabPtr(std::move(libPtr));

        Specify inputs as matlab::data::Array objects; cannot use std::vector
        matlab::data::ArrayFactory factory;
        matlab::data::TypedArray<double> p1 = factory.createArray({ 1,2 }, { 0.0, 0.0 });
        matlab::data::TypedArray<double> p2 = factory.createArray({ 1,2 }, { 3.0, 4.0 });

        // Call MATLAB function and print result
        matlab::data::TypedArray<double> distance = calculateDistance(matlabPtr, p1, p2);
        std::cout << "Euclidean distance between ["
            << p1[0] << ", " << p1[1] << "] and [" << p2[0] << ", " << p2[1] << "] is: "
            << distance[0] << "\n";

    }
    catch (const std::exception& exc) {
        std::cerr << exc.what() << std::endl;
        return -1;
    }
    return 0;
}

// Call setup() to initialize MATLAB Runtime, use runMain() to run mainFunc(), 
// and reset MATLAB Runtime after completion
int main(const int argc, const char* argv[])
{
    int ret = 0;
    try {
        auto matlabApplication = setup();
        ret = matlab::cpplib::runMain(mainFunc, std::move(matlabApplication), argc, argv);
        matlabApplication.reset();
    }
    catch (const std::exception& exc) {
        std::cerr << exc.what() << std::endl;
        return -1;
    }
    return ret;
}

In C++ application code, the distinction between including an arguments block with type information and not doing so lies in the specification of inputs and outputs to the MATLAB function. When an arguments block detailing type information is included, the use of C++ Standard Library and primitive types is permissible for input and output specification. On the other hand, when an arguments block detailing type information is not included, inputs and outputs must be defined as matlab::data::Array objects.

Compile and link the application by executing the mbuild function at the MATLAB command prompt.
```
mbuild -v DistanceConsoleApp.cpp -outdir output\bin
```

Handle Code Archive (`.ctf` file)

To ensure your C++ application can access the code archive (.ctf file) containing MATLAB code, place the file in a location accessible to the executable. For this example we are going to do this by setting the CPPSHARED_BASE_CTF_PATH environment variable in the MATLAB desktop environment.

setenv("CPPSHARED_BASE_CTF_PATH","P:\MATLAB\work\output\v2\generic_interface")

If you're using Visual Studio, see Set Environment Variables in Visual Studio.

For a complete list of code archive (.ctf file) placement options, see Code Archive (.ctf file) Placement.

Run C++ Application

For testing purposes, you can run the application from MATLAB command prompt. This does not require a MATLAB Runtime installation.

!output\bin\DistanceConsoleApp.exe

Euclidean distance between [0, 0] and [3, 4] is: 5

Subtleties of Deploying to C++ Using MATLAB Data API

When deploying MATLAB code to a C++ application using the MATLAB Data API, MATLAB Compiler SDK does not generate a C++ shared library. The primary outputs from the compiler.build.cppSharedLibrary function or the Library Compiler app are a code archive (.ctf file) and a header file(.hpp file). If you want MATLAB Compiler SDK to generate a C++ shared library from MATLAB code, you need to use the mwArray API. However, this API uses the older C++03 standard, lacking many of the modern features offered by the MATLAB Data API, which is built upon the more current C++11 standard.
Since R2021b, MATLAB Compiler SDK has supported argument type specification, albeit exclusively for input arguments. Within a MATLAB function, the data types for output arguments were derived from the type specifications and interactions of various functions inside the function. As a result, the output type was always mapped to a matlab::data::Array object in C++.
Since R2023b, argument type specification is supported for both input and output arguments. Inside a MATLAB function, the type specifications and interactions of various functions continue to determine the resulting output type. However, when this output is returned to the C++ application, it is cast to the type that the C++ application needs. This casting is managed in the generated header (.hpp file).
Consider the calculateDistance function in the calculateDistance.m file. This function performs four operations to compute the Euclidean distance:
```
diff = p1 - p2;
diffSq = diff.^2;
sumSq = sum(diffSq);
distance = sqrt(sumSq);
```
When providing two inputs to this function, say p1 = int32([0, 0]) and p2 = int32([3 4]), the int32 type is maintained until the sum function executes. After execution, sumSq changes to a double type. Consequently, when sqrt executes, the output argument distance also becomes a double.
Review the last few lines of the calculateDistancev2.hpp header:
```
matlab::data::Array _result_mda = _matlabPtr->feval(u"calculateDistance", _args);
int32_t _result;
_result = MatlabTypesInterface::convertMDAtoScalar<int32_t>(_result_mda);
return _result;
```
When examining the final lines of the calculateDistancev2.hpp file, we observe the feval call to the MATLAB function calculateDistance. The result of this function call is stored in the variable _result_mda, which is an object of type matlab::data::Array.
Subsequently, a new variable _result is declared as an int32_t type. In the following line, the _result_mda variable, which originally was a matlab::data::Array type, undergoes a conversion to int32_t. This conversion is achieved through the convertMDAtoScalar<int32_t>() function, a part of the MatlabTypesInterface library.
Finally, _result is returned by the function. This return value is a scalar integer (an int32_t), which was converted from a MATLAB array.
Given two new points p1 and p2 represented as int32 arrays with values [0,0] and [3, 7] respectively, the calculateDistance MATLAB function computes the Euclidean distance between these points. In this particular case, the calculated distance is 7.6158, a value with double data type.
However, when this result is returned to the C++ application, a type conversion occurs. Specifically, the double result is converted to an int32_t type. As a result of this conversion process, the original double value 7.6158 gets rounded up to 8, which is then received by the C++ application as an int32_t.
This demonstrates how type conversions between MATLAB and C++ can affect the precision of data. It's crucial to be aware of these potential rounding issues when designing and interfacing between MATLAB functions and C++ applications.
It's important to remember that employing an arguments block to specify type information in MATLAB functions is not mandatory—it's a feature to be utilized solely based on the specific requirements of your C++ application. However, this feature offers several benefits which should not be overlooked.
The ability to define types in a MATLAB function allows for more precise control over the data types returned to the C++ application from MATLAB functions. This reduces the need for additional type conversions within the C++ code, which can often be a source of performance inefficiency and potential bugs.
In essence, this feature facilitates a smoother integration of MATLAB code within C++ applications. By specifying the data types directly in MATLAB, developers can streamline the process of interfacing between the two languages.