docs(build): add canonical build instructions, pyproject.toml, and add more radio presets (#7222)

Co-authored-by: raphaelcoeffic <1050031+raphaelcoeffic@users.noreply.github.com> Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Co-authored-by: Peter Feerick <peter.feerick@gmail.com>
2026-09-03 10:58:04 +10:00
parent 1ca4e58274
commit a9f89323a9
15 changed files with 609 additions and 62 deletions
@@ -1,4 +1,4 @@
-name: 'Setup WASI SDK'
+name: 'Python Dependencies'
 inputs:
  python-version:
    description: 'Python version'
@@ -8,10 +8,16 @@ runs:
  using: "composite"
  steps:

-    - uses: actions/setup-python@v7
+    - name: Install uv
+      uses: astral-sh/setup-uv@v10.0.1
      with:
        python-version: ${{ inputs.python-version }}
-        cache: 'pip' # caching pip dependencies
+        enable-cache: true
+        cache-dependency-glob: pyproject.toml

-    - run: python3 -m pip install -r requirements.txt
+    - name: Install Python dependencies
      shell: bash
+      run: |
+        uv sync
+        echo "VIRTUAL_ENV=$PWD/.venv" >> "$GITHUB_ENV"
+        echo "$PWD/.venv/bin" >> "$GITHUB_PATH"
@@ -8,7 +8,11 @@ on:
      - v*
    paths:
      - '.github/workflows/companion.yml'
+      - '.github/actions/python_dependencies/**'
+      - '.github/actions/wasi_sdk/**'
+      - '.github/actions/build_companion/**'
      - 'companion/**'
+      - 'pyproject.toml'
      - 'tools/build-companion.sh'
      - 'tools/build-wasm-modules.sh'
      - 'cmake/wasm/CMakeLists.txt'
@@ -16,7 +20,11 @@ on:
  pull_request:
    paths:
      - '.github/workflows/companion.yml'
+      - '.github/actions/python_dependencies/**'
+      - '.github/actions/wasi_sdk/**'
+      - '.github/actions/build_companion/**'
      - 'companion/**'
+      - 'pyproject.toml'
      - 'tools/build-companion.sh'
      - 'tools/build-wasm-modules.sh'
      - 'cmake/wasm/CMakeLists.txt'
@@ -7,7 +7,7 @@ on:
    paths:
      - 'docs/**'
      - 'mkdocs.yml'
-      - 'docs-requirements.txt'
+      - 'pyproject.toml'
      - '.github/workflows/docs.yml'
    tags:
      - 'v[0-9]+.[0-9]+.[0-9]+'   # release tags only, not -rc
@@ -15,7 +15,7 @@ on:
    paths:
      - 'docs/**'
      - 'mkdocs.yml'
-      - 'docs-requirements.txt'
+      - 'pyproject.toml'
      - '.github/workflows/docs.yml'
  workflow_dispatch:

@@ -41,15 +41,15 @@ jobs:

      - name: Build docs (PR check)
        if: github.event_name == 'pull_request'
-        run: uv run --with-requirements docs-requirements.txt mkdocs build --strict
+        run: uv run --extra docs -- mkdocs build --strict

      - name: Deploy as latest (main branch)
        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
-        run: uv run --with-requirements docs-requirements.txt mike deploy --push --update-aliases latest
+        run: uv run --extra docs -- mike deploy --push --update-aliases latest

      - name: Deploy release version
        if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/')
        run: |
          # Extract minor version from tag, e.g. v2.11.2 -> v2.11
          VERSION=$(echo "${GITHUB_REF_NAME}" | sed 's/\.[0-9]*$//')
-          uv run --with-requirements docs-requirements.txt mike deploy --push --update-aliases "${VERSION}" stable
+          uv run --extra docs -- mike deploy --push --update-aliases "${VERSION}" stable
@@ -0,0 +1,39 @@
+---
+name: Validate CMakePresets.json
+on:
+  push:
+    branches:
+      - 'main'
+      - '[0-9]+.[0-9]+'
+    paths:
+      - 'CMakePresets.json'
+      - '.prettierrc.json'
+      - '.github/workflows/validate_cmake_presets.yml'
+  pull_request:
+    branches:
+      - 'main'
+      - '[0-9]+.[0-9]+'
+    paths:
+      - 'CMakePresets.json'
+      - '.prettierrc.json'
+      - '.github/workflows/validate_cmake_presets.yml'
+  workflow_dispatch:
+
+jobs:
+  validate:
+    name: Validate CMakePresets.json
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v10.0.1
+
+      - name: Validate against CMake's presets schema
+        run: |
+          cmake --version
+          CMAKE_PREFIX="$(dirname "$(dirname "$(command -v cmake)")")"
+          uvx check-jsonschema --schemafile "$CMAKE_PREFIX"/share/cmake-*/Help/manual/presets/schema.json CMakePresets.json
+
+      - name: Check formatting (prettier)
+        run: npx --yes prettier@3.9.6 --check CMakePresets.json
@@ -29,7 +29,7 @@ jobs:

      - name: Install Python dependencies
        working-directory: .
-        run: uv venv && uv pip install -r requirements.txt
+        run: uv sync

      - name: Check Python script syntax
        run: uv run python3 -m py_compile *.py
@@ -20,11 +20,16 @@ CMakeUserPresets.json
 .DS_Store
 _deps
 _wasi_sdk_fetch
-*.pyc

 # MkDocs
 /site/

+# Python (uv / pip)
+.venv/
+*.egg-info/
+__pycache__/
+*.pyc
+
 output/
 *.dmg
 .devcontainer/devcontainer-lock.json
@@ -0,0 +1,10 @@
+{
+  "overrides": [
+    {
+      "files": "CMakePresets.json",
+      "options": {
+        "printWidth": 120
+      }
+    }
+  ]
+}
@@ -13,9 +13,9 @@
    },
    {
      "name": "firmware",
+      "hidden": true,
      "inherits": "default",
-      "displayName": "Firmware",
-      "binaryDir": "build/fw",
+      "binaryDir": "build/${presetName}",
      "toolchainFile": "cmake/toolchain/arm-none-eabi.cmake",
      "cacheVariables": {
        "EdgeTX_SUPERBUILD": false,
@@ -23,60 +23,348 @@
      }
    },
    {
-      "name": "companion",
+      "name": "native",
+      "hidden": true,
      "inherits": "default",
-      "displayName": "Companion",
-      "binaryDir": "build/companion",
+      "binaryDir": "build/${presetName}",
      "toolchainFile": "cmake/toolchain/native.cmake",
      "cacheVariables": {
        "EdgeTX_SUPERBUILD": false,
        "NATIVE_BUILD": true
      }
    },
