Improve SDL2 bundling and add SDL3 support for macOS

companion/src/CMakeLists.txt

@@ -570,12 +570,61 @@ elseif(APPLE)
   # Run macdeployqt
   install(SCRIPT ${qt_deploy_companion} COMPONENT Runtime)
 
-  # Bundle SDL2
+  # Bundle SDL2 (copy the real dylib; IMPORTED_RUNTIME_ARTIFACTS keeps
+  # Homebrew symlinks and breaks the app inside a .dmg). Homebrew's
+  # sdl2-compat also loads SDL3 from @loader_path/libSDL3.dylib at runtime.
   if(TARGET SDL2::SDL2)
-    install(IMPORTED_RUNTIME_ARTIFACTS SDL2::SDL2
-            FRAMEWORK DESTINATION "${companion_app_dir}/Contents/Frameworks"
-            LIBRARY   DESTINATION "${companion_app_dir}/Contents/Frameworks"
-            COMPONENT Runtime)
+    get_target_property(_sdl2_location SDL2::SDL2 IMPORTED_LOCATION)
+    if(NOT _sdl2_location)
+      get_target_property(_sdl2_location SDL2::SDL2 IMPORTED_LOCATION_RELEASE)
+    endif()
+    if(_sdl2_location)
+      get_filename_component(_sdl2_real "${_sdl2_location}" REALPATH)
+      get_filename_component(_sdl2_name "${_sdl2_location}" NAME)
+      install(FILES "${_sdl2_real}"
+              DESTINATION "${companion_app_dir}/Contents/Frameworks"
+              RENAME "${_sdl2_name}"
+              COMPONENT Runtime)
+
+      set(_sdl3_real "")
+      find_package(SDL3 CONFIG QUIET)
+      if(TARGET SDL3::SDL3-Shared)
+        get_target_property(_sdl3_location SDL3::SDL3-Shared IMPORTED_LOCATION)
+        if(_sdl3_location)
+          get_filename_component(_sdl3_real "${_sdl3_location}" REALPATH)
+        endif()
+      endif()
+      if(NOT _sdl3_real)
+        get_filename_component(_sdl2_libdir "${_sdl2_real}" DIRECTORY)
+        get_filename_component(_sdl2_root "${_sdl2_libdir}" DIRECTORY)
+        get_filename_component(_brew_prefix "${_sdl2_root}" DIRECTORY)
+        foreach(_candidate
+            "${_brew_prefix}/sdl3/lib/libSDL3.0.dylib"
+            "/opt/homebrew/opt/sdl3/lib/libSDL3.0.dylib"
+            "/usr/local/opt/sdl3/lib/libSDL3.0.dylib")
+          if(EXISTS "${_candidate}")
+            get_filename_component(_sdl3_real "${_candidate}" REALPATH)
+            break()
+          endif()
+        endforeach()
+      endif()
+      if(_sdl3_real)
+        install(FILES "${_sdl3_real}"
+                DESTINATION "${companion_app_dir}/Contents/Frameworks"
+                RENAME "libSDL3.dylib"
+                COMPONENT Runtime)
+      else()
+        message(WARNING "SDL3 not found; packaged Companion may crash if linked against sdl2-compat")
+      endif()
+
+      install(CODE "
+        set(_fw \"\${CMAKE_INSTALL_PREFIX}/${companion_app_dir}/Contents/Frameworks\")
+        execute_process(COMMAND install_name_tool -id \"@executable_path/../Frameworks/${_sdl2_name}\" \"\${_fw}/${_sdl2_name}\")
+        if(EXISTS \"\${_fw}/libSDL3.dylib\")
+          execute_process(COMMAND install_name_tool -id \"@executable_path/../Frameworks/libSDL3.dylib\" \"\${_fw}/libSDL3.dylib\")
+        endif()
+      " COMPONENT Runtime)
+    endif()
   endif()
 
   # Re-sign bundle after all contents are installed

docs/building/macos-sequoia.md

@@ -3,13 +3,16 @@
 # Install [Homebrew](https://brew.sh/)
 
 - Run command in `Terminal`:
+
 ```
 /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
 ```
+
 !!! tip
-    Installing Brew via the command above will automatically install the [Xcode Command Line Tools](https://mac.install.guide/commandlinetools/). If for some reason you need to do this manually, run `xcode-select —install` via the Terminal app.
+    Installing Brew via the command above will automatically install the [Xcode Command Line Tools](https://mac.install.guide/commandlinetools/). If for some reason you need to do this manually, run `xcode-select --install` via the Terminal app.
 
 # Install Qt 6
+
 !!! note
     If you only intend on building the firmware, and not `simu`, `companion` or `simulator`, this is not necessary, and you can skip to the next step.
 
@@ -18,6 +21,7 @@ brew install qt@6
 ```
 
 Once Qt has been installed, you should set a couple environment variables (please modify according to the real installation paths):
+
 ```
 export QTDIR=$(brew --prefix)/opt/qt@6
 export QT_PLUGIN_PATH=$QTDIR/plugins
@@ -29,19 +33,22 @@ Please note that `QT_PLUGIN_PATH` is required to be able to run Companion from y
 
 Download and install the ARM GCC toolchain [from here](https://developer.arm.com/downloads/-/arm-gnu-toolchain-downloads) (installs in `/Applications/ArmGNUToolchain/`):
 
-- For Intel Mac: https://developer.arm.com/-/media/Files/downloads/gnu/14.2.rel1/binrel/arm-gnu-toolchain-14.2.rel1-darwin-x86_64-arm-none-eabi.pkg
-- If Mac Silicon (i.e. M1-M5): https://developer.arm.com/-/media/Files/downloads/gnu/14.2.rel1/binrel/arm-gnu-toolchain-14.2.rel1-darwin-arm64-arm-none-eabi.pkg
+- Intel Mac: <https://developer.arm.com/-/media/Files/downloads/gnu/14.2.rel1/binrel/arm-gnu-toolchain-14.2.rel1-darwin-x86_64-arm-none-eabi.pkg>
+- Apple Silicon (M1–M5): <https://developer.arm.com/-/media/Files/downloads/gnu/14.2.rel1/binrel/arm-gnu-toolchain-14.2.rel1-darwin-arm64-arm-none-eabi.pkg>
 
-Please note that this installation takes care of allowing the downloaded binaries to be run and prevents them being quarantined. If you choose to install the `tar.xz` archive to another location, you will have to take care of that yourself (see https://disable-gatekeeper.github.io/ for more details).
+If you install the `.tar.xz` archive manually instead of the `.pkg`, you may need to remove the macOS quarantine flag yourself. See <https://disable-gatekeeper.github.io/> for details.
 
-# Install various dependencies
+# Other tools
 
-- With `brew` in a `Terminal`:
 ```
-brew install sdl cmake
+brew install sdl2 sdl3 cmake uv
 ```
 
+!!! note
+    Homebrew's `sdl2` package is [sdl2-compat](https://github.com/libsdl-org/sdl2-compat), which depends on **SDL3** at runtime. Both `sdl2` and `sdl3` must be installed before building Companion or a `.dmg`.
+
 If you plan to run the standalone simulator for debugging:
+
 ```
 brew install --cask quartz
 ```
@@ -61,55 +68,46 @@ cd edgetx
 
 # Install Python dependencies
 
-Since Python 3.11 enabled the "externally managed" flag, it is recommended that you use a virtual environment. [uv](https://docs.astral.sh/uv/getting-started/installation/) is one of the easiest tools to do and manage this, and can be installed with brew. It is recommended you create the virtual environment now rather than earlier in the process, as doing it now will create it in the edgetx directory.
+Since Python 3.11+, macOS uses an externally managed Python environment. Create a project virtual environment with [uv](https://docs.astral.sh/uv/getting-started/installation/):
 
-- Install UV:
-```
-brew install uv
-```
-
-- Create the virtual environment (and use specific version of python for this environment):
 ```
 uv venv --python 3.14
-```
-
-- Activate the virtual environment (you will need to run this whenever you want to compile in the future from a new terminal session):
-```
 source .venv/bin/activate
+uv pip install -r requirements.txt
 ```
 
-- Install the packages:
+
+Activate the virtual environment in every new terminal session before building:
+
 ```
-uv pip install Pillow clang lz4 jinja2
+source .venv/bin/activate
 ```
 
-# Compile EdgeTX
+# Configure the build
 
-- Create and enter build directory:
 ```
 mkdir -p build && cd build
 ```
 
-Configure build flags using `cmake` (in this case, for RadioMaster TX16S, [see here](https://github.com/EdgeTX/edgetx/blob/main/tools/build-common.sh) for other possible handset specific flags).
+Configure for RadioMaster TX16S ([other radio flags](https://github.com/EdgeTX/edgetx/blob/main/tools/build-common.sh)):
+
 ```
 cmake -DPCB=X10 -DPCBREV=TX16S \
    -DCMAKE_PREFIX_PATH=$QTDIR \
+   -DCMAKE_OSX_DEPLOYMENT_TARGET=14.0 \
    -DARM_TOOLCHAIN_DIR=/Applications/ArmGNUToolchain/14.2.Rel1/arm-none-eabi/bin/ ..
 ```
 
-!!! note
-    Please note that the variables `CMAKE_PREFIX_PATH`, `ARM_TOOLCHAIN_DIR` must be specified additionally to what is described in the other compilation HowTos:
+| Variable | Purpose |
+|----------|---------|
+| `CMAKE_PREFIX_PATH` | Path to your Qt installation (`$QTDIR`) |
+| `CMAKE_OSX_DEPLOYMENT_TARGET` | Minimum macOS version for Companion. Use `14.0` for Sonoma and later. If omitted, the compiler uses the current SDK minimum (for example macOS 26 only) |
+| `ARM_TOOLCHAIN_DIR` | Path to ARM GCC binaries. Must end with `/` |
 
-    - `CMAKE_PREFIX_PATH`: this must point to your Qt installation path.
-    - `ARM_TOOLCHAIN_DIR`: this must point to where ARM GCC has been installed (and MUST contain `/` at the end).
+## Build firmware
 
-Configure the compiler for firmware building (parallel limits the number of CPU cores used - you can increase this if your machine can handle more):
 ```
 cmake --build . --target arm-none-eabi-configure --parallel 4
-```
-
-Build the firmware!
-```
 cmake --build . --target firmware
 ```