Main Content

Package MATLAB Function Using C++ Shared Library Compiler App with MATLAB Data 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 MATLAB Data API.

Before R2025a: See Generate a C++ MATLAB Data API Shared Library and Build a C++ Application (R2024b).

Prerequisites

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 Functionsaddmatrix.m
eigmatrix.m
multiplymatrix.m
C++ MATLAB Data API Application Code matrix_mda.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. 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.

Application Deployment section of the Apps gallery

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

Create compiler task dialog box with the text 'To deploy your MATLAB code, you need a MATLAB project to organize code and a compiler task to handle deployment.' The option 'Start a new project and create a compiler task' is selected.

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 create more C++ compiler tasks or package 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.

Exported file section of the compiler task with no file selected and a button labeled Add Exported Function

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

To choose a different output location for the generated files, update the paths in the Output Locations section.

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 MATLAB Data API. For more information, see Choose C++ Deployment Option.

C++ API Selection section with the option 'Create interface that uses the MATLAB Data API for C++' selected

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.

Two buttons labeled Export Build Script and Build and Package

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 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.

If you created 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 MATLAB Code Archive 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.

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.

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_mda.cpp.

 matrix_mda.cpp

The matrix application performs these actions.

  • Includes the C++ header file.

  • Initializes the matrix library libmatrix.

  • Creates the input data using the MATLAB Data API.

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

  • Uses a try-catch block to handle exceptions.

Copy and paste the generated code archive libmatrix.ctf from the v2\generic_interface folder into the project folder that contains your C++ application.

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

mbuild matrix_mda.cpp
The compiler generates an executable file named matrix_mda for your C++ application.

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

matrix_mda.exe

The application outputs 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 details, see Download and Install 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 executable file and MATLAB Runtime to the end user.

See Also

| | |

Topics