build: bundle matplotlib+pillow in release binaries (plots work out-of-box)

CI builds desktop binaries with NETSIM_WITH_PLOTS=1 (pip install matplotlib
pillow) so 'run plots/gif/viz' work with no setup; adds a 'run plots' smoke
test (MPLBACKEND=Agg). Trade-off: binaries ~80MB vs ~8-20MB. Android APK
unaffected (uses canvas charts). Docs + spec comment updated.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: diagonalciso

.github/workflows/build.yml

@@ -33,10 +33,17 @@ jobs:
       - uses: actions/setup-python@v5
         with:
           python-version: "3.12"
-      - run: pip install pyinstaller
-      - run: pyinstaller netsim.spec --clean --noconfirm
-      - name: smoke test
+      - run: pip install pyinstaller matplotlib pillow
+      - name: build (matplotlib/pillow folded in so plot demos work out-of-box)
+        run: pyinstaller netsim.spec --clean --noconfirm
+        env:
+          NETSIM_WITH_PLOTS: "1"
+      - name: smoke test — core
         run: ${{ matrix.binpath }} bakeoff --cc reno,bbr --time 4
+      - name: smoke test — bundled plotting
+        run: ${{ matrix.binpath }} run plots
+        env:
+          MPLBACKEND: Agg
       - name: rename to unique asset name
         shell: bash
         run: mv "${{ matrix.binpath }}" "dist/${{ matrix.artifact }}"

PACKAGING.md

@@ -23,9 +23,10 @@ is what each one is, in everyday language.
 ### The desktop programs (pick the one for your computer)
 
 These four files are the **same program**, each compiled for a different kind of
-computer. They are *self-contained*: the Python language runtime is baked inside,
-so you do **not** need to install Python or anything else. Download, allow it to
-run, done.
+computer. They are *self-contained*: the Python language runtime **and** the
+plotting library (matplotlib) are baked inside, so you do **not** need to install
+Python or anything else — even the chart-drawing demos work immediately. Download,
+allow it to run, done. (That bundled library is why each download is ~80 MB.)
 
 | If your computer is… | Download this file | What "x86_64 / arm64" means |
 |----------------------|--------------------|------------------------------|
@@ -43,6 +44,8 @@ arguments tip-of-the-day style, or give it a command:
 
 - `list` — show all the built-in demonstrations.
 - `run m3` — run demo #3 (the TCP "sawtooth"); `m1`…`m16` are available.
+- `run plots` / `run gif` / `run viz` — render the figures/animation (matplotlib
+  is bundled in the binaries, so these work with no setup).
 - `bakeoff …` — a configurable experiment comparing congestion-control
   algorithms (see Part 4).
 - `web` — start a small website on your own machine (`http://127.0.0.1:8112`)
@@ -184,15 +187,21 @@ is why CI builds each platform on its own runner.
 ```bash
 pip install pyinstaller
 pyinstaller netsim.spec --clean --noconfirm
-./dist/netsim list                  # Linux/macOS -> dist/netsim  (~7-20 MB)
+./dist/netsim list                  # Linux/macOS -> dist/netsim  (~7-20 MB, no plots)
 dist\netsim.exe list                # Windows     -> dist\netsim.exe
 ```
 
-Fold the plotting demos into the binary too (much bigger — pulls in matplotlib):
+A plain local build (above) excludes matplotlib to stay small, so `run
+plots`/`gif`/`viz` won't work in it. The **published release binaries** are
+instead built with `NETSIM_WITH_PLOTS=1`, which folds matplotlib + pillow in so
+the plotting demos work out of the box (at the cost of a larger ~80 MB file).
+Reproduce that locally:
 
 ```bash
+pip install pyinstaller matplotlib pillow
 NETSIM_WITH_PLOTS=1 pyinstaller netsim.spec --clean --noconfirm     # Linux/macOS
 set NETSIM_WITH_PLOTS=1 && pyinstaller netsim.spec --clean --noconfirm  # Windows
+./dist/netsim run plots             # now works -> plots/*.png
 ```
 
 ### Android APK — Chaquopy
@@ -230,9 +239,10 @@ that starts with `v` (e.g. `v1.0.1`) it:
    `windows-latest` → `netsim-windows-x86_64.exe`,
    `macos-latest` → `netsim-macos-arm64`,
    `macos-13` → `netsim-macos-x86_64`.
-   Each binary is renamed to its unique asset name before upload (Linux and macOS
-   both produce a file literally called `netsim`, which would otherwise collide
-   on the Release).
+   Each is built with `NETSIM_WITH_PLOTS=1` (matplotlib + pillow folded in) and a
+   plotting smoke-test (`run plots`) before upload, and renamed to its unique
+   asset name (Linux and macOS both produce a file literally called `netsim`,
+   which would otherwise collide on the Release).
 2. **builds and signs the Android APK** in a separate `android` job (gated on the
    repo variable `BUILD_ANDROID` plus the keystore secrets — see below). This job
    is independent, so it never blocks the desktop release.

README.md

@@ -67,7 +67,10 @@ Pre-built, **single-file, zero-dependency** binaries are attached to every
 [GitHub Release](https://github.com/diagonalciso/netsim/releases/latest). Pick
 the one for your platform, mark it executable, and run it. There is nothing to
 install — the Python runtime is baked into the binary by PyInstaller (desktop)
-or Chaquopy (Android).
+or Chaquopy (Android). The desktop binaries also bundle **matplotlib + pillow**,
+so the plotting demos (`run plots`, `run gif`, `run viz`) work out of the box
+with no extra setup (this is why the desktop downloads are ~80 MB rather than a
+few MB).
 
 | Platform | Asset | Notes |
 |----------|-------|-------|
@@ -145,7 +148,9 @@ pip install -e '.[plots]'       # + matplotlib/pillow for viz/plots/gif demos
 ```
 
 The plotting demos (`viz`, `plots`, `gif`) are the **only** things that need a
-third-party package. Keep matplotlib in a venv so the core stays dependency-free:
+third-party package (the pre-built binaries already bundle it; this only applies
+when running from source). Keep matplotlib in a venv so the core stays
+dependency-free:
 
 ```bash
 python3 -m venv .venv && .venv/bin/pip install matplotlib pillow

netsim.spec

@@ -4,9 +4,11 @@
 #   pyinstaller netsim.spec            # -> dist/netsim   (or dist/netsim.exe)
 #
 # The examples/ dir is bundled as data so `netsim run mN` works inside the
-# frozen binary. matplotlib is NOT collected by default (keeps the binary
+# frozen binary. matplotlib is NOT collected by default (keeps a local build
 # small + the stdlib demos work everywhere); build with NETSIM_WITH_PLOTS=1
-# to fold matplotlib/pillow in for the viz/plots/gif demos.
+# to fold matplotlib/pillow in for the viz/plots/gif demos. The CI release
+# binaries ARE built with NETSIM_WITH_PLOTS=1, so the published downloads have
+# the plotting demos working out of the box (at the cost of a larger file).
 import os
 from PyInstaller.utils.hooks import collect_all