wxPython Wagons: Update build instructions

Author: davidfstr

doc/how_to_make_wxpython_wagon.md

@@ -146,7 +146,7 @@ sed -i 's/from urllib import urlopen/from urllib.request import urlopen/' $WAGON
 ```bash
 # Compile wagon
 cd /usr/src  # shared folder with Docker host
-time wagon create wxPython==4.2.4  # use version from pyproject.toml
+time wagon create wxPython==4.2.5  # use version from pyproject.toml
     # real  81m6.382s (Python 3.9)
     # real  ~80m+ (Python 3.12.9)
     # real  ~80m+ (Python 3.13.5)
@@ -156,11 +156,11 @@ time wagon create wxPython==4.2.4  # use version from pyproject.toml
 If using a locally built Python from source:
 
 ```bash
-time ./python -m wagon create wxPython==4.2.4  # use version from pyproject.toml
+time ./python -m wagon create wxPython==4.2.5  # use version from pyproject.toml
 ```
 
 * Upload the .wgn file as a release artifact to a release tag on GitHub,
-  such as the [v1.4.0b tag](https://github.com/davidfstr/Crystal-Web-Archiver/releases/tag/v1.4.0b)
+  such as the [v1.5.0b tag](https://github.com/davidfstr/Crystal-Web-Archiver/releases/tag/v1.5.0b)
 
 * Copy the URL for that .wgn to ci.yaml, replacing the old .wgn
 
@@ -170,3 +170,31 @@ time ./python -m wagon create wxPython==4.2.4  # use version from pyproject.toml
 * Ensure the job completes successfully. In particular ensure that the
   "Install dependency wxPython from wagon" step does successfully install
   and the "Install remaining dependencies with Poetry" step does not timeout.
+
+### Troubleshooting: Building wxPython < 4.2.5
+
+wxPython versions before 4.2.5 have a build incompatibility with setuptools >= 81.
+The symptom is a `TypeError` during the wheel packaging step (after compilation
+succeeds):
+
+```
+File "<string>", line 249, in wx_copy_file
+TypeError: copy_file() takes from 2 to 7 positional arguments but 8 were given
+```
+
+This was fixed in wxPython 4.2.5 (commit 1dec4c8, Feb 6, 2026) which updated
+the monkey-patched `copy_file` and `copy_tree` functions in `setup.py` to match
+the new distutils API.
+
+Note that pip creates an **isolated build environment** (per PEP 517) and
+downloads the latest setuptools from PyPI into it, regardless of what setuptools
+version is installed globally. So simply running `pip install "setuptools<81"`
+before building will **not** help.
+
+If you must build wxPython < 4.2.5, an **untested** workaround is to disable
+pip's build isolation so it uses a globally pinned older setuptools:
+
+```bash
+pip install "setuptools<81" wheel
+pip wheel wxPython==4.2.4 --no-build-isolation --no-cache-dir
+```

doc/how_to_make_wxpython_wagon/build_wagon_py314_wx425.sh

@@ -0,0 +1,54 @@
+#!/bin/bash
+set -e
+
+echo "========================================="
+echo "Building wxPython wagon for aarch64"
+echo "========================================="
+
+echo "Architecture check:"
+uname -m
+
+echo ""
+echo "Installing build dependencies..."
+apt-get update
+apt-get install -y build-essential zlib1g-dev libncurses5-dev libgdbm-dev libnss3-dev libssl-dev libsqlite3-dev libreadline-dev libffi-dev curl libbz2-dev wget libgtk-3-dev
+
+echo ""
+echo "Building Python 3.14 from source..."
+cd /tmp
+curl -O https://www.python.org/ftp/python/3.14.0/Python-3.14.0.tar.xz
+tar -xf Python-3.14.0.tar.xz
+cd Python-3.14.0
+echo "Configure..."
+./configure
+echo "Compile (this will take a few minutes)..."
+make -j4
+make install
+
+echo ""
+echo "Python version:"
+python3.14 --version
+
+echo ""
+echo "Installing pip..."
+curl -O https://bootstrap.pypa.io/get-pip.py
+python3.14 get-pip.py
+
+echo ""
+echo "Installing wagon..."
+python3.14 -m pip install wagon[dist]
+
+echo ""
+echo "Patching wagon for Python 3.14+..."
+WAGON_PATH=/usr/local/lib/python3.14/site-packages/wagon.py
+sed -i 's/from urllib.request import URLopener/from urllib.request import urlopen/' $WAGON_PATH
+sed -i 's/from urllib import urlopen/from urllib.request import urlopen/' $WAGON_PATH
+
+echo ""
+echo "Building wxPython wagon (this will take 30-60 minutes)..."
+cd /usr/src
+python3.14 -m wagon create wxPython==4.2.5
+
+echo ""
+echo "Build complete!"
+ls -lh /usr/src/*.wgn