STF-1287: Build and publish PIE precompiled binaries on tag

.github/dependabot.yml

@@ -0,0 +1,42 @@
+version: 2
+updates:
+  # Keeps the SHA-pinned `uses:` refs in release.yml current. Pinning by digest
+  # is what makes an action review-able; it is also what makes it go stale
+  # without something like this.
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+      day: monday
+      time: '14:00'
+    cooldown:
+      default-days: 7
+
+  # MaxMind-DB-Reader-php is the extension itself: its ext/ sources are what
+  # every lane compiles and what the release tarball ships. Tracking main here
+  # is deliberate -- a release bumps this pointer, and the pointer is what
+  # defines the release's contents.
+  - package-ecosystem: gitsubmodule
+    directory: /
+    schedule:
+      interval: weekly
+      day: monday
+      time: '14:00'
+    cooldown:
+      default-days: 7
+# Not covered by any ecosystem above, and so still bumped by hand:
+#
+#   - the digest-pinned php:*-cli-bookworm and php:*-zts-bookworm images, which
+#     live in a shell `case` in release.yml. Dependabot's docker ecosystem reads
+#     Dockerfiles and compose files, not image references inside a run: script.
+#   - the ubuntu:24.04 digest in the smoke job, for the same reason.
+#
+# Raising the Linux glibc floor means editing those digests, which is the point
+# of pinning them -- but nothing will remind us, so they are worth a look
+# whenever the PHP version list here changes.
+#
+# pie is not on that list: it is a mise tool, pinned and checksummed in
+# mise.lock. Dependabot has no mise ecosystem, so nothing bumps it until the
+# planned move to Renovate, whose mise manager understands the github: backend
+# -- and which could take the image digests above too, through a regex manager,
+# which is not something Dependabot can be configured into doing.

README.md

@@ -8,9 +8,29 @@ This is the C extension for MaxMind DB Reader, providing significantly faster IP
 pie install maxmind-db/reader-ext
 ```
 
+Precompiled binaries for common platforms are attached to each release, so on
+those platforms no compiler or library headers are needed. Elsewhere PIE falls
+back to building the extension from source.
+
+**PIE 1.4.0 or later is required.** Earlier versions do not understand a
+package that offers both a precompiled binary and a source fallback, and they
+do not all fail clearly about it: 1.3.8 through 1.3.13 quietly fetch an archive
+that contains no C sources, so the build fails with nothing pointing at the
+cause. Check with `pie --version`.
+
 ## Prerequisites
 
-The extension requires the libmaxminddb C library:
+None on the platforms with a precompiled binary — that is the point of them.
+
+When building from source, the extension needs libmaxminddb. It can compile the
+copy vendored in the source archive, which is what the precompiled binaries are
+built from and what CI tests:
+
+```bash
+pie install maxmind-db/reader-ext --with-maxminddb-bundled
+```
+
+Otherwise it links the libmaxminddb installed on the system:
 
 ### Ubuntu/Debian
 ```bash

composer.json

@@ -24,11 +24,15 @@
     "priority": 50,
     "support-zts": true,
     "support-nts": true,
-    "download-url-method": "pre-packaged-source",
+    "download-url-method": ["pre-packaged-binary", "pre-packaged-source"],
     "configure-options": [
       {
         "name": "with-maxminddb",
         "description": "Enable MaxMind DB Reader extension support"
+      },
+      {
+        "name": "with-maxminddb-bundled",
+        "description": "Build the bundled libmaxminddb sources into the extension instead of linking a system library"
       }
     ]
   }

