Add Apple XCFramework artifact workflow

Author: tsvvladimir

.github/workflows/run_unix.yml

@@ -116,6 +116,53 @@ jobs:
         do
           BRAINFLOW_LIB_DIR=$GITHUB_WORKSPACE/installed/lib swift run "$example"
         done
+    - name: Build Apple XCFramework Artifacts
+      if: (matrix.os == 'macos-14')
+      run: |
+        $GITHUB_WORKSPACE/tools/apple/build_xcframeworks.sh \
+          --output $GITHUB_WORKSPACE/build/apple_xcframeworks
+      env:
+        BRAINFLOW_VERSION: ${{ steps.version.outputs.version }}
+    - name: Verify Apple XCFramework Artifacts
+      if: (matrix.os == 'macos-14')
+      run: |
+        $GITHUB_WORKSPACE/tools/apple/verify_xcframeworks.sh $GITHUB_WORKSPACE/build/apple_xcframeworks
+    - name: Build Generated Swift Binary Package MacOS
+      if: (matrix.os == 'macos-14')
+      run: |
+        cd $GITHUB_WORKSPACE/build/apple_xcframeworks/BrainFlowSwiftBinaryPackage
+        swift build
+    - name: Test Generated Swift Binary Package MacOS
+      if: (matrix.os == 'macos-14')
+      run: |
+        $GITHUB_WORKSPACE/tools/apple/test_swift_binary_package.sh $GITHUB_WORKSPACE/build/apple_xcframeworks
+    - name: Build iOS Demo With Generated XCFrameworks
+      if: (matrix.os == 'macos-14')
+      run: |
+        BRAINFLOW_APPLE_XCFRAMEWORKS_DIR=$GITHUB_WORKSPACE/build/apple_xcframeworks/XCFrameworks \
+        xcodebuild -quiet \
+          -project $GITHUB_WORKSPACE/swift_package/examples/apps/ios/BrainFlowiOSDemo/BrainFlowiOSDemo.xcodeproj \
+          -scheme BrainFlowiOSDemo \
+          -configuration Debug \
+          -destination 'generic/platform=iOS Simulator' \
+          -derivedDataPath $GITHUB_WORKSPACE/build/ios-demo-derived \
+          CODE_SIGNING_ALLOWED=NO \
+          build
+    - name: Package macOS Demo With Generated XCFrameworks
+      if: (matrix.os == 'macos-14')
+      run: |
+        BRAINFLOW_APPLE_XCFRAMEWORKS_DIR=$GITHUB_WORKSPACE/build/apple_xcframeworks/XCFrameworks \
+        $GITHUB_WORKSPACE/tools/apple/package_macos_demo_app.sh $GITHUB_WORKSPACE/build/apple_xcframeworks/BrainFlowMacDemo.app
+    - name: Upload Apple XCFramework Artifacts
+      if: (matrix.os == 'macos-14')
+      uses: actions/upload-artifact@v4
+      with:
+        name: brainflow-apple-xcframeworks
+        path: |
+          ${{ github.workspace }}/build/apple_xcframeworks/BrainFlowAppleXCFrameworks.zip
+          ${{ github.workspace }}/build/apple_xcframeworks/BrainFlowAppleXCFrameworks.zip.sha256
+          ${{ github.workspace }}/build/apple_xcframeworks/checksums.sha256
+          ${{ github.workspace }}/build/apple_xcframeworks/manifest.json
     - name: Compile BrainFlow Ubuntu
       if: (matrix.os == 'ubuntu-latest')
       run: |

.gitignore

@@ -53,6 +53,7 @@ BenchmarkDotNet.Artifacts/
 project.lock.json
 project.fragment.lock.json
 artifacts/
+swift_package/Artifacts/Apple/
 
 # StyleCop
 StyleCopReport.xml
