Package MATLAB Function Using C++ Shared Library Compiler App with mwArray API

Supported platforms: Windows^®, Linux^®, Mac

This example shows how to use the C++ Shared Library Compiler app to package MATLAB^® functions into a C++ shared library. The provided C++ application demonstrates passing matrices between the MATLAB functions and the C++ application using the mwArray API.

Before R2025a: Create a C++ shared library using the Library Compiler as shown in Generate a C++ mwArray API Shared Library and Build a C++ Application (R2024b).

Prerequisites

• Verify that you have a C++ compiler that is compatible with MATLAB Compiler SDK™. 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.

Create MATLAB Functions

Write MATLAB code that you want to package. This example uses these files in matlabroot\extern\examples\compilersdk\c_cpp\matrix:

MATLAB Functions	addmatrix.m eigmatrix.m multiplymatrix.m
C++ mwArray API Application Code	matrix_mwarray.cpp

At the MATLAB command prompt, copy the contents of the matrix folder that ships with MATLAB to a new folder named MatrixProject.

copyfile(fullfile(matlabroot,'extern','examples', ...
    'compilersdk','c_cpp','matrix'),"MatrixProject")

Examine and test addmatrix.m, multiplymatrix.m, and eigmatrix.m.

function a = addmatrix(a1, a2)
%ADDMATRIX Add two matrices
%    This function adds the two matrices passed as input. This function is
%    used to demonstrate the functionality of MATLAB Compiler SDK.

a = a1 + a2;

function e = eigmatrix(a1)
%EIGMATRIX Returns the eigenvalues of the given matrix
%    This function returns the eigenvalues of the input matrix. This
%    function is used to demonstrate the functionality of MATLAB Compiler SDK.

    try
        %Tries to calculate the eigenvalues and return them.
        e = eig(a1);
    catch
        %Returns a -1 on error.
        e = -1;
end

function m = multiplymatrix(a1, a2)
%MULTIPLYMATRIX Multiplies two matrices
%    This function multiplies the two matrices passed as input. This
%    function is used to demonstrate the functionality of MATLAB Compiler SDK.

m =  a1*a2;

Create Project and Compiler Task

Create a compiler task for your C++ shared library using the C++ Shared Library Compiler app. Compiler tasks allow you to compile files in a project for a specific deployment target.

To open the app, on the Apps tab, expand the Apps gallery. In the Application Deployment section, click C++ Shared Library Compiler.

You can also open the app using the cppSharedLibraryCompiler function at the MATLAB Command Window.

After you open the app, the Create Compiler Task dialog box prompts you to add a task to a new or an existing MATLAB project. For this example, select Start a new project and create a compiler task and create a new project named MatrixProject in the MatrixProject folder. For more information on creating and using MATLAB projects, see Create Projects.

A new compiler task named CppSharedLib1 opens in the Editor. You can compile code for other deployment targets by opening the Compiler Task Manager or going to the Manage Tasks tab and creating a new compiler task.

Specify Build Options

You can specify options for the C++ shared library and its installer before packaging to customize the building and packaging process. For instance, you can obfuscate the MATLAB code or specify the method of including MATLAB Runtime in the generated installer.

Add the MATLAB functions to the C++ shared library. All files must be located in the project root folder to be added to the project. For this example, in the Exported Functions section of the compiler task, click Add File and select addmatrix.m, multiplymatrix.m, and eigmatrix.m. In the Project panel, the files now have the labels Design and Exported Function File.

In the Package Info section, replace the string My C++ Package with the name for your C++ shared library, libmatrix.

In the C++ API Selection section, choose the API to use for exchanging data between the C++ application and the MATLAB functions. For this example, select the mwArray API. For more information, see Choose C++ Deployment Option.

View Code and Package C++ Shared Library

To view code that contains instructions on building and packaging your component, click the arrow next to Export Build Script and select Show Code. On the right, a window displays a deployment script with the compiler.build.cppSharedLibrary and compiler.package.installer functions that corresponds to your build options. You can convert this code to a MATLAB script file by clicking the Export Build Script button. Running the generated build script is equivalent to clicking the Build and Package button.

To create the C++ shared library and an installer, click Build and Package. To create only the C++ shared library, click the arrow next to Build and Package and select Build.

The compiler generates files in the <compiler_task_name>/output folder in your project folder. The build subfolder contains the shared library and the package subfolder contains an installer for your shared library along with MATLAB Runtime. To choose a different output location for the generated files, update the paths in the Output Locations section.

If you create an installer, the package subfolder contains the installer for your shared library files along with MATLAB Runtime.

Caution

The generated installer does not include a C++ application executable. You must compile and link your C++ application using mbuild after packaging. Then, manually distribute the application file along with MATLAB Runtime or include the executable in an installer using the AdditionalFiles option of compiler.package.installer. For more information, see Distribute MATLAB Compiler SDK Files to Application Developers.

Integrate C++ Shared Library into C++ Application

After creating the C++ shared library, write source code for a C++ application in your preferred C++ development environment. For details, see Set Up C++ Development Environment.

There are two C++ applications included with this example: matrix_mda.cpp, which uses the MATLAB Data API, and matrix_mwarray.cpp, which uses the mwArray API. For this example, use the file matrix_mwarray.cpp.

 matrix_mwarray.cpp