+    {
+      "name": "companion",
+      "displayName": "Companion",
+      "inherits": "native",
+      "binaryDir": "build/companion"
+    },
    {
      "name": "simu",
-      "inherits": "default",
-      "displayName": "SDL Simu",
-      "binaryDir": "build/simu",
-      "toolchainFile": "cmake/toolchain/native.cmake",
-      "cacheVariables": {
-        "EdgeTX_SUPERBUILD": false,
-        "NATIVE_BUILD": true
-      }
+      "displayName": "SDL Simulator",
+      "inherits": "native",
+      "binaryDir": "build/simu"
+    },
+
+    {
+      "name": "f16",
+      "displayName": "Fatfish F16",
+      "inherits": "firmware",
+      "cacheVariables": { "PCB": "X10", "PCBREV": "F16" }
+    },
+
+    {
+      "name": "el18",
+      "displayName": "FlySky EL18",
+      "inherits": "firmware",
+      "cacheVariables": { "PCB": "PL18", "PCBREV": "EL18" }
+    },
+    {
+      "name": "nb4p",
+      "displayName": "FlySky NB4+",
+      "inherits": "firmware",
+      "cacheVariables": { "PCB": "PL18", "PCBREV": "NB4P" }
+    },
+    {
+      "name": "nv14",
+      "displayName": "FlySky NV14",
+      "inherits": "firmware",
+      "cacheVariables": { "PCB": "PL18", "PCBREV": "NV14" }
+    },
+    {
+      "name": "pa01",
+      "displayName": "FlySky PA01",
+      "inherits": "firmware",
+      "cacheVariables": { "PCB": "PA01" }
+    },
+    {
+      "name": "pl18",
+      "displayName": "FlySky PL18",
+      "inherits": "firmware",
+      "cacheVariables": { "PCB": "PL18" }
+    },
+    {
+      "name": "pl18ev",
+      "displayName": "FlySky PL18EV",
+      "inherits": "firmware",
+      "cacheVariables": { "PCB": "PL18", "PCBREV": "PL18EV" }
+    },
+    {
+      "name": "pl18u",
+      "displayName": "FlySky PL18U",
+      "inherits": "firmware",
+      "cacheVariables": { "PCB": "PL18", "PCBREV": "PL18U" }
+    },
+    {
+      "name": "st16",
+      "displayName": "FlySky ST16",
+      "inherits": "firmware",
+      "cacheVariables": { "PCB": "ST16" }
+    },
+
+    {
+      "name": "x10",
+      "displayName": "FrSky X10",
+      "inherits": "firmware",
+      "cacheVariables": { "PCB": "X10" }
+    },
+    {
+      "name": "x10express",
+      "displayName": "FrSky Horus X10 Express",
+      "inherits": "firmware",
+      "cacheVariables": { "PCB": "X10", "PCBREV": "EXPRESS", "PXX1": "YES" }
+    },
+    {
+      "name": "x12s",
+      "displayName": "FrSky X12S",
+      "inherits": "firmware",
+      "cacheVariables": { "PCB": "X12S" }
+    },
+    {
+      "name": "x7",
+      "displayName": "FrSky QX7",
+      "inherits": "firmware",
+      "cacheVariables": { "PCB": "X7" }
+    },
+    {
+      "name": "x7access",
+      "displayName": "FrSky QX7 Access",
+      "inherits": "firmware",
+      "cacheVariables": { "PCB": "X7", "PCBREV": "ACCESS", "PXX1": "YES" }
+    },
+    {
+      "name": "x9dp",
+      "displayName": "FrSky X9D+",
+      "inherits": "firmware",
+      "cacheVariables": { "PCB": "X9D+" }
+    },
+    {
+      "name": "x9dp2019",
+      "displayName": "FrSky X9D+ 2019",
+      "inherits": "firmware",
+      "cacheVariables": { "PCB": "X9D+", "PCBREV": "2019" }
+    },
+    {
+      "name": "x9e",
+      "displayName": "FrSky X9E",
+      "inherits": "firmware",
+      "cacheVariables": { "PCB": "X9E" }
+    },
+    {
+      "name": "xlite",
+      "displayName": "FrSky X-Lite",
+      "inherits": "firmware",
+      "cacheVariables": { "PCB": "XLITE" }
+    },
+
+    {
+      "name": "v12",
+      "displayName": "HelloRadioSky V12",
+      "inherits": "firmware",
+      "cacheVariables": { "PCB": "V12" }
+    },
+    {
+      "name": "v14",
+      "displayName": "HelloRadioSky V14",
+      "inherits": "firmware",
+      "cacheVariables": { "PCB": "X7", "PCBREV": "V14" }
+    },
+    {
+      "name": "v14lcd",
+      "displayName": "HelloRadioSky V14LCD",
+      "inherits": "firmware",
+      "cacheVariables": { "PCB": "X7", "PCBREV": "V14LCD" }
+    },
+    {
+      "name": "v16",
+      "displayName": "HelloRadioSky V16",
+      "inherits": "firmware",
+      "cacheVariables": { "PCB": "X10", "PCBREV": "V16" }
+    },
+
+    {
+      "name": "commando8",
+      "displayName": "iFlight Commando 8",
+      "inherits": "firmware",
+      "cacheVariables": { "PCB": "X7", "PCBREV": "COMMANDO8" }
+    },
+    {
+      "name": "c14",
+      "displayName": "iFlight Commando 14",
+      "inherits": "firmware",
+      "cacheVariables": { "PCB": "C14" }
+    },
+
+    {
+      "name": "bumblebee",
+      "displayName": "Jumper Bumblebee",
+      "inherits": "firmware",
+      "cacheVariables": { "PCB": "X7", "PCBREV": "BUMBLEBEE" }
+    },
+    {
+      "name": "t12max",
+      "displayName": "Jumper T12 MAX",
+      "inherits": "firmware",
+      "cacheVariables": { "PCB": "X7", "PCBREV": "T12MAX" }
+    },
+    {
+      "name": "t14",
+      "displayName": "Jumper T14",
+      "inherits": "firmware",
+      "cacheVariables": { "PCB": "X7", "PCBREV": "T14" }
+    },
+    {
+      "name": "t15",
+      "displayName": "Jumper T15",
+      "inherits": "firmware",
+      "cacheVariables": { "PCB": "X10", "PCBREV": "T15", "INTERNAL_MODULE_CRSF": "ON" }
+    },
+    {
+      "name": "t15pro",
+      "displayName": "Jumper T15 Pro",
+      "inherits": "firmware",
+      "cacheVariables": { "PCB": "T15PRO" }
+    },
+    {
+      "name": "t16",
+      "displayName": "Jumper T16",
+      "inherits": "firmware",
+      "cacheVariables": { "PCB": "X10", "PCBREV": "T16", "INTERNAL_MODULE_MULTI": "ON" }
+    },
+    {
+      "name": "t18",
+      "displayName": "Jumper T18",
+      "inherits": "firmware",
+      "cacheVariables": { "PCB": "X10", "PCBREV": "T18" }
+    },
+    {
+      "name": "t20",
+      "displayName": "Jumper T20",
+      "inherits": "firmware",
+      "cacheVariables": { "PCB": "X7", "PCBREV": "T20" }
+    },
+    {
+      "name": "t20v2",
+      "displayName": "Jumper T20 V2",
+      "inherits": "firmware",
+      "cacheVariables": { "PCB": "X7", "PCBREV": "T20V2" }
+    },
+    {
+      "name": "t22",
+      "displayName": "Jumper T22",
+      "inherits": "firmware",
+      "cacheVariables": { "PCB": "T22" }
+    },
+    {
+      "name": "tpro",
+      "displayName": "Jumper T-Pro",
+      "inherits": "firmware",
+      "cacheVariables": { "PCB": "X7", "PCBREV": "TPRO" }
+    },
+    {
+      "name": "tpros",
+      "displayName": "Jumper T-Pro S",
+      "inherits": "firmware",
+      "cacheVariables": { "PCB": "X7", "PCBREV": "TPROS" }
+    },
+    {
+      "name": "tprov2",
+      "displayName": "Jumper T-Pro V2",
+      "inherits": "firmware",
+      "cacheVariables": { "PCB": "X7", "PCBREV": "TPROV2" }
+    },
+
+    {
+      "name": "boxer",
+      "displayName": "RadioMaster Boxer",
+      "inherits": "firmware",
+      "cacheVariables": { "PCB": "X7", "PCBREV": "BOXER" }
+    },
+    {
+      "name": "gx12",
+      "displayName": "RadioMaster GX12",
+      "inherits": "firmware",
+      "cacheVariables": { "PCB": "X7", "PCBREV": "GX12" }
+    },
+    {
+      "name": "gx15",
+      "displayName": "RadioMaster GX15",
+      "inherits": "firmware",
+      "cacheVariables": { "PCB": "GX15" }
+    },
+    {
+      "name": "mt12",
+      "displayName": "RadioMaster MT12",
+      "inherits": "firmware",
+      "cacheVariables": { "PCB": "X7", "PCBREV": "MT12" }
+    },
+    {
+      "name": "pocket",
+      "displayName": "RadioMaster Pocket",
+      "inherits": "firmware",
+      "cacheVariables": { "PCB": "X7", "PCBREV": "POCKET" }
+    },
+    {
+      "name": "tx12",
+      "displayName": "RadioMaster TX12",
+      "inherits": "firmware",
+      "cacheVariables": { "PCB": "X7", "PCBREV": "TX12" }
+    },
+    {
+      "name": "tx12mk2",
+      "displayName": "RadioMaster TX12 MK2",
+      "inherits": "firmware",
+      "cacheVariables": { "PCB": "X7", "PCBREV": "TX12MK2" }
+    },
+    {
+      "name": "tx15",
+      "displayName": "RadioMaster TX15",
+      "inherits": "firmware",
+      "cacheVariables": { "PCB": "TX15" }
+    },
+    {
+      "name": "tx16s",
+      "displayName": "RadioMaster TX16S",
+      "inherits": "firmware",
+      "cacheVariables": { "PCB": "X10", "PCBREV": "TX16S" }
+    },
+    {
+      "name": "tx16smk3",
+      "displayName": "RadioMaster TX16S MK3",
+      "inherits": "firmware",
+      "cacheVariables": { "PCB": "TX16SMK3" }
+    },
+    {
+      "name": "zorro",
+      "displayName": "RadioMaster Zorro",
+      "inherits": "firmware",
+      "cacheVariables": { "PCB": "X7", "PCBREV": "ZORRO" }
    }
  ],
  "buildPresets": [
    {
      "name": "firmware",
-      "displayName": "Firmware",
-      "configurePreset": "firmware",
-      "targets": [
-        "firmware"
-      ]
+      "hidden": true,
+      "configurePreset": "tx16s",
+      "targets": ["firmware"]
    },
    {
      "name": "companion",
      "displayName": "Companion",
      "configurePreset": "companion",
-      "targets": [
-        "companion"
-      ]
+      "targets": ["companion"]
    },
    {
      "name": "simu",
-      "displayName": "SDL Simu",
+      "displayName": "SDL Simulator",
      "configurePreset": "simu",
-      "targets": [
-        "simu"
-      ]
+      "targets": ["simu"]
    },
    {
      "name": "tests-radio",
      "displayName": "Radio Tests",
      "configurePreset": "simu",
-      "targets": [
-        "tests-radio"
-      ]
+      "targets": ["tests-radio"]
    }
  ]
 }
