Add preliminary support for Xcode and building universal dylib

Initial support for Apple Frameworks

Move scripts into subfolder

Remove set(CMAKE_MACOSX_RPATH ON) because that is already the default value.

Fix framework install directory when not installing to the system.

Author: cboulay

.github/workflows/cppcmake.yml

@@ -39,18 +39,26 @@ jobs:
         - {name: "ubuntu-24.04", os: "ubuntu-24.04",   cmake_extra: "-DLSL_BUNDLED_PUGIXML=OFF" }
         - {name: "windows-x64",  os: "windows-latest", cmake_extra: "-T v142,host=x86"}
         - {name: "windows-32",   os: "windows-latest", cmake_extra: "-T v142,host=x86 -A Win32"}
-        - {name: "macOS-latest", os: "macOS-latest"}
+        - {name: "macOS-latest", os: "macOS-latest", cmake_extra: "-DCMAKE_OSX_DEPLOYMENT_TARGET=10.15 -DCMAKE_OSX_ARCHITECTURES=x86_64;arm64 DCMAKE_SYSTEM_NAME=Darwin -DLSL_FRAMEWORK=ON -G Xcode" }
 
     # runs all steps in the container configured in config.docker or as subprocesses when empty
     container: ${{ matrix.config.docker }}
     steps:
     - uses: actions/checkout@v4
+
     - name: set up build environment in container
+      if: ${{ matrix.config.docker }}
       run: |
          set -x
          apt update
          apt install -y --no-install-recommends g++ git ninja-build file dpkg-dev lsb-release sudo curl cmake libpugixml-dev
-      if: ${{ matrix.config.docker }}
+
+    - name: Setup Xcode
+      if: ${{ matrix.config.name == 'macOS-latest' }}
+      uses: maxim-lobanov/setup-xcode@v1
+      with:
+        xcode-version: 'latest-stable'
+
     - name: Configure CMake
       run: |
            if [[ "${{ matrix.config.name }}" = ubuntu-2* ]]; then
@@ -68,8 +76,12 @@ jobs:
                 ${{ matrix.config.cmake_extra }} \
                 ${{ github.event.inputs.cmakeextra }}
             echo ${PWD}
+
     - name: make
-      run: cmake --build build --target install --config Release -j
+      run: cmake --build build --config Release -j
+
+    - name: make install
+      run: cmake --build build --config Release --target install
 
     - name: test install using examples
       run: |
@@ -101,6 +113,7 @@ jobs:
            fi
            cmake -E remove_directory package/_CPack_Packages
            cp testing/lslcfgs/default.cfg .
+
     - name: upload install dir
       uses: actions/upload-artifact@master
       with:
@@ -112,6 +125,7 @@ jobs:
       with:
         name: pkg-${{ matrix.config.name }}
         path: package
+
     - name: print network config
       run: |
            which ifconfig && ifconfig
@@ -133,12 +147,14 @@ jobs:
         install/bin/lsl_test_internal --order rand --wait-for-keypress never --durations yes || test ! -z "${{ matrix.config.docker }}"
         install/bin/lsl_test_exported --order rand --wait-for-keypress never --durations yes
       timeout-minutes: 10
+
     - name: upload dump
       if: failure()
       uses: actions/upload-artifact@master
       with:
         name: dumps-${{ matrix.config.name }}
         path: dumps
+
     - name: upload to release page
       if: github.event_name == 'release'
       env:

cmake/CompilerSettings.cmake

@@ -30,6 +30,4 @@ endif()
 # Platform-specific settings
 if(WIN32)
     add_definitions(-D_CRT_SECURE_NO_WARNINGS)
-elseif(APPLE)
-    set(CMAKE_MACOSX_RPATH ON)
 endif()

cmake/CreateFrameworkSymlinks.cmake.in

@@ -0,0 +1,39 @@
+# This script is executed at install time.
+# It was generated from CreateFrameworkSymlinks.cmake.in
+
+set(FRAMEWORK_DIR "${CMAKE_INSTALL_PREFIX}/@CMAKE_INSTALL_FRAMEWORK_DIR@/lsl.framework")
+
+message(STATUS "Executing configured symlink script.")
+message(STATUS "  -- Target Directory='${FRAMEWORK_DIR}'")
+
+if(NOT EXISTS "${FRAMEWORK_DIR}")
+    message(FATAL_ERROR "Framework version directory does not exist. Cannot create symlink.")
+endif()
+
+message(STATUS "  -- Framework version directory exists. Creating symlink...")
+
+execute_process(
+    COMMAND ln -sf include Headers
+    WORKING_DIRECTORY "${FRAMEWORK_DIR}/Versions/A"
+    RESULT_VARIABLE result
+    ERROR_VARIABLE error
+)
+if(NOT result EQUAL 0)
+    message(FATAL_ERROR "Failed to create Headers->include symlink: ${error}")
+endif()
+
+execute_process(
+        COMMAND ln -sf Versions/Current/Headers
+        WORKING_DIRECTORY "${FRAMEWORK_DIR}"
+        RESULT_VARIABLE result
+        ERROR_VARIABLE error
+)
+if(NOT result EQUAL 0)
+    message(FATAL_ERROR "Failed to create <root>Headers->Versions/Current/Headers symlink: ${error}")
+endif()
+
+if(NOT result EQUAL 0)
+    message(FATAL_ERROR "Failed to create Headers symlink in framework: ${error}")
+endif()
+
+message(STATUS "  -- Framework symlink created successfully.")

