Integrate C Shared Libraries

C Shared Library Wrapper

The C library wrapper option allows you to create a shared library from a set of MATLAB^® files. MATLAB Compiler SDK™ generates a wrapper file, a header file, and an export list. The header file contains all of the entry points for all of the compiled MATLAB functions. The export list contains the set of symbols that are exported from a C shared library.

C Shared Library Example

This example takes several MATLAB files and creates a C shared library. It also includes a standalone driver application to call the shared library.

Building the Shared Library

Copy the following files from matlabroot\extern\examples\compilersdk to your work directory:

matlabroot\extern\examples\compilersdk\addmatrix.m
matlabroot\extern\examples\compilersdk\multiplymatrix.m
matlabroot\extern\examples\compilersdk\eigmatrix.m

To create the shared library, enter the following command on a single line:
```
mcc -B csharedlib:libmatrix addmatrix.m multiplymatrix.m 
eigmatrix.m -v
```
The -B csharedlib option is a bundle option that expands into
```
-W lib:<libname> -T link:lib
```
The -W lib:<libname> option tells the compiler to generate a function wrapper for a shared library and call it libname. The -T link:lib option specifies the target output as a shared library. Note the directory where the product puts the shared library because you will need it later on.

Writing a Driver Application for a Shared Library

Copy matlabroot\extern\examples\compilersdk\matrixdriver.c to your working directory. This file contains the driver code for the application.

All programs that call MATLAB Compiler SDK generated shared libraries have roughly the same structure:

Initialize the MATLAB Runtime using mclmcrInitialize().
Use mclRunMain() to call the code that uses the MATLAB generated shared library.
Declare variables and process/validate input arguments.
Call mclInitializeApplication, and test for success. This function sets up the global MATLAB Runtime state and enables the construction of MATLAB Runtime instances.
Call, once for each library, <libraryname>Initialize, to create the MATLAB Runtime instance required by the library.

Invoke functions in the library, and process the results. (This is the main body of the program.)

Note If your driver application displays MATLAB figure windows, you should include a call to mclWaitForFiguresToDie(NULL) before calling the Terminate functions and mclTerminateApplication in the following two steps.

Call, once for each library, <lib>Terminate, to destroy the associated MATLAB Runtime.

Caution <lib>Terminate will bring down enough of the MATLAB Runtime address space that the same library (or any other library) cannot be initialized. Issuing a <lib>Initialize call after a <lib>Terminate call causes unpredictable results. Instead, use the following structure:

...code... 
mclInitializeApplication(); 
lib1Initialize(); 
lib2Initialize(); 

lib1Terminate(); 
lib2Terminate(); 
mclTerminateApplication(); 
...code...

Call mclTerminateApplication to free resources associated with the global MATLAB Runtime state.
Clean up variables, close files, etc., and exit.

Compiling the Driver Application

To compile the driver code, matrixdriver.c, you use your C/C++ compiler. Execute the following mbuild command that corresponds to your development platform. This command uses your C/C++ compiler to compile the code.

mbuild matrixdriver.c libmatrix.lib    (Windows)
mbuild matrixdriver.c -L. -lmatrix -I. (UNIX)

Note This command assumes that the shared library and the corresponding header file created from are in the current working directory.

This generates a standalone application, matrixdriver.exe, on Windows^®, and matrixdriver, on UNIX^®.

Testing the Driver Application

These steps test your standalone driver application and shared library on your development machine.

To run the application, add the directory containing the shared library that was created in Building the Shared Library to your dynamic library path.
Update the path for your platform by following the instructions in MATLAB Runtime Path Settings for Development and Testing.

Run the driver application from the prompt (DOS prompt on Windows, shell prompt on UNIX) by typing the application name.

matrixdriver.exe                             (On Windows)
matrixdriver	                              (On UNIX)
matrixdriver.app/Contents/MacOS/matrixdriver (On Mac)

The results are displayed as

The value of added matrix is: 
2.00		8.00		14.00	 
4.00		10.00		16.00	 
6.00		12.00		18.00	 
 
The value of the multiplied matrix is: 
30.00		66.00		102.00	 
36.00		81.00		126.00	 
42.00		96.00		150.00		 
 
The eigenvalues of the first matrix are: 
16.12		-1.12		-0.00

Was this topic helpful?

Documentation