@@ -374,6 +375,7 @@ src/ml/train/data/
 src/ml/train/data/*.onnx
 tools/brainflow-android.aar
 build_android_aar/
+build_apple/
 tools/simpleble-bridge.jar
 tools/simpleble-bridge-classes/
 tools/simpleble-bridge-sources.txt

AGENTS.md

@@ -0,0 +1,40 @@
+# Agent Notes
+
+## Apple XCFramework Artifacts
+
+Apple binary artifacts are generated build outputs. They contain framework-wrapped XCFrameworks
+for iOS device, iOS simulator, and macOS app integration, plus a generated
+`BrainFlowSwiftBinaryPackage` for app developers.
+
+Regenerate the artifacts from the repository root:
+
+```bash
+tools/apple/regenerate_artifacts.sh
+```
+
+Verify an existing artifact tree:
+
+```bash
+tools/apple/verify_xcframeworks.sh build/apple_xcframeworks
+```
+
+The regeneration script builds native BrainFlow Apple slices, packages the XCFrameworks, verifies
+the required core frameworks, and creates `BrainFlowAppleXCFrameworks.zip` plus checksum files.
+
+By default, `tools/apple/regenerate_artifacts.sh` and `tools/apple/build_xcframeworks.sh` write to
+`build/apple_xcframeworks`. Do not commit `build/`, `build_apple/`, `swift_package/Artifacts/Apple`,
+or local `installed/` outputs.
+
+The iOS demo and macOS packaging script default to `build/apple_xcframeworks/XCFrameworks`.
+CI may override artifact paths with
+`BRAINFLOW_APPLE_XCFRAMEWORKS_DIR`.
+
+When changing Apple artifact generation, regenerate locally, run verification, and let CI upload
+`BrainFlowAppleXCFrameworks.zip` plus `BrainFlowAppleXCFrameworks.zip.sha256`, `checksums.sha256`,
+and `manifest.json` as the distributable artifact set. Generated framework headers and binaries
+should come from the scripts, not from files copied into the repository.
+
+For a BrainFlow release or Apple-library refresh, build from the release commit/tag with
+`BRAINFLOW_VERSION` set, regenerate artifacts, verify the generated tree, smoke-test the generated
+Swift binary package, and validate the iOS/macOS sample apps against the regenerated XCFrameworks.
+Do not manually patch release frameworks after generation; update source and rerun the script.

CMakeLists.txt

@@ -28,6 +28,7 @@ option (BUILD_ONNX "BUILD_ONNX" OFF)
 option (BUILD_TESTS "BUILD_TESTS" OFF)
 option (BUILD_PERIPHERY "BUILD_PERIPHERY" OFF)
 option (BRAINFLOW_COPY_TO_PACKAGE_DIRS "Copy built artifacts into language package folders" ON)
+option (BRAINFLOW_APPLE_DYNAMIC_FRAMEWORKS "Build Apple iOS native libraries as dynamic libraries for framework/XCFramework packaging" OFF)
 
 set (BRAINFLOW_IOS OFF)
 if (CMAKE_SYSTEM_NAME STREQUAL "iOS")
@@ -38,6 +39,11 @@ set (BRAINFLOW_CORE_LIBRARY_TYPE SHARED)
 if (BRAINFLOW_IOS)
     set (BRAINFLOW_CORE_LIBRARY_TYPE STATIC)
 
+    if (BRAINFLOW_APPLE_DYNAMIC_FRAMEWORKS)
+        message (STATUS "Building iOS BrainFlow native libraries as dynamic libraries for XCFramework packaging.")
+        set (BRAINFLOW_CORE_LIBRARY_TYPE SHARED)
+    endif ()
+
     if (BRAINFLOW_COPY_TO_PACKAGE_DIRS)
         message (STATUS "Disabling BRAINFLOW_COPY_TO_PACKAGE_DIRS for iOS builds.")
         set (BRAINFLOW_COPY_TO_PACKAGE_DIRS OFF CACHE BOOL "Copy built artifacts into language package folders" FORCE)

docs/BuildBrainFlow.rst

@@ -167,14 +167,25 @@ Local build example:
 
 The Swift package intentionally does not vendor BrainFlow native binaries. Like source builds for other bindings, it dynamically loads native libraries built from this repository. The loader searches :code:`BRAINFLOW_LIB_DIR`, system library paths, :code:`installed/lib`, and app bundle resource/framework directories for :code:`libBoardController`, :code:`libDataHandler`, and :code:`libMLModule`.
 
+For production iOS and macOS applications, use Apple XCFramework artifacts and the generated Swift binary package. Regenerate Apple artifacts with:
+
+.. code-block:: bash
+
+    tools/apple/regenerate_artifacts.sh
+    tools/apple/verify_xcframeworks.sh build/apple_xcframeworks
+
+The default generated artifact directory is :code:`build/apple_xcframeworks`. It contains :code:`XCFrameworks`, :code:`BrainFlowSwiftBinaryPackage`, :code:`BrainFlowAppleXCFrameworks.zip`, and checksum files. These generated headers and binaries are release/CI artifacts, not source files committed to the repository.
+
+The generated :code:`BrainFlowSwiftBinaryPackage` contains the Swift API and binary targets for :code:`BoardController.xcframework`, :code:`DataHandler.xcframework`, and :code:`MLModule.xcframework`. Add this package to an app through Xcode or Swift Package Manager so embedded frameworks are handled by standard Apple build, embed, and signing flows.
+
 The macOS demo can be built with:
 
 .. code-block:: bash
 
     cd swift_package
     BRAINFLOW_LIB_DIR=../installed/lib swift run BrainFlowMacDemo
 
-iOS and Mac App Store sample source and release-preparation notes are available in :code:`swift_package/examples/apps` and :code:`swift_package/Docs/AppStoreReadiness.md`. iOS runtime support requires BrainFlow native libraries compiled for the target iOS architectures and embedded as signed app-bundle libraries or XCFrameworks.
+iOS and Mac App Store sample source and release-preparation notes are available in :code:`swift_package/examples/apps`, :code:`swift_package/Docs/AppleBinaryDistribution.md`, and :code:`swift_package/Docs/AppStoreReadiness.md`. App runtime support requires matching BrainFlow native frameworks embedded and signed inside the app bundle; App Store builds should not depend on :code:`BRAINFLOW_LIB_DIR` or local development directories.
 
 Docker Image
 --------------

src/utils/inc/runtime_dll_loader.h

@@ -5,6 +5,8 @@
 #include <windows.h>
 #else
 #include <dlfcn.h>
+#include <string>
+#include <vector>
 #endif
 
 
@@ -19,7 +21,8 @@ class DLLLoader
 public:
     DLLLoader (const char *dll_path)
     {
-        strcpy (this->dll_path, dll_path);
+        strncpy (this->dll_path, dll_path, sizeof (this->dll_path) - 1);
+        this->dll_path[sizeof (this->dll_path) - 1] = '\0';
         this->lib_instance = NULL;
     }
 
@@ -68,11 +71,15 @@ class DLLLoader
         {
             // RTLD_DEEPBIND will search for symbols in loaded lib first and after that in global
             // scope
-            lib_instance = dlopen (this->dll_path, RTLD_LAZY | RTLD_DEEPBIND);
-            if (!lib_instance)
+            for (const std::string &candidate : get_dlopen_candidates ())
             {
-                return false;
+                lib_instance = dlopen (candidate.c_str (), RTLD_LAZY | RTLD_DEEPBIND);
+                if (lib_instance)
+                {
+                    return true;
+                }
             }
+            return false;
         }
         return true;
     }
@@ -97,6 +104,115 @@ class DLLLoader
 #endif
 
 private:
+#ifndef _WIN32
+    std::vector<std::string> get_dlopen_candidates () const
+    {
+        std::vector<std::string> candidates;
+        append_unique (candidates, this->dll_path);
+
+#ifdef __APPLE__
+        std::string original_path = this->dll_path;
+        std::string directory = parent_directory (original_path);
+        std::string file_name = last_path_component (original_path);
+        std::string framework_name = apple_framework_name (file_name);
+
+        if (!framework_name.empty ())
+        {
+            append_unique (candidates, framework_name + ".framework/" + framework_name);
+            append_unique (candidates, "@rpath/" + framework_name + ".framework/" + framework_name);
+            if (!directory.empty ())
+            {
+                append_unique (
+                    candidates, directory + framework_name + ".framework/" + framework_name);
+                std::string framework_parent = parent_frameworks_directory (directory);
+                if (!framework_parent.empty ())
+                {
+                    append_unique (candidates,
+                        framework_parent + framework_name + ".framework/" + framework_name);
+                }
+            }
+        }
+#endif
+        return candidates;
+    }
+
+    static void append_unique (std::vector<std::string> &values, const std::string &value)
+    {
+        if (value.empty ())
+        {
+            return;
+        }
+        for (const std::string &existing : values)
+        {
+            if (existing == value)
+            {
+                return;
+            }
+        }
+        values.push_back (value);
+    }
+
+#ifdef __APPLE__
+    static std::string last_path_component (const std::string &path)
+    {
+        size_t slash = path.find_last_of ('/');
+        if (slash == std::string::npos)
+        {
+            return path;
+        }
+        return path.substr (slash + 1);
+    }
+
+    static std::string parent_directory (const std::string &path)
+    {
+        size_t slash = path.find_last_of ('/');
+        if (slash == std::string::npos)
+        {
+            return "";
+        }
+        return path.substr (0, slash + 1);
+    }
+
+    static std::string parent_frameworks_directory (const std::string &directory)
+    {
+        std::string normalized = directory;
+        if (!normalized.empty () && normalized[normalized.size () - 1] == '/')
+        {
+            normalized.resize (normalized.size () - 1);
+        }
+
+        size_t framework_suffix = normalized.rfind (".framework");
+        if (framework_suffix == std::string::npos)
+        {
+            return "";
+        }
+
+        size_t framework_dir_start = normalized.find_last_of ('/', framework_suffix);
+        if (framework_dir_start == std::string::npos)
+        {
+            return "";
+        }
+        return normalized.substr (0, framework_dir_start + 1);
+    }
+
+    static std::string apple_framework_name (const std::string &file_name)
+    {
+        std::string name = file_name;
+        const std::string dylib_suffix = ".dylib";
+        if (name.size () > dylib_suffix.size () &&
+            name.substr (name.size () - dylib_suffix.size ()) == dylib_suffix)
+        {
+            name.resize (name.size () - dylib_suffix.size ());
+        }
+        if (name.size () > 3 && name.substr (0, 3) == "lib")
+        {
+            name = name.substr (3);
+        }
+        return name;
+    }
+#endif
+#endif
+
     char dll_path[1024];
 #ifdef _WIN32
     HINSTANCE lib_instance;

swift_package/Docs/AppStoreReadiness.md

@@ -8,32 +8,42 @@ This checklist is intentionally separate from the sample source because final Ap
 - Replace placeholder bundle IDs.
 - Add production app icons and screenshots.
 - Keep the synthetic-board demo path available so App Review can exercise the app without external hardware.
-- Embed BrainFlow native libraries or XCFrameworks in the app bundle and sign them with the app.
+- Embed BrainFlow XCFramework products in the app bundle and sign them with the app.
+- Use the generated `BrainFlowSwiftBinaryPackage` for production app integration. Do not rely on `BRAINFLOW_LIB_DIR`, local `installed/lib` folders, or loose development dylibs in App Store builds.
 - Confirm final privacy answers reflect real-board connectivity, Bluetooth, networking, files, and any third-party native dependencies actually shipped.
 - Run an archive build and install it on a physical device or clean Mac before upload.
+- Verify the archive contains only device slices for iOS, with embedded framework install names in the form `@rpath/<Framework>.framework/<Framework>`.
 
 ## iOS
 
 - Use `examples/apps/ios/BrainFlowiOSDemo` as the Xcode app project.
-- Keep `swift_package` as the local package dependency.
-- Provide iOS-compatible BrainFlow native binaries. The current high-level Swift package compiles for iOS, but the app can only run BrainFlow calls when matching native libraries are embedded.
+- Use the generated Swift binary package or embed framework slices from `build/apple_xcframeworks/XCFrameworks`.
+- Provide iOS-compatible BrainFlow native binaries through XCFrameworks. The high-level Swift package compiles for iOS, but BrainFlow calls can only run when matching native frameworks are embedded and signed.
 - For Muse native BLE boards, build BrainFlow native libraries with BLE support enabled for the target platform and keep the Bluetooth privacy string in the app plist.
 - Keep permissions minimal. The synthetic-board demo needs no network or file permissions.
 - Test via TestFlight before App Store submission.
 
 ## macOS
 
-- Use `swift_package` product `BrainFlowMacDemo` for local development, or create an Xcode app target for App Store archiving.
+- Use `swift_package` product `BrainFlowMacDemo` for local development, or package it with `tools/apple/package_macos_demo_app.sh` for app-bundle smoke testing.
 - Add the files from `examples/apps/macos/BrainFlowMacDemo`.
 - Enable App Sandbox.
-- Embed and sign BrainFlow dylibs/XCFrameworks.
-- Verify dynamic loading works inside the archived app bundle, not only with `BRAINFLOW_LIB_DIR`.
+- Embed and sign BrainFlow XCFramework products.
+- Verify dynamic loading works inside the app bundle, not only with `BRAINFLOW_LIB_DIR`.
 
 ## Production Gate
 
 - Swift package builds.
 - Swift tests pass with native libraries present.
 - CLI smoke test succeeds with the synthetic board.
-- iOS and macOS app targets launch, handle missing native libraries gracefully, and run the synthetic-board workflow when libraries are embedded.
+- `tools/apple/build_xcframeworks.sh` and `tools/apple/verify_xcframeworks.sh` pass.
+- `tools/apple/regenerate_artifacts.sh` refreshes `build/apple_xcframeworks`, and `tools/apple/verify_xcframeworks.sh build/apple_xcframeworks` passes.
+- The Apple release artifact set includes `BrainFlowAppleXCFrameworks.zip`,
+  `BrainFlowAppleXCFrameworks.zip.sha256`, `checksums.sha256`, and `manifest.json` from the same
+  build.
+- `manifest.json` records the BrainFlow version, source revision, toolchain versions, deployment
+  targets, and optional native feature flags.
+- A clean app consumes `BrainFlowSwiftBinaryPackage` without building native BrainFlow locally.
+- iOS and macOS app targets launch, handle missing native frameworks gracefully, and run the synthetic-board workflow when frameworks are embedded.
 - Accessibility labels and dynamic text behavior are reviewed in the sample apps.
 - Crash logs are clean after repeated start, stop, read, and release cycles.