edgetx-gx12/docs/building/macos-sequoia.md

# Build Instructions using macOS 15 (Sequoia) and macOS 26 (Tahoe)

# Install [Homebrew](https://brew.sh/)

- Run command in `Terminal`:

```bash
/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.

# 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.

```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
```

Please note that `QT_PLUGIN_PATH` is required to be able to run Companion from your build directory without having to build a `DMG` package first.

# Install ARM toolchain

Download and install the ARM GCC toolchain [from here](https://developer.arm.com/downloads/-/arm-gnu-toolchain-downloads) (installs in `/Applications/ArmGNUToolchain/`):

- 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>

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.

# Other tools

```bash
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:

```bash
brew install --cask xquartz
```

# Download EdgeTX code

- Checkout code

```bash
git clone --recursive https://github.com/EdgeTX/edgetx.git
```

- Switch into the source directory:

```bash
cd edgetx
```

# Install Python dependencies

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 .
```

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 \
   -DARM_TOOLCHAIN_DIR=/Applications/ArmGNUToolchain/14.2.Rel1/arm-none-eabi/bin/ ..
```

| Variable | Purpose |
|----------|---------|
| `CMAKE_PREFIX_PATH` | Path to your Qt installation (`$QTDIR`) |
| `CMAKE_OSX_DEPLOYMENT_TARGET` | Minimum macOS version for Companion. `14.0` (Sonoma) is a convenient local-dev default; release builds (CI) target `12.0` for broader compatibility — pass `-DCMAKE_OSX_DEPLOYMENT_TARGET=12.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

```bash
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:

```bash
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).

## Run Companion from the build directory

```bash
export QT_PLUGIN_PATH=$(brew --prefix)/opt/qt@6/plugins
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/*.app/Contents/MacOS/
```

## Build a distributable `.dmg`

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
cmake --build native --target package
```

The `.dmg` is written to `build/native/edgetx-companion-<version>.dmg` (the version number matches your EdgeTX release).

Open it and drag **EdgeTX Companion** into `/Applications`:

```bash
open native/edgetx-companion-*.dmg
```

The packaging step bundles Qt, SDL2, and SDL3 into the `.app` automatically, then verifies that
nothing in the bundle still points at a library outside it. If that check fails, the build stops
rather than producing a `.dmg` that only runs on your machine — most often because a dependency
was picked up from Homebrew without being copied in. Pass `-DCOMPANION_VERIFY_BUNDLE=OFF` to
package anyway.

!!! note
    A locally built `.dmg` is not what CI ships. Homebrew's bottles are single-architecture and
    target your macOS version, so your build is arm64-only and requires the macOS you built it
    on. CI builds sdl2-compat and SDL3 from source as universal (`x86_64` + `arm64`) binaries
    targeting macOS 11.0 — see `.github/actions/build_companion/setup-sdl.sh`. Both use the same
    sdl2-compat + SDL3 stack, so the code path is identical; only the slices and minimum OS
    differ.

# Troubleshooting

## Notes on compiling simulator plug-ins

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
-rwxr-xr-x  1 etx  staff  57089384 Jan  7 11:22 libedgetx-nv14-simulator.dylib
-rwxr-xr-x  1 etx  staff  61167768 Jan  7 08:44 libedgetx-tx16s-simulator.dylib
-rwxr-xr-x  1 etx  staff  60327272 Jan  5 12:48 libedgetx-x10express-simulator.dylib
-rwxr-xr-x  1 etx  staff   1849768 Dec 26 08:56 libedgetx-x9d+-simulator.dylib
-rwxr-xr-x  1 etx  staff   1881224 Dec 31 16:44 libedgetx-zorro-simulator.dylib

% ls -l simulator.app/Contents/MacOS/
total 392616
-rwxr-xr-x  1 etx  staff  57089384 Jan  7 11:22 libedgetx-nv14-simulator.dylib
-rwxr-xr-x  1 etx  staff  61168056 Jan  5 11:52 libedgetx-tx16s-simulator.dylib
-rwxr-xr-x  1 etx  staff  60327272 Jan  5 12:34 libedgetx-x10express-simulator.dylib
-rwxr-xr-x  1 etx  staff  21732144 Jan  7 11:48 simulator
```

## 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

  error:
  /Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/otool-classic:
  can't open file: @rpath/libsharpyuv.0.dylib (No such file or directory)

Call Stack (most recent call first):
  /opt/homebrew/Cellar/cmake/3.27.7/share/cmake/Modules/BundleUtilities.cmake:527 (get_item_rpaths)
  /opt/homebrew/Cellar/cmake/3.27.7/share/cmake/Modules/BundleUtilities.cmake:614 (set_bundle_key_values)
  /opt/homebrew/Cellar/cmake/3.27.7/share/cmake/Modules/BundleUtilities.cmake:933 (get_bundle_keys)
  /Users/jean-christophedreyfus/Documents/edgetx/build/native/companion/src/cmake_install.cmake:180 (fixup_bundle)
  /Users/jean-christophedreyfus/Documents/edgetx/build/native/cmake_install.cmake:43 (include)


CPack Error: Error when generating package: companion
make: *** [package] Error 1
```

It can be fixed by entering the following command at terminal:

`install_name_tool -change "@rpath/libsharpyuv.0.dylib" "$(brew --prefix)/lib/libsharpyuv.0.dylib" "$(brew --prefix)/lib/libwebp.7.dylib" && codesign --force -s - "$(brew --prefix)/lib/libwebp.7.dylib"`