Fixed macOS installation bug, updated INSTALL.md

1 files changed, 33 insertions, 1 deletions

diff --git a/doc/dev notes.txt b/doc/dev notes.txt
index d825ee7..3aa2db5 100644
--- a/doc/dev notes.txt
+++ b/doc/dev notes.txt
@@ -76,7 +76,7 @@ the pad in analog mode you must:
    games) to increase timing accuracy.
  * If a digital pad response (type = 4) is received from a port that hasn't
    previously been flagged as digital-only, attempt to put the pad into config
-   mode using command 43h.
+   mode using command 43h *twice* (as the proper response is delayed).
    * If the pad doesn't recognize the config command, flag it as digital-only
      and treat all further digital pad responses from it as valid.
    * If the pad recognizes the command, it will reply by identifying as an
@@ -166,6 +166,38 @@ cache or something like that (?). The only workaround I know of is to use
 CPACK_PRE_BUILD_SCRIPTS to trigger a custom script that deletes anything other
 than the actual files to be packaged (see cpack/fakeroot_fix.cmake).
 
+* Project installation might fail on macOS (and possibly some Linux distros) if
+CMake attempts to set permissions on system directories such as /usr/local.
+This is usually caused by install() commands that copy files to the root
+installation directory rather than to a subfolder, like this:
+
+ install(
+   DIRECTORY   install_tree/
+   DESTINATION .
+   USE_SOURCE_PERMISSIONS
+ )
+
+If the USE_SOURCE_PERMISSIONS flag is specified CMake will attempt to set
+permissions on the DESTINATION folder, which in this case would be the root
+prefix (/usr/local by default on macOS), to match the source directory. This
+will however fail as macOS restricts top-level system directories from having
+their permissions changed. The simplest workaround is to avoid using
+"DESTINATION ." and install each subdirectory explicitly instead, like this:
+
+ foreach(
+   _dir IN ITEMS
+     ${CMAKE_INSTALL_BINDIR}
+     ${CMAKE_INSTALL_LIBDIR}
+     ${CMAKE_INSTALL_INCLUDEDIR}
+     ${CMAKE_INSTALL_DATADIR}
+ )
+   install(
+     DIRECTORY   install_tree/${_dir}/
+     DESTINATION ${_dir}
+     USE_SOURCE_PERMISSIONS
+   )
+ endforeach()
+
 * Depending on how you find external dependencies (find_package(), vcpkg,
 pkg-config...), CMake may end up outputting an executable that relies on a DLL
 installed system-wide. To correctly install the DLL alongside the executable