From 4f60f44512f4df1ab0fb1226a1b40b94b6820d05 Mon Sep 17 00:00:00 2001 From: Jean-Pierre Martineau Date: Mon, 7 Sep 2026 05:00:22 -0400 Subject: [PATCH] A build you can download and run without Python MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Most people who want MeshTerm have a radio and a terminal, not a Python toolchain. This is the install for them: one file, download it, run it. `packaging/meshterm.spec` freezes the app with PyInstaller in console mode — which is not a detail, since a windowed build of a terminal program starts with nowhere to draw and exits. The assets land at `meshterm/assets` inside the bundle so that `Path(__file__).parent.parent / "assets"` keeps resolving exactly as it does in a checkout, and bleak's per-platform backends are named as hidden imports because nothing static ever sees the one that actually gets used. UPX is off: a few megabytes are not worth being flagged by antivirus on a first release. The build was run here rather than only written. The Windows executable comes out at 14 MB, runs from a directory with no source tree in sight, and draws the specimen card — which is the real test, because the specimen reads the asset files. `installers.yml` does the same on five machines, because frozen builds cannot be cross-compiled. Windows, macOS on both Apple silicon and Intel (plenty of people still have one, and an arm64 build will not run for them), and Linux on x64 and ARM64 — the last for the uConsole. Each leg runs the binary from a temporary directory before uploading it, so a build that only works beside its own source fails on the runner instead of on somebody's laptop, and each one gets a checksum written beside it. It publishes nothing; attaching these to a release stays a separate decision. Also here: `meshterm --help` now opens with the same sentence as the package summary, rather than a fourth description of the project written in its own way. Co-Authored-By: Claude Opus 5 (1M context) --- .github/workflows/installers.yml | 93 ++++++++++++++++++++++++++++++++ CHANGELOG.md | 7 +++ meshterm/cli.py | 8 ++- packaging/entry.py | 22 ++++++++ packaging/meshterm.spec | 67 +++++++++++++++++++++++ 5 files changed, 196 insertions(+), 1 deletion(-) create mode 100644 .github/workflows/installers.yml create mode 100644 packaging/entry.py create mode 100644 packaging/meshterm.spec diff --git a/.github/workflows/installers.yml b/.github/workflows/installers.yml new file mode 100644 index 0000000..4c55de8 --- /dev/null +++ b/.github/workflows/installers.yml @@ -0,0 +1,93 @@ +# Standalone builds — a single file you download and run, with no Python installed. +# +# For most people who want MeshTerm, this is the install. They have a radio and a +# terminal, not a Python toolchain. +# +# Frozen builds cannot be cross-compiled: each one is made on the system it targets, so +# the matrix is the point of this file rather than an optimisation. Everything here +# uploads artifacts and nothing publishes — attaching them to a release stays a separate, +# deliberate act. +name: Installers + +on: + workflow_dispatch: + # Only when the packaging itself changes. Three operating systems is not something to + # spend on every commit while the repository is private and minutes are metered. + push: + paths: + - "packaging/**" + - ".github/workflows/installers.yml" + +permissions: + contents: read + +concurrency: + group: installers-${{ github.ref }} + cancel-in-progress: true + +jobs: + build: + name: ${{ matrix.label }} + runs-on: ${{ matrix.os }} + timeout-minutes: 25 + strategy: + fail-fast: false + matrix: + include: + - { os: windows-latest, label: windows-x64, ext: ".exe" } + - { os: macos-latest, label: macos-arm64, ext: "" } + # Apple silicon builds do not run on Intel Macs, and plenty of people still + # have one. macos-13 is the last x86_64 runner image. + - { os: macos-13, label: macos-x64, ext: "" } + - { os: ubuntu-22.04, label: linux-x64, ext: "" } + # For the uConsole and other 64-bit ARM handhelds. ARM runners are free on + # public repositories; on a private one this leg may sit unclaimed until the + # repo is public. Drop the line if it blocks you. + - { os: ubuntu-22.04-arm, label: linux-arm64, ext: "" } + steps: + - uses: actions/checkout@v4 + + - uses: actions/setup-python@v5 + with: + # Oldest supported version on purpose: a binary built against an older glibc + # and an older Python runs on more machines than one built against the newest. + python-version: "3.10" + + - run: pip install . pyinstaller + + - name: Build + working-directory: packaging + run: pyinstaller --clean --noconfirm meshterm.spec + + - name: Check it actually runs + shell: bash + run: | + bin="packaging/dist/meshterm${{ matrix.ext }}" + chmod +x "$bin" || true + # Run it from somewhere else entirely, so a build that only works next to the + # source tree fails here rather than on someone's laptop. + cd "$(mktemp -d)" + "$GITHUB_WORKSPACE/$bin" --help > /dev/null + "$GITHUB_WORKSPACE/$bin" specimen > /dev/null + echo "runs, and finds its assets" + + - name: Name it after the version and the platform + shell: bash + run: | + version=$(python -c "import meshterm; print(meshterm.__version__)") + out="meshterm-${version}-${{ matrix.label }}${{ matrix.ext }}" + mv "packaging/dist/meshterm${{ matrix.ext }}" "$out" + # A checksum beside the binary, so anyone can tell they got what we built. + if command -v sha256sum > /dev/null; then + sha256sum "$out" > "$out.sha256" + else + shasum -a 256 "$out" > "$out.sha256" + fi + cat "$out.sha256" + + - uses: actions/upload-artifact@v4 + with: + name: meshterm-${{ matrix.label }} + path: | + meshterm-* + if-no-files-found: error diff --git a/CHANGELOG.md b/CHANGELOG.md index 927d583..494f665 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -26,6 +26,11 @@ allowed to change behaviour, not just add to it. it on purpose and types the version. - A security policy, a code of conduct, issue and pull request templates, weekly dependency updates, and the funding links the app's own support page already offers. +- Standalone builds. A PyInstaller spec and a workflow that builds a single runnable + file for Windows, macOS (Intel and Apple silicon) and Linux (x64 and ARM64), checks + each one runs from outside the source tree, and writes a checksum beside it. Nothing + is published; the files are workflow artifacts until someone attaches them to a + release. ## [0.2.0] — 2026-09-07 @@ -49,6 +54,8 @@ deliberately not reconstructed here. which is the only handle a tile operator has on a client. - `macOS` and `Bluetooth` are spelled one way across the project. `BLE` stays where it is an identifier — the transport name, the config keys, the CLI. +- `meshterm --help` opens with the same description as the package summary and the + PyPI page, instead of a fourth wording of its own. ### Fixed diff --git a/meshterm/cli.py b/meshterm/cli.py index d354948..bed0e65 100644 --- a/meshterm/cli.py +++ b/meshterm/cli.py @@ -68,7 +68,13 @@ app = typer.Typer( # section panels flattened to plain headings by _unframe_help_panels() above — a # splash of colour, none of the framing. rich_markup_mode="rich", - help="MeshTerm — a modern toolkit for tuning and exploring your MeshCore mesh", + # The one description, same as the package summary and the PyPI page. See + # `meshterm.__doc__` — if this drifts from that, one of them is lying. + help=( + "MeshTerm is a full-featured TUI-based MeshCore client for your terminal. " + "Supports USB, Bluetooth and TCP companion connection. " + "For Windows, macOS and Linux." + ), ) # The context built by the callback and consumed by subcommands within one process. diff --git a/packaging/entry.py b/packaging/entry.py new file mode 100644 index 0000000..efc9f5e --- /dev/null +++ b/packaging/entry.py @@ -0,0 +1,22 @@ +"""Launcher for the frozen builds. + +PyInstaller freezes a *script*, not a console-script entry point, so this is the script: +it does what the ``meshterm`` command does and nothing else. Kept in ``packaging/`` +rather than in the package, because it exists for the installers and has no business +being importable. +""" + +from __future__ import annotations + +import multiprocessing +import sys + +if __name__ == "__main__": + # Windows and macOS spawn child processes by re-running this executable. Without + # this call a frozen app that ever starts one forks a second copy of the whole UI + # instead, which looks like the app launching itself over and over. + multiprocessing.freeze_support() + + from meshterm.cli import main + + sys.exit(main()) diff --git a/packaging/meshterm.spec b/packaging/meshterm.spec new file mode 100644 index 0000000..6be50f7 --- /dev/null +++ b/packaging/meshterm.spec @@ -0,0 +1,67 @@ +# PyInstaller spec for the downloadable builds. Run from the repository root: +# +# pyinstaller packaging/meshterm.spec +# +# One file, console mode. Console is not a detail: MeshTerm *is* a terminal program, and +# a windowed build would start with nowhere to draw and exit immediately. +# +# Built on the machine it targets. There is no cross-compiling here — the Windows build +# comes off a Windows runner, the macOS one off macOS. That is what the workflow is for. + +from PyInstaller.utils.hooks import collect_submodules + +# The assets have to land at `meshterm/assets`, because `ui/about.py` finds them with +# `Path(__file__).parent.parent / "assets"` and that path has to keep resolving inside +# the bundle exactly as it does in a checkout. +datas = [ + ("../meshterm/assets", "meshterm/assets"), +] + +hiddenimports = [ + # bleak picks its backend at runtime by platform, so static analysis never sees the + # one that actually gets used. Collect all of them and let the unused ones sit. + *collect_submodules("bleak.backends"), + # Same story for the companion library's transports. + *collect_submodules("meshcore"), + # Rich and prompt_toolkit both reach for things dynamically. + "rich.console", + "prompt_toolkit.output.win32", + "prompt_toolkit.output.vt100", +] + +a = Analysis( + ["entry.py"], + pathex=[".."], + binaries=[], + datas=datas, + hiddenimports=hiddenimports, + hookspath=[], + hooksconfig={}, + runtime_hooks=[], + # Nothing here is used, and each one drags in a GUI toolkit or a test framework. + excludes=["tkinter", "pytest", "IPython", "matplotlib", "numpy", "PIL"], + noarchive=False, +) + +pyz = PYZ(a.pure) + +exe = EXE( + pyz, + a.scripts, + a.binaries, + a.datas, + [], + name="meshterm", + debug=False, + bootloader_ignore_signals=False, + strip=False, + # UPX is off deliberately: it saves a few megabytes and gets the result flagged by + # antivirus often enough that it is not a trade worth making for a first release. + upx=False, + console=True, + disable_windowed_traceback=False, + argv_emulation=False, + target_arch=None, + codesign_identity=None, + entitlements_file=None, +)