dev-bin/build-ext.sh

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+#
+# Build maxminddb.so from the submodule's ext/ sources and record the fields the
+# published asset name is derived from. Used by both Unix lanes: on Linux inside
+# a digest-pinned container, on macOS directly on the runner. Windows builds
+# through php/php-windows-builder and does not run this.
+#
+# Usage: build-ext.sh <ext-dir> <out-dir>
+
+set -euo pipefail
+
+ext_dir="$1"
+out_dir="$2"
+
+# --with-maxminddb-bundled compiles libmaxminddb's vendored sources into the
+# extension so the published .so needs nothing but libc. config.m4 does refuse
+# this itself -- AC_MSG_ERROR on both a missing --with-maxminddb and missing
+# sources -- so this is not the only thing standing between us and a binary with
+# a dangling libmaxminddb dependency. It is worth keeping because it fires
+# before phpize and says so as a GitHub annotation rather than in autoconf
+# output partway down a job log.
+if [ ! -f "$ext_dir/libmaxminddb/src/maxminddb.c" ]; then
+    echo "::error::$ext_dir/libmaxminddb is missing. The submodule must point at a commit that supports --with-maxminddb-bundled."
+    exit 1
+fi
+
+mkdir -p "$out_dir"
+out_dir="$(cd "$out_dir" && pwd)" # absolute, because the build cd's away
+cd "$ext_dir"
+phpize
+./configure --with-maxminddb --with-maxminddb-bundled
+make -j"$(getconf _NPROCESSORS_ONLN 2>/dev/null || echo 2)"
+cp modules/maxminddb.so "$out_dir/maxminddb.so"
+
+# Record these as reported by the PHP that actually built the object, so the
+# asset filename cannot disagree with the binary inside it.
+php-config --version | cut -d. -f1,2 > "$out_dir/php-abi"
+php -r 'echo ZEND_THREAD_SAFE ? "-zts" : "";' > "$out_dir/ts-suffix"

dev-bin/collect-assets.sh

@@ -0,0 +1,68 @@
+#!/usr/bin/env bash
+#
+# Collect one release asset out of each staged artifact directory and assert
+# that the set is complete. Run by verify-assets on every run, and again by
+# publish immediately before it uploads, so a pull request exercises the same
+# assertion a release depends on.
+#
+# Usage: collect-assets.sh <dist-dir> <assets-dir>
+#
+# Reads TAG, PHP_VERSIONS, TS_MODES, LINUX_ARCHES and WINDOWS_COUNT.
+
+set -euo pipefail
+
+dist="$1"
+assets="$2"
+
+# shellcheck source=dev-bin/lib.sh
+. "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/lib.sh"
+
+find "$dist" -type f | sort
+
+# Every build job stages exactly one file at its artifact root. The Windows
+# action additionally stages a logs/ subdirectory, so select only files one
+# level below an artifact directory and leave the logs out of the release.
+mkdir -p "$assets"
+find "$dist" -mindepth 2 -maxdepth 2 -type f -exec cp -t "$assets/" {} +
+
+staged="$(find "$dist" -mindepth 2 -maxdepth 2 -type f | wc -l)"
+collected="$(find "$assets" -maxdepth 1 -type f | wc -l)"
+[ "$staged" -eq "$collected" ] ||
+    fail "Two artifacts contain the same filename ($staged staged, $collected collected)."
+
+# set -u does not fire on a set-but-empty variable, and arithmetic coerces one
+# to 0 -- so an empty WINDOWS_COUNT would quietly mean "expect no Windows
+# assets", and a release missing all of them would match the expectation and
+# ship. Require a count before using it as one.
+case "${WINDOWS_COUNT:-}" in
+'' | *[!0-9]*)
+    fail "WINDOWS_COUNT is '${WINDOWS_COUNT:-}', which is not a count."
+    ;;
+esac
+
+php_count="$(jq 'length' <<<"$PHP_VERSIONS")"
+ts_count="$(jq 'length' <<<"$TS_MODES")"
+arch_count="$(jq 'length' <<<"$LINUX_ARCHES")"
+# Linux (php x ts x arch) + macOS (php x ts).
+binary_count=$((php_count * ts_count * arch_count + php_count * ts_count))
+
+# 1 source tarball + the binary lanes + whatever the Windows matrix said it
+# would produce. Everything but WINDOWS_COUNT comes from setup, which is also
+# what each matrix expands, so the expectation cannot drift from what was built
+# -- including when setup hands out the reduced pull-request lists. WINDOWS_COUNT
+# comes from windows-matrix, which derives it from the matrix it emits.
+expected=$((1 + binary_count + WINDOWS_COUNT))
+
+echo "Expecting $expected assets, found $collected:"
+find "$assets" -maxdepth 1 -type f -printf '  %f\n' | sort
+
+# This assertion is the point of the job. A release that silently ships the
+# source tarball and zero binaries -- because an artifact glob matched nothing
+# -- looks successful and is not.
+[ "$collected" -eq "$expected" ] ||
+    fail "Expected $expected release assets but found $collected. Refusing to publish a partial release."
+
+# Named explicitly because every platform without a prebuilt binary depends on
+# this one file.
+[ -f "$assets/maxminddb-${TAG}.tgz" ] ||
+    fail "$assets/maxminddb-${TAG}.tgz is missing."