Makefile: context-aware make help (root + per-package)

[th0ma7]

What

Make make help a first-class, context-aware entry point across spksrc.

At the repository root

make help lists the orchestration targets grouped by section (General, Build, Clean, Prepare, Digests, Lint, Toolchain & kernel, Setup), plus the per-package pattern targets (<spk>, spk-<spk>-<arch>-<tcversion>, native-<name>, toolchain-<arch>, kernel-<arch>). make help-<topic> filters by section or name, e.g. make help-clean, make help-toolchain.

Inside a package directory

make help prints the targets relevant to that context, for every tree: cross/, spk/, diyspk/, native/, toolchain/, toolkit/, kernel/ and python/:

• Build: all, arch-<arch>-<tcvers> (cross/spk/kernel/diyspk), the <step> lifecycle (download → checksum → extract → patch → configure → compile → install [→ plist]), a reminder that all and every <step> except download need ARCH+TCVERSION, tc_vars/tk_vars (toolchain/toolkit) and the rustup <args> passthrough (e.g. make rustup show).
• Multi-arch (cross/spk/diyspk): all-supported, all-latest, plus publish-all-supported / publish-all-latest for spk/diyspk (after make setup-synocommunity + PUBLISH_API_KEY).
• Python wheels (spk/diyspk with PYTHON_PACKAGE or named python3*): wheel-<arch>-<tcvers>, crossenv-<arch>-<tcvers>, download-wheels, and the clean set wheelclean / wheelcleancache / wheelcleanall / crossenvclean / crossenvcleanall, with the WHEELS="pkg==ver ..." semantics in the header.
• Inspect: dependency-tree / dependency-flat / dependency-list.
• Cleanup / Maintenance: clean, smart-clean, download, digests (with a note that digests auto-runs download and how to force a refresh).
• python/ tree: states the module is built as an spk dependency only, plus Inspect.

How

• Root help (root Makefile) is generated from ##@ Section headers and trailing ## description comments — self-documenting, so it never drifts, and only documented targets appear (internal pre_*/post_*/*_msg hooks carry no ## and are hidden by construction). help-<topic> uses a help-% pattern rule so the topic is never mistaken for a build goal.
• Package help is a new mk/spksrc.common/help.mk, included by spksrc.common.mk after default: all so the help target can never become the default goal. It only activates when the parent directory is one of the known trees and CURDIR != BASEDIR (so a checkout living under a parent named e.g. spk/ cannot shadow the root help). An include guard prevents "overriding recipe" warnings when common.mk is included more than once.
• HELP_PYTHON is a deferred (=) variable checked at recipe time, so the wheels section shows even when PYTHON_PACKAGE is set after include spksrc.common.mk (e.g. spk/borgbackup).

Fixes folded in

• root downloads target looped over dl but invoked make -C $${tc} (empty variable) — broken loop, now fixed since help advertises it.
• docs aligned with the actual target inventory: build-rules.md (complete cross/spk tables, arch-<arch>-<tcvers> naming, python-wheel vs python-module include fix), build-workflow.md (make help note covering all trees), python.md (accurate wheel-clean target descriptions).

Notes

• make with no target still builds all, at the root and in packages (verified: the help include is parsed after default: all).
• Verified in root, cross, spk, diyspk, native, toolchain, toolkit and python contexts.

Example (inside spk/borgbackup)

borgbackup  (spk package)

Build
  all                      build this package (default target)
  arch-<arch>-<tcvers>     build for one arch/version (e.g. arch-x64-7.1)
  <step>                   run one build step, in order:
                             download checksum extract patch configure compile install plist
    all and every <step> except download need ARCH=<arch> TCVERSION=<tcvers>
  rustup <args>            run rustup for the rust toolchain (e.g. make rustup show)

Multi-arch  (needs 'make setup' once at the spksrc root first)
  all-supported            build for every supported arch
  all-latest               build for the latest toolchains only
  publish-all-supported    build and publish every supported arch (after 'make setup-synocommunity' + PUBLISH_API_KEY)
  publish-all-latest       build and publish the latest toolchains only

Python wheels  (WHEELS="pkg1==ver pkg2==ver ..." restricts the (re)build to those wheels; unset rebuilds all)
  wheel-<arch>-<tcvers>    build the package's wheels for one arch
  crossenv-<arch>-<tcvers> build the cross-compilation Python venv
  download-wheels          download the wheel sources only
  wheelclean               remove wheel build state (run before rebuilding)
  wheelcleancache          remove the local pip cache only (work-*/pip)
  wheelcleanall            wheelclean + caches, incl. the shared distrib/pip
  crossenvclean            remove the crossenv and wheel state
  crossenvcleanall         remove the crossenv, wheels and all caches

Inspect
  dependency-tree          print the resolved dependency graph
  dependency-flat          flat, de-duplicated dependency list
  dependency-list          raw per-package dependency list

Cleanup
  clean                    remove all work directories
  smart-clean              remove this package's source and cookies (needs ARCH+TCVERSION)

Maintenance
  download                 fetch the source archive(s)
  digests                  regenerate the digests file (auto-runs download)
    to refresh digests: make clean, delete the file in distrib/, then make digests

🤖 Generated with Claude Code

[th0ma7]

@hgy59 and @mreid-tt if you have a few cycles to spare and tryout using make help in various areas of the framework and let me know what you think or if there is something missing?

Yet to validate are all the spksrc's root directory recipe that I almost never use... but otherwise running make help from under cross|native|spk|diyspk/abc should provide meaningful info. It also detects python based spk and provide additional info.

Feedback welcomed