Update documents to describe macos

.github/workflows/build.yml

@@ -104,7 +104,13 @@ jobs:
 
     strategy:
       matrix:
-        os: [macos-12, macos-14]  # macos-13 is an intel runner, macos-14 is apple silicon
+        # macos-14 is Apple silicon and we configure it to build only arm64 wheels.
+        # macos-13 and lower are an Intel runners and we configure them to build
+        # only x86_64 wheels.
+        # The macos-13 intel runner builds wheels that cause segfaults when executed on
+        # macos-11, so we build on macos-12. When we drop macos-11 support, we can
+        # drop macos-12 from the matrix and use macos-13 instead, assuming it works.
+        os: [macos-12, macos-14]
 
     steps:
       - uses: actions/checkout@v4
@@ -117,22 +123,25 @@ jobs:
           name: wheels-${{ matrix.os }}
           path: ./wheelhouse/*.whl
 
-  test_minimum_macos:
+  cross_check_macos:
     needs: [wheels_macos]
-    name: Test minimum macOS
-    runs-on: macos-11
+    name: Test Python x86_64 wheels on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [macos-11, macos-12, macos-13]
     steps:
       - uses: actions/checkout@v4
 
       - uses: actions/setup-python@v5
         name: Install Python
         with:
-          python-version: "3.9"
+          python-version: "3.8"
 
       - name: Download x86_64 wheels
         uses: actions/download-artifact@v4
         with:
-          name: wheels-macos-12  # download wheels produced by macos-12, the intel runner
+          name: wheels-${{ matrix.os }}  # download wheels produced by macos-12, the intel runner
           path: wheelhouse
 
       - name: Output downloads
@@ -141,7 +150,7 @@ jobs:
 
       - name: Install wheels
         run: |
-          WHEEL=wheelhouse/pikepdf*cp39*macos*x86_64.whl
+          WHEEL=wheelhouse/pikepdf*cp38*macos*x86_64.whl
           python -m pip install $WHEEL
           python -c "import pikepdf; print(pikepdf.__version__)"
 

docs/references/build.rst

@@ -42,16 +42,12 @@ but installing on a macos-12-x86_64 runner gives this error:
 
 (Same for MACOSX_DEPLOYMENT_TARGET="12.0").
 
-Thus, we have to pick a different value for this environment variable
-for the pikepdf. Clearly something is wrong here, but this unintuitive
-configuration is what works. When MACOSX_DEPLOYMENT_TARGET is not set
-pybind11's Pybind11Extension class examines other settings and should
-set -mmacosx-version-min=10.14 for when cxx_std=17.
+Setting SYSTEM_VERSION_COMPAT=0 will generate wheels with the correct
+target.
 
-Adding to confusion, the build logs from setuptools show that are
-targeting 10.9, and the wheels are generated for 10.9.
-
-There may be dragons here, still.
+macos-13 GitHub runners appear to be incapable of generating wheels that
+run on macos-11. macos-11 is past of end of life anyway, but this is
+an irritating complication.
 
 3. arm64. MACOSX_DEPLOYMENT_TARGET="11.0" is the minimum version for arm64.
 We set this to ensure that pikepdf builds for this target, and then

pyproject.toml

@@ -174,7 +174,10 @@ before-all = [
 [[tool.cibuildwheel.overrides]]
 select = "*-macosx*x86_64"
 inherit.environment = "append"
+# QPDF requires C++17 which is not fully supported on macOS < 11.0.
 environment.MACOSX_DEPLOYMENT_TARGET = "11.0"
+# When MACOSX_DEPLOYMENT_TARGET is >= 11.0, set this to 0
+# to ensure that pip/auditwheel generate the correct version stamp.
 environment.SYSTEM_VERSION_COMPAT = 0
 
 [[tool.cibuildwheel.overrides]]