Add comment explaining the symbolic link issue

Author: sgilmore10

dev/tasks/matlab/rename_macos_arm64_dylibs.sh

@@ -19,6 +19,59 @@
 
 set -ex
 
+# Issue Number 1:
+#
+# MATLAB's programmatic packaging interface does not properly handle symbolic link files. Instead
+# of adding a symbolic link entry to the archive, the interface follows the link to
+# copy the link's target file contents AND uses the target file name as the entry name.
+#
+# Example:
+# 
+# Suppose you had this folder structure:   
+#    
+#        $ tree /tmp/example
+#        /tmp/example
+#        ├── regular_file.txt
+#        └── symbolic_link -> regular_file.txt
+#  
+# In MATLAB, if the symbolic link and its target file are in the same folder, then the symbolic link
+# is not included as one of the files to be packaged:
+#
+#       >> opts = matlab.addons.toolbox.ToolboxOptions("/tmp/example", "dummy-identifier");
+#       >> opts.ToolboxFiles
+#
+#       ans = 
+#
+#            "/private/tmp/example/regular_file.txt"
+#
+# This is a bug. 
+#
+# Why is this a problem? On macOS, building the Arrow C++ bindings generates the following files:
+#     
+#        $ tree arrow/matlab/install/arrow_matlab/+libmexclass/+proxy/ 
+#        . 
+#        ├── libarrow.1700.0.0.dylib
+#        ├── libarrow.1700.dylib -> libarrow.1700.0.0.dylib
+#        └── libarrow.dylib -> libarrow.1700.dylib
+#
+# When arrow/matlab/install/arrow_matlab is packaged into an MLTBX file, only the "reguar file"
+# libarrow.1700.0.0.dylib is included. This is problematic because building the MATLAB creates
+# a shared library named libarrowproxy.dylib, which links against libarrow.1700.dylib 
+# - not libarrow.1700.0.0.dylib:
+#
+#        $ otool -L libarrowproxy.dylib | grep -E '@rpath/libarrow\.'
+#	            @rpath/libarrow.1700.dylib
+#
+# To avoid a run-time linker issue, we need to update the name of libarrowproxy.dylib's 
+# dependent shared library from @rpath/libarrow.1700.dylib to @rpath/libarrow.1700.0.0.dylib.
+#
+# ==============================================================================================
+#
+# Issue Number 2:
+#
+#
+
+
 if [ "$#" -ne 1 ]; then
   echo "Usage: $0 <dylib-dir>"
   exit
@@ -43,21 +96,30 @@ NEW_LIBARROW_MAJOR_MINOR_PATCH_DYLIB="libarrow_arm64.${MAJOR_MINOR_PATCH_VERSION
 NEW_LIBARROWPROXY_DYLIB="libarrowproxy_arm64.dylib"
 NEW_LIBMEXCLASS_DYLIB="libmexclass_arm64.dylib"
 
+# Delete the symbolic links. These files are not included in the packaged MLTBX file. 
 rm ${ORIG_LIBARROW_MAJOR_DYLIB}
 rm ${ORIG_LIBARROW_DYLIB}
 
+# Rename libarrow.*.*.*.dylib to libarrow_arm64.*.*.*.dylib (e.g. libarrow.1700.0.0.dylib -> libarrow_arm64.1700.0.0.dylib)
 mv ${ORIG_LIBARROW_MAJOR_MINOR_PATCH_DYLIB} ${NEW_LIBARROW_MAJOR_MINOR_PATCH_DYLIB}
+# Rename libarrowproxy.dylib to libarrowproxy_arm64.dylib
 mv ${ORIG_LIBARROWPROXY_DYLIB} ${NEW_LIBARROWPROXY_DYLIB}
+# Rename libmexclass.dylib to libmexclass_arm64.dylib
 mv ${ORIG_LIBMEXCLASS_DYLIB} ${NEW_LIBMEXCLASS_DYLIB}
 
+# Update the identificaton names of the renamed dynamic libraries
 install_name_tool -id @rpath/${NEW_LIBMEXCLASS_DYLIB} ${NEW_LIBMEXCLASS_DYLIB}
 install_name_tool -id @rpath/${NEW_LIBARROWPROXY_DYLIB} ${NEW_LIBARROWPROXY_DYLIB}
 install_name_tool -id @rpath/${NEW_LIBARROW_MAJOR_MINOR_PATCH_DYLIB} ${NEW_LIBARROW_MAJOR_MINOR_PATCH_DYLIB}
 
+# Change install name of dependent shared library libarrow.*.*.*.dylib to libarrow_arm64.*.*.*.dylib in libarrowproxy_arm64.dylib
 install_name_tool -change @rpath/${ORIG_LIBARROW_MAJOR_DYLIB} @rpath/${NEW_LIBARROW_MAJOR_MINOR_PATCH_DYLIB} ${NEW_LIBARROWPROXY_DYLIB}
+# Change install name of dependent shared library libmexclass.dylib to libmexclass_arm64.*.*.*.dylib libarrowproxy_arm64.dylib
 install_name_tool -change @rpath/${ORIG_LIBMEXCLASS_DYLIB} @rpath/${NEW_LIBMEXCLASS_DYLIB} ${NEW_LIBARROWPROXY_DYLIB}
 
+# Change install name of dependent shared library libmexclass.dylib to libmexclass_arm64.dylib in gateway.mexmaca64
 install_name_tool -change @rpath/${ORIG_LIBMEXCLASS_DYLIB} @rpath/${NEW_LIBMEXCLASS_DYLIB} ${MEX_GATEWAY}
+# Change install name of dependent shared library libarrowproxy.dylib to libarrowproxy_arm64.dylib in gateway.mexmaca64
 install_name_tool -change @rpath/${ORIG_LIBARROWPROXY_DYLIB} @rpath/${NEW_LIBARROWPROXY_DYLIB} ${MEX_GATEWAY}
 
 cd ${ORIG_DIR}