Improve MATLAB bindings (SSMC pipeline, type minimization, allocator safety, tests)

.gitignore

@@ -4,7 +4,15 @@
 
 scripts
 venv
-build*
+build/
+build-*/
 compile_flags.txt
 ._*
 tensor_test_files
+
+# MATLAB/Octave MEX files
+*.mex
+*.mexa64
+*.mexw32
+*.mexw64
+*.mexmaci64

.pre-commit-config.yaml

@@ -8,6 +8,7 @@ repos:
   rev: v16.0.6
   hooks:
     - id: clang-format
+      exclude: '\.m$'
 
 - repo: https://github.com/pre-commit/pre-commit-hooks
   rev: v4.4.0

CMakeLists.txt

@@ -9,11 +9,18 @@ cmake_policy(SET CMP0079 NEW)
 
 set(CMAKE_C_STANDARD 11)
 set(CMAKE_CXX_STANDARD 20)
-set(CMAKE_C_FLAGS "-O3 -march=native")
+
+# FIXME: -march=native is not portable
+# set(CMAKE_C_FLAGS "-O3 -march=native")
+set(CMAKE_C_FLAGS "-g ")
+set(CMAKE_CXX_FLAGS "-g ")
+
+option(ENABLE_SANITIZERS "Enable Clang sanitizers" OFF)
 
 include(GNUInstallDirs)
 
 add_library(binsparse STATIC)
+add_library(binsparse_dynamic SHARED)
 
 add_subdirectory(include)
 add_subdirectory(src)
@@ -24,8 +31,15 @@ add_subdirectory(src)
 
 find_package(HDF5 REQUIRED COMPONENTS C)
 target_link_libraries(binsparse PUBLIC ${HDF5_C_LIBRARIES})
+target_link_libraries(binsparse_dynamic PUBLIC ${HDF5_C_LIBRARIES})
 
 include(FetchContent)
+
+# Force cJSON to build as static library for MEX compatibility
+set(BUILD_SHARED_LIBS_BACKUP ${BUILD_SHARED_LIBS})
+set(BUILD_SHARED_LIBS OFF CACHE INTERNAL "Build cJSON as static library")
+set(ENABLE_CJSON_TEST OFF CACHE INTERNAL "Disable cJSON tests")
+
 FetchContent_Declare(
   cJSON
   # GIT_REPOSITORY https://github.com/DaveGamble/cJSON.git
@@ -34,8 +48,12 @@ FetchContent_Declare(
 )
 FetchContent_MakeAvailable(cJSON)
 
+# Restore original BUILD_SHARED_LIBS setting
+set(BUILD_SHARED_LIBS ${BUILD_SHARED_LIBS_BACKUP})
+
 configure_file(${cJSON_SOURCE_DIR}/cJSON.h ${CMAKE_BINARY_DIR}/include/cJSON/cJSON.h)
-target_link_libraries(${PROJECT_NAME} PUBLIC cjson)
+target_link_libraries(binsparse PRIVATE cjson)
+target_link_libraries(binsparse_dynamic PRIVATE cjson)
 
 # Set up include directories properly for both build and install
 target_include_directories(${PROJECT_NAME}
@@ -46,13 +64,27 @@ target_include_directories(${PROJECT_NAME}
         $<INSTALL_INTERFACE:${CMAKE_INSTALL_INCLUDEDIR}>
         ${HDF5_INCLUDE_DIRS})
 
+target_include_directories(binsparse_dynamic
+    PUBLIC
+        $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}>
+        $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
+        $<BUILD_INTERFACE:${CMAKE_BINARY_DIR}/include>
+        $<INSTALL_INTERFACE:${CMAKE_INSTALL_INCLUDEDIR}>
+        ${HDF5_INCLUDE_DIRS})
+
 # Installation rules - these are always needed when the library is built
 install(TARGETS binsparse
         EXPORT binsparse-targets
         LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
         ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR}
         RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}
         INCLUDES DESTINATION ${CMAKE_INSTALL_INCLUDEDIR})
