ci: fail the build when cassandra.so has undeclared native dependencies

[CodeLieutenant]

Closes #117.

What was reported

Unable to load dynamic library 'cassandra.so' (Error relocating cassandra.so: __gmpz_cmp_ui: symbol not found) on Alpine. The reporter worked around it by renaming cassandra.ini so it sorted after gmp.ini.

Diagnosis

The module referenced libgmp's mpz_* symbols with no libgmp entry in DT_NEEDED. On the v1.3.x branch the reporter built, cmake/FindLibGMP.cmake attached gmp to ext_scylladb as a side effect of find_package, before the sub-libraries that use it existed.

That linkage bug is already gone on trunk — a build on Alpine 3.21 shows NEEDED libgmp.so.10, loads with php -n (ext/gmp never loaded), and round-trips Varint/Decimal correctly. This PR does not change the linking. It adds the guard, because nothing in CI could have caught the original bug and nothing stops it recurring.

Why CI could not catch it

PHP dlopens extensions with RTLD_LAZY|RTLD_GLOBAL (Zend/zend_portability.h):

• glibc binds lazily — an unresolved symbol is deferred until first call, so php -d extension=cassandra -m prints cassandra and exits 0 on a module that dies the moment a Varint is constructed.
• RTLD_GLOBAL — any earlier-loaded extension donates its symbols, so an ext/gmp that php.ini loaded first silently supplied them. That is exactly why the reporter's ini rename "fixed" it, and it is proof the NEEDED entry was absent.
• musl has no lazy binding — the identical file fails outright at dlopen. Hence Alpine-only reports while CI stayed green on Ubuntu.

The guard

scripts/check-module-symbols.sh: every undefined symbol in the built module must be provided by a library the module itself declares, or by the PHP binary. It consults nothing about the ambient process, so ini load order and the host's own libraries cannot mask a missing dependency.

That independence is load-bearing, not theoretical. My first attempt was LD_BIND_NOW=1 php -n alone; it passes on a broken module on Debian 13, because the php binary there links libgmp itself and satisfies the symbols from the process's global scope. The isolated load is kept as a second check since it catches things a symbol audit cannot (e.g. a broken MINIT), but it is not the guard.

Wired into verify-extension, run from the shared build action and inline in the PIE job (which does not go through CMake). Skipped under ASan, which needs its runtime LD_PRELOADed, and on macOS, which links extensions with -undefined dynamic_lookup.

Verification

Built in Docker both ways — as-is, and with LibGMP::LibGMP unlinked to re-create the fault:

Platform	Current tree	LibGMP::LibGMP unlinked
Alpine 3.21 / musl	512 symbols resolve, loads	caught, build fails
Debian 13 / glibc 2.41	507 symbols resolve, loads	caught, build fails
macOS arm64	skips audit, loads	n/a

In the failure case the linker accepts the broken .so and php -d extension=... -m still reports success on both libcs — the audit is what fails it.

Also: shellcheck clean, both YAML files parse, and removing the script makes the target fail rather than silently pass.

Note for reviewers

Considered and deliberately not included: an Alpine/musl CI job. It would add real coverage for musl-specific compile breakage, but it would not reliably catch this bug — with php.ini loaded, gmp.so resolves the symbols on Alpine too, as the table's middle column shows. That is a separate CI-time tradeoff worth deciding on its own merits.

[mergify]

Tick the box to add this pull request to the merge queue (same as @mergifyio queue).

• Queue this pull request