/*==============================================================
 *
 * MATRIX_MWARRAY.CPP
 * Sample driver code that calls a C++ mwArray shared library 
 * created using the MATLAB Compiler SDK. Refer to the MATLAB 
 * Compiler SDK documentation for more information.
 *
 * Copyright 1984-2021 The MathWorks, Inc.
 *
 *============================================================*/

// Include the library specific header file as generated by the 
// MATLAB Compiler SDK
#include "libmatrix.h"

// This function should only be used after mclInitializeApplication
// has been called.
void printErrorMessageWithDetailsIfAny(const char *message)
{
    const char * lastErrorMessage = mclGetLastErrorMessage();
    if (lastErrorMessage && *lastErrorMessage)
    {
        std::cerr << message << std::endl << "Details:" << std::endl 
            << lastErrorMessage << std::endl;
    }
    else
    {
        std::cerr << message << std::endl;
    }
}

int run_main(int argc, const char **argv)
{
    if( !libmatrixInitialize() )
    {
        printErrorMessageWithDetailsIfAny("Could not initialize the matrix library.");
        return -2;
    }
    else
    {
        try
        {
            // Create input data
            double data[] = {1,2,3,4,5,6,7,8,9};
            mwArray in1(3, 3, mxDOUBLE_CLASS, mxREAL);
            mwArray in2(3, 3, mxDOUBLE_CLASS, mxREAL);
            in1.SetData(data, 9);
            in2.SetData(data, 9);
            
            // Create output array
            mwArray out;
            
            // Call the library function
            addmatrix(1, out, in1, in2);
            
            // Display the return value of the library function
            std::cout << "The sum of the matrix with itself is:" << std::endl;
            std::cout << out << std::endl;
            
            multiplymatrix(1, out, in1, in2);
            std::cout << "The product of the matrix with itself is:" 
                      << std::endl;
            std::cout << out << std::endl;
            
            eigmatrix(1, out, in1);
            std::cout << "The eigenvalues of the original matrix are:"
                      << std::endl;
            std::cout << out << std::endl;
        }
        catch (const mwException& e)
        {
            std::cerr << e.what() << std::endl;
            return -3;
        }
        catch (...)
        {
            std::cerr << "Unexpected error thrown" << std::endl;
            return -4;
        }     
        // Call the application and library termination routine
        libmatrixTerminate();
    }
    // mclTerminateApplication shuts down the MATLAB Runtime.
    // You cannot restart it by calling mclInitializeApplication.
    // Call mclTerminateApplication once and only once in your application.
    mclTerminateApplication();
    return 0;
}

// The main routine. On the Mac, the main thread runs the system code, and
// user code must be processed by a secondary thread. On other platforms, 
// the main thread runs both the system code and the user code.
int main(int argc, const char **argv)
{
    // Call application and library initialization. Perform this 
    // initialization before calling any API functions or
    // Compiler SDK-generated libraries.
    if (!mclInitializeApplication(nullptr, 0)) 
    {
        std::cerr << "Could not initialize the application."
                  << std::endl;
        return -1;
    }

    return mclRunMain(static_cast<mclMainFcnType>(run_main), argc, argv);
}

The matrix application performs these actions.

• Includes the C++ header file.

• Initializes the matrix library libmatrix.

• Creates the input data using the mwArray API.

• Calls the addmatrix, multiplymatrix, and eigmatrix methods with print statements to return the results.

• Uses a try-catch block to handle exceptions.

For more details on using the mwArray API, see Integrate C++ Shared Libraries with mwArray.

Copy and paste the generated C++ library file libmatrix.lib into the folder that contains your C++ application file, matrix_mwarray.cpp.

Note

The .lib extension is used on Windows. On macOS, the file extension is .dylib, and on Linux it is .so.

Compile and link the application using mbuild at the MATLAB prompt or your system command prompt.

mbuild matrix_mwarray.cpp

Run the application from the system command prompt. To test your application in MATLAB before deployment, run the executable using the bang (!) operator.

matrix_mwarray.exe

The application returns the results of matrix calculations using the packaged MATLAB functions.

The original matrix is:  
1 4 7  
2 5 8  
3 6 9  
 
The sum of the matrix with itself is:  
2 8 14  
4 10 16  
6 12 18  
 
The product of the matrix with itself is:  
30 66 102  
36 81 126  
42 96 150  
 
The eigenvalues of the original matrix are:  
16.1168  
-1.11684  
-1.57673e-16  
 
The original contents of the column-major matrix are:  
100 102 104  
101 103 105  
 
The sum of the column-major matrix with itself is:  
200 204 208  
202 206 210  
 
The original contents of the row-major matrix are:  
100 101  
102 103  
104 105  
 
The sum of the row-major matrix with itself is:  
200 202  
204 206  
208 210

To run the C++ application outside of MATLAB, you must install MATLAB Runtime. For more information, see About MATLAB Runtime. If you create an installer using Build and Package, the installer contains a version of MATLAB Runtime that matches the version of MATLAB used to compile the C++ shared library.

To deploy the C++ application, distribute the code archive, the executable .exe file, and MATLAB Runtime to the end user.