Deploy MATLAB Function to C++ Application Using MATLAB Data API - MATLAB & Simulink (original) (raw)

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 namedwork.
• 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. Thearguments block lets you represent C++ data types with an equivalent MATLAB type. For instance, if your C++ application employs anint32_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 anarguments 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 andvarargout 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

#include "MatlabTypesInterface.hpp"
#include <map>

template<size_t nargout>
struct return_type_calculateDistance { typedef void type; };

template<size_t nargout = 1>
typename return_type_calculateDistance<nargout>::type calculateDistance(
    std::shared_ptr<MATLABControllerType> _matlabPtr, 
    std::vector<int32_t> p1, std::vector<int32_t> p2) {
    static_assert(nargout<=1, "Too many outputs specified. Maximum outputs is 1.");
}
template<>
struct return_type_calculateDistance<0> { typedef void type; };

template<>
struct return_type_calculateDistance<1> { typedef int32_t type; };

template<>
void calculateDistance<0>(
    std::shared_ptr<MATLABControllerType> _matlabPtr, 
    std::vector<int32_t> p1, std::vector<int32_t> p2) { 
    matlab::data::ArrayFactory _arrayFactory;
    matlab::data::ArrayDimensions _dims1 = {1, p1.size()};
    matlab::data::ArrayDimensions _dims2 = {1, p2.size()};
    std::vector<matlab::data::Array> _args = 
    {        _arrayFactory.createArray(_dims1, p1.begin(), p1.end()),
        _arrayFactory.createArray(_dims2, p2.begin(), p2.end()) };
    _matlabPtr->feval(u"calculateDistance", 0, _args);
}

template<>
int32_t calculateDistance<1>(
    std::shared_ptr<MATLABControllerType> _matlabPtr, 
    std::vector<int32_t> p1, std::vector<int32_t> p2) { 
    matlab::data::ArrayFactory _arrayFactory;
    matlab::data::ArrayDimensions _dims1 = {1, p1.size()};
    matlab::data::ArrayDimensions _dims2 = {1, p2.size()};
    std::vector<matlab::data::Array> _args = 
    {        _arrayFactory.createArray(_dims1, p1.begin(), p1.end()),
        _arrayFactory.createArray(_dims2, p2.begin(), p2.end()) };
    matlab::data::Array _result_mda = _matlabPtr->feval(u"calculateDistance", _args);
    int32_t _result;
    _result = MatlabTypesInterface::convertMDAtoScalar<int32_t>(_result_mda);
    return _result;
}

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

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)

#include "MatlabTypesInterface.hpp" #include

template struct return_type_calculateDistance { typedef void type; };

template typename return_type_calculateDistance::type calculateDistance( std::shared_ptr _matlabPtr, matlab::data::Array arg1, matlab::data::Array arg2) { static_assert(nargout<=1, "Too many outputs specified. Maximum outputs is 1."); } template<> struct return_type_calculateDistance<0> { typedef void type; };

template<> struct return_type_calculateDistance<1> { typedef matlab::data::Array type; };

template<> void calculateDistance<0>( std::shared_ptr _matlabPtr, matlab::data::Array arg1, matlab::data::Array arg2) { matlab::data::ArrayFactory _arrayFactory; std::vectormatlab::data::Array _args = { arg1, arg2 }; _matlabPtr->feval(u"calculateDistance", 0, _args); }

template<> matlab::data::Array calculateDistance<1>( std::shared_ptr _matlabPtr, matlab::data::Array arg1, matlab::data::Array arg2) { matlab::data::ArrayFactory _arrayFactory; std::vectormatlab::data::Array _args = { arg1, arg2 }; matlab::data::Array _result_mda = _matlabPtr->feval(u"calculateDistance", _args); matlab::data::Array _result; _result = _result_mda; return _result; }

The primary difference between the header files rests in the type specification for input and output variables. When anarguments block is used with type information specified, the inputs and outputs are categorized asstd::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 thebuildResults 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.

1. In the work folder for this example create a new file named DistanceConsoleApp.cpp with the following code.
   DistanceConsoleApp.cpp
   // Include header files

#include
#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_ptrmatlab::cpplib::MATLABApplication setup()
{
auto mode = matlab::cpplib::MATLABApplicationMode::IN_PROCESS;
std::vectorstd::u16string options = { u"-nojvm" };
std::shared_ptrmatlab::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_ptrmatlab::cpplib::MATLABApplication app, const int argc, const char* argv[])
{
try {
auto libPtr = matlab::cpplib::initMATLABLibrary(app, u"calculateDistance.ctf");
std::shared_ptr matlabPtr(std::move(libPtr));
// Specify inputs using std::vector; no need to create matlab::data::Array objects
std::vector p1 = { 0, 0 };
std::vector 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
#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_ptrmatlab::cpplib::MATLABApplication setup()
{
auto mode = matlab::cpplib::MATLABApplicationMode::IN_PROCESS;
std::vectorstd::u16string options = { u"-nojvm" };
std::shared_ptrmatlab::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_ptrmatlab::cpplib::MATLABApplication app, const int argc, const char* argv[])
{
try {
auto libPtr = matlab::cpplib::initMATLABLibrary(app, u"calculateDistance.ctf");
std::shared_ptr matlabPtr(std::move(libPtr));
Specify inputs as matlab::data::Array objects; cannot use std::vector
matlab::data::ArrayFactory factory;
matlab::data::TypedArray p1 = factory.createArray({ 1,2 }, { 0.0, 0.0 });
matlab::data::TypedArray p2 = factory.createArray({ 1,2 }, { 3.0, 4.0 });
// Call MATLAB function and print result
matlab::data::TypedArray 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 anarguments 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 anarguments block detailing type information is not included, inputs and outputs must be defined asmatlab::data::Array objects. 2. 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 theCPPSHARED_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 C++ Shared 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 amatlab::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 thecalculateDistance.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 adouble type. Consequently, whensqrt executes, the output argumentdistance also becomes adouble.
  Review the last few lines of thecalculateDistancev2.hpp header:
  matlab::data::Array _result_mda = _matlabPtr->feval(u"calculateDistance", _args);
  int32_t _result;
  _result = MatlabTypesInterface::convertMDAtoScalar(_result_mda);
  return _result;
  When examining the final lines of thecalculateDistancev2.hpp file, we observe thefeval call to the MATLAB function calculateDistance. The result of this function call is stored in the variable_result_mda, which is an object of typematlab::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 amatlab::data::Array type, undergoes a conversion to int32_t. This conversion is achieved through theconvertMDAtoScalar<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 is7.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 value7.6158 gets rounded up to 8, which is then received by the C++ application as anint32_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 anarguments 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.

See Also

mbuild | compiler.build.cppSharedLibrary | arguments

Topics

• Data Type Mappings Between C++ and Strongly Typed MATLAB Code
• Deploy MATLAB Classes to C++ Application Using MATLAB Data API
• Code Archive (.ctf file) Placement
• Summary of MATLAB Compiler SDK C++ APIs
• Function Argument Validation
• Argument Validation Functions