fix(ci): pass libstdc++ ABI via CMake for manylinux client-cpp packages

Resolve gcc from PATH in manylinux containers; use -Diotdb.extra.cxx.flags so ABI applies to iotdb_session and Thrift. Document Linux zip linking in README.

Author: hongzhi-gao

.github/scripts/package-client-cpp-manylinux-glibc217.sh

@@ -18,8 +18,7 @@
 set -euxo pipefail
 
 MAX_GLIBC=2.17
-SYSTEM_GCC=/usr/bin/gcc
-SYSTEM_GXX=/usr/bin/g++
+IOTDB_EXTRA_CXX_FLAGS=-D_GLIBCXX_USE_CXX11_ABI=0
 
 MACHINE=$(uname -m)
 case "${MACHINE}" in
@@ -62,13 +61,23 @@ if [[ ! -x "${JAVA_HOME}/bin/java" ]]; then
   JAVA_HOME=/opt/jdk-17
 fi
 
-export PATH="${CMAKE_DIR}/bin:${JAVA_HOME}/bin:/usr/bin:${PATH}"
+export PATH="${CMAKE_DIR}/bin:${JAVA_HOME}/bin:${PATH}"
 export JAVA_HOME
 
+# manylinux images expose gcc under devtoolset paths, not /usr/bin/gcc.
+SYSTEM_GCC=$(command -v gcc)
+SYSTEM_GXX=$(command -v g++)
+if [[ -z "${SYSTEM_GCC}" || ! -x "${SYSTEM_GCC}" ]]; then
+  echo "ERROR: gcc not found on PATH" >&2
+  exit 1
+fi
+if [[ -z "${SYSTEM_GXX}" || ! -x "${SYSTEM_GXX}" ]]; then
+  echo "ERROR: g++ not found on PATH" >&2
+  exit 1
+fi
+
 export CC="${SYSTEM_GCC}"
 export CXX="${SYSTEM_GXX}"
-export CFLAGS="-D_GLIBCXX_USE_CXX11_ABI=0 ${CFLAGS:-}"
-export CXXFLAGS="-D_GLIBCXX_USE_CXX11_ABI=0 ${CXXFLAGS:-}"
 
 "${SYSTEM_GCC}" --version
 "${SYSTEM_GXX}" --version
@@ -78,7 +87,8 @@ java -version
 cd "${GITHUB_WORKSPACE:?GITHUB_WORKSPACE is not set}"
 ./mvnw clean package -P with-cpp -pl iotdb-client/client-cpp -am -DskipTests \
   -Dspotless.skip=true \
-  -Dclient.cpp.package.classifier="${PACKAGE_CLASSIFIER}"
+  -Dclient.cpp.package.classifier="${PACKAGE_CLASSIFIER}" \
+  "-Diotdb.extra.cxx.flags=${IOTDB_EXTRA_CXX_FLAGS}"
 
 SO="iotdb-client/client-cpp/target/install/lib/libiotdb_session.so"
 test -f "${SO}"

.github/scripts/package-client-cpp-manylinux-glibc224.sh

@@ -14,12 +14,11 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 #
-# Default libstdc++ cxx11 ABI on manylinux_2_24; max glibc 2.24.
+# cxx11 libstdc++ ABI on manylinux_2_24; max glibc 2.24.
 set -euxo pipefail
 
 MAX_GLIBC=2.24
-SYSTEM_GCC=/usr/bin/gcc
-SYSTEM_GXX=/usr/bin/g++
+IOTDB_EXTRA_CXX_FLAGS=-D_GLIBCXX_USE_CXX11_ABI=1
 
 MACHINE=$(uname -m)
 case "${MACHINE}" in
@@ -62,9 +61,20 @@ if [[ ! -x "${JAVA_HOME}/bin/java" ]]; then
   JAVA_HOME=/opt/jdk-17
 fi
 
-export PATH="${CMAKE_DIR}/bin:${JAVA_HOME}/bin:/usr/bin:${PATH}"
+export PATH="${CMAKE_DIR}/bin:${JAVA_HOME}/bin:${PATH}"
 export JAVA_HOME
 
