Vendor xerces (#12)

* build: bundle xerces-c as submodule and link statically

Adds third_party/xerces-c (pinned to tag v3.2.5; the xercesc_3_2 ABI
namespace is hard-coded across ORCA so the 3.3.x line cannot be used
without a source migration) and a new PG_ORCA_BUNDLED_XERCES CMake
option (default ON) that builds it as a static archive folded into
pg_orca.so. The system-xerces pkg-config / manual search path is kept
as a fallback when the option is set to OFF.

CPack deb/rpm drop the libxerces-c runtime dependency in bundled mode,
so the resulting package installs cleanly on hosts without an external
xerces-c (e.g. self-hosted Supabase, distroless containers).

* build: require bundled xerces for release deb/rpm packaging

CPackConfig.cmake now hard-errors when PG_ORCA_BUNDLED_XERCES=OFF, so
release packages can never accidentally ship with a runtime libxerces-c
dependency that may be absent on the target host (Ubuntu 24.04's t64
rename, RHEL 9, Supabase / distroless images). The previously
conditional deb/rpm Depends/Requires lines collapse to the bundled-only
form.

build-packages.sh passes -DPG_ORCA_BUNDLED_XERCES=ON explicitly so
stale cache values cannot disable bundling.

Author: yjhjstz

.github/workflows/build.yml

@@ -23,6 +23,8 @@ jobs:
 
     steps:
       - uses: actions/checkout@v5
+        with:
+          submodules: recursive
 
       - name: Add PostgreSQL apt repository (pgdg)
         run: |
@@ -95,6 +97,8 @@ jobs:
             perl perl-IPC-Run
 
       - uses: actions/checkout@v5
+        with:
+          submodules: recursive
 
       - name: Show toolchain versions
         run: |
@@ -161,6 +165,8 @@ jobs:
             git
 
       - uses: actions/checkout@v5
+        with:
+          submodules: recursive
 
       - name: Show toolchain versions
         run: |
@@ -208,6 +214,8 @@ jobs:
             perl perl-IPC-Run
 
       - uses: actions/checkout@v5
+        with:
+          submodules: recursive
 
       - name: Show toolchain versions
         run: |
@@ -258,6 +266,8 @@ jobs:
 
     steps:
       - uses: actions/checkout@v5
+        with:
+          submodules: recursive
 
       - name: Add PostgreSQL apt repository (pgdg)
         run: |
@@ -303,6 +313,8 @@ jobs:
 
     steps:
       - uses: actions/checkout@v5
+        with:
+          submodules: recursive
 
       - name: Install build dependencies
         run: |

.github/workflows/package.yml

@@ -14,6 +14,8 @@ jobs:
 
     steps:
       - uses: actions/checkout@v5
+        with:
+          submodules: recursive
 
       - name: Add PostgreSQL apt repository (pgdg)
         run: |

.gitmodules

@@ -0,0 +1,8 @@
+# Submodule pin: the recorded gitlink SHA below freezes xerces-c to a
+# specific commit (currently tag v3.2.5). The ABI namespace `xercesc_3_2`
+# is hard-coded throughout ORCA, so we cannot bump to the 3.3.x line
+# without a coordinated source change. Run `git submodule update --init
+# --recursive` after cloning.
+[submodule "third_party/xerces-c"]
+	path = third_party/xerces-c
+	url = https://github.com/apache/xerces-c

CMakeLists.txt

@@ -53,52 +53,106 @@ message(STATUS "  server headers: ${PG_SERVER_INCLUDEDIR}")
 message(STATUS "  pkglibdir:      ${PG_PKGLIBDIR}")
 
 # -------------------------------------------------------------------
-# xerces-c (needed by ORCA for DXL XML parsing)
-# Prefer pkg-config (works on Linux and Homebrew macOS); fall back to
-# manual find_library + find_path for installations without .pc files.
+# xerces-c (needed by ORCA for DXL XML parsing).
+#
+# Default on Linux: build the bundled submodule under third_party/xerces-c
+# as a static library folded into pg_orca.so. This makes the extension
+# self-contained — no runtime libxerces-c.so dependency — which matters
+# for the deb/rpm release packages (self-hosted Supabase, distroless
+# containers, hosts without a matching xerces-c package).
+#
+# Default on macOS: use Homebrew's xerces-c. Release packaging is
+# Linux-only; for macOS dev builds the system library is easier and
+# avoids quirks of the static build on the Apple toolchain.
+#
+# Override either way with -DPG_ORCA_BUNDLED_XERCES=ON/OFF.
 # -------------------------------------------------------------------
-find_package(PkgConfig QUIET)
-if(PKG_CONFIG_FOUND)
-    pkg_check_modules(XERCES xerces-c)
+if(APPLE)
+    set(_pg_orca_bundled_default OFF)
+else()
+    set(_pg_orca_bundled_default ON)
 endif()
+option(PG_ORCA_BUNDLED_XERCES
+    "Build xerces-c from third_party/ submodule and link statically"
+    ${_pg_orca_bundled_default})
 
-if(XERCES_FOUND)
-    # pkg-config succeeded — prefer absolute paths from XERCES_LINK_LIBRARIES so
-    # the linker doesn't need to search for it. On macOS Homebrew, xerces-c
-    # lives in /opt/homebrew/opt/xerces-c/lib which is not a default search
-    # path, so passing only "-lxerces-c" fails with "library not found".
-    if(XERCES_LINK_LIBRARIES)
-        set(XERCES_LIB ${XERCES_LINK_LIBRARIES})
-    else()
-        set(XERCES_LIB ${XERCES_LIBRARIES})
+if(PG_ORCA_BUNDLED_XERCES)
+    set(_xerces_src "${CMAKE_SOURCE_DIR}/third_party/xerces-c")
+    if(NOT EXISTS "${_xerces_src}/CMakeLists.txt")
+        message(FATAL_ERROR
+            "PG_ORCA_BUNDLED_XERCES=ON but ${_xerces_src}/CMakeLists.txt is "
+            "missing. Run: git submodule update --init --recursive")
     endif()
-    set(XERCES_INCLUDE ${XERCES_INCLUDE_DIRS})
-    message(STATUS "xerces-c (pkg-config): ${XERCES_LIB}")
+
+    # Force xerces options before adding its subdirectory. FORCE is required
+    # because xerces-c declares these with CACHE; without FORCE our values
+    # would be ignored on the second cmake run.
+    set(BUILD_SHARED_LIBS    OFF       CACHE BOOL   "" FORCE)
+    set(network              OFF       CACHE BOOL   "" FORCE)  # no socket-based entity resolver
+    set(transcoder           "gnuiconv" CACHE STRING "" FORCE) # use glibc iconv, not ICU
+    set(message-loader       "inmemory" CACHE STRING "" FORCE) # no external catalog files
+    set(threads              ON        CACHE BOOL   "" FORCE)
+    # Suppress xerces install rules; we never install its headers/libs.
+    set(CMAKE_SKIP_INSTALL_RULES_BACKUP "${CMAKE_SKIP_INSTALL_RULES}")
+    set(CMAKE_SKIP_INSTALL_RULES TRUE)
+    add_subdirectory(third_party/xerces-c EXCLUDE_FROM_ALL)
+    set(CMAKE_SKIP_INSTALL_RULES "${CMAKE_SKIP_INSTALL_RULES_BACKUP}")
+
+    set_target_properties(xerces-c PROPERTIES
+        POSITION_INDEPENDENT_CODE ON
+        CXX_VISIBILITY_PRESET     hidden
+        VISIBILITY_INLINES_HIDDEN ON)
+
+    # The xerces-c target propagates its include dirs as PUBLIC, so consumers
+    # only need to link to it. Keep XERCES_INCLUDE empty for the static path.
+    set(XERCES_LIB     xerces-c)
+    set(XERCES_INCLUDE "")
+    message(STATUS "xerces-c: bundled static build (third_party/xerces-c)")
 else()
-    # Fall back to manual search
-    find_library(XERCES_LIB xerces-c
-        PATHS
-            /opt/homebrew/opt/xerces-c/lib   # Apple Silicon Homebrew
-            /usr/local/opt/xerces-c/lib      # Intel Homebrew
-            /usr/local/lib                   # Linux generic
-            /usr/lib
-            /usr/lib/x86_64-linux-gnu        # Debian/Ubuntu amd64
-            /usr/lib/aarch64-linux-gnu       # Debian/Ubuntu arm64
-    )
-    find_path(XERCES_INCLUDE xercesc/util/XercesDefs.hpp
-        PATHS
-            /opt/homebrew/opt/xerces-c/include
-            /usr/local/opt/xerces-c/include
-            /usr/local/include
-            /usr/include
-    )
-    if(NOT XERCES_LIB OR NOT XERCES_INCLUDE)
-        message(FATAL_ERROR
-            "xerces-c not found. Install it (e.g. 'apt install libxerces-c-dev' "
-            "or 'brew install xerces-c') or set -DXERCES_LIB= and "
-            "-DXERCES_INCLUDE= manually.")
+    # Legacy path: find a system-installed xerces-c.
+    find_package(PkgConfig QUIET)
+    if(PKG_CONFIG_FOUND)
+        pkg_check_modules(XERCES xerces-c)
+    endif()
+
+    if(XERCES_FOUND)
+        # pkg-config succeeded — prefer absolute paths from XERCES_LINK_LIBRARIES
+        # so the linker doesn't need to search for it. On macOS Homebrew,
+        # xerces-c lives in /opt/homebrew/opt/xerces-c/lib which is not a
+        # default search path, so passing only "-lxerces-c" fails.
+        if(XERCES_LINK_LIBRARIES)
+            set(XERCES_LIB ${XERCES_LINK_LIBRARIES})
+        else()
+            set(XERCES_LIB ${XERCES_LIBRARIES})
+        endif()
+        set(XERCES_INCLUDE ${XERCES_INCLUDE_DIRS})
+        message(STATUS "xerces-c (pkg-config): ${XERCES_LIB}")
+    else()
+        find_library(XERCES_LIB xerces-c
+            PATHS
+                /opt/homebrew/opt/xerces-c/lib   # Apple Silicon Homebrew
+                /usr/local/opt/xerces-c/lib      # Intel Homebrew
+                /usr/local/lib                   # Linux generic
+                /usr/lib
+                /usr/lib/x86_64-linux-gnu        # Debian/Ubuntu amd64
+                /usr/lib/aarch64-linux-gnu       # Debian/Ubuntu arm64
+        )
+        find_path(XERCES_INCLUDE xercesc/util/XercesDefs.hpp
+            PATHS
+                /opt/homebrew/opt/xerces-c/include
+                /usr/local/opt/xerces-c/include
+                /usr/local/include
+                /usr/include
+        )
+        if(NOT XERCES_LIB OR NOT XERCES_INCLUDE)
+            message(FATAL_ERROR
+                "xerces-c not found. Install it (e.g. 'apt install libxerces-c-dev' "
+                "or 'brew install xerces-c'), set -DXERCES_LIB= and "
+                "-DXERCES_INCLUDE= manually, or use the default "
+                "-DPG_ORCA_BUNDLED_XERCES=ON to build from third_party/.")
+        endif()
+        message(STATUS "xerces-c (manual): ${XERCES_LIB}, headers: ${XERCES_INCLUDE}")
     endif()
-    message(STATUS "xerces-c (manual): ${XERCES_LIB}, headers: ${XERCES_INCLUDE}")
 endif()
 
 # -------------------------------------------------------------------
@@ -132,6 +186,15 @@ file(GLOB_RECURSE ORCA_CORE_SRC CONFIGURE_DEPENDS
 
 add_library(orca_core OBJECT ${ORCA_CORE_SRC})
 
+# Pull in xerces-c headers via the target's PUBLIC interface. For the
+# bundled build XERCES_LIB is the "xerces-c" target which propagates its
+# header search path; for the system build XERCES_LIB is a library path
+# with no usage requirements (XERCES_INCLUDE supplies headers separately,
+# see target_include_directories below). OBJECT libs accept
+# target_link_libraries since CMake 3.12 — no symbol is actually linked,
+# but compile-time properties propagate.
+target_link_libraries(orca_core PUBLIC ${XERCES_LIB})
+
 target_compile_definitions(orca_core PUBLIC
     $<$<CONFIG:Debug>:GPOS_DEBUG>
     USE_CMAKE

packaging/CPackConfig.cmake

@@ -10,6 +10,20 @@
 #
 # Or use packaging/build-packages.sh as a thin wrapper.
 
+# -------------------------------------------------------------------
+# Release packages must statically bundle xerces-c. Shipping a .deb/.rpm
+# that runtime-depends on the distro's libxerces-c is fragile (Ubuntu
+# 24.04 renamed the package to libxerces-c3.2t64, RHEL 9 has no current
+# build, Supabase / distroless images often lack it entirely). Refuse to
+# package if someone has overridden PG_ORCA_BUNDLED_XERCES=OFF.
+# -------------------------------------------------------------------
+if(NOT PG_ORCA_BUNDLED_XERCES)
+    message(FATAL_ERROR
+        "Release packaging requires PG_ORCA_BUNDLED_XERCES=ON so xerces-c "
+        "is linked statically into pg_orca.so. Reconfigure without "
+        "-DPG_ORCA_BUNDLED_XERCES=OFF.")
+endif()
+
 # -------------------------------------------------------------------
 # Version: parse from pg_orca.control's default_version (single source).
 # -------------------------------------------------------------------
@@ -69,9 +83,9 @@ set(CPACK_DEBIAN_PACKAGE_SECTION    "database")
 set(CPACK_DEBIAN_PACKAGE_PRIORITY   "optional")
 # Match dpkg arch (amd64/arm64) rather than CMAKE_SYSTEM_PROCESSOR (x86_64/aarch64).
 set(CPACK_DEBIAN_PACKAGE_SHLIBDEPS  ON)
-# postgresql-NN supplies pkglibdir/sharedir; libxerces-c is the runtime XML lib.
-set(CPACK_DEBIAN_PACKAGE_DEPENDS
-    "postgresql-${PG_MAJOR}, libxerces-c3.2 | libxerces-c3.2t64")
+# postgresql-NN supplies pkglibdir/sharedir. xerces-c is statically linked
+# into pg_orca.so (enforced above), so no runtime libxerces-c is required.
+set(CPACK_DEBIAN_PACKAGE_DEPENDS "postgresql-${PG_MAJOR}")
 # Override default file name to use dpkg arch.
 execute_process(COMMAND dpkg --print-architecture
     OUTPUT_VARIABLE _deb_arch OUTPUT_STRIP_TRAILING_WHITESPACE
@@ -92,8 +106,8 @@ set(CPACK_RPM_PACKAGE_URL         "${CPACK_PACKAGE_HOMEPAGE_URL}")
 set(CPACK_RPM_PACKAGE_VENDOR      "${CPACK_PACKAGE_VENDOR}")
 set(CPACK_RPM_PACKAGE_SUMMARY     "${CPACK_PACKAGE_DESCRIPTION_SUMMARY}")
 set(CPACK_RPM_PACKAGE_DESCRIPTION "${CPACK_PACKAGE_DESCRIPTION}")
-# PGDG postgresqlNN-server, distro xerces-c. autoreq picks up the rest.
-set(CPACK_RPM_PACKAGE_REQUIRES "postgresql${PG_MAJOR}-server, xerces-c")
+# PGDG postgresqlNN-server only; xerces-c is bundled into pg_orca.so.
+set(CPACK_RPM_PACKAGE_REQUIRES "postgresql${PG_MAJOR}-server")
 set(CPACK_RPM_PACKAGE_AUTOREQ  ON)
 # Don't claim ownership of system dirs we install into.
 set(CPACK_RPM_EXCLUDE_FROM_AUTO_FILELIST_ADDITION

packaging/build-packages.sh

@@ -58,9 +58,12 @@ repo_root="$(cd "$(dirname "$0")/.." && pwd)"
 cd "$repo_root"
 
 echo "==> Configuring ($build_type) with PG_CONFIG=$pg_config"
+# PG_ORCA_BUNDLED_XERCES=ON is required for release packages so xerces-c
+# is statically linked into pg_orca.so (no runtime libxerces-c dep).
 cmake -S . -B "$build_dir" \
     -DCMAKE_BUILD_TYPE="$build_type" \
     -DPG_CONFIG="$pg_config" \
+    -DPG_ORCA_BUNDLED_XERCES=ON \
     -GNinja
 
 echo "==> Building"