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
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
:
\extern\examples\compilersdk\c_cpp\matrixmatlabroot
MATLAB Functions | addmatrix.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.
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 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
.
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.
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
folder in your project
folder. The key files utilized during the integration process are the code archive
(<compiler_task_name>
/output.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
.
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
, andeigmatrix
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
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
C++ Shared
Library Compiler | compiler.build.cppSharedLibrary
| compiler.package.installer
| mbuild