Skip to content

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

Merged
pfeerick merged 8 commits into
mainfrom
building-md-py-deps
Sep 3, 2026
Merged

docs(build): add canonical build instructions, pyproject.toml, and add more radio presets#7222
pfeerick merged 8 commits into
mainfrom
building-md-py-deps

Conversation

@raphaelcoeffic

@raphaelcoeffic raphaelcoeffic commented Mar 26, 2026 •
edited by pfeerick
Loading

Copy link
Copy Markdown
Member

Update docs overview(docs/building/index.md) with canonical build instructions covering firmware, simulator, companion, and WASM plugin workflows using both CMake presets and manual superbuild invocations.

Add pyproject.toml declaring all Python build dependencies for use with uv (pip install . for backward compatibility, and pip install ".[docs]" for doc building requirements). Adds previously missing asciitree, pyelftools. Dependent CI tasks (i.e. Companion, WASI) will auto-fire on any changes to the file in the future.

Expand CMakePresets.json with per-radio firmware presets for all currently supported targets

Add CI schema/format validation for the CMakePresets to protect against any mangling of the file.

Base automatically changed from dependency-cache to main June 22, 2026 04:32
@pfeerick pfeerick added compilation Related to compiling the firmware and firmware options documentation 📝 Improvements or additions to documentation labels Jun 22, 2026
@pfeerick pfeerick added this to the 3.0 milestone Jun 22, 2026
@pfeerick pfeerick added the needs: rebase A git rebase on top of the latest destination branch version is required label Jun 22, 2026
@pfeerick

pfeerick commented Jun 22, 2026

Copy link
Copy Markdown
Member
  • Need to decide if we actually want/need requirements.txt as since we are using uv everywhere now, makes two files to keep in sync. With a slight tweak to the pyproject.toml, pip should happily do the install (i.e. no requirement to use uv) via pip install . or pip install ".[docs]"
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -22,3 +22,10 @@
     "mkdocs-minify-plugin>=0.8",
     "mike>=2.0",
 ]
+
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools]
+packages = []
  • Would be better if BUILDING.md was in docs, as this is what it is, and it can then be added to the documentation site ;)

@raphaelcoeffic @claude @pfeerick
docs(build): add BUILDING.md, pyproject.toml, and radio presets
93799ae 
Add BUILDING.md with canonical build instructions covering firmware,
simulator, companion, and WASM plugin workflows using both CMake presets
and manual superbuild invocations.

Add pyproject.toml declaring all Python build dependencies for use with
uv, and sync requirements.txt to match (adds asciitree, pyelftools).

Expand CMakePresets.json with per-radio firmware presets for all major
RadioMaster, Jumper, FrSky, and FlySky targets.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@pfeerick
pfeerick force-pushed the building-md-py-deps branch from 74f9023 to 93799ae Compare September 2, 2026 07:12
@pfeerick pfeerick removed the needs: rebase A git rebase on top of the latest destination branch version is required label Sep 2, 2026
@pfeerick
feat(build): add all fw.json radio targets as CMake presets, move BUI…
96b41f2 
…LDING.md into docs site

- Add the 24 CMake presets that were missing relative to fw.json's
  officially tracked target list (f16, pa01, pl18ev, pl18u, st16,
  x10express, x7access, x9e, v12/v14/v14lcd/v16, commando8, c14,
  bumblebee, t12max, t15, t16, t18, t22, tpros, tprov2, gx15, tx15),
  bringing the preset list to full parity with fw.json (53 presets
  total, the 43 fw.json targets plus 5 pre-existing non-released
  ones). Presets are now ordered alphabetically by manufacturer then
  model, matching fw.json's own ordering.
- Move BUILDING.md's content into docs/building/index.md (replacing
  the old stub Overview page) so it's part of the published docs site
  instead of only visible to repo browsers; delete the root
  BUILDING.md now that nothing references it.

requirements.txt and pyproject.toml's main dependency list were
already in sync, no change needed there.
@pfeerick
pfeerick marked this pull request as ready for review September 2, 2026 08:36
pfeerick and others added 6 commits September 2, 2026 08:49
@pfeerick
build(python): consolidate on pyproject.toml, retire requirements.txt…
1bd0f60 
… / docs-requirements.txt

pyproject.toml now gets a [build-system]/[tool.setuptools] section
(packages = []) so it's installable directly via `pip install .` or
`pip install ".[docs]"`, not just `uv sync` -- no requirement to use
uv. Every CI job and doc page that installed Python deps from the two
standalone requirements files now installs from pyproject.toml instead:

- .github/actions/python_dependencies/action.yml (used by
  companion.yml): `pip install -r requirements.txt` -> `pip install .`
- .github/workflows/validate_hw_defs.yml: `uv pip install -r
  requirements.txt` -> `uv pip install .`
- .github/workflows/docs.yml: `uv run --with-requirements
  docs-requirements.txt` -> `uv run --extra docs --`, and its path
  triggers now watch pyproject.toml instead of the deleted file
- docs/README.md, docs/building/macos-sequoia.md: same substitution
  for the documented manual install commands
- Justfile: update a stale comment pointing at a requirements.txt
  path that never existed

requirements.txt and docs-requirements.txt are deleted now that
nothing references them.

