Squashed 'wrap/' changes from b28b3570d..b0eb968f2

b0eb968f2 Completely handle Matlab wrapping (#34)
4ad71812a Merge pull request #33 from borglab/fix/script-destination
0c832eed7 reverted from TYPE to DESTINATION for wrapper scripts
10e1efd6f Merge pull request #32 from ayushbaid/feature/pickle
55d5d7fbe ignoring pickle in matlab wrap
8d70c7fe2 adding newlines
dee8aaee3 adding markers for pickling
46fc45d82 separating out the marker for pickle
d37b8a972 Merge pull request #31 from ayushbaid/feature/pickle
efd4a0fb4 removing tab
42fd231f3 adding newline for test compare
0aa316150 removing extra brackets
7fe1d7d0f adding pickle code to expected file
9c3ab7a8b fixing string format for new classname
2f89284e8 moving pickle support with the serialization code
5a8abc916 adding pickle support for select classes using serialization

git-subtree-dir: wrap
git-subtree-split: b0eb968f29a2261700361599cab2823221dd0f9d

CMakeLists.txt

@@ -21,20 +21,27 @@ else()
   set(SCRIPT_INSTALL_DIR "${CMAKE_INSTALL_PREFIX}/lib/cmake")
 endif()
 
-# Install scripts to the standard CMake script directory.
-install(FILES cmake/gtwrapConfig.cmake cmake/PybindWrap.cmake
-              cmake/GtwrapUtils.cmake
+# Install CMake scripts to the standard CMake script directory.
+install(FILES cmake/gtwrapConfig.cmake cmake/MatlabWrap.cmake
+              cmake/PybindWrap.cmake cmake/GtwrapUtils.cmake
         DESTINATION "${SCRIPT_INSTALL_DIR}/gtwrap")
 
+# Needed for the CMAKE_INSTALL_X variables used below.
 include(GNUInstallDirs)
-# Install the gtwrap python package as a directory so it can be found for
-# wrapping.
+
+# Install the gtwrap python package as a directory so it can be found  by CMake
+# for wrapping.
 install(DIRECTORY gtwrap DESTINATION "${CMAKE_INSTALL_DATADIR}/gtwrap")
 
 # Install wrapping scripts as binaries to `CMAKE_INSTALL_PREFIX/bin` so they can
-# be invoked for wrapping.
-install(PROGRAMS scripts/pybind_wrap.py scripts/matlab_wrap.py TYPE BIN)
+# be invoked for wrapping. We use DESTINATION (instead of TYPE) so we can
+# support older CMake versions.
+install(PROGRAMS scripts/pybind_wrap.py scripts/matlab_wrap.py
+        DESTINATION ${CMAKE_INSTALL_BINDIR})
 
-# Install pybind11 directory to `CMAKE_INSTALL_PREFIX/lib/pybind11` This will
-# allow the gtwrapConfig.cmake file to load it later.
+# Install pybind11 directory to `CMAKE_INSTALL_PREFIX/lib/gtwrap/pybind11` This
+# will allow the gtwrapConfig.cmake file to load it later.
 install(DIRECTORY pybind11 DESTINATION "${CMAKE_INSTALL_LIBDIR}/gtwrap")
+
+# Install the matlab.h file to `CMAKE_INSTALL_PREFIX/lib/gtwrap/matlab.h`.
+install(FILES matlab.h DESTINATION "${CMAKE_INSTALL_INCLUDEDIR}/gtwrap")

README.md

@@ -1,4 +1,3 @@
-
 # WRAP
 
 The wrap library wraps the GTSAM library into a Python library or MATLAB toolbox.
@@ -43,36 +42,64 @@ pybind_wrap(${PROJECT_NAME}_py # target
 
 For more information, please follow our [tutorial](https://github.com/borglab/gtsam-project-python).
 
-## GTSAM Python wrapper
+## Python Wrapper
 
 **WARNING: On macOS, you have to statically build GTSAM to use the wrapper.**
 
 1. Set `GTSAM_BUILD_PYTHON=ON` while configuring the build with `cmake`.
 1. What you can do in the `build` folder:
-    1. Just run python then import GTSAM and play around:
-        ```
-
-        import gtsam
-        gtsam.__dir__()
-        ```
-
-    1. Run the unittests:
-        ```
-        python -m unittest discover
-        ```
-    1. Edit the unittests in `python/gtsam/*.py` and simply rerun the test.
-    They were symlinked to `<build_folder>/gtsam/*.py` to facilitate fast development.
-        ```
-        python -m unittest gtsam/tests/test_Pose3.py
-        ```
-        - NOTE: You might need to re-run `cmake ..` if files are deleted or added.
+
+   1. Just run python then import GTSAM and play around:
+
+      ```
+      import gtsam
+      gtsam.__dir__()
+      ```
+
+   1. Run the unittests:
+      ```
+      python -m unittest discover
+      ```
+   1. Edit the unittests in `python/gtsam/*.py` and simply rerun the test.
+      They were symlinked to `<build_folder>/gtsam/*.py` to facilitate fast development.
+      `python -m unittest gtsam/tests/test_Pose3.py` - NOTE: You might need to re-run `cmake ..` if files are deleted or added.
+
 1. Do `make install` and `cd <gtsam_install_folder>/python`. Here, you can:
-    1. Run the unittests:
-        ```
-        python setup.py test
-        ```
-    2. Install `gtsam` to your current Python environment.
-        ```
-        python setup.py install
-        ```
-        - NOTE: It's a good idea to create a virtual environment otherwise it will be installed in your system Python's site-packages.
+   1. Run the unittests:
+      ```
+      python setup.py test
+      ```
+   2. Install `gtsam` to your current Python environment.
+      ```
+      python setup.py install
+      ```
+      - NOTE: It's a good idea to create a virtual environment otherwise it will be installed in your system Python's site-packages.
+
+## Matlab Wrapper
+
+In the CMake, simply include the `MatlabWrap.cmake` file.
+
+```cmake
+include(MatlabWrap)
+```
+
+This cmake file defines functions for generating MATLAB wrappers.
+
+- `wrap_and_install_library(interfaceHeader linkLibraries extraIncludeDirs extraMexFlags)` Generates wrap code and compiles the wrapper.
+
+Usage example:
+
+    `wrap_and_install_library("lba.h" "" "" "")`
+
+Arguments:
+
+- `interfaceHeader`: The relative or absolute path to the wrapper interface definition file.
+- `linkLibraries`: Any _additional_ libraries to link. Your project library
+  (e.g. `lba`), libraries it depends on, and any necessary
+  MATLAB libraries will be linked automatically. So normally,
+  leave this empty.
+- `extraIncludeDirs`: Any _additional_ include paths required by dependent
+  libraries that have not already been added by
+  include_directories. Again, normally, leave this empty.
+- `extraMexFlags`: Any _additional_ flags to pass to the compiler when building
+  the wrap code. Normally, leave this empty.