C++ Shared Library Target :: Libraries (MATLAB® Compiler™)

The C++ library wrapper option allows you to create a shared library from an arbitrary set of MATLAB files. MATLAB Compiler generates a wrapper file and a header file. The header file contains all of the entry points for all of the compiled MATLAB functions.

Note Even if you are not producing a shared library, you must use -W lib or -W cpplib when including any MATLAB Compiler generated code into a larger application. For more information, refer to Combining Your MATLAB and C/C++ Code.

C++ Shared Library Example

This example rewrites the previous C shared library example using C++. The procedure for creating a C++ shared library from MATLAB files is identical to the procedure for creating a C shared library, except you use the cpplib wrapper. Enter the following command on a single line:

mcc -W cpplib:libmatrixp -T link:lib addmatrix.m multiplymatrix.m eigmatrix.m -v

The -W cpplib:<libname> option tells MATLAB 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.

Writing the Driver Application

Note Due to name mangling in C++, you must compile your driver application with the same version of your third-party compiler that you use to compile your C++ shared library.

In the C++ version of the matrixdriver application matrixdriver.cpp, arrays are represented by objects of the class mwArray. Every mwArray class object contains a pointer to a MATLAB array structure. For this reason, the attributes of an mwArray object are a superset of the attributes of a MATLAB array. Every MATLAB array contains information about the size and shape of the array (i.e., the number of rows, columns, and pages) and either one or two arrays of data. The first array stores the real part of the array data and the second array stores the imaginary part. For arrays with no imaginary part, the second array is not present. The data in the array is arranged in column-major, rather than row-major, order.

Caution Avoid issuing cd commands from the driver application prior to calling mclInitializeApplication. Failure to do so can cause a failure in MCR initialization.

Caution to Mac users: when running the matrixdriver example, invoke mclInitializeApplication prior to mclRunMain.

Linking to mclmcrrt.lib: How the MCLMCRRT Proxy Layer Handles Loading of Libraries in \bin. . All application and software components generated by MATLAB Compiler and the associated builder products need to link against only one MathWorks library, mclmcrrtxx.lib. This versioned library (with the version represented by xx) provides a proxy API for all the public functions in MATLAB libraries used for matrix operations, MAT-file access, utility and memory management, and application runtime.

Caution Deployed applications must only link to mclmcrrtxx.lib. Do not link to other libraries, such as mclmcr.lib, libmx.lib, and so on.

The relationship between mclmcrrtxx.lib and other MATLAB modules is shown in the following figure.

The MCLMCRRT Proxy Layer

The MCLMCRRT Proxy Layer depicts solid arrows designating static linking and dotted arrows designating dynamic linking.

The MCLMCRRT module lies between deployed components and other modules, providing the following functionality:

Ensures that multiple versions of the MATLAB Compiler Runtime can coexist
Provides a layer of indirection
Enforces thread safety
Loads the dependent (re-exported) libraries dynamically

Other Details.

In addition, the figure shows that the MCLMCR contains the run-time functionality of the deployed components. Additionally, the MCR module ensures each deployed component runs in its own context at runtime. mclmcrrtxx.lib, in addition to loading the MCLMCR, also dynamically loads the MX and MAT modules, primarily for mxArray manipulation.

For more information, see the MathWorks Support database and search for information on the MSVC shared library.

Compiling the Driver Application

To compile the matrixdriver.cpp driver code, you use your C++ compiler. By executing the following mbuild command that corresponds to your development platform, you will use your C++ compiler to compile the code.

mbuild matrixdriver.cpp libmatrixp.lib            (Windows)
mbuild matrixdriver.cpp -L. -lmatrixp -I.         (UNIX)

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

On Windows, if this is not the case, specify the full path to libmatrixp.lib, and use a -I option to specify the directory containing the header file.

On UNIX, if this is not the case, replace the "." (dot) following the -L and -I options with the name of the directory that contains these files, respectively.

Incorporating a C++ Shared Library into an Application

To incorporate a C++ shared library into your application, you will, in general, follow the steps in Using a Shared Library. There are two main differences to note when using a C++ shared library:

Interface functions use the mwArray type to pass arguments, rather than the mxArray type used with C shared libraries.
C++ exceptions are used to report errors to the caller. Therefore, all calls must be wrapped in a try-catch block.

Exported Function Signature

The C++ shared library target generates two sets of interfaces for each MATLAB function. The first set of exported interfaces is identical to the mlx signatures that are generated in C shared libraries. The second set of interfaces is the C++ function interfaces. The generic signature of the exported C++ functions is as follows:

MATLAB Functions with No Return Values.

bool MW_CALL_CONV <function-name>(<list_of_input_variables>);

MATLAB Functions with at Least One Return Value.

bool MW_CALL_CONV <function-name>(int <number_of_return_values>,
     <list_of_return_variables>, <list_of_input_variables>);

In this case, <list_of_input_variables> represents a comma-separated list of type const mwArray& and <list_of_return_variables> represents a comma-separated list of type mwArray&. For example, in the libmatrix library, the C++ interfaces to the addmatrix MATLAB function is generated as:

void addmatrix(int nargout, mwArray& a , const mwArray& a1,  
               const mwArray& a2);

Error Handling

C++ interface functions handle errors during execution by throwing a C++ exception. Use the mwException class for this purpose. Your application can catch mwExceptions and query the what() method to get the error message. To correctly handle errors when calling the C++ interface functions, wrap each call inside a try-catch block.

	try
{
		...
		(call function)
		...
}
catch (const mwException& e)
{
		...
		(handle error)
		...
}

The matrixdriver.cpp application illustrates the typical way to handle errors when calling the C++ interface functions.

Using C/C++ Shared Libraries on a Mac OS X System

To use a MATLAB Compiler generated library on a Mac OS X system, a separate thread needs to be created.

The initialization of the shared library and subsequent calls to that library's functions is performed by this thread. The function mclRunMain, provided by MATLAB Compiler, takes care of the thread creation process.

The main thread of the application is the thread that calls your driver program's main() function. The body of your main() function should call the mclRunMain function, passing to it the address of another function. This function should contain the library initialization routines and necessary calls to the shared library generated by MATLAB Compiler.

The matrixdriver.c example illustrates this procedure. This example rewrites the C shared library example from this chapter for use on Mac OS X. Follow the same procedure as in C Shared Library Example to build and run this application.

The Mac version of the matrixdriver application differs from the version on other platforms. The run_main() function performs the basic tasks of initialization, calling the library's functions, and termination. Compare this function with the matrixdriver main() function on other platforms, listed in the earlier example.

Working with C++ Shared Libraries and Sparse Arrays

The MATLAB Compiler API includes static factory methods for working with sparse arrays.

For a complete list of the methods, see Static Factory Methods for Sparse Arrays.

C Shared Library Target

MATLAB Compiler Generated Interface Functions

Free MATLAB Compiler Interactive Kit

Learn how to build standalone executables and C/C++ shared libraries from MATLAB code.

Get free kit

Trials Available

Try the latest version of MATLAB Compiler.

Get trial software