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>
This commit is contained in:
Raphael Coeffic
co-authored by
raphaelcoeffic
Claude Opus 4.6
Peter Feerick
raphaelcoeffic
Claude Opus 4.6
Peter Feerick
parent
1ca4e58274
commit
a9f89323a9
+3
-2
@@ -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.
|
||||
|
||||
+176
-5
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user