@@ -61,7 +61,7 @@ codegen: gen-fonts cfn-sort gen-yaml gen-radios gen-simstr
 check-radio-macros:
    python3 tools/check_radio_macros.py

-# Needs: the Python packages in radio/util/hw_defs/requirements.txt.
+# Needs: the Python packages in pyproject.toml (uv pip install . / pip install .).
 [doc('Validate the hw_defs JSON and that every template renders for every board')]
 [group('checks')]
 check-hw-defs:
@@ -1,4 +0,0 @@
-mkdocs>=1.6
-mkdocs-material>=9.5
-mkdocs-minify-plugin>=0.8
-mike>=2.0
@@ -7,13 +7,14 @@ This folder contains the source for the EdgeTX developer documentation site, bui
 Install the required packages from the repo root. Using [`uv`](https://docs.astral.sh/uv/getting-started/installation/) is recommended:

 ```bash
-uv pip install -r docs-requirements.txt
+uv sync --extra docs
+source .venv/bin/activate
 ```

 Or with plain pip:

 ```bash
-pip install -r docs-requirements.txt
+pip install ".[docs]"
 ```

 [`mike`](https://github.com/jimporter/mike) is included as a dependency — it manages versioned deployments of the site (e.g. publishing a new release). You won't need it for local editing or preview.
@@ -1,9 +1,180 @@
 # Building EdgeTX

-This section contains step-by-step build instructions for every supported platform. Whether you want to build a custom firmware binary, run the EdgeTX simulator, or contribute to development, pick the guide that matches your environment.
+This guide covers how to build EdgeTX firmware, the SDL simulator, and the
+Companion application from source using CMake Presets. For platform-specific
+environment setup (installing toolchains, Qt, etc.), see the platform guides
+in this section.

-## Notes
+!!! note
+    The instructions here are meant to help you develop or test changes to
+    EdgeTX on your PC, not to build flight/radio-safe versions of binaries.

- The document here is meant to help you develop or test changes to EdgeTX on your PC, not to build flight/radio safe version of binaries.
- For a list of all available CMake build options, see [Compilation Options](compilation-options.md).
- For radio-specific build flags (`PCB`, `PCBREV`), refer to the build scripts at [https://github.com/EdgeTX/edgetx/tree/main/tools](https://github.com/EdgeTX/edgetx/tree/main/tools).
+## Prerequisites
+
+| Component | Required for | Notes |
+|-----------|-------------|-------|
+| **CMake >= 3.21** | Everything | |
+| **arm-none-eabi-gcc** | Firmware | 14.2.rel1 recommended |
+| **Python >= 3.10** | Firmware, Companion | Code generation at build time |
+| **Qt 6** | Companion | 6.9+ recommended |
+| **SDL2** | Simulator | |
+| **Ninja** (optional) | Everything | Faster than Make |
+
+### Python dependencies
+
+The build invokes Python scripts for code generation (YAML parsers, hardware
+definitions, bitmap encoding, etc.). Install the required packages with
+[uv](https://docs.astral.sh/uv/):
+
+```bash
+uv sync
+source .venv/bin/activate   # CMake needs the venv activated to find Python
+```
+
+The virtual environment must stay activated when running CMake, so that the
+build can find the installed packages. On Windows, use `.venv\Scripts\activate`
+instead.
+
+## Quick start with CMake Presets
+
+The repository ships CMake presets for all supported radios and build types.
+These work in VSCode (CMake Tools), CLion, and the command line.
+
+### Firmware
+
+```bash
+# Configure for a specific radio
+cmake --preset tx16s
+
+# Build
+cmake --build build/tx16s --target firmware
+```
+
+Replace `tx16s` with any supported radio preset. Run `cmake --list-presets` to
+see all available presets. A few examples:
+
+| Preset | Radio |
+|--------|-------|
+| `tx16s` | RadioMaster TX16S |
+| `tx16smk3` | RadioMaster TX16S MK3 |
+| `boxer` | RadioMaster Boxer |
+| `pocket` | RadioMaster Pocket |
+| `zorro` | RadioMaster Zorro |
+| `t20` | Jumper T20 |
+| `t14` | Jumper T14 |
+| `tpro` | Jumper T-Pro |
+| `x9dp2019` | FrSky X9D+ 2019 |
+| `x10` | FrSky X10 |
+| `nv14` | FlySky NV14 |
+| `pl18` | FlySky PL18 |
+
+### Simulator
+
+```bash
+cmake --preset simu -DPCB=X10 -DPCBREV=TX16S
+cmake --build build/simu --target simu
+```
+
+### Companion
+
+Companion embeds a radio simulator that uses WASM plugins — one per radio
+target. With presets, this requires two build directories: one for the WASM
+plugins and one for Companion itself.
+
+Build the WASM plugins for all radios:
+
+```bash
+tools/build-wasm-modules.sh
+
+# or limit to specific radios
+FLAVOR="tx16s;boxer" tools/build-wasm-modules.sh
+```
+
+Then build Companion:
+
+```bash
+cmake --preset companion
+cmake --build build/companion --target companion --parallel
+```
+
+When developing for a specific radio, you can build just that one WASM plugin
+using the superbuild instead (see [Manual CMake](#manual-cmake-without-presets)
+below):
+
+```bash
+cmake -S . -B build-tx16s -DPCB=X10 -DPCBREV=TX16S
+cmake --build build-tx16s --target wasi-module --parallel
+cmake --build build-tx16s --target companion --parallel
+```
+
+### Tests
+
+```bash
+cmake --preset simu -DPCB=X10 -DPCBREV=TX16S
+cmake --build build/simu --target tests-radio
+```
+
+## Manual CMake (without presets)
+
+If you prefer to invoke CMake directly, the superbuild takes care of toolchain
+selection and sub-build configuration automatically:
+
+```bash
+# configure
+cmake -S . -B build-tx16s -DPCB=X10 -DPCBREV=TX16S
+
+# build firmware
+cmake --build build-tx16s --target firmware --parallel
+
+# build simulator (same build directory)
+cmake --build build-tx16s --target simu --parallel
+
+# run tests
+cmake --build build-tx16s --target tests-radio --parallel
+```
+
+## Key CMake variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `PCB` | (required) | Target radio family (X7, X10, PL18, ...) |
+| `PCBREV` | (varies) | Radio variant within a PCB family (TX16S, BOXER, ...) |
+| `CMAKE_BUILD_TYPE` | | `Release` or `Debug` (native builds only; firmware ELF always includes debug symbols, stripped for .bin/.uf2) |
+| `TRANSLATIONS` | EN | Firmware language (EN, FR, DE, ES, ...) |
+| `DEFAULT_MODE` | | Stick mode 1-4 |
+| `LUA` | ON | Lua scripting support |
+
+For the full list, see [Compilation Options](compilation-options.md). For
+radio-specific build flags (`PCB`, `PCBREV`) not covered above, refer to the
+build scripts at
+[https://github.com/EdgeTX/edgetx/tree/main/tools](https://github.com/EdgeTX/edgetx/tree/main/tools).
+
+## FetchContent dependency cache
+
+Downloaded third-party dependencies (googletest, yaml-cpp, imgui, etc.) are
+cached in `.cache/fetchcontent/` at the repository root. This cache is shared
+across all build directories so that switching targets or doing clean rebuilds
+does not re-download dependencies.
+
+To override the cache location, set the `FETCHCONTENT_BASE_DIR` environment
+variable or pass it as a CMake variable:
+
+```bash
+export FETCHCONTENT_BASE_DIR=~/edgetx-deps
+cmake --preset tx16s
+```
+
+## CI builds
+
+CI uses the scripts in `tools/`:
+
+| Script | Purpose |
+|--------|---------|
+| `build-gh.sh` | Firmware release builds (all targets) |
+| `commit-tests.sh` | Debug builds with warnings-as-errors |
+| `build-companion.sh` | Companion app (Linux, macOS, Windows) |
+| `build-wasm-modules.sh` | WebAssembly simulator modules |
+| `build-common.sh` | Shared helpers and target definitions |
+
+These scripts use `FLAVOR` environment variables and are tailored for GitHub
+Actions. For local development, prefer the CMake presets above.
@@ -74,7 +74,7 @@ Since Python 3.11+, macOS uses an externally managed Python environment. Create
 ```bash
 uv venv --python 3.14
 source .venv/bin/activate
-uv pip install -r requirements.txt
+uv pip install .
 ```

 Activate the virtual environment in every new terminal session before building:
@@ -101,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. `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 |
+| `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
@@ -0,0 +1,31 @@
+[project]
+name = "edgetx"
+version = "3.0.0"
+description = "Build-time Python dependencies for EdgeTX"
+requires-python = ">=3.10"
+
+dependencies = [
+    "asciitree",
+    "clang",
+    "jinja2",
+    "lz4",
+    "pillow",
+    "pydantic",
+    "pyelftools",
+    "typing_extensions",
+]
+
+[project.optional-dependencies]
+docs = [
+    "mkdocs>=1.6",
+    "mkdocs-material>=9.5",
+    "mkdocs-minify-plugin>=0.8",
+    "mike>=2.0",
+]
+
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools]
+packages = []
@@ -1,8 +0,0 @@
-asciitree
-clang
-jinja2
-pillow
-lz4
-pydantic
-pyelftools
-typing_extensions