WIP Let the GMT/MEX toolbox be an optional supplement in the main GMT project

CMakeLists.txt

@@ -185,11 +185,25 @@ else (SUPPL_EXTRA_DIRS)
 	set (PROTO "none")
 endif (SUPPL_EXTRA_DIRS)
 
-if (GMT_INSTALL_MODULE_LINKS)
-	set (LINKS "yes")
-else (GMT_INSTALL_MODULE_LINKS)
-	set (LINKS "no")
-endif (GMT_INSTALL_MODULE_LINKS)
+if (SUPPL_EXTRA_DIRS)
+	set (PROTO ${SUPPL_EXTRA_DIRS})
+else (SUPPL_EXTRA_DIRS)
+	set (PROTO "none")
+endif (SUPPL_EXTRA_DIRS)
+
+if (GMT_BUILD_GMTMEX)
+	set (MATLAB_APP "$ENV{MATLAB}")
+	set (MATLAB_INC "${Matlab_INCLUDE_DIRS}")
+	set (MATLAB_LIB1 "${Matlab_MEX_LIBRARY}")
+	set (MATLAB_LIB2 "${Matlab_MX_LIBRARY}")
+	set (MATLAB_EXT "${Matlab_MEX_EXTENSION}")
+else (GMT_BUILD_GMTMEX)
+	set (MATLAB_APP "not used")
+	set (MATLAB_INC "not used")
+	set (MATLAB_LIB1 "not used")
+	set (MATLAB_LIB2 "not used")
+	set (MATLAB_EXT "not used")
+endif (GMT_BUILD_GMTMEX)
 
 # Configure header file to pass some of the CMake settings to the source code
 configure_file (src/config.h.in src/config.h)