+SYSTEM_GCC=$(command -v gcc)
+SYSTEM_GXX=$(command -v g++)
+if [[ -z "${SYSTEM_GCC}" || ! -x "${SYSTEM_GCC}" ]]; then
+  echo "ERROR: gcc not found on PATH" >&2
+  exit 1
+fi
+if [[ -z "${SYSTEM_GXX}" || ! -x "${SYSTEM_GXX}" ]]; then
+  echo "ERROR: g++ not found on PATH" >&2
+  exit 1
+fi
+
 export CC="${SYSTEM_GCC}"
 export CXX="${SYSTEM_GXX}"
 
@@ -76,7 +86,8 @@ java -version
 cd "${GITHUB_WORKSPACE:?GITHUB_WORKSPACE is not set}"
 ./mvnw clean package -P with-cpp -pl iotdb-client/client-cpp -am -DskipTests \
   -Dspotless.skip=true \
-  -Dclient.cpp.package.classifier="${PACKAGE_CLASSIFIER}"
+  -Dclient.cpp.package.classifier="${PACKAGE_CLASSIFIER}" \
+  "-Diotdb.extra.cxx.flags=${IOTDB_EXTRA_CXX_FLAGS}"
 
 SO="iotdb-client/client-cpp/target/install/lib/libiotdb_session.so"
 test -f "${SO}"
@@ -104,7 +115,7 @@ fi
 
 echo "glibc compatibility check passed (max=${max_glibc} <= ${MAX_GLIBC})"
 
-echo "=== Optional example link test (default cxx11 ABI) ==="
+echo "=== Optional example link test (cxx11 ABI) ==="
 INSTALL_ROOT="${GITHUB_WORKSPACE}/iotdb-client/client-cpp/target/install"
 EXAMPLE_SRC="${GITHUB_WORKSPACE}/example/client-cpp-example/src"
 LINKTEST_BUILD="/tmp/client-cpp-example-linktest-glibc224"
@@ -113,7 +124,8 @@ mkdir -p "${LINKTEST_BUILD}"
 unset CC CXX CFLAGS CXXFLAGS
 "${CMAKE_DIR}/bin/cmake" -S "${EXAMPLE_SRC}" -B "${LINKTEST_BUILD}" \
   -DCMAKE_BUILD_TYPE=Release \
-  -DIOTDB_SDK_ROOT="${INSTALL_ROOT}"
+  -DIOTDB_SDK_ROOT="${INSTALL_ROOT}" \
+  -DCMAKE_CXX_FLAGS=-D_GLIBCXX_USE_CXX11_ABI=1
 "${CMAKE_DIR}/bin/cmake" --build "${LINKTEST_BUILD}" --target SessionExample -j"$(nproc)"
 test -x "${LINKTEST_BUILD}/SessionExample"
 echo "Example link test passed"

iotdb-client/client-cpp/CMakeLists.txt

@@ -34,6 +34,9 @@ endif()
 
 if(NOT MSVC)
     set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -Wall -g -O2")
+    if(IOTDB_EXTRA_CXX_FLAGS)
+        set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} ${IOTDB_EXTRA_CXX_FLAGS}")
+    endif()
 endif()
 
 if(MSVC)
@@ -44,6 +47,9 @@ endif()
 option(WITH_SSL "Build with OpenSSL support" OFF)
 option(BUILD_TESTING "Build IT test executables" OFF)
 option(IOTDB_OFFLINE "Disable all network access during configure" OFF)
+# e.g. -D_GLIBCXX_USE_CXX11_ABI=0 for legacy Linux release zips (Maven: -Diotdb.extra.cxx.flags=...)
+set(IOTDB_EXTRA_CXX_FLAGS ""
+    CACHE STRING "Extra flags appended to CMAKE_CXX_FLAGS (libstdc++ ABI, etc.)")
 
 set(IOTDB_DEPS_DIR "${CMAKE_CURRENT_SOURCE_DIR}/third-party"
     CACHE PATH "Local tarball cache for third-party dependencies (lives under client-cpp/)")

iotdb-client/client-cpp/README.md