+install(TARGETS binsparse_dynamic
+        EXPORT binsparse-targets_dynamic
+        LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
+        ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR}
+        RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}
+        INCLUDES DESTINATION ${CMAKE_INSTALL_INCLUDEDIR})
 
 # Install headers
 install(DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/include/binsparse
@@ -65,6 +97,10 @@ install(EXPORT binsparse-targets
         FILE binsparse-targets.cmake
         NAMESPACE binsparse::
         DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/binsparse)
+install(EXPORT binsparse-targets_dynamic
+        FILE binsparse-targets_dynamic.cmake
+        NAMESPACE binsparse::
+        DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/binsparse)
 
 # Create and install package config files
 include(CMakePackageConfigHelpers)
@@ -84,6 +120,14 @@ install(FILES
     DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/binsparse)
 
 if(CMAKE_PROJECT_NAME STREQUAL PROJECT_NAME)
+  if (ENABLE_SANITIZERS)
+      set(SANITIZER_FLAGS "-fsanitize=address,undefined")
+      target_compile_options(binsparse INTERFACE ${SANITIZER_FLAGS} -g -O1 -fno-omit-frame-pointer)
+      target_link_options(binsparse INTERFACE ${SANITIZER_FLAGS})
+      target_compile_options(binsparse_dynamic INTERFACE ${SANITIZER_FLAGS} -g -O1 -fno-omit-frame-pointer)
+      target_link_options(binsparse_dynamic INTERFACE ${SANITIZER_FLAGS})
+  endif()
+
   add_subdirectory(examples)
   add_subdirectory(test)
 endif()

README.md

@@ -18,7 +18,8 @@ This library provides a C interface for reading and writing binsparse matrices.
 #include <binsparse/binsparse.h>
 
 int main(int argc, char** argv) {
-  bsp_matrix_t mat = bsp_read_matrix("chesapeake.bsp.hdf5");
+  bsp_matrix_t mat;
+  bsp_read_matrix(&mat, "chesapeake.bsp.hdf5", NULL);
 
   if (mat.format == BSP_COO) {
     float* values = mat.values.data;
@@ -33,6 +34,7 @@ int main(int argc, char** argv) {
            bsp_get_matrix_format_string(mat.format));
   }
 
+  bsp_destroy_matrix_t(&mat);
   return 0;
 }
 ```

bindings/matlab/Contents.m

@@ -0,0 +1,35 @@
+% Binsparse MATLAB/Octave bindings
+%
+% Core functions (MEX, with .m help stubs):
+%   binsparse_read                  - read a matrix from a Binsparse HDF5 file
+%   binsparse_write                 - write a matrix to a Binsparse HDF5 file
+%   binsparse_from_ssmc             - convert SSMC A+Zeros to a Binsparse matrix struct
+%   binsparse_minimize_types        - minimize value/index types in a Binsparse struct
+%   binsparse_write_string_dataset  - write an HDF5 UTF-8 string dataset
+%   write_binsparse_from_matlab     - write an SSMC Problem struct (delegates to generate_bsp_from_ssmc)
+%
+% MATLAB helpers:
+%   generate_bsp_from_ssmc          - write an SSMC Problem to a Binsparse file
+%   convert_to_problem_struct       - convert a Binsparse problem to an SSMC Problem
+%   bsp_matrix_create               - create a Binsparse matrix struct
+%   bsp_matrix_info                 - display information about a Binsparse matrix struct
+%
+% Build scripts:
+%   build_matlab_bindings           - build all MEX functions with MATLAB's mex
+%   build_octave_bindings           - build all MEX functions with Octave's mkoctfile
+%   compile_octave.sh               - build the Octave MEX functions from the shell
+%
+% Tests:
+%   test_binsparse_read             - error-handling tests for binsparse_read
+%   test_binsparse_write            - write and round-trip tests for binsparse_write
+%   test_binsparse_from_ssmc        - basic test for binsparse_from_ssmc
+%   test_binsparse_minimize_roundtrip - SSMC conversion + type minimization test
+%   test_bsp_matrix_struct          - tests for the Binsparse matrix struct helpers
+%   test_convert_to_problem_struct  - tests for Binsparse Problem conversion
+%   test_generate_bsp_from_ssmc     - end-to-end test for generate_bsp_from_ssmc
+%   test_write_binsparse_from_matlab - end-to-end test for the SSMC writer MEX
+%   test_binsparse_roundtrip_dir    - round-trip every .h5 file in a directory
+
+% SPDX-FileCopyrightText: 2024 Binsparse Developers
+%
+% SPDX-License-Identifier: BSD-3-Clause