A build you can download and run without Python

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) <noreply@anthropic.com>
This commit is contained in:
Jean-Pierre MartineauandClaude Opus 5 committed 2026-09-07 05:00:22 -04:00
1 parent ab8ef2aa23
commit 4f60f44512
5 files changed
+196 -1

No files matched your search

+93
View File
@@ -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
+7
View File
@@ -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
+7 -1
View File
@@ -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.
+22
View File
@@ -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())
+67
View File
@@ -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,
)