|
MexIFace
A C++/Matlab object-based interface library and cross-platform CMake MEX build tool.
|
|
MexIFace
A C++/Matlab object-based interface library and cross-platform CMake MEX build tool.
|
A C++/Matlab object-based interface library and cross-platform CMake build system for creating interactive Matlab MEX modules with persistent state and complex behavior.
The MexIFace class provides a flexible means of wrapping a complex C++ library into a Matlab class via Matlab's MEX function extension method. A standard Matlab MEX module implements a single function API, with no obvious way to manage shared state across one or more interacting MEX components. A MexIFace generated MEX module is wrapped in a regular Matlab handle class interface with normal Matlab properties and methods. MexIFace Matlab objects have associated C++ state that is persistent across method calls into the MEX module.
Instead of the procedural workflow implied by the static mexFunction() interface, a MexIFace wrapped class can be used interactively. Multiple objects of the wrapped type can be created and accessed independently using the same MEX module. Each instantiated object has its own persistent state; and when Matlab garbage collects a MexIFace object, it's C++ resources are freed as well.
mxArray objects as C++ Armadillo objects. This makes it possible to directly share multidimensional array data. (see: Armadillo and mxArrays)glnxa64) and Windows (win64) environments
The MexIFace Doxygen documentation can be build with the OPT_DOC CMake option and is also available online:
Matlab uses compiled plugins called MEX files to enable linking and running C and C++ code. A MEX file is a shared object file (ELF on Linux and DLL on Windows) that is dynamically loaded by the Matlab binary when the function it names is called. Each MEX file presents to Matlab an interface consisting of exactly one function with variable input and output arguments.
Separate MEX functions have no direct way to communicate with this API, and as C and C++ libraries become more complex this isolated, static function interface becomes increasingly restrictive.
Complex simulations an analysis libraries have more demanding requirements; they must:
In other words, complex libraries are much more like objects than functions. An object-oriented MEX file interface provides an easier, safer, faster, and more organized way of interacting with complex C++ libraries from Matlab.
MexIFace uses the Armadillo package to provide an efficient and powerful C++ interface to Matlab array types. Passing and returning large array data between C++ and Matlab can be very inefficient if data needs to be copied repeatedly. The Armadillo auxillary-memory constructors allow C++ Armadillo arrays to transparently manipulate Matlab mxArray raw data, as both use column-major layouts.
This allows the same memory allocated by Matlab to be used in C++ with very little overhead incurred when passing large array arguments. Return arguments can also be allocated from C++ into Matlab managed memory using Matlab's mxArray API, then mapped directly to an Armadillo C++ array used as output.
The mexiface::MexIFace class implements templated methods to succinctly convert data views between mxArray and armadillo array data types,
MexIFace uses the MATLAB_ROOT and MATLAB_ROOTS environment variables to find Matlab installations. For each Matlab release found, the build system creates a CMakeMexIFace::MexIFaceX_Y target corresponding to a libMexIFaceX_Y.so library, where X_Y is the numerical release code for each Matlab as returned by Matlab version command. Each Matlab release has potentially incompatible dependency and linking requirements, so a MexIFace library must be produced for each Matlab release that will be targeted.
MATLAB_ROOTS environment variable to list (';' or ':' separated) of matlab root directories or a folder containing them.Native Linux build
Matlab glnxa64 R2016b+: Linux gcc-4.9.4 environment cross-compile.
Matlab glnxa64 R2018a+: Linux gcc-6.5.0 environment cross-compile.
Matlab win64 R2016b+: Windows MXE-MexIFace mingw-w64/gcc-4.9.4 environment cross-compile
Run Matlab unit tests on command line
Setup MexIFace paths from inside matlab
MATLAB_ROOT or MATLAB_ROOTS to any directory containing Matlab roots. A MexIFace library will be created for each supported release root found.In order to build for a particular Matlab target environment, the development machine must have system libraries and all relevant dependencies built with the correct version of GCC.
For C++, the most important restriction involves libsdtc++ versioning, which prevents the use of a GCC with a CXXABI version newer than that used by the Matlab release targeted. Currently the following GCC versions are supported for use with MexIFace.
| GCC Version | Compatible Matlab Releases |
|---|---|
| gcc-4.9.4 | R2016b+ |
| gcc-6.5.0 | R2018a+ |
gcc<=4.7 which has an incomplete C++11 implementation.mingw-w64 for Windows targets is subject to the same GCC version restrictions.The BLAS and LAPACK libraries are common numerical dependencies. Matlab includes internal BLAS and LAPACK libraries that used 64-bit integers for array indexing. Many commonly available BLAS and LAPACK implementations instead use an incompatible 32-bit integer ABI. To make dual-use C++ and Matlab libraries it necessary to have system versions of the 64-bit BLAS and LAPACK.
OPT_MexIFace_MATLAB_INTERLEAVED_COMPLEX - Enable interleaved complex API in R2018a+.OPT_MexIFace_MATLAB_LARGE_ARRAY_DIMS - Enable 64-bit array indexes in R2017a+. If BLAS or LAPACK are used this needs to be on, as Matlab uses 64-bit indexes.OPT_MexIFace_INSTALL_DISTRIBUTION_STARTUP- Install an additional copy of startupPackage.m at the INSTALL_PREFIX root in addition to the normal directory. This makes it easy to distribute as a binary archive file (.zip, .tar.gz, etc.).OPT_MexIFace_PROFILE - Built-in gperftools profiling ProfileStart()/ProfileStop() for every method call to a MexIFace object.OPT_MexIFace_VERBOSE - Verbose output for MexIFace CMake configuration.OPT_MexIFace_SILENT - Silent output for MexIFace CMake configuration. Warnings and errors only.BUILD_TESTING - Build testing frameworkOPT_DOC - Build documentationOPT_INSTALL_TESTING - Install testing executablesOPT_EXPORT_BUILD_TREE - Configure the package so it is usable from the build tree. Useful for development.OPT_EXTRA_DEBUG - Support extra noisy debugging features (Armadillo).OPT_DOC
These dependencies are included via the git subrepo mechanism, unlike git submodule there is not need to fetch subrepos in a seperate step after cloning.
These packages are specialized CMake projects. If they are not currently installed on the development machines we use the AddExternalDependency.cmake module which will automatically download, configure, build and install the CMake-based dependency to the CMAKE_INSTALL_PREFIX. The dependency can then be found through the normal CMake find_package() system.
BacktraceException]() is called. MexIFace translates BacktraceException exceptions into calls to Matlab's mexErrMsgIdAndTxt mechanism allowing very useful debugging output for tracing down errant exceptions. Often this provides enough information to isolate bugs without attaching a debugger to the Matlab process.Because Matlab is closed-source we cannot provide the actual Matlab libraries necessary to link the MexIFace library. If you do have one or more valid releases of Matlab, and you would like to build or test build in an environment with no valid Matlab license, you can use what we call a linkable-stub Matlab environment. The result is archives matlab_stub-ARCH-VERS.tar.bz2 for each find-able <atlab root under the given search paths:
> ./scripts/create-matlab-linker-stub.py –outdir <outdir> <matlab_root_search_paths...>
1.8.11