cmake/Installation.cmake

@@ -4,10 +4,27 @@ include(CMakePackageConfigHelpers)
 # Paths
 if(LSL_UNIXFOLDERS)
     include(GNUInstallDirs)
+    if(CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT)
+        set(FRAMEWORK_DIR_DEFAULT Library/Frameworks)
+    else()
+        set(FRAMEWORK_DIR_DEFAULT Frameworks)
+    endif()
+    set(CMAKE_INSTALL_FRAMEWORK_DIR ${FRAMEWORK_DIR_DEFAULT} CACHE PATH "Install directory for frameworks on macOS")
 else()
     set(CMAKE_INSTALL_BINDIR LSL)
     set(CMAKE_INSTALL_LIBDIR LSL)
     set(CMAKE_INSTALL_INCLUDEDIR LSL/include)
+    set(CMAKE_INSTALL_FRAMEWORK_DIR LSL/Frameworks CACHE PATH "Install directory for frameworks on macOS")
+endif()
+
+# For Apple frameworks, we need to next the install directories within the framework.
+if(APPLE AND LSL_FRAMEWORK)
+    # For the includes, this is insufficient. Later we will create more accessible symlinks.
+    set(LSL_INSTALL_INCLUDEDIR ${CMAKE_INSTALL_FRAMEWORK_DIR}/lsl.framework/Versions/A/include)
+    set(LSL_CONFIG_INSTALL_DIR ${CMAKE_INSTALL_FRAMEWORK_DIR}/lsl.framework/Resources/CMake)
+else()
+    set(LSL_INSTALL_INCLUDEDIR ${CMAKE_INSTALL_INCLUDEDIR})
+    set(LSL_CONFIG_INSTALL_DIR ${CMAKE_INSTALL_LIBDIR}/cmake/lsl)
 endif()
 
 # Generate a version file for the package.
@@ -27,20 +44,21 @@ install(TARGETS ${LSLTargets}
     RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}
     LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
     ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR}
-    FILE_SET HEADERS DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}
+    FRAMEWORK DESTINATION ${CMAKE_INSTALL_FRAMEWORK_DIR}
+    FILE_SET HEADERS DESTINATION ${LSL_INSTALL_INCLUDEDIR}
 )
 
 # Generate the LSLConfig.cmake file and mark it for installation
 install(EXPORT LSLTargets
         FILE LSLConfig.cmake
         COMPONENT liblsl
         NAMESPACE "LSL::"
-        DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/LSL
+        DESTINATION ${LSL_CONFIG_INSTALL_DIR}
 )
 # A common alternative to installing the exported package config file is to generate it from a template.
 #configure_package_config_file(${CMAKE_CURRENT_SOURCE_DIR}/lslConfig.cmake.in
 #        ${CMAKE_CURRENT_BINARY_DIR}/LSLConfig.cmake
-#        INSTALL_DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/lsl)
+#        INSTALL_DESTINATION ${LSL_CONFIG_INSTALL_DIR})
 # If we use this method, then we need a corresponding install(FILES ...) command to install the generated file.
 
 # Install the version file and the helper CMake script.
@@ -49,5 +67,17 @@ install(
         cmake/LSLCMake.cmake
         ${CMAKE_CURRENT_BINARY_DIR}/LSLConfigVersion.cmake
     COMPONENT liblsl
-    DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/LSL
+    DESTINATION ${LSL_CONFIG_INSTALL_DIR}
 )
+
+if(APPLE AND LSL_FRAMEWORK)
+    # Create symlinks for the framework. The variables we want to use to identify the symlink locations
+    #  are not available at install time. Instead, we create a script during configuration time that will
+    #  be run at install time to create the symlinks.
+    configure_file(
+            ${CMAKE_CURRENT_SOURCE_DIR}/cmake/CreateFrameworkSymlinks.cmake.in
+            ${CMAKE_CURRENT_BINARY_DIR}/CreateFrameworkSymlinks.cmake
+            @ONLY
+    )
+    install(SCRIPT ${CMAKE_CURRENT_BINARY_DIR}/CreateFrameworkSymlinks.cmake COMPONENT liblsl)
+endif()

cmake/ProjectOptions.cmake

@@ -2,6 +2,7 @@
 option(LSL_DEBUGLOG "Enable (lots of) additional debug messages" OFF)
 option(LSL_UNIXFOLDERS "Use the unix folder layout for install targets" ON)
 option(LSL_BUILD_STATIC "Build LSL as a static library." OFF)
