From 017d748b7ead83b18c01c042edaa3c61a6f06fb2 Mon Sep 17 00:00:00 2001 From: Sergey Yugoman Date: Mon, 13 Jul 2026 04:03:10 +0300 Subject: [PATCH 1/8] fix(cmake): improve SDL2 bundling and add SDL3 support for macOS --- docs/building/macos-sequoia.md | 62 ++++++++++++++++------------------ 1 file changed, 30 insertions(+), 32 deletions(-) diff --git a/docs/building/macos-sequoia.md b/docs/building/macos-sequoia.md index a62c752dbd2..439ec0596ef 100644 --- a/docs/building/macos-sequoia.md +++ b/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: +- Apple Silicon (M1–M5): -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 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 ``` From b27b32ce7ac4c2d14006db220cb92f8bced2c747 Mon Sep 17 00:00:00 2001 From: Sergey Yugoman Date: Mon, 13 Jul 2026 04:03:23 +0300 Subject: [PATCH 2/8] fix(cmake): enhance SDL2 bundling and add SDL3 support for macOS --- companion/src/CMakeLists.txt | 59 +++++++++++++++++++++++++++++++++--- 1 file changed, 54 insertions(+), 5 deletions(-) diff --git a/companion/src/CMakeLists.txt b/companion/src/CMakeLists.txt index 7225914a789..22db04fefa8 100644 --- a/companion/src/CMakeLists.txt +++ b/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 From 7b0d78912a6db3009ea199c29a55824eac52d068 Mon Sep 17 00:00:00 2001 From: Sergey Yugoman Date: Mon, 13 Jul 2026 04:28:49 +0300 Subject: [PATCH 3/8] fix(cmake): improve error handling for install_name_tool commands on macOS --- companion/src/CMakeLists.txt | 18 ++++++++++++++++-- 1 file changed, 16 insertions(+), 2 deletions(-) diff --git a/companion/src/CMakeLists.txt b/companion/src/CMakeLists.txt index 22db04fefa8..4468f8fae13 100644 --- a/companion/src/CMakeLists.txt +++ b/companion/src/CMakeLists.txt @@ -619,9 +619,23 @@ elseif(APPLE) 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}\") + execute_process( + COMMAND install_name_tool -id \"@executable_path/../Frameworks/${_sdl2_name}\" \"\${_fw}/${_sdl2_name}\" + RESULT_VARIABLE _sdl2_id_result + ERROR_VARIABLE _sdl2_id_error + ) + if(NOT _sdl2_id_result EQUAL 0) + message(FATAL_ERROR \"install_name_tool failed for ${_sdl2_name}: \${_sdl2_id_error}\") + endif() if(EXISTS \"\${_fw}/libSDL3.dylib\") - execute_process(COMMAND install_name_tool -id \"@executable_path/../Frameworks/libSDL3.dylib\" \"\${_fw}/libSDL3.dylib\") + execute_process( + COMMAND install_name_tool -id \"@executable_path/../Frameworks/libSDL3.dylib\" \"\${_fw}/libSDL3.dylib\" + RESULT_VARIABLE _sdl3_id_result + ERROR_VARIABLE _sdl3_id_error + ) + if(NOT _sdl3_id_result EQUAL 0) + message(FATAL_ERROR \"install_name_tool failed for libSDL3.dylib: \${_sdl3_id_error}\") + endif() endif() " COMPONENT Runtime) endif() From b9713ed54ddaf6a2a2859e818810cf1c3c382339 Mon Sep 17 00:00:00 2001 From: Sergey Yugoman Date: Mon, 13 Jul 2026 05:25:33 +0300 Subject: [PATCH 4/8] fix(cmake): enhance SDL3 detection and improve library search paths --- companion/src/CMakeLists.txt | 47 ++++++++++++++++++++++++++---------- 1 file changed, 34 insertions(+), 13 deletions(-) diff --git a/companion/src/CMakeLists.txt b/companion/src/CMakeLists.txt index 4468f8fae13..ae0916ba665 100644 --- a/companion/src/CMakeLists.txt +++ b/companion/src/CMakeLists.txt @@ -588,25 +588,46 @@ elseif(APPLE) set(_sdl3_real "") find_package(SDL3 CONFIG QUIET) - if(TARGET SDL3::SDL3-Shared) - get_target_property(_sdl3_location SDL3::SDL3-Shared IMPORTED_LOCATION) + if(TARGET SDL3::SDL3-shared) + get_target_property(_sdl3_location SDL3::SDL3-shared IMPORTED_LOCATION_RELEASE) + if(NOT _sdl3_location) + get_target_property(_sdl3_location SDL3::SDL3-shared IMPORTED_LOCATION) + endif() 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() + set(_sdl3_hints "") + if(DEFINED ENV{HOMEBREW_PREFIX}) + list(APPEND _sdl3_hints + "$ENV{HOMEBREW_PREFIX}/opt/sdl3/lib" + "$ENV{HOMEBREW_PREFIX}/lib") + endif() + find_program(_brew_EXECUTABLE brew) + if(_brew_EXECUTABLE) + execute_process( + COMMAND "${_brew_EXECUTABLE}" --prefix sdl3 + OUTPUT_VARIABLE _brew_sdl3_prefix + OUTPUT_STRIP_TRAILING_WHITESPACE + ERROR_QUIET + RESULT_VARIABLE _brew_sdl3_result + ) + if(_brew_sdl3_result EQUAL 0 AND _brew_sdl3_prefix) + list(APPEND _sdl3_hints "${_brew_sdl3_prefix}/lib") endif() - endforeach() + endif() + find_library(_sdl3_library + NAMES SDL3.0 SDL3 + HINTS ${_sdl3_hints} + NO_DEFAULT_PATH + ) + if(NOT _sdl3_library) + find_library(_sdl3_library NAMES SDL3.0 SDL3) + endif() + if(_sdl3_library) + get_filename_component(_sdl3_real "${_sdl3_library}" REALPATH) + endif() endif() if(_sdl3_real) install(FILES "${_sdl3_real}" From 891dc20c60c322644d32e9c65beff94c7edcfb1f Mon Sep 17 00:00:00 2001 From: Sergey Yugoman Date: Mon, 13 Jul 2026 05:25:40 +0300 Subject: [PATCH 5/8] docs(macos-sequoia): add build instructions for Companion and packaging steps --- docs/building/macos-sequoia.md | 55 ++++++++++++++++++++++++++++++++++ 1 file changed, 55 insertions(+) diff --git a/docs/building/macos-sequoia.md b/docs/building/macos-sequoia.md index 439ec0596ef..faf07675e56 100644 --- a/docs/building/macos-sequoia.md +++ b/docs/building/macos-sequoia.md @@ -111,6 +111,61 @@ cmake --build . --target arm-none-eabi-configure --parallel 4 cmake --build . --target firmware ``` +The firmware binary is written to `build/arm-none-eabi/firmware.bin`. + +## Build Companion + +Firmware and Companion are separate targets. Companion requires Qt, SDL2, and SDL3 (see above). + +From the `build` directory: + +``` +source ../.venv/bin/activate +export QTDIR=$(brew --prefix)/opt/qt@6 +export QT_PLUGIN_PATH=$QTDIR/plugins + +cmake --build . --target native-configure --parallel 4 +cmake --build . --target wasi-module --parallel 4 +mkdir -p native/plugins +cp wasm/edgetx-*-simulator.wasm native/plugins/ +cmake --build . --target companion --parallel 4 +``` + +The application bundle is created at `build/native/EdgeTX Companion 3.0.app` (the version number matches your EdgeTX release; check with `ls native/*.app`). + +## Run Companion from the build directory + +``` +export QT_PLUGIN_PATH=$(brew --prefix)/opt/qt@6/plugins +open "native/EdgeTX Companion 3.0.app" +``` + +For the radio simulator to work when running from the build tree, copy the WASM module into the bundle: + +``` +cp wasm/edgetx-*-simulator.wasm "native/EdgeTX Companion 3.0.app/Contents/MacOS/" +``` + +## Build a distributable `.dmg` + +The `package` target lives in the `native` build tree, **not** in the top-level `build` directory. + +``` +mkdir -p native/plugins +cp wasm/edgetx-*-simulator.wasm native/plugins/ 2>/dev/null || true +cmake --build native --target package +``` + +The `.dmg` is written to `build/native/edgetx-companion-.dmg` (for example `edgetx-companion-3.0.0.dmg`). + +Open it and drag **EdgeTX Companion** into `/Applications`: + +``` +open native/edgetx-companion-3.0.0.dmg +``` + +The packaging step bundles Qt, SDL2, and SDL3 into the `.app` automatically. + # Troubleshooting ## Notes on compiling simulator plug-ins From 6186df5e615ab152ad6139a8d52b9bb4e4d7dd3d Mon Sep 17 00:00:00 2001 From: Sergey Yugoman Date: Mon, 13 Jul 2026 05:33:20 +0300 Subject: [PATCH 6/8] docs(macos-sequoia): update code blocks for consistency and clarity --- docs/building/macos-sequoia.md | 46 +++++++++++++++++----------------- 1 file changed, 23 insertions(+), 23 deletions(-) diff --git a/docs/building/macos-sequoia.md b/docs/building/macos-sequoia.md index faf07675e56..46af7e9bf44 100644 --- a/docs/building/macos-sequoia.md +++ b/docs/building/macos-sequoia.md @@ -4,7 +4,7 @@ - Run command in `Terminal`: -``` +```bash /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" ``` @@ -16,13 +16,13 @@ !!! 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. -``` +```bash brew install qt@6 ``` Once Qt has been installed, you should set a couple environment variables (please modify according to the real installation paths): -``` +```bash export QTDIR=$(brew --prefix)/opt/qt@6 export QT_PLUGIN_PATH=$QTDIR/plugins ``` @@ -40,7 +40,7 @@ If you install the `.tar.xz` archive manually instead of the `.pkg`, you may nee # Other tools -``` +```bash brew install sdl2 sdl3 cmake uv ``` @@ -49,20 +49,20 @@ brew install sdl2 sdl3 cmake uv If you plan to run the standalone simulator for debugging: -``` +```bash brew install --cask quartz ``` - # Download EdgeTX code +-Checkout code -- Checkout code -``` +```bash git clone --recursive https://github.com/EdgeTX/edgetx.git ``` -- Switch into the source directory: -``` +-Switch into the source directory: + +```bash cd edgetx ``` @@ -70,28 +70,27 @@ cd edgetx 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/): -``` +```bash uv venv --python 3.14 source .venv/bin/activate uv pip install -r requirements.txt ``` - Activate the virtual environment in every new terminal session before building: -``` +```bash source .venv/bin/activate ``` # Configure the build -``` +```bash mkdir -p build && cd build ``` Configure for RadioMaster TX16S ([other radio flags](https://github.com/EdgeTX/edgetx/blob/main/tools/build-common.sh)): -``` +```bash cmake -DPCB=X10 -DPCBREV=TX16S \ -DCMAKE_PREFIX_PATH=$QTDIR \ -DCMAKE_OSX_DEPLOYMENT_TARGET=14.0 \ @@ -106,7 +105,7 @@ cmake -DPCB=X10 -DPCBREV=TX16S \ ## Build firmware -``` +```bash cmake --build . --target arm-none-eabi-configure --parallel 4 cmake --build . --target firmware ``` @@ -119,7 +118,7 @@ Firmware and Companion are separate targets. Companion requires Qt, SDL2, and SD From the `build` directory: -``` +```bash source ../.venv/bin/activate export QTDIR=$(brew --prefix)/opt/qt@6 export QT_PLUGIN_PATH=$QTDIR/plugins @@ -135,14 +134,14 @@ The application bundle is created at `build/native/EdgeTX Companion 3.0.app` (th ## Run Companion from the build directory -``` +```bash export QT_PLUGIN_PATH=$(brew --prefix)/opt/qt@6/plugins open "native/EdgeTX Companion 3.0.app" ``` For the radio simulator to work when running from the build tree, copy the WASM module into the bundle: -``` +```bash cp wasm/edgetx-*-simulator.wasm "native/EdgeTX Companion 3.0.app/Contents/MacOS/" ``` @@ -150,7 +149,7 @@ cp wasm/edgetx-*-simulator.wasm "native/EdgeTX Companion 3.0.app/Contents/MacOS/ The `package` target lives in the `native` build tree, **not** in the top-level `build` directory. -``` +```bash mkdir -p native/plugins cp wasm/edgetx-*-simulator.wasm native/plugins/ 2>/dev/null || true cmake --build native --target package @@ -160,7 +159,7 @@ The `.dmg` is written to `build/native/edgetx-companion-.dmg` (for exam Open it and drag **EdgeTX Companion** into `/Applications`: -``` +```bash open native/edgetx-companion-3.0.0.dmg ``` @@ -172,7 +171,7 @@ The packaging step bundles Qt, SDL2, and SDL3 into the `.app` automatically. When compiling simulator plug-ins (using `cmake --build . --target libsimulator` with the target properly configured), the product of this compilation will be a `.dylib` stored in your build directory. If you want the Companion or Simulator apps to be able to use it, you will need to copy it manually into the respective directories. Here is how it should look with a couple of plug-ins copied: -``` +```bash % ls -l companion.app/Contents/MacOS/ total 411976 -rwxr-xr-x 1 etx staff 27908864 Jan 7 11:48 companion @@ -193,7 +192,8 @@ total 392616 ## Notes on possible error while trying to run build-companion.sh If you encounter this error: -``` + +```bash CPack: - Install project: EdgeTX [] CMake Error at /opt/homebrew/Cellar/cmake/3.27.7/share/cmake/Modules/BundleUtilities.cmake:458 (message): otool -l failed: 1 From e82f6910f992165673e12e30880d1bb686f9a948 Mon Sep 17 00:00:00 2001 From: Peter Feerick <5500713+pfeerick@users.noreply.github.com> Date: Wed, 12 Aug 2026 09:24:27 +1000 Subject: [PATCH 7/8] fix(cmake): bundle upstream SDL2.framework, not just the Homebrew dylib The previous fix only handled Homebrew's sdl2-compat dylib (copy the real file, bundle its dlopen'd SDL3 shim alongside). It dropped the framework branch entirely, which silently broke CI: setup-sdl2.sh installs the genuine upstream SDL2.framework, whose IMPORTED_LOCATION points inside a .framework bundle and has no SDL3 dlopen dependency at all. Flat-copying that path as a single file would have discarded the framework structure. Restore the framework case as its own branch using the original IMPORTED_RUNTIME_ARTIFACTS install (unchanged from what CI has shipped all along), gated on the resolved SDL2 location matching *.framework. Also warn instead of silently no-op'ing when SDL2::SDL2 has no IMPORTED_LOCATION at all. Ignore stray .dmg build artifacts. --- .gitignore | 1 + companion/src/CMakeLists.txt | 15 ++++++++++++++- 2 files changed, 15 insertions(+), 1 deletion(-) diff --git a/.gitignore b/.gitignore index 2def5be3217..10a10093bfe 100644 --- a/.gitignore +++ b/.gitignore @@ -26,4 +26,5 @@ _wasi_sdk_fetch /site/ output/ +*.dmg .devcontainer/devcontainer-lock.json diff --git a/companion/src/CMakeLists.txt b/companion/src/CMakeLists.txt index ae0916ba665..744ecd0eeb9 100644 --- a/companion/src/CMakeLists.txt +++ b/companion/src/CMakeLists.txt @@ -578,7 +578,18 @@ elseif(APPLE) if(NOT _sdl2_location) get_target_property(_sdl2_location SDL2::SDL2 IMPORTED_LOCATION_RELEASE) endif() - if(_sdl2_location) + if(_sdl2_location AND _sdl2_location MATCHES "\\.framework(/|$)") + # Genuine upstream SDL2.framework (CI's setup-sdl2.sh, or a manual framework + # install): no SDL3 dlopen shim to worry about, and IMPORTED_RUNTIME_ARTIFACTS + # copies frameworks correctly — it's only the Homebrew dylib case below whose + # symlinks it mangles. This is what CI has shipped all along. + message(STATUS "Bundling SDL2 framework: ${_sdl2_location}") + install(IMPORTED_RUNTIME_ARTIFACTS SDL2::SDL2 + FRAMEWORK DESTINATION "${companion_app_dir}/Contents/Frameworks" + LIBRARY DESTINATION "${companion_app_dir}/Contents/Frameworks" + COMPONENT Runtime) + elseif(_sdl2_location) + message(STATUS "Bundling SDL2 library: ${_sdl2_location}") get_filename_component(_sdl2_real "${_sdl2_location}" REALPATH) get_filename_component(_sdl2_name "${_sdl2_location}" NAME) install(FILES "${_sdl2_real}" @@ -659,6 +670,8 @@ elseif(APPLE) endif() endif() " COMPONENT Runtime) + else() + message(WARNING "SDL2::SDL2 has no IMPORTED_LOCATION; SDL2 will not be bundled") endif() endif() From 30bc04866b041063b7c69a262eaa15e9b86445f1 Mon Sep 17 00:00:00 2001 From: Peter Feerick <5500713+pfeerick@users.noreply.github.com> Date: Wed, 12 Aug 2026 09:24:35 +1000 Subject: [PATCH 8/8] docs(macos-sequoia): fix broken list items and reduce path duplication - Restore the "- " markers on the checkout/cd steps, lost in a previous edit, so they render as list items instead of plain paragraphs. - Correct the CMAKE_OSX_DEPLOYMENT_TARGET description: omitting the flag means no -mmacosx-version-min is passed at all, not "current SDK minimum" as previously stated. Reconcile the doc's 14.0 local-dev default against CI's 11.0. - Replace the hardcoded "EdgeTX Companion 3.0.app" / dmg filename (repeated four times, and drifts with VERSION_FAMILY) with an inline native/*.app / native/edgetx-companion-*.dmg glob at each use site, so the commands stay directly readable without an intermediate variable. - Fix the xquartz cask name (was "quartz"). --- docs/building/macos-sequoia.md | 21 +++++++++++---------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/docs/building/macos-sequoia.md b/docs/building/macos-sequoia.md index 46af7e9bf44..e7bc231abd4 100644 --- a/docs/building/macos-sequoia.md +++ b/docs/building/macos-sequoia.md @@ -50,17 +50,18 @@ brew install sdl2 sdl3 cmake uv If you plan to run the standalone simulator for debugging: ```bash -brew install --cask quartz +brew install --cask xquartz ``` # Download EdgeTX code --Checkout code + +- Checkout code ```bash git clone --recursive https://github.com/EdgeTX/edgetx.git ``` --Switch into the source directory: +- Switch into the source directory: ```bash cd edgetx @@ -100,7 +101,7 @@ cmake -DPCB=X10 -DPCBREV=TX16S \ | 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) | +| `CMAKE_OSX_DEPLOYMENT_TARGET` | Minimum macOS version for Companion. `14.0` (Sonoma) is a convenient local-dev default; release builds (CI) target `11.0` for broader compatibility — pass `-DCMAKE_OSX_DEPLOYMENT_TARGET=11.0` if you want a build matching what CI ships. If omitted entirely, no `-mmacosx-version-min` flag is passed and clang targets whatever OS version your Mac is running | | `ARM_TOOLCHAIN_DIR` | Path to ARM GCC binaries. Must end with `/` | ## Build firmware @@ -130,19 +131,19 @@ cp wasm/edgetx-*-simulator.wasm native/plugins/ cmake --build . --target companion --parallel 4 ``` -The application bundle is created at `build/native/EdgeTX Companion 3.0.app` (the version number matches your EdgeTX release; check with `ls native/*.app`). +The application bundle is created at `build/native/EdgeTX Companion 3.0.app` (the version number matches your EdgeTX release). ## Run Companion from the build directory ```bash export QT_PLUGIN_PATH=$(brew --prefix)/opt/qt@6/plugins -open "native/EdgeTX Companion 3.0.app" +open native/*.app ``` For the radio simulator to work when running from the build tree, copy the WASM module into the bundle: ```bash -cp wasm/edgetx-*-simulator.wasm "native/EdgeTX Companion 3.0.app/Contents/MacOS/" +cp wasm/edgetx-*-simulator.wasm native/*.app/Contents/MacOS/ ``` ## Build a distributable `.dmg` @@ -151,16 +152,16 @@ The `package` target lives in the `native` build tree, **not** in the top-level ```bash mkdir -p native/plugins -cp wasm/edgetx-*-simulator.wasm native/plugins/ 2>/dev/null || true +cp wasm/edgetx-*-simulator.wasm native/plugins/ 2>/dev/null cmake --build native --target package ``` -The `.dmg` is written to `build/native/edgetx-companion-.dmg` (for example `edgetx-companion-3.0.0.dmg`). +The `.dmg` is written to `build/native/edgetx-companion-.dmg` (the version number matches your EdgeTX release). Open it and drag **EdgeTX Companion** into `/Applications`: ```bash -open native/edgetx-companion-3.0.0.dmg +open native/edgetx-companion-*.dmg ``` The packaging step bundles Qt, SDL2, and SDL3 into the `.app` automatically.