turbo-ext: build the shared core and the per-version extension with make SPLIT=1

`make SPLIT=1` builds phpstan_turbo_core.so (everything but the four
version-specific sources) and a phpstan_turbo.so linked against it, which
finds it next to itself ($ORIGIN, @loader_path); `make SPLIT=1 extension`
links only the extension against a core already in place, which is what a
per-PHP-version CI leg does. `make pgo` and `make strip` handle the pair; a
plain `make` (and the phpize build) still produce the one self-contained
extension.

The boundary is functions only — pt_abi, pt_globals and pt_type_op_infos
are reached through accessors from the version-specific side, since a
Windows DLL can delay-load functions but not data — and main.cpp is
version-specific like Abi/Shadow/TrustedTypes. The extension refuses a
core of another version: it registers nothing and reports "core-mismatch",
which TurboExtensionEnabler rejects. On Windows it loads the core from its
own directory in get_module() (PHP loads extensions with plain
LoadLibrary, which would search the application's directory instead), and
zend_is_true() goes through pt_abi there (no assembler names on MSVC).

Verified in the CI images: a PGO+LTO core built in the 8.5 image (6.73 MB
stripped) with extensions built against it in the 8.3, 8.4, 8.6 and 8.6
ZTS images (68 KB each): smoke.php ALL OK on each; a version-mismatched
pair reports core-mismatch and stays inactive. macOS: the same via make
SPLIT=1, ALL OK on 8.5.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017h1GfB7vfJPgwcTHD9Fth6

Author: ondrejmirtes

turbo-ext/Makefile

@@ -207,17 +207,81 @@ CXXFLAGS += $(PGO_FLAGS)
 SOURCES := $(wildcard src/*.cpp) $(wildcard src/parser/*.cpp)
 OBJECTS := $(SOURCES:.cpp=.o)
 
+# The shared core and the per-PHP-version extension (README.md, "Shared
+# core"). The sources below are the only ones compiled against a PHP
+# version's own layout; every other object compiles to the same code against
+# each supported version's headers (bin/shared-core/gate-*.sh proves it), so
+# it is built once per platform into the core. TerminateHandler.cpp goes into
+# both: each links libstdc++ in statically.
+SHIM_SOURCES := src/Abi.cpp src/Shadow.cpp src/TrustedTypes.cpp src/main.cpp
+SHIM_OBJECTS := $(SHIM_SOURCES:.cpp=.o) src/TerminateHandler.o
+CORE_OBJECTS := $(filter-out $(SHIM_SOURCES:.cpp=.o),$(OBJECTS))
+CORE_LIB := phpstan_turbo_core.so
+
+# `make SPLIT=1` builds the pair — phpstan_turbo_core.so and a
+# phpstan_turbo.so loading it from its own directory — instead of the one
+# self-contained phpstan_turbo.so a plain `make` (and the phpize build)
+# produces; main.cpp then checks the core's version at startup
+ifeq ($(SPLIT),1)
+CXXFLAGS += -DPHPSTANTURBO_SPLIT
+endif
+
+ifeq ($(UNAME_S),Darwin)
+CORE_LINK_FLAGS := -install_name @loader_path/$(CORE_LIB)
+EXTENSION_LINK_FLAGS :=
+else
+# --exclude-libs: the statically folded libstdc++ stays out of the dynamic
+# symbol tables of both, so neither binds the other's copy
+CORE_LINK_FLAGS := -Wl,-soname,$(CORE_LIB) -Wl,--exclude-libs,ALL
+EXTENSION_LINK_FLAGS := -Wl,-rpath,'$$ORIGIN' -Wl,--exclude-libs,ALL
+endif
+
+# the symbols a shared object exports — a stripped one keeps only its
+# dynamic table on ELF
+ifeq ($(UNAME_S),Darwin)
+NM_EXPORTS := nm -g
+else
+NM_EXPORTS := nm -D --defined-only
+endif
+
 # the objects alone — what bin/shared-core/gate-*.sh compare between the PHP
 # versions' headers
 objects: $(OBJECTS)
 .PHONY: objects
 
+# a shared object links with undefined symbols allowed (the engine's are
+# resolved at load time), so a helper declared but never defined only
+# surfaces as a jump to NULL at run time — fail the build instead; the
+# extension's may come from the core, which must then export them
+define pt_check_undefined
+	@undefined=$$(nm -u $(1) | grep -E 'pt_[a-z_]+|phpstanturbo' | awk '{print $$NF}' | while read -r sym; do \
+		if [ -n "$(2)" ] && $(NM_EXPORTS) $(2) 2>/dev/null | awk '$$2 != "U" {print $$3}' | grep -qx "$$sym"; then continue; fi; \
+		echo "$$sym"; done); \
+	if [ -n "$$undefined" ]; then echo "undefined extension symbols in $(1):"; echo "$$undefined"; rm -f $(1); exit 1; fi
+endef
+
+ifeq ($(SPLIT),1)
+phpstan_turbo.so: $(SHIM_OBJECTS) $(CORE_LIB)
+	$(CXX) `$(PHP_CONFIG) --ldflags` -shared $(LTO_FLAGS) $(LINK_FLAGS) $(EXTENSION_LINK_FLAGS) $(PGO_FLAGS) -o $@ $(SHIM_OBJECTS) $(CORE_LIB)
+	$(call pt_check_undefined,$@,$(CORE_LIB))
+else
 phpstan_turbo.so: $(OBJECTS)
 	$(CXX) `$(PHP_CONFIG) --ldflags` -shared $(LTO_FLAGS) $(LINK_FLAGS) $(PGO_FLAGS) -o $@ $(OBJECTS)
-	@# a shared object links with undefined symbols allowed (the engine's are
-	@# resolved at load time), so a helper declared but never defined only
-	@# surfaces as a jump to NULL at run time — fail the build instead
-	@if nm -u $@ | grep -E 'pt_[a-z_]+|phpstanturbo' > /dev/null; then echo "undefined extension symbols in $@:"; nm -u $@ | grep -E 'pt_[a-z_]+|phpstanturbo'; rm -f $@; exit 1; fi
+	$(call pt_check_undefined,$@,)
+endif
+
+$(CORE_LIB): $(CORE_OBJECTS)
+	$(CXX) `$(PHP_CONFIG) --ldflags` -shared $(LTO_FLAGS) $(LINK_FLAGS) $(CORE_LINK_FLAGS) $(PGO_FLAGS) -o $@ $(CORE_OBJECTS)
+	$(call pt_check_undefined,$@,)
+
+# the extension alone, against a $(CORE_LIB) already in place (built for
+# another PHP version, by the CI job building the platform's core): the
+# per-version CI legs compile only $(SHIM_SOURCES)
+extension: $(SHIM_OBJECTS)
+	@test -f $(CORE_LIB) || { echo "$(CORE_LIB) is missing — build it, or put the platform's core here"; exit 1; }
+	$(CXX) `$(PHP_CONFIG) --ldflags` -shared $(LTO_FLAGS) $(LINK_FLAGS) $(EXTENSION_LINK_FLAGS) $(PGO_FLAGS) -o phpstan_turbo.so $(SHIM_OBJECTS) $(CORE_LIB)
+	$(call pt_check_undefined,phpstan_turbo.so,$(CORE_LIB))
+.PHONY: extension
 
 # The distributed binaries ship without symbol tables: a quarter of the .so
 # (2.4 MB on Linux, 3.2 MB on macOS) that the loader never reads, since the
@@ -228,9 +292,9 @@ phpstan_turbo.so: $(OBJECTS)
 strip:
 	@test -f phpstan_turbo.so || { echo "phpstan_turbo.so is missing — build it first"; exit 1; }
 ifeq ($(UNAME_S),Darwin)
-	strip -x phpstan_turbo.so
+	strip -x phpstan_turbo.so $(wildcard $(CORE_LIB))
 else
-	strip --strip-unneeded phpstan_turbo.so
+	strip --strip-unneeded phpstan_turbo.so $(wildcard $(CORE_LIB))
 endif
 
 # every object depends on every header: the op tables and the trait helper
@@ -240,7 +304,7 @@ HEADERS := $(wildcard src/*.h) $(wildcard src/generated/*.h)
 src/%.o: src/%.cpp $(HEADERS)
 	$(CXX) $(CXXFLAGS) -c -o $@ $<
 
-src/main.o: version.stamp
+src/main.o src/Core.o: version.stamp
 
 version.stamp: FORCE
 	@echo '$(PHPSTANTURBO_VERSION)' | cmp -s - $@ 2>/dev/null || echo '$(PHPSTANTURBO_VERSION)' > $@
@@ -262,7 +326,7 @@ pgo:
 	$(MAKE) pgo-clean
 	$(MAKE) PGO_FLAGS="$(PGO_GEN_FLAGS)" phpstan_turbo.so
 	PGO_DIR="$(PGO_DIR)" bin/pgo-train.sh
-	rm -f $(OBJECTS) phpstan_turbo.so
+	rm -f $(OBJECTS) phpstan_turbo.so $(CORE_LIB)
 ifeq ($(CXX_IS_CLANG),1)
 	$(LLVM_PROFDATA) merge -output=$(PGO_DIR)/turbo.profdata $(PGO_DIR)/*.profraw
 endif
@@ -273,7 +337,7 @@ endif
 LLVM_PROFDATA ?= $(shell command -v llvm-profdata 2>/dev/null || (command -v xcrun > /dev/null 2>&1 && echo "xcrun llvm-profdata") || ls /usr/bin/llvm-profdata-* 2>/dev/null | sort -V | tail -1)
 
 pgo-clean:
-	rm -f $(OBJECTS) phpstan_turbo.so version.stamp
+	rm -f $(OBJECTS) phpstan_turbo.so $(CORE_LIB) version.stamp
 	rm -rf $(PGO_DIR)
 	find src -name '*.gcda' -delete
 

turbo-ext/src/Abi.cpp

@@ -372,4 +372,5 @@ void pt_abi_init()
 	pt_abi.stream_free = abi_stream_free;
 	pt_abi.stream_read = abi_stream_read;
 	pt_abi.run_on_fresh_stack = abi_run_on_fresh_stack;
+	pt_abi.is_true = [](const zval *op) -> bool { return zend_is_true((zval *) op); };
 }

turbo-ext/src/Core.cpp

@@ -10,10 +10,35 @@
 #include "support.h"
 #include "reg.h"
 #include "Engine.h"
+#include "version.h"
 
 #include <vector>
 
-PT_CORE_API pt_abi_globals pt_abi;
+pt_abi_globals pt_abi;
+
+/* the core's data, for the version-specific library: through functions,
+ * since a Windows DLL can delay-load functions only */
+PT_CORE_API pt_abi_globals *pt_core_abi()
+{
+	return &pt_abi;
+}
+
+PT_CORE_API pt_globals_t *pt_core_globals()
+{
+	return &pt_globals;
+}
+
+PT_CORE_API const pt_type_op_info *pt_core_type_op_infos()
+{
+	return pt_type_op_infos;
+}
+
+/* the version the core was built at — the extension refuses a core of
+ * another version (main.cpp) */
+PT_CORE_API const char *pt_core_version()
+{
+	return PHPSTANTURBO_VERSION;
+}
 
 /* the PT_MINIT_REGISTRATION() functions of every file, in name order; a
  * constant-initialized pointer, so it is null before any of the file-static

turbo-ext/src/TypeOps.h

@@ -181,7 +181,11 @@ struct pt_type_op_info
 	uint8_t argKinds; /* two bits per argument, argument 0 in the low bits */
 };
 
-PT_CORE_API extern const pt_type_op_info pt_type_op_infos[PT_OP_COUNT];
+extern const pt_type_op_info pt_type_op_infos[PT_OP_COUNT];
+PT_CORE_API const pt_type_op_info *pt_core_type_op_infos();
+#ifdef PHPSTANTURBO_ABI_IMPL
+#define pt_type_op_infos (pt_core_type_op_infos())
+#endif
 
 constexpr uint8_t pt_type_op_kinds(pt_type_op_arg a0 = PT_OPARG_ANY, pt_type_op_arg a1 = PT_OPARG_ANY)
 {

turbo-ext/src/abi.h

@@ -66,7 +66,11 @@
  * hidden. The dependency only runs that way — the core never references a
  * symbol of the version-specific library. */
 #if defined(_WIN32)
+#ifdef PHPSTANTURBO_CORE_BUILD
+#define PT_CORE_API __declspec(dllexport)
+#else
 #define PT_CORE_API
+#endif
 #else
 #define PT_CORE_API __attribute__((visibility("default")))
 #endif
@@ -169,10 +173,18 @@ struct pt_abi_globals
 	/* pt_engine_run_on_fresh_stack(): a fiber context, its switch and a
 	 * zend_try around the body (8.6 moved SETJMP to sigsetjmp) */
 	void (*run_on_fresh_stack)(void (*body)(void *), void *data);
+	/* zend_is_true() where the declaration cannot be renamed (MSVC, below) */
+	bool (*is_true)(const zval *op);
 };
 
-/* Defined by the shared core, filled by the version-specific library. */
-PT_CORE_API extern pt_abi_globals pt_abi;
+/* Defined by the shared core, filled by the version-specific library, which
+ * reaches it through pt_core_abi() (abi.h's PHPSTANTURBO_ABI_IMPL block) */
+extern pt_abi_globals pt_abi;
+PT_CORE_API pt_abi_globals *pt_core_abi();
+PT_CORE_API const char *pt_core_version();
+#ifdef PHPSTANTURBO_ABI_IMPL
+#define pt_abi (*pt_core_abi())
+#endif
 
 /* fills pt_abi from the running engine; first thing MINIT (and, in ZTS
  * builds, RINIT) does — version-specific (Abi.cpp) */
@@ -583,6 +595,10 @@ static zend_always_inline bool pt_abi_object_is_lazy(const zend_object *obj)
 #define PT_ABI_SYMBOL_STR(prefix, name) PT_ABI_SYMBOL_STR2(prefix, name)
 extern "C" ZEND_API bool ZEND_FASTCALL pt_abi_zend_is_true(const zval *op) __asm__(PT_ABI_SYMBOL_STR(__USER_LABEL_PREFIX__, zend_is_true));
 #define zend_is_true(op) pt_abi_zend_is_true(op)
+#else
+/* MSVC has no assembler names for declarations: through Abi.cpp, which
+ * calls the running engine's own */
+#define zend_is_true(op) pt_abi.is_true(op)
 #endif
 #endif
 

turbo-ext/src/main.cpp

@@ -8,30 +8,19 @@
  * the boundary-economics rules in turbo-ext/README.md).
  */
 