+option(LSL_FRAMEWORK "Build LSL as an Apple Framework (Mac only)" ON)
 option(LSL_LEGACY_CPP_ABI "Build legacy C++ ABI into lsl-static" OFF)
 option(LSL_OPTIMIZATIONS "Enable some more compiler optimizations" ON)
 option(LSL_BUNDLED_BOOST "Use the bundled Boost by default" ON)

cmake/TargetLib.cmake

@@ -47,3 +47,34 @@ target_compile_definitions(lsl
         # don't use #pragma(lib) in MSVC builds. TODO: Maybe this can be inherited from lslobj or removed on lslobj?
         $<$<CXX_COMPILER_ID:MSVC>:LSLNOAUTOLINK>
 )
+
+# Extra configuration for Apple targets -- set xcode attributes
+if(APPLE)
+    set_target_properties(lsl PROPERTIES
+            XCODE_ATTRIBUTE_PRODUCT_BUNDLE_IDENTIFIER "org.labstreaminglayer.liblsl"
+    )
+    # If environment variables are set for Apple Development Team and Code Sign Identity then add these to the target
+    # -> if `-G Xcode` generator is used then Xcode will use these variables to sign the framework.
+    # Note, however, that it is likely that the build products will be modified post-build, invalidating the signature,
+    #  so post-hoc signing will be required. Nevertheless, this is useful for initial signing and normal Xcode workflow.
+    if(DEFINED ENV{APPLE_DEVELOPMENT_TEAM} AND DEFINED ENV{APPLE_CODE_SIGN_IDENTITY_APP})
+        set_target_properties(lsl PROPERTIES
+                XCODE_ATTRIBUTE_CODE_SIGN_IDENTITY $ENV{APPLE_CODE_SIGN_IDENTITY_APP}
+                XCODE_ATTRIBUTE_DEVELOPMENT_TEAM $ENV{APPLE_DEVELOPMENT_TEAM}
+                XCODE_ATTRIBUTE_CODE_SIGN_STYLE "Manual"
+                XCODE_ATTRIBUTE_DEPLOYMENT_POSTPROCESSING YES   # this is needed for strip symbols
+                XCODE_ATTRIBUTE_OTHER_CODE_SIGN_FLAGS "--deep"
+        )
+    endif()
+    # Configure Apple Framework
+    if(LSL_FRAMEWORK)
+        set_target_properties(lsl PROPERTIES
+                FRAMEWORK TRUE
+                FRAMEWORK_VERSION A
+                MACOSX_FRAMEWORK_IDENTIFIER "org.labstreaminglayer.liblsl"
+                MACOSX_FRAMEWORK_SHORT_VERSION_STRING "${liblsl_VERSION_MAJOR}.${liblsl_VERSION_MINOR}"
+                MACOSX_FRAMEWORK_BUNDLE_VERSION ${PROJECT_VERSION}
+                XCODE_ATTRIBUTE_CODE_SIGN_ENTITLEMENTS "${CMAKE_CURRENT_SOURCE_DIR}/lsl.entitlements"
+        )
+    endif(LSL_FRAMEWORK)
+endif(APPLE)

examples/CMakeLists.txt

@@ -42,7 +42,7 @@ function(addlslexample name extension)
     # However, this is not necessary for the examples, as they are not intended to be relocated.
 #    if(APPLE)
 #        set_target_properties(${name} PROPERTIES
-#                INSTALL_RPATH "@loader_path;@loader_path/../lib"
+#                INSTALL_RPATH "@loader_path;@loader_path/../lib;@loader_path/../Frameworks"
 #        )
 #    elseif(UNIX)
 #        set_target_properties(${name} PROPERTIES

lsl.entitlements

@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <!-- Required for allowing outgoing network connections (TCP and UDP). -->
+  <key>com.apple.security.network.client</key>
+  <true/>
+
+  <!-- Required for allowing your framework to listen for incoming connections. -->
+  <key>com.apple.security.network.server</key>
+  <true/>
+
+  <!-- Specifically required for sending and receiving UDP multicast traffic used in stream advertising. -->
+  <key>com.apple.security.network.multicast</key>
+  <true/>
+</dict>
+</plist>

standalone_compilation_linux.sh renamed to scripts/standalone_compilation_linux.sh

@@ -6,6 +6,7 @@
 # (pip install cmake) or as binary download from cmake.org
 
 set -e -x
+cd "$(dirname "$0")/.."
 # Try to read LSLGITREVISION from git if the variable isn't set
 echo ${LSLGITREVISION:="$(git describe --tags HEAD)"}
 ${CXX:-g++} -fPIC -fvisibility=hidden -O2 ${CFLAGS} ${CXXFLAGS} -Ilslboost \

update_lslboost.sh renamed to scripts/update_lslboost.sh

@@ -1,6 +1,8 @@
 # the absolute path to the extracted boost source archive (https://www.boost.org/users/download/)
 set -e
 set -x
+cd "$(dirname "$0")/.."
+
 BOOSTPATH=/tmp/boost_1_84_0
 TMPPATH=/tmp/lslboost