Left alone: docs/building/macos-sonoma.md, macos-catalina.md,
windows.md, and tools/setup_buildenv_ubuntu{22,24}.04.sh all install
Python packages *before* cloning the repo, so there's no pyproject.toml
on disk yet for them to point at -- switching those over would mean
reordering their instructions, not just swapping a command.

Also: add .venv/, *.egg-info/, and __pycache__/ to .gitignore (both
`uv sync` and `pip install .` create these in the repo root and
weren't previously ignored), and group *.pyc alongside them.
@pfeerick
ci(python): move companion's python_dependencies action onto uv
2da09e8 
Swap actions/setup-python + `pip install .` for astral-sh/setup-uv +
`uv sync`, matching the pattern already used by validate_hw_defs.yml
and docs.yml. The venv's bin dir is prepended to GITHUB_PATH so the
downstream WASM module build (which invokes python3 through CMake,
not directly) keeps finding it exactly as it did with setup-python.

Also fixes the action's `name:` field, which was a stale copy-paste
leftover reading "Setup WASI SDK".

validate_hw_defs.yml's install step becomes a plain `uv sync` instead
of `uv venv && uv pip install .`, for consistency and so it'd pick up
a uv.lock if one is ever added.

This was the only Python-related CI step left on plain pip;
validate_fw_json.yml runs stdlib-only scripts directly and
build_fw.yml installs nothing (relies on the pre-baked edgetx-dev
image), so nothing else needed touching to be fully uv-based.
@pfeerick
ci(companion): trigger on changes to its own composite actions and py…
33f2df3 
…project.toml

companion.yml's path filters didn't include the three composite
actions its jobs actually use (python_dependencies, wasi_sdk,
build_companion) or pyproject.toml, which python_dependencies now
installs from. Found this because the previous commit's conversion of
python_dependencies to uv wouldn't have triggered this workflow at
all on this PR otherwise.
@pfeerick
fix(ci): export VIRTUAL_ENV so CMake's FindPython3 picks up the uv venv
e24ac1d 
cmake/GenericDefinitions.cmake sets Python3_FIND_VIRTUALENV FIRST,
which makes CMake's Python discovery key off the VIRTUAL_ENV
environment variable specifically -- not just PATH. The previous
commit only prepended .venv/bin to PATH, which was enough for uv run
(used by validate_hw_defs.yml) but not for the WASM module build,
which invokes python3 indirectly through CMake/make during hw_defs
codegen. That failed with "ModuleNotFoundError: No module named
'jinja2'" in CI since CMake found some other python3 instead of the
one uv sync had actually installed dependencies into.
@pfeerick @claude
ci(cmake): validate CMakePresets.json against CMake's schema and format
db51f71 
Adds a small workflow that runs on any change to CMakePresets.json:

- Schema validation via check-jsonschema (run through uvx, no
  persistent install) against the presets JSON schema bundled with
  whatever CMake version the runner has -- matching the exact CMake
  version enforcing these presets rather than an arbitrary remote
  copy. (An earlier attempt at using CMake's GitHub mirror URL for
  this turned out to resolve to an empty/non-functional schema, so
  the runner's own local copy is used instead.)
- Formatting check via prettier, pinned to 3.9.6. A .prettierrc.json
  override bumps printWidth to 120 for this file specifically (the
  repo-wide default stays 80 for anything else prettier might touch
  later); at that width the file's existing style -- compact
  single-line cacheVariables entries, blank lines separating
  manufacturer groups -- already passes --check with zero changes.
  A generic JSON pretty-printer (python -m json.tool, pre-commit-hooks'
  pretty-format-json) was considered and rejected: both force every
  cacheVariables entry onto multiple lines and drop the blank-line
  grouping, since neither preserves short objects inline or blank
  lines the way prettier's JSON printer does.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@pfeerick @claude
fix(cmake-presets): fix schema glob expansion, drop stray blank lines
c13aa7e 
The check-jsonschema schema path used an unquoted glob assigned to a
variable in a single step, which bash does not expand on plain
assignment (only when used unquoted as a command argument) -- the
literal "cmake-*" string was being passed straight to
check-jsonschema, which then failed with FileNotFoundError. Split the
assignment so the glob expands where it's actually used.

Also drops three blank lines between the default/firmware/native/
companion presets in CMakePresets.json -- copy/paste artifacts from
before this PR's changes, inconsistent with companion/simu already
having none between them.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@pfeerick pfeerick changed the title docs(build): add BUILDING.md, pyproject.toml, and radio presets docs(build): add canonical build instructions, pyproject.toml, and add more radio presets Sep 3, 2026
@pfeerick pfeerick added the ci/cd 🔧 Related to GitHub Actions and similar issues label Sep 3, 2026
@pfeerick
pfeerick merged commit a9f8932 into main Sep 3, 2026
22 checks passed
@pfeerick
pfeerick deleted the building-md-py-deps branch September 3, 2026 00:58
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

ci/cd 🔧 Related to GitHub Actions and similar issues compilation Related to compiling the firmware and firmware options documentation 📝 Improvements or additions to documentation

Projects

None yet

Milestone

3.0

Development

Successfully merging this pull request may close these issues.

2 participants

@raphaelcoeffic @pfeerick