@@ -93,17 +93,20 @@ deployment environment:
 Example file name:
 `client-cpp-2.0.7-SNAPSHOT-linux-x86_64-glibc224.zip`.
 
-**Linux ABI and glibc:** Two Linux families are published. **`glibc224`** packages
-are built on [`manylinux_2_24`](https://github.com/pypa/manylinux) with the
-image default `/usr/bin/g++` and the **new** libstdc++ ABI (symbols contain
-`__cxx11`); they require **glibc ≥ 2.24** on the deployment host. Prefer these
-on modern distros (Ubuntu 22.04+, Kylin V10, etc.) when your application uses
-the default compiler ABI. **`glibc217`** packages are built on `manylinux2014`
-with **`-D_GLIBCXX_USE_CXX11_ABI=0`** (no `__cxx11` symbols) for hosts that only
-have **glibc 2.17** and cannot upgrade to 2.24+; your application must compile
-with the same flag when linking against that SDK. The `manylinux_2_24` image
-series is **EOL**; it remains the oldest manylinux image that ships a gcc with
-native cxx11 ABI support.
+**Linux ABI and glibc:** Two Linux families are published.
+
+| Package | manylinux image | Deployment glibc | libstdc++ ABI | How to match when you build your app |
+|---------|-----------------|------------------|---------------|--------------------------------------|
+| `*-glibc224` | `manylinux_2_24` | **≥ 2.24** | **cxx11** (`nm` shows `__cxx11`) | Default g++ on Ubuntu 22.04+, Kylin V10, etc. — no extra flags |
+| `*-glibc217` | `manylinux2014` | **≥ 2.17** | **legacy** (no `__cxx11`) | Add **`-D_GLIBCXX_USE_CXX11_ABI=0`** to your compile flags |
+
+Prefer **`glibc224`** on modern distros. Use **`glibc217`** only when the target
+host cannot run glibc 2.24+ binaries, or you must stay on the legacy ABI.
+The `manylinux_2_24` image series is **EOL**; it is the oldest manylinux line
+used here that can produce a cxx11-ABI SDK with the image toolchain.
+
+CI passes libstdc++ ABI into CMake via **`-Diotdb.extra.cxx.flags=...`** (see
+below). Setting `CXXFLAGS` alone is **not** enough for the Maven/CMake build.
 
 Thrift **0.21.0** is compiled from source during the CMake configure step (see
 `cmake/FetchThrift.cmake`). Older releases that used pre-built
@@ -114,21 +117,28 @@ and OS used to build** the SDK, not by that Maven property.
 
 ### Local build for a specific classifier
 
-Linux x86_64 (glibc 2.24 + cxx11 ABI — match a modern distro or
-`manylinux_2_24`):
+Linux x86_64 (**glibc224**, cxx11 ABI — modern distro or `manylinux_2_24`):
 
 ```bash
 mvn -P with-cpp -pl iotdb-client/client-cpp -am -DskipTests \
-  -Dclient.cpp.package.classifier=linux-x86_64-glibc224 package
+  -Dclient.cpp.package.classifier=linux-x86_64-glibc224 \
+  -Diotdb.extra.cxx.flags=-D_GLIBCXX_USE_CXX11_ABI=1 package
 ```
 
-Linux x86_64 (glibc 2.17 + legacy ABI — CentOS 7 / manylinux2014; compile with
-`-D_GLIBCXX_USE_CXX11_ABI=0`):
+Linux x86_64 (**glibc217**, legacy ABI — CentOS 7 / `manylinux2014`):
 
 ```bash
-export CXXFLAGS="-D_GLIBCXX_USE_CXX11_ABI=0"
 mvn -P with-cpp -pl iotdb-client/client-cpp -am -DskipTests \
-  -Dclient.cpp.package.classifier=linux-x86_64-glibc217 package
+  -Dclient.cpp.package.classifier=linux-x86_64-glibc217 \
+  -Diotdb.extra.cxx.flags=-D_GLIBCXX_USE_CXX11_ABI=0 package
+```
+
+Standalone CMake (same ABI flags):
+
+```bash
+cmake -S iotdb-client/client-cpp -B build \
+  -DIOTDB_EXTRA_CXX_FLAGS=-D_GLIBCXX_USE_CXX11_ABI=1   # or =0 for glibc217
+cmake --build build --target install
 ```
 
 Windows (match the Visual Studio version you use to build your application):
@@ -163,6 +173,7 @@ pass them as Maven properties (the POM maps them to `-D` options for CMake):
 | `BUILD_TESTING` | `build.tests` |
 | `IOTDB_DEPS_DIR` | `iotdb.deps.dir` |
 | `BOOST_INCLUDEDIR` | `boost.include.dir` (legacy alias) |
+| `IOTDB_EXTRA_CXX_FLAGS` | `iotdb.extra.cxx.flags` (e.g. `-D_GLIBCXX_USE_CXX11_ABI=0`) |
 
 For a **standalone** `cmake` configure, pass `-DWITH_SSL=ON`, `-DIOTDB_OFFLINE=ON`,
 etc. directly.
@@ -178,6 +189,7 @@ etc. directly.
 | `BOOST_ROOT`          | (unset)                          | Existing Boost install to reuse, equivalent to `-Dboost.include.dir=...` from the legacy build.          |
 | `OPENSSL_ROOT_DIR`    | (unset)                          | Existing OpenSSL install when `WITH_SSL=ON`.                                                             |
 | `CMAKE_INSTALL_PREFIX`| `<build>/install`                | Install location.                                                                                        |
+| `IOTDB_EXTRA_CXX_FLAGS` | (empty)                        | Appended to `CMAKE_CXX_FLAGS` on Linux/macOS (libstdc++ ABI, etc.). Also applied to the Thrift sub-build. |
 
 ## Online build (default)
 
@@ -345,35 +357,75 @@ as a separate install artifact.
 
 ## Using the C++ client
 
+### Application code
+
 ```cpp
 #include "Session.h"
-    #include <memory>
-    #include <iostream>
-
-    int main() {
-    auto session = std::make_shared<Session>("127.0.0.1", 6667, "root", "root");
-        session->open(false);
-        session->setStorageGroup("root.test01");
-        if (!session->checkTimeseriesExists("root.test01.d0.s0")) {
-        session->createTimeseries(
-            "root.test01.d0.s0",
-            TSDataType::INT64,
-            TSEncoding::RLE,
-            CompressionType::SNAPPY);
-    }
-        session->close();
-    }
+#include <iostream>
+#include <memory>
+
+int main() {
+  auto session = std::make_shared<Session>("127.0.0.1", 6667, "root", "root");
+  session->open(false);
+  session->setStorageGroup("root.test01");
+  if (!session->checkTimeseriesExists("root.test01.d0.s0")) {
+    session->createTimeseries(
+        "root.test01.d0.s0",
+        TSDataType::INT64,
+        TSEncoding::RLE,
+        CompressionType::SNAPPY);
+  }
+  session->close();
+}
 ```
 
-Compile against the produced SDK:
+### Link against a pre-built zip (Linux)
+
+1. Unzip `client-cpp-<version>-<classifier>.zip` and note `include/` and `lib/`.
+2. Pick the classifier that matches your machine (see table above).
+3. Compile with the **same libstdc++ ABI** as the zip:
 
 ```bash
-clang++ -O2 user-cpp-code.cpp \
-    -I/path/to/sdk/include \
-    -L/path/to/sdk/lib \
-    -liotdb_session -lpthread \
-    -Wl,-rpath,/path/to/sdk/lib \
-    -std=c++11
+SDK=/path/to/client-cpp-2.0.7-SNAPSHOT-linux-x86_64-glibc224
+
+# glibc224 zip (default g++ ABI on modern Linux):
+g++ -std=c++11 -O2 -o myapp myapp.cpp \
+  -I"${SDK}/include" -L"${SDK}/lib" -liotdb_session -lpthread \
+  -Wl,-rpath,"${SDK}/lib"
+
+# glibc217 zip (legacy ABI — required):
+g++ -std=c++11 -O2 -o myapp myapp.cpp \
+  -D_GLIBCXX_USE_CXX11_ABI=0 \
+  -I"${SDK}/include" -L"${SDK}/lib" -liotdb_session -lpthread \
+  -Wl,-rpath,"${SDK}/lib"
 ```
 
+If linking fails with `undefined reference to ... __cxx11::basic_string`, the zip
+ABI and your compiler flags do not match — switch zip (`glibc224` vs `glibc217`)
+or add/remove `-D_GLIBCXX_USE_CXX11_ABI=0`.
+
+At runtime, ensure `libiotdb_session.so` is found (`LD_LIBRARY_PATH` or
+`-Wl,-rpath` as above). Thrift is **inside** the SDK shared library; you do not
+ship a separate `libthrift.so`.
+
+### Link after a local Maven/CMake build
+
+Install tree: `iotdb-client/client-cpp/target/install/{include,lib}`.
+
+```bash
+g++ -std=c++11 -O2 -o myapp myapp.cpp \
+  -Iiotdb-client/client-cpp/target/install/include \
+  -Liotdb-client/client-cpp/target/install/lib \
+  -liotdb_session -lpthread \
+  -Wl,-rpath,"$PWD/iotdb-client/client-cpp/target/install/lib"
+```
+
+Use the same `-D_GLIBCXX_USE_CXX11_ABI=...` flag you passed when building the SDK
+(`-Diotdb.extra.cxx.flags=...`).
+
+### Examples
+
+See [client-cpp-example](../../example/client-cpp-example/README.md) for CMake
+projects that consume an unpacked SDK (`-DIOTDB_SDK_ROOT=...`).
+
 For full API documentation see the [C++ Native API guide](https://iotdb.apache.org/UserGuide/latest/API/Programming-Cpp-Native-API.html).

iotdb-client/client-cpp/cmake/FetchThrift.cmake

@@ -122,9 +122,15 @@ if(MSVC)
     list(APPEND _thrift_cmake_args
             "-DCMAKE_MSVC_RUNTIME_LIBRARY=MultiThreadedDLL")
 else()
+    set(_thrift_cxxflags "-fPIC")
+    if(IOTDB_EXTRA_CXX_FLAGS MATCHES "_GLIBCXX_USE_CXX11_ABI=0")
+        set(_thrift_cxxflags "-D_GLIBCXX_USE_CXX11_ABI=0 -fPIC")
+    elseif(IOTDB_EXTRA_CXX_FLAGS MATCHES "_GLIBCXX_USE_CXX11_ABI=1")
+        set(_thrift_cxxflags "-D_GLIBCXX_USE_CXX11_ABI=1 -fPIC")
+    endif()
     list(APPEND _thrift_cmake_args
             "-DCMAKE_C_FLAGS=-fPIC"
-            "-DCMAKE_CXX_FLAGS=-fPIC")
+            "-DCMAKE_CXX_FLAGS=${_thrift_cxxflags}")
 endif()
 
 if(WITH_SSL)

iotdb-client/client-cpp/pom.xml

@@ -55,6 +55,8 @@
         <!-- Optional convenience: when a user still passes -Dboost.include.dir=...
              (legacy CLI from the old build), feed it to CMake as BOOST_INCLUDEDIR. -->
         <boost.include.dir></boost.include.dir>
+        <!-- e.g. -D_GLIBCXX_USE_CXX11_ABI=0 for legacy Linux packages (see README). -->
+        <iotdb.extra.cxx.flags></iotdb.extra.cxx.flags>
         <!-- Override via -Dclient.cpp.package.classifier=... for per-toolchain release zips. -->
         <client.cpp.package.classifier>${os.classifier}</client.cpp.package.classifier>
     </properties>
@@ -92,6 +94,7 @@
                                 <option>-DIOTDB_DEPS_DIR=${iotdb.deps.dir}</option>
                                 <option>-DBOOST_INCLUDEDIR=${boost.include.dir}</option>
                                 <option>-DCMAKE_POLICY_DEFAULT_CMP0091=NEW</option>
+                                <option>-DIOTDB_EXTRA_CXX_FLAGS=${iotdb.extra.cxx.flags}</option>
                             </options>
                         </configuration>
                     </execution>