The C++ library wrapper option allows you to create a shared library from an arbitrary set of MATLAB® files. MATLAB Compiler SDK™ generates a wrapper file and a header file. The header file contains all of the entry points for all of the compiled MATLAB functions.
This example rewrites the 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 SDK 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.
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 |
For information about how MATLAB Compiler SDK uses a proxy
layer for the libraries that an application must link, see Understand the mclmcrrt
Proxy Layer.
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 On UNIX®, if this is not the case, replace the " |
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.
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>(<mwArray_lists>);
MATLAB Functions with at Least One Return Value.
bool MW_CALL_CONV <function-name>(int <number_of_return_values>, <mxArray_pointers>, <mwArray_lists>);
In this case, mwArray_lists
represents
a comma-separated list of type const mwArray&
and mxArray_pointers
represents
a comma-separated list of pointers 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);
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
matrixdriver.cpp
application
illustrates the typical way to handle errors when calling the C++
interface functions.
The MATLAB Compiler SDK C/C++ API includes static factory methods for working with sparse arrays.
For a complete list of the methods, see C++ Utility Classes.