+/* version-specific: the module entry carries the engine's API number */
+#define PHPSTANTURBO_ABI_IMPL
 #include "support.h"
 #include "reg.h"
 #include "Engine.h"
+#include "version.h"
 
 #ifdef PHP_WIN32
 #include <process.h>
 #else
 #include <unistd.h>
 #endif
 
-/* The short SHA of the last commit touching the watched set: baked from git
- * by the Makefile (quoted string passed directly), or from the VERSION.txt
- * the subsplit workflow commits into phpstan/turbo-ext; "dev" with neither,
- * which the enabler rejects. config.w32 and config.m4 pass the bare token as
- * PHPSTANTURBO_VERSION_RAW — quote characters do not survive the Windows
- * configure-to-nmake pipeline — and it is stringized here. */
-#ifdef PHPSTANTURBO_VERSION_RAW
-#define PT_VERSION_STR2(x) #x
-#define PT_VERSION_STR(x) PT_VERSION_STR2(x)
-#define PHPSTANTURBO_VERSION PT_VERSION_STR(PHPSTANTURBO_VERSION_RAW)
-#endif
-#ifndef PHPSTANTURBO_VERSION
-#define PHPSTANTURBO_VERSION "dev"
-#endif
 
 /* PHPStanTurbo\Runtime::configure() — cold-path configuration entry point.
  * TurboExtensionEnabler passes the generated class map (derived from the
@@ -138,11 +127,63 @@ static void ZEND_FASTCALL runtimeExitImmediately(INTERNAL_FUNCTION_PARAMETERS)
 	_exit(EG(exit_status));
 }
 
+/* Whether the shared core loaded next to this library carries the same
+ * version: a mismatched pair (a torn update of the distributed files) must
+ * never run together — the extension then registers nothing and reports
+ * the mismatch as its version, which TurboExtensionEnabler rejects, so
+ * PHPStan runs without it. */
+static bool pt_core_matches = false;
+
+extern "C" {
+extern zend_module_entry phpstan_turbo_module_entry;
+}
+
+#ifdef PHP_WIN32
+/* Windows searches the dependencies of a DLL loaded by full path in the
+ * application's directory, not the DLL's own, and PHP loads extensions with
+ * plain LoadLibrary(): the core is delay-loaded (config.w32) and loaded here
+ * by its full path, next to this DLL, before PHP calls anything that needs
+ * it — the delay-load helper then finds it already loaded by name. */
+#ifdef ZTS
+#define PT_CORE_DLL L"phpstan_turbo_core-zts.dll"
+#else
+#define PT_CORE_DLL L"phpstan_turbo_core.dll"
+#endif
+static bool pt_load_core()
+{
+	HMODULE self = NULL;
+	if (!GetModuleHandleExW(GET_MODULE_HANDLE_EX_FLAG_FROM_ADDRESS | GET_MODULE_HANDLE_EX_FLAG_UNCHANGED_REFCOUNT, (LPCWSTR) &pt_load_core, &self)) return false;
+	wchar_t path[4096];
+	DWORD length = GetModuleFileNameW(self, path, (DWORD) (sizeof(path) / sizeof(path[0])));
+	if (length == 0 || length >= sizeof(path) / sizeof(path[0])) return false;
+	wchar_t *slash = wcsrchr(path, L'\\');
+	size_t directory = slash != NULL ? (size_t) (slash - path) + 1 : 0;
+	size_t name = wcslen(PT_CORE_DLL);
+	if (directory + name + 1 > sizeof(path) / sizeof(path[0])) return false;
+	wmemcpy(path + directory, PT_CORE_DLL, name + 1);
+	return LoadLibraryExW(path, NULL, LOAD_WITH_ALTERED_SEARCH_PATH) != NULL;
+}
+static bool pt_core_loaded = false;
+#endif
+
 static PHP_MINIT_FUNCTION(phpstan_turbo)
 {
 #ifdef ZTS
 	ZEND_TSRMLS_CACHE_UPDATE();
 #endif
+#ifdef PHPSTANTURBO_SPLIT
+#ifdef PHP_WIN32
+	if (!pt_core_loaded) {
+		phpstan_turbo_module_entry.version = "core-missing";
+		return SUCCESS;
+	}
+#endif
+	if (strcmp(pt_core_version(), PHPSTANTURBO_VERSION) != 0) {
+		phpstan_turbo_module_entry.version = "core-mismatch";
+		return SUCCESS;
+	}
+#endif
+	pt_core_matches = true;
 	pt_abi_init();
 
 	static const reg::Arg returnsBool = reg::boolArg("");
@@ -163,13 +204,15 @@ static PHP_MINIT_FUNCTION(phpstan_turbo)
 
 static PHP_MSHUTDOWN_FUNCTION(phpstan_turbo)
 {
+	if (!pt_core_matches) return SUCCESS;
 	pt_core_mshutdown();
 
 	return SUCCESS;
 }
 
 static PHP_RINIT_FUNCTION(phpstan_turbo)
 {
+	if (!pt_core_matches) return SUCCESS;
 #ifdef ZTS
 	ZEND_TSRMLS_CACHE_UPDATE();
 	pt_abi_init();
@@ -182,6 +225,7 @@ static PHP_RINIT_FUNCTION(phpstan_turbo)
 
 static PHP_RSHUTDOWN_FUNCTION(phpstan_turbo)
 {
+	if (!pt_core_matches) return SUCCESS;
 	pt_core_rshutdown();
 
 	return SUCCESS;
@@ -212,6 +256,14 @@ zend_module_entry phpstan_turbo_module_entry = {
 	STANDARD_MODULE_PROPERTIES,
 };
 
+#if defined(PHP_WIN32) && defined(PHPSTANTURBO_SPLIT)
+ZEND_DLEXPORT zend_module_entry *get_module(void)
+{
+	pt_core_loaded = pt_core_loaded || pt_load_core();
+	return &phpstan_turbo_module_entry;
+}
+#else
 ZEND_GET_MODULE(phpstan_turbo)
+#endif
 
 }

turbo-ext/src/support.h

@@ -518,7 +518,11 @@ struct pt_globals_t {
 	char trusted_types_prefix[MAXPATHLEN + 16];
 };
 
-PT_CORE_API extern pt_globals_t pt_globals;
+extern pt_globals_t pt_globals;
+PT_CORE_API pt_globals_t *pt_core_globals();
+#ifdef PHPSTANTURBO_ABI_IMPL
+#define pt_globals (*pt_core_globals())
+#endif
 
 #define PT_G(v) (pt_globals.v)
 

turbo-ext/src/version.h

@@ -0,0 +1,19 @@
+#ifndef PHPSTANTURBO_VERSION_H
+#define PHPSTANTURBO_VERSION_H
+
+/* The short SHA of the last commit touching the watched set: baked from git
+ * by the Makefile (quoted string passed directly), or from the VERSION.txt
+ * the subsplit workflow commits into phpstan/turbo-ext; "dev" with neither,
+ * which the enabler rejects. config.w32 and config.m4 pass the bare token as
+ * PHPSTANTURBO_VERSION_RAW — quote characters do not survive the Windows
+ * configure-to-nmake pipeline — and it is stringized here. */
+#ifdef PHPSTANTURBO_VERSION_RAW
+#define PT_VERSION_STR2(x) #x
+#define PT_VERSION_STR(x) PT_VERSION_STR2(x)
+#define PHPSTANTURBO_VERSION PT_VERSION_STR(PHPSTANTURBO_VERSION_RAW)
+#endif
+#ifndef PHPSTANTURBO_VERSION
+#define PHPSTANTURBO_VERSION "dev"
+#endif
+
+#endif