@@ -243,6 +257,11 @@ message(
 	"*  Build GMT for developers   : ${DEVEL}\n"
 	"*  Build proto supplements    : ${PROTO}\n"
 	"*  Build module links         : ${LINKS}\n"
+	"*  MATLAB Application         : ${MATLAB_APP}\n"
+	"*  MATLAB include dir         : ${MATLAB_INC}\n"
+	"*  MATLAB MEX library         : ${MATLAB_LIB1}\n"
+	"*  MATLAB MX library          : ${MATLAB_LIB2}\n"
+	"*  MATLAB mex extension       : ${MATLAB_EXT}\n"
 	"*  Found Ghostscript (gs)     : ${GMT_CONFIG_GS_MESSAGE}\n"
 	"*  Found GraphicsMagick (gm)  : ${GMT_CONFIG_GM_MESSAGE}\n"
 	"*  Found ffmpeg               : ${GMT_CONFIG_FFMPEG_MESSAGE}\n"

admin/ConfigReleaseBuild.cmake

@@ -18,7 +18,6 @@ set (DCW_ROOT "$ENV{GMT_DCW_SOURCE}")
 #set (GMT_USE_THREADS TRUE)
 set (GMT_ENABLE_OPENMP TRUE)
 
-# recommended even for release build
 set (CMAKE_C_FLAGS "-Wall -Wdeclaration-after-statement ${CMAKE_C_FLAGS}")
 # extra warnings
 set (CMAKE_C_FLAGS "-Wextra ${CMAKE_C_FLAGS}")

cmake/ConfigUserAdvancedTemplate.cmake

@@ -57,6 +57,9 @@
 #set (GMT_EXCLUDE_BLAS TRUE)
 #set (GMT_EXCLUDE_ZLIB TRUE)
 
+# Include special gmtmex supplement for the GMT/MEX toolbox [which requires MATLAB]
+#set (GMT_BUILD_GMTMEX TRUE)
+
 # ============================================================================
 # Advanced configuration begins here.  Usually it is not necessary to edit any
 # settings below.  You should know what you are doing if you do though.  Note:

share/tools/CMakeLists.txt

@@ -25,11 +25,17 @@ install (PROGRAMS
 	gmt_links.sh
 	gmt_prepmex.sh
 	gmt_uninstall.sh
+	gmt_mexbuild.sh
 	ncdeflate
 	${CMAKE_CURRENT_BINARY_DIR}/gmt5syntax
 	DESTINATION ${GMT_DATADIR}/tools
 	COMPONENT Runtime)
 
+install (PROGRAMS
+	gmt_mexbuild.sh
+	DESTINATION ${GMT_BINDIR}
+	COMPONENT Runtime)
+
 if (NOT DEFINED BASH_COMPLETION_DIR)
 	set (BASH_COMPLETION_DIR etc/bash_completion.d)
 endif (NOT DEFINED BASH_COMPLETION_DIR)

share/tools/gmt_mexbuild.sh

@@ -0,0 +1,77 @@
+#!/usr/bin/env bash
+#
+# Compile and link the GMT/MEX toolbox with the user's (most recent) MATLAB version.
+# This step must be done by the user since we cannot distribute MATLAB, and the user
+# needs to have a MATLAB license.  The requirements to build the GMT/MEX toolbox are:
+#
+#  1. A recent MATLAB installation in /Applications
+#  2. A recent installation of Xcode command line tools (CLI)
+#------------------------------------------------------------------------------------
+
+# 0. Check if already installed
+if [ -f ${BUNDLE_RESOURCES}/bin/gmtmex.mexmaci64 ]; then
+	printf "gmt_mexbuild.sh: GMT/MEX toolbox already installed on this computer.\n" >&2
+	printf "gmt_mexbuild.sh: To reinstall you must first remove this file:\n${BUNDLE_RESOURCES}/bin/gmtmex.mexmaci64.\n" >&2
+	exit 1
+fi
+
+# 1. Determine a single, most recent Matlab version
+MATLAB_VERSION=$(ls /Applications | grep MATLAB | sort -r | head -1)
+if [ "X${MATLAB_VERSION}" = "X" ]; then
+	printf "gmt_mexbuild.sh: MATLAB not found in /Applications - exiting.\n" >&2
+	exit -1
+fi
+
+# 2. Determine that Xcode CLI has been installed
+if ! [ -x "$(command -v xcrun)" ]; then
+	echo 'gmt_mexbuild.sh: Error: Xcode CLI tools (xcrun) not found in your search PATH.' >&2
+	exit 1
+fi
+
+printf "\ngmt_mexbuild.sh: Found most recent MATLAB application: %s\n" ${MATLAB_VERSION} >&2
+printf "\ngmt_mexbuild.sh: Will build and place the GMT/MEX toolbox in:\n%s\n" ${BUNDLE_RESOURCES}/bin >&2
+# 3. If use does not have write permission, explain they must use sudo
+if [ ! -w ${BUNDLE_RESOURCES} ]; then
+	printf "You must have sudo privileges on this computer to complete this installation.\n\nContinue? (y/n) [y]:" >&2
+	read answer
+	if [ "X$answer" = "Xn" ]; then
+		exit 0
+	fi
+fi
+
+printf "\ngmt_mexbuild.sh: Working..." >&2
+# 4. Make a listing of all shared libraries but skip symbolic links
+mkdir -p /tmp/gmtmexinstall
+find ${BUNDLE_RESOURCES}/lib -name '*.dylib' > /tmp/gmtmexinstall/raw.lis
+find ${BUNDLE_RESOURCES}/lib -name '*.so'   >> /tmp/gmtmexinstall/raw.lis
+while read file; do
+	if [ ! -L $file ]; then	# Skipping symbolic links
+		echo $file >> /tmp/gmtmexinstall/lib.lis
+	fi
+done < /tmp/gmtmexinstall/raw.lis
+# 5. Make all shared libraries use rpath instead of executable path
+#    For each library, replace @executable_path/../lib/*.dylib with @rpath/lib*.dylib
+while read file; do
+	otool -L $file | grep '@executable_path' | tr '/' ' ' | awk '{printf "install_name_tool -change @executable_path/../lib/%s @rpath/%s %s\n", $4, $4, "'$file'"}' >> /tmp/gmtmexinstall/mexjob.sh
+done < /tmp/gmtmexinstall/lib.lis
+sh /tmp/gmtmexinstall/mexjob.sh
+
+# 6. Update the plugin to use rpath
+install_name_tool -add_rpath ${BUNDLE_RESOURCES}/lib ${BUNDLE_RESOURCES}/lib/gmt/plugins/supplements.so
+
+# 7. Update the gmt executable to use rpath also
+install_name_tool -add_rpath ${BUNDLE_RESOURCES}/lib ${BUNDLE_RESOURCES}/bin/gmt
+
+# 8. Build the gmtmex executable
+type=$(uname -m)
+xcrun clang -I${BUNDLE_RESOURCES}/include/gmt -I/Applications/${MATLAB_VERSION}/extern/include -m64 -fPIC -fno-strict-aliasing -std=c99 -DGMT_MATLAB -c ${BUNDLE_RESOURCES}/share/tools/gmtmex.c -o /tmp/gmtmexinstall/gmtmex.o
+xcrun clang -undefined error -arch ${type} -bundle /tmp/gmtmexinstall/gmtmex.o -L${BUNDLE_RESOURCES}/lib -lgmt -L/Applications/${MATLAB_VERSION}/bin/maci64 -lmx -lmex -o ${BUNDLE_RESOURCES}/bin/gmtmex.mexmaci64
+cp -f ${BUNDLE_RESOURCES}/share/tools/gmt.m ${BUNDLE_RESOURCES}/bin
+# 9. Update the gmtmex plugin to use rpath also
+version=$(gmt --version | awk -Fr '{print $1}')	# Skip trailing stuff like rc1
+install_name_tool -change @executable_path/../lib/libgmt.${version}.dylib @rpath/libgmt.${version}.dylib ${BUNDLE_RESOURCES}/bin/gmtmex.mexmaci64
+install_name_tool -add_rpath ${BUNDLE_RESOURCES}/lib ${BUNDLE_RESOURCES}/bin/gmtmex.mexmaci64
+# 10. Clean up and we are done
+rm -rf /tmp/gmtmexinstall
+printf "done\n" >&2
+printf "gmt_mexbuild.sh: You must add this path to your MATLAB path:\n%s\n" ${BUNDLE_RESOURCES}/bin >&2

src/CMakeLists.txt

@@ -590,6 +590,14 @@ endforeach (_gmt_prog)
 # Rename gmt target to prevent version clash
 set_target_properties (gmt PROPERTIES OUTPUT_NAME gmt${GMT_INSTALL_NAME_SUFFIX})
 
+if (GMT_BUILD_GMTMEX)
+	# If your Matlab version is younger than Cmake then you must add that version here
+	set (MATLAB_ADDITIONAL_VERSIONS
+		"R2021a=9.10")
+	find_package (Matlab)
+	add_subdirectory (gmtmex)
+endif (GMT_BUILD_GMTMEX)
+
 # psldemo
 add_executable (psldemo psldemo.h psldemo.c)
 target_link_libraries (psldemo pslib)
@@ -664,6 +672,12 @@ install (PROGRAMS gmt_shell_functions.sh
 	DESTINATION ${GMT_BINDIR}
 	COMPONENT Runtime)
 
+install (PROGRAMS
+	gmtmex/gmt.m
+	gmtmex/gmtmex.c
+	DESTINATION ${GMT_DATADIR}/tools
+	COMPONENT Runtime)
+
 if (WIN32)
 	install (PROGRAMS gmtswitch.bat
 		DESTINATION ${GMT_BINDIR}
@@ -875,7 +889,7 @@ if (BUILD_SUPPLEMENTS)
 			DESTINATION ${GMT_DOCDIR}/${GMT_SUPPL_LIB_NAME}/${_suppl_name}
 			COMPONENT Documentation)
 
-		# install example scriptss
+		# install example scripts
 		install (PROGRAMS ${_suppl_example_progs}
 			DESTINATION ${GMT_DOCDIR}/${GMT_SUPPL_LIB_NAME}/${_suppl_name}
 			COMPONENT Documentation)
@@ -889,7 +903,6 @@ if (BUILD_SUPPLEMENTS)
 	endforeach (_dir)
 endif (BUILD_SUPPLEMENTS)
 
-
 ##
 ## Print out CFLAGS
 ##

src/gmtmex/CMakeLists.txt

@@ -0,0 +1,45 @@
+#
+# Copyright (c) 1991-2024 by the GMT Team (https://www.generic-mapping-tools.org/team.html)
+# See LICENSE.TXT file for copying and redistribution conditions.
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published by
+# the Free Software Foundation; version 3 or any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# Contact info: www.generic-mapping-tools.org
+#-------------------------------------------------------------------------------
+##
+##	Settings for GMT MexFunction shared library
+##
+# Note: Only activated if GMT_BUILD_GMTMEX is set in ConfigUserAdvanced.cmake
+
+if (GMT_BUILD_GMTMEX)
+	# Add the flag to select Matlab vs Octave
+	add_definitions(-DGMT_MATLAB)
+	# Add the mexfunction as a shared library
+	add_library (GMTmexfunction SHARED gmtmex.c)
+	# Set the Matlab include file directory
+	target_include_directories (GMTmexfunction PUBLIC ${GMT_SOURCE_DIR}/src ${GMT_BINARY_DIR}/src ${Matlab_INCLUDE_DIRS})
+	# Link with the Matlab and mex libraries and gmt library
+	target_link_libraries (GMTmexfunction gmtlib ${Matlab_MX_LIBRARY} ${Matlab_MEX_LIBRARY})
+	# Set output properties of shared library
+	set_target_properties (GMTmexfunction
+		PROPERTIES
+		OUTPUT_NAME gmtmex
+		RUNTIME_OUTPUT_NAME gmtmex
+		SUFFIX ".${Matlab_MEX_EXTENSION}"
+		PREFIX "")
+	# Install gmt.m in the bin dir
+	install (PROGRAMS gmt.m
+		DESTINATION ${GMT_BINDIR}
+		COMPONENT Runtime)
+	# Install the gmtmex function in the bin dir instead of lib dir
+	install (PROGRAMS "${GMT_BINARY_DIR}/src/gmtmex/gmtmex.${Matlab_MEX_EXTENSION}"
+		DESTINATION ${GMT_BINDIR}
+		COMPONENT Runtime)
+endif (GMT_BUILD_GMTMEX)

src/gmtmex/README.gmtmex

@@ -0,0 +1,9 @@
+#
+Distributed under the GNU Lesser Public License; see file
+LICENSE.TXT in main GMT directory.
+
+GMT 5 Release introduced a full set of Matlab interface functions
+for all GMT modules.  GMT 6 continued this work, and GMT 6.5 made
+some internal changes, necessitating GMTMEX 2.0.0
+
+See documentation for usage.