Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/mathworks/libmexclass
libmexclass is a MATLAB framework which enables users to implement the functionality of MATLAB classes in terms of equivalent C++ classes using MEX.
https://github.com/mathworks/libmexclass
cpp matlab mex
Last synced: 3 months ago
JSON representation
libmexclass is a MATLAB framework which enables users to implement the functionality of MATLAB classes in terms of equivalent C++ classes using MEX.
- Host: GitHub
- URL: https://github.com/mathworks/libmexclass
- Owner: mathworks
- License: bsd-3-clause
- Created: 2022-07-13T17:06:21.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2024-05-21T17:36:42.000Z (9 months ago)
- Last Synced: 2024-05-22T16:52:45.929Z (9 months ago)
- Topics: cpp, matlab, mex
- Language: C++
- Homepage:
- Size: 188 KB
- Stars: 4
- Watchers: 10
- Forks: 1
- Open Issues: 8
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Security: SECURITY.md
Awesome Lists containing this project
README
# libmexclass
## DISCLAIMERS
1. **NOTE**: The [MATLAB® Interface to C++](https://www.mathworks.com/help/matlab/build-matlab-interface-to-c-library.html) is the recommended way to interface with C++ classes in MATLAB.
2. **NOTE**: `libmexclass` is **UNDER ACTIVE DEVELOPMENT**. It is **NOT** recommended for production use.
## Overview
`libmexclass` is a MATLAB framework which enables users to implement the functionality of MATLAB classes in terms of equivalent C++ classes using [MEX](https://www.mathworks.com/help/matlab/call-mex-files-1.html).
For MATLAB® projects that are already using [MEX](https://www.mathworks.com/help/matlab/call-mex-files-1.html), `libmexclass` aims to provide an alternative for interfacing with C++ classes.
It is recommended to use `libmexclass` with CMake.
## Usage
### Technical Background
`libmexclass` enables client code to:
1. Implement MATLAB class methods in terms of equivalent C++ class methods using a MEX based proxying mechanism
2. Bound the lifetime of C++ objects to equivalent MATLAB objects`libmexclass` is heavily inspired by the [Proxy Design Pattern](https://en.wikipedia.org/wiki/Proxy_pattern). Using `libmexclass` involves connecting `mexclass.Proxy` subclasses in MATLAB with corresponding `mexclass::Proxy` subclasses in C++.
### Getting Started
To use `libmexclass` in a MATLAB project, several steps are required, which are enumerated below.
#### 1. Subclass `mexclass::ProxyFactory` in C++
Create a subclass of `mexclass::ProxyFactory` in C++ with the name `CustomProxyFactory`.
`mexclass::ProxyFactory` is a ["simple factory"](https://en.wikipedia.org/wiki/Factory_(object-oriented_programming)#Terminology). `CustomProxyFactory` is responsible for returning subclasses of `mexclass::Proxy` which wrap "raw" C++ objects and control access to their state.
##### Notes
1. Your subclass *MUST* be named `CustomProxyFactory`.
2. Your filenames *MUST* be named `CustomProxyFactory.hpp` and `CustomProxyFactory.cpp`.
2. `CustomProxyFactory.hpp` and `CustomProxyFactory.cpp` *MUST* be in the same directory.##### Examples
1. `example/CustomProxyFactory.hpp` and `example/CustomProxyFactory.cpp` provide an example of how to implement `CustomProxyFactory`.
#### 2. Subclass `mexclass.Proxy` in MATLAB
Create a subclass of `mexclass.Proxy` in MATLAB whose class name is **identical** to the string used in the `switch` statement inside of your `CustomProxyFactory` implementation.
##### Notes
1. If the names of your corresponding MATLAB and C++ `Proxy` subclasses don't match exactly, then `libmexclass` won't be able to connect them.
##### Examples
1. If you created a custom `mexclass::Proxy` subclass in C++ named `CustomProxy` and used the string `CustomProxy` in the `switch` statement inside of your `CustomProxyFactory` implementation, then the name of your `mexclass.Proxy` subclass in MATLAB *MUST* also be `CustomProxy`.
#### 3. Build and Install using CMake
To use `libmexclass` in a MATLAB project, use the [`ExternalProject_Add()`](https://cmake.org/cmake/help/latest/module/ExternalProject.html) CMake function.
```cmake
ExternalProject_Add(libmexclass
GIT_REPOSITORY https://github.com/mathworks/libmexclass
CMAKE_ARGS -D CUSTOM_PROXY_FACTORY_DIR=)
```In the CMake code snippet above, replace `` with the location of your implementation of `CustomProxyFactory` relative to the `CMakeLists.txt` file for your project.
## MATLAB Version Compatibility
`libmexclass` is compatible with [MATLAB R2022a](https://www.mathworks.com/products/new_products/latest_features.html) or newer.
## Contributing
We welcome external contributions! Feel free to open a pull request!
For more information, see [CONTRIBUTING.md](CONTRIBUTING.md).
Copyright © 2022, The MathWorks, Inc.