This is an automated email from the ASF dual-hosted git repository.
jt2594838 pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/iotdb.git
The following commit(s) were added to refs/heads/master by this push:
new 2fc89d07d08 C++ client: build with OpenSSL 3.x by default and bundle
the runtime … (#17987)
2fc89d07d08 is described below
commit 2fc89d07d084aa7586edbf52293b272c03e0507a
Author: Hongzhi Gao <[email protected]>
AuthorDate: Thu Jun 25 10:42:24 2026 +0800
C++ client: build with OpenSSL 3.x by default and bundle the runtime …
(#17987)
* C++ client: build with OpenSSL 3.x by default and bundle the runtime libs
Enables SSL for the C++ session client out of the box and ships a
self-contained package.
What
- Default WITH_SSL / with.ssl to ON (CMake + Maven), so the client and the
CI packaging/verify jobs build with SSL by default.
- Bundle the OpenSSL shared libraries into the package lib/ (new
InstallOpenSSLRuntime.cmake) so the SDK runs on machines without a system
OpenSSL. iotdb_session gets an $ORIGIN / @loader_path runtime path, and
the
examples copy the bundled libs next to their binaries, so the package is
self-contained (verified the example smoke test resolves the bundled
libssl.so.3, not a system one).
- Bump the bundled Apache Thrift 0.21.0 -> 0.23.0.
OpenSSL version
- Use OpenSSL 3.x (Apache-2.0). OpenSSL 1.1.1 is EOL and not Apache-2.0, so
it
is never linked or redistributed.
- Note: OpenSSL 4.0 removed the legacy TLS-method APIs (TLSv1_method,
SSLv3_method, ASN1_STRING_data) that Thrift's TSSLSocket still calls, so
the
CI pins OpenSSL 3.x rather than installing the latest.
- find_package(OpenSSL) uses the system OpenSSL when present; otherwise it
builds OpenSSL 3.5.0 from source as shared libraries. The Linux packaging
build forces the from-source build (-DIOTDB_OPENSSL_FROM_SOURCE=ON)
because
the manylinux_2_28 / AlmaLinux 8 baseline ships OpenSSL 1.1.1, preserving
the
glibc 2.28 floor while shipping 3.x.
Build tooling
- Build bison >= 3.7 from source when the system bison is too old for Thrift
0.23's grammar build (manylinux ships 3.0.4).
- Encode WITH_SSL in the bundled-Thrift build stamp and forward
OPENSSL_ROOT_DIR
so Thrift's TSSLSocket links the same OpenSSL that is bundled.
CI
- Install/point at OpenSSL 3.x (not 4.0): Windows uses a pinned prebuilt
OpenSSL 3.5.x; macOS uses brew openssl@3; the manylinux job builds 3.x
from
source (installs the perl modules OpenSSL's Configure needs).
Tested
- Windows (MSVC / VS2022): iotdb_session.dll links and imports
libssl-3-x64.dll / libcrypto-3-x64.dll, both bundled into lib/.
- Linux (Ubuntu via WSL): from-source OpenSSL 3.5.0 shared build,
libiotdb_session.so has RUNPATH=$ORIGIN and the bundled libssl.so.3 /
libcrypto.so.3 are resolved in preference to the system OpenSSL.
* C++ client: add third-party LICENSE/NOTICE attribution for the package
Bundling/static-linking third-party components requires reproducing their
notices in the binary distribution.
- Add third_party/NOTICE attributing the redistributed components: Apache
Thrift (statically linked, Apache-2.0, incl. its NOTICE text), OpenSSL
(bundled shared libs, Apache-2.0), and Boost (statically linked, BSL-1.0).
- Add third_party/licenses/LICENSE-Boost-1.0 (BSL-1.0 is not Apache-2.0).
Apache-2.0 components are covered by the package's top-level LICENSE.
- Ship third_party/NOTICE and third_party/licenses/ in the package
(assembly).
- DEPENDENCIES.md: split redistributed (Thrift/Boost/OpenSSL) from
build-only
tools (m4/flex/bison), which are not in the distributed binary.
- apache-rat: exclude the bundled third-party NOTICE / license texts (they
must
not carry an ASF header).
* Address C++ package review feedback
- examples/CMakeLists.txt: stage bundled OpenSSL runtime libraries into the
example-dist dist/ directory, so a copied dist/ runs on a machine without
a
system OpenSSL (previously only executables and iotdb_session were
staged).
- third_party/NOTICE: clarify that Boost is header-only/build-time and that
Boost Software License "Version 1.0" refers to the license version, not
the
compiled Boost release.
---
.github/scripts/package-client-cpp-manylinux228.sh | 13 +++
.github/workflows/client-cpp-package.yml | 18 ++-
.github/workflows/multi-language-client.yml | 15 ++-
iotdb-client/client-cpp/CMakeLists.txt | 27 ++++-
iotdb-client/client-cpp/README.md | 53 +++++----
iotdb-client/client-cpp/README_zh.md | 8 +-
.../client-cpp/cmake/FetchBuildTools.cmake | 17 ++-
iotdb-client/client-cpp/cmake/FetchOpenSSL.cmake | 58 ++++++----
iotdb-client/client-cpp/cmake/FetchThrift.cmake | 21 +++-
.../client-cpp/cmake/InstallOpenSSLRuntime.cmake | 121 +++++++++++++++++++++
iotdb-client/client-cpp/examples/CMakeLists.txt | 35 ++++++
iotdb-client/client-cpp/examples/README.md | 2 +-
iotdb-client/client-cpp/examples/README_zh.md | 2 +-
iotdb-client/client-cpp/pom.xml | 4 +-
.../client-cpp/src/assembly/client-cpp.xml | 2 +
.../package-metadata/third_party/DEPENDENCIES.md | 25 ++++-
.../assembly/package-metadata/third_party/NOTICE | 34 ++++++
.../third_party/licenses/LICENSE-Boost-1.0 | 23 ++++
iotdb-client/client-cpp/third-party/README.md | 6 +-
pom.xml | 3 +
20 files changed, 421 insertions(+), 66 deletions(-)
diff --git a/.github/scripts/package-client-cpp-manylinux228.sh
b/.github/scripts/package-client-cpp-manylinux228.sh
index 773e835d7ef..6bfef0aa415 100755
--- a/.github/scripts/package-client-cpp-manylinux228.sh
+++ b/.github/scripts/package-client-cpp-manylinux228.sh
@@ -71,9 +71,22 @@ fi
cmake --version
java -version
+# manylinux_2_28 is AlmaLinux 8, whose system OpenSSL is 1.1.1 (EOL and not
+# Apache-2.0 - must not be bundled/redistributed in an ASF convenience binary).
+# Build OpenSSL 3.x from source instead (-Diotdb.openssl.from.source=ON), which
+# keeps the glibc 2.28 baseline. OpenSSL 3.x's Configure needs perl plus a few
+# modules (IPC::Cmd, Data::Dumper) that are not on the minimal image - install
+# them even when perl itself is already present.
+if command -v dnf >/dev/null 2>&1; then
+ dnf install -y perl perl-IPC-Cmd perl-Data-Dumper
+else
+ yum install -y perl perl-IPC-Cmd perl-Data-Dumper
+fi
+
cd "${GITHUB_WORKSPACE:?GITHUB_WORKSPACE is not set}"
./mvnw clean package -P with-cpp -pl iotdb-client/client-cpp -am -DskipTests \
-Dspotless.skip=true \
+ -Diotdb.openssl.from.source=ON \
-Dclient.cpp.package.classifier="${PACKAGE_CLASSIFIER}"
SO="iotdb-client/client-cpp/target/install/lib/libiotdb_session.so"
diff --git a/.github/workflows/client-cpp-package.yml
b/.github/workflows/client-cpp-package.yml
index 3c8c2b2844f..38eac3fbcbc 100644
--- a/.github/workflows/client-cpp-package.yml
+++ b/.github/workflows/client-cpp-package.yml
@@ -309,10 +309,14 @@ jobs:
shell: bash
run: |
set -euxo pipefail
- brew install boost openssl llvm@17 bison
+ # Pin openssl@3 (Apache-2.0): the default 'openssl' formula will
move to
+ # OpenSSL 4.0, which drops the legacy TLS-method APIs Thrift still
uses.
+ brew install boost openssl@3 llvm@17 bison
ln -sf "$(brew --prefix llvm@17)/bin/clang-format" "$(brew
--prefix)/bin/clang-format"
echo "$(brew --prefix bison)/bin" >> "$GITHUB_PATH"
echo "$(brew --prefix llvm@17)/bin" >> "$GITHUB_PATH"
+ # Homebrew OpenSSL is keg-only, so point find_package(OpenSSL) at it.
+ echo "OPENSSL_ROOT_DIR=$(brew --prefix openssl@3)" >> "$GITHUB_ENV"
clang-format --version
bison --version
- name: Cache Maven packages
@@ -429,8 +433,16 @@ jobs:
throw "Boost not found under C:\local after installing ${{
matrix.boost_choco }}"
}
echo $boostDir.FullName >> $env:GITHUB_PATH
- choco install openssl -y --no-progress
- $sslPath = (Get-ChildItem 'C:\Program Files\OpenSSL*' -Directory |
Select-Object -First 1).FullName
+ # Use a pinned OpenSSL 3.x (Apache-2.0). 'choco install openssl' now
+ # installs OpenSSL 4.0, which removed the legacy TLS-method APIs that
+ # Apache Thrift's TSSLSocket still calls. The FireDaemon zip is a
clean
+ # prebuilt OpenSSL 3.5.x that keeps them.
+ $sslZip = "$env:RUNNER_TEMP\openssl-3.5.3.zip"
+ $sslDir = "$env:RUNNER_TEMP\openssl-3"
+ curl.exe -L --fail --retry 3 -o $sslZip
'https://download.firedaemon.com/FireDaemon-OpenSSL/openssl-3.5.3.zip'
+ Expand-Archive -Path $sslZip -DestinationPath $sslDir -Force
+ $sslPath = (Get-ChildItem $sslDir -Recurse -Directory -Filter 'x64'
| Select-Object -First 1).FullName
+ if (-not $sslPath) { throw "OpenSSL x64 dir not found under $sslDir"
}
echo "$sslPath\bin" >> $env:GITHUB_PATH
echo "OPENSSL_ROOT_DIR=$sslPath" >> $env:GITHUB_ENV
- name: Cache Maven packages
diff --git a/.github/workflows/multi-language-client.yml
b/.github/workflows/multi-language-client.yml
index 16c6d93ae2d..5437a654985 100644
--- a/.github/workflows/multi-language-client.yml
+++ b/.github/workflows/multi-language-client.yml
@@ -144,10 +144,13 @@ jobs:
if: runner.os == 'macOS'
shell: bash
run: |
- brew install boost openssl llvm@17 bison
+ # Pin openssl@3 (Apache-2.0); the default formula will move to
OpenSSL 4.0.
+ brew install boost openssl@3 llvm@17 bison
ln -sf "$(brew --prefix llvm@17)/bin/clang-format" "$(brew
--prefix)/bin/clang-format"
echo "$(brew --prefix bison)/bin" >> "$GITHUB_PATH"
echo "$(brew --prefix llvm@17)/bin" >> "$GITHUB_PATH"
+ # Homebrew OpenSSL is keg-only, so point find_package(OpenSSL) at it.
+ echo "OPENSSL_ROOT_DIR=$(brew --prefix openssl@3)" >> "$GITHUB_ENV"
clang-format --version
bison --version
sudo rm -rf /Applications/Xcode_14.3.1.app
@@ -163,8 +166,14 @@ jobs:
$boost_path = (Get-ChildItem -Path 'C:\local\' -Filter
'boost_*').FullName
echo $boost_path >> $env:GITHUB_PATH
- choco install openssl -y
- $sslPath = (Get-ChildItem 'C:\Program Files\OpenSSL*' -Directory |
Select-Object -First 1).FullName
+ # Pinned OpenSSL 3.x (Apache-2.0): 'choco install openssl' now
installs
+ # OpenSSL 4.0, which removed the legacy TLS-method APIs Thrift uses.
+ $sslZip = "$env:RUNNER_TEMP\openssl-3.5.3.zip"
+ $sslDir = "$env:RUNNER_TEMP\openssl-3"
+ curl.exe -L --fail --retry 3 -o $sslZip
'https://download.firedaemon.com/FireDaemon-OpenSSL/openssl-3.5.3.zip'
+ Expand-Archive -Path $sslZip -DestinationPath $sslDir -Force
+ $sslPath = (Get-ChildItem $sslDir -Recurse -Directory -Filter 'x64'
| Select-Object -First 1).FullName
+ if (-not $sslPath) { throw "OpenSSL x64 dir not found under $sslDir"
}
echo "$sslPath\bin" >> $env:GITHUB_PATH
echo "OPENSSL_ROOT_DIR=$sslPath" >> $env:GITHUB_ENV
choco install llvm --version=17.0.6 --force -y
diff --git a/iotdb-client/client-cpp/CMakeLists.txt
b/iotdb-client/client-cpp/CMakeLists.txt
index 749341dc88c..ad357dd61a9 100644
--- a/iotdb-client/client-cpp/CMakeLists.txt
+++ b/iotdb-client/client-cpp/CMakeLists.txt
@@ -78,7 +78,7 @@ if(NOT MSVC)
file(WRITE "${_iotdb_cxx11_abi_stamp}" "${_iotdb_cxx11_abi_stamp_value}")
endif()
-option(WITH_SSL "Build with OpenSSL support" OFF)
+option(WITH_SSL "Build with OpenSSL support" ON)
option(BUILD_TESTING "Build IT test executables" OFF)
option(IOTDB_OFFLINE "Disable all network access during configure" OFF)
set(IOTDB_SESSION_VERSION "0.0.0"
@@ -97,7 +97,7 @@ else()
endif()
set(BOOST_VERSION "${_iotdb_default_boost_version}"
CACHE STRING "Boost version used when downloading / unpacking (Thrift
build only)")
-set(THRIFT_VERSION "0.21.0"
+set(THRIFT_VERSION "0.23.0"
CACHE STRING "Apache Thrift version used when downloading / building")
if(WIN32)
@@ -120,6 +120,7 @@ include(FetchBoost) # -> BOOST_INCLUDE_DIR (Thrift
build only)
include(FetchBuildTools)
if(WITH_SSL)
include(FetchOpenSSL)
+ include(InstallOpenSSLRuntime)
endif()
include(FetchThrift)
include(GenerateThriftSources)
@@ -144,6 +145,22 @@ if(UNIX AND NOT APPLE)
SOVERSION "${IOTDB_SESSION_SOVERSION}")
endif()
+# When SSL is on we bundle the OpenSSL shared libraries next to
libiotdb_session
+# in the package lib/ directory. Give the library an $ORIGIN-relative runtime
+# search path so the loader finds them without LD_LIBRARY_PATH / install_name
+# tweaks, keeping the SDK self-contained.
+if(WITH_SSL)
+ if(APPLE)
+ set_target_properties(iotdb_session PROPERTIES
+ BUILD_RPATH "@loader_path"
+ INSTALL_RPATH "@loader_path")
+ elseif(UNIX)
+ set_target_properties(iotdb_session PROPERTIES
+ BUILD_RPATH "$ORIGIN"
+ INSTALL_RPATH "$ORIGIN")
+ endif()
+endif()
+
add_dependencies(iotdb_session iotdb_thrift_external iotdb_thrift_codegen)
target_compile_definitions(iotdb_session PRIVATE THRIFT_STATIC_DEFINE
IOTDB_BUILDING_SHARED)
@@ -223,6 +240,12 @@ install(TARGETS iotdb_session
LIBRARY DESTINATION lib
ARCHIVE DESTINATION lib)
+# Ship the OpenSSL shared libraries we link against next to iotdb_session so
the
+# packaged SDK is self-contained on machines without a system OpenSSL.
+if(WITH_SSL)
+ iotdb_install_openssl_runtime()
+endif()
+
foreach(_hdr IN LISTS IOTDB_PUBLIC_HEADERS)
install(FILES "${CMAKE_CURRENT_SOURCE_DIR}/src/include/${_hdr}"
DESTINATION include)
diff --git a/iotdb-client/client-cpp/README.md
b/iotdb-client/client-cpp/README.md
index 2572fd8e42e..a88293738fd 100644
--- a/iotdb-client/client-cpp/README.md
+++ b/iotdb-client/client-cpp/README.md
@@ -300,7 +300,7 @@ so they require glibc 2.28 or newer on the deployment host.
| ppc64le | `quay.io/pypa/manylinux_2_28_ppc64le` |
| s390x | `quay.io/pypa/manylinux_2_28_s390x` |
-Thrift **0.21.0** is compiled from source during the CMake configure step (see
+Thrift **0.23.0** is compiled from source during the CMake configure step (see
`cmake/FetchThrift.cmake`). Older releases that used pre-built
`iotdb-tools-thrift` Maven artifacts and `-Diotdb-tools-thrift.version=...`
for glibc/MSVC compatibility apply only to the **legacy** client-cpp build;
@@ -378,13 +378,13 @@ etc. directly.
| Option | Default | Purpose
|
|-----------------------|----------------------------------|----------------------------------------------------------------------------------------------------------|
-| `WITH_SSL` | `OFF` | Link against
OpenSSL. See *SSL* below.
|
+| `WITH_SSL` | `ON` | Link against
OpenSSL and bundle its runtime libraries. See *SSL* below.
|
| `BUILD_TESTING` | `OFF` (Maven sets `ON` for verify) | Build Catch2 IT
executables (Catch2 v2.13.7 header downloaded at configure time).
|
| `CATCH2_INCLUDE_DIR` | (unset) | Pre-downloaded
Catch2 include dir (Maven sets this under `target/test/catch2`).
|
| `IOTDB_OFFLINE` | `OFF` | Disallow any
network access during configure.
|
| `IOTDB_DEPS_DIR` | `<client-cpp>/third-party` | Override the
local tarball cache directory.
|
| `BOOST_VERSION` | `1.60.0` (`1.84.0` on macOS) | Boost version
that CMake will look for / download.
|
-| `THRIFT_VERSION` | `0.21.0` | Apache Thrift
version to build from source.
|
+| `THRIFT_VERSION` | `0.23.0` | Apache Thrift
version to build from source.
|
| `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.
|
@@ -427,12 +427,12 @@ cmake --build build --config Release --target install
| Platform | Required files
|
|------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------|
- | `linux/` | `thrift-0.21.0.tar.gz`, `boost_1_60_0.tar.gz`,
`m4-1.4.19.tar.gz`, `flex-2.6.4.tar.gz`, `bison-3.8.tar.gz` (and
`openssl-3.5.0.tar.gz` when `WITH_SSL=ON`) |
- | `mac/` | `thrift-0.21.0.tar.gz`, `boost_1_84_0.tar.gz` (newer Boost
for Xcode/Clang; Apple ships m4/flex/bison; `openssl-3.5.0.tar.gz` optional)
|
- | `windows/` | `thrift-0.21.0.tar.gz`, `boost_1_60_0.tar.gz` (Boost headers
only - no `b2` build required for `iotdb_session`)
|
+ | `linux/` | `thrift-0.23.0.tar.gz`, `boost_1_60_0.tar.gz`,
`m4-1.4.19.tar.gz`, `flex-2.6.4.tar.gz`, `bison-3.8.tar.gz` (and
`openssl-3.5.0.tar.gz` only when `WITH_SSL=ON` and no system OpenSSL is
present) |
+ | `mac/` | `thrift-0.23.0.tar.gz`, `boost_1_84_0.tar.gz` (newer Boost
for Xcode/Clang; Apple ships m4/flex/bison; `openssl-3.5.0.tar.gz` optional)
|
+ | `windows/` | `thrift-0.23.0.tar.gz`, `boost_1_60_0.tar.gz` (Boost headers
only - no `b2` build required for `iotdb_session`)
|
Reference URLs (the configure step uses the same):
- - Apache Thrift 0.21.0:
<https://archive.apache.org/dist/thrift/0.21.0/thrift-0.21.0.tar.gz>
+ - Apache Thrift 0.23.0:
<https://archive.apache.org/dist/thrift/0.23.0/thrift-0.23.0.tar.gz>
- Boost 1.60.0:
<https://archives.boost.io/release/1.60.0/source/boost_1_60_0.tar.gz>
- GNU m4 1.4.19: <https://ftp.gnu.org/gnu/m4/m4-1.4.19.tar.gz>
- GNU flex 2.6.4:
<https://github.com/westes/flex/releases/download/v2.6.4/flex-2.6.4.tar.gz>
@@ -461,7 +461,7 @@ CI environments can share a single cache by setting
### Linux
- Tested with GCC 7+ and Clang 9+. Anything that can compile Apache Thrift
- 0.21.0 works.
+ 0.23.0 works.
- Build deps that must already exist on the host (only required when
CMake auto-builds m4/flex/bison from tarball): `make`, `autoconf`,
`gcc`, plus the standard C/C++ toolchain. `sudo` is **not** required;
@@ -492,9 +492,11 @@ Prerequisites:
2. **flex / bison.** Install <https://sourceforge.net/projects/winflexbison/>
and rename `win_flex.exe`→`flex.exe`, `win_bison.exe`→`bison.exe` on
`PATH`.
-3. **OpenSSL** *(only when `WITH_SSL=ON`)*: run the Win64 OpenSSL
- installer from <https://slproweb.com/products/Win32OpenSSL.html>, then
- pass `-DOPENSSL_ROOT_DIR=...` to CMake.
+3. **OpenSSL** *(`WITH_SSL=ON` is the default)*: install OpenSSL — e.g.
+ `choco install openssl`, or a Win64 OpenSSL installer from
+ <https://slproweb.com/products/Win32OpenSSL.html> — then pass
+ `-DOPENSSL_ROOT_DIR=...` to CMake if it is not auto-detected. Pass
+ `-DWITH_SSL=OFF` to build without SSL.
On Windows the SDK ships as **`iotdb_session.dll`** plus an import library
**`iotdb_session.lib`**, built with **`/MD`** (dynamic CRT, same as a
@@ -507,16 +509,27 @@ the GNU autotools tarballs assume a POSIX shell
environment.
## SSL
-Both Thrift and `iotdb_session` build without OpenSSL by default. Enable
-SSL with `-Dwith.ssl=ON` (Maven) or `-DWITH_SSL=ON` (standalone CMake).
-CMake first calls `find_package(OpenSSL)`;
-if nothing is found, it falls back to:
+`iotdb_session` builds **with OpenSSL by default** (`WITH_SSL=ON`). Disable
+it with `-Dwith.ssl=OFF` (Maven) or `-DWITH_SSL=OFF` (standalone CMake).
-- **Linux / macOS** – use a local `openssl-<ver>.tar.gz` (or download it
- when not in offline mode), configure with `no-shared`, install into
- `build/_deps/openssl/install`, and link statically.
-- **Windows** – fail with a friendly message that points at the Win64
- OpenSSL installer. Building OpenSSL from source via MSVC is out of scope.
+OpenSSL **3.x** is used (Apache-2.0 licensed). Note that **OpenSSL 4.0
removed**
+the legacy TLS-method APIs (`TLSv1_method`, `SSLv3_method`, …) that Apache
+Thrift's `TSSLSocket` still calls, so install/point at a 3.x build, not 4.0.
+
+CMake calls `find_package(OpenSSL)` and uses the system OpenSSL it finds. Its
+shared libraries are **bundled into the package `lib/` directory** (next to
+`iotdb_session`, which records an `$ORIGIN`/`@loader_path` runtime path) so the
+published SDK is self-contained.
+
+Fallbacks:
+
+- **Linux / macOS** – when no system OpenSSL is found (or
+ `-DIOTDB_OPENSSL_FROM_SOURCE=ON`, which the Linux packaging build uses so the
+ AlmaLinux 8 baseline's OpenSSL 1.1.1 is never redistributed), build
+ `openssl-3.5.0.tar.gz` from source as **shared** libraries and bundle them.
+- **Windows** – fail with a friendly message; install a prebuilt OpenSSL 3.x
+ (e.g. the FireDaemon or slproweb 3.5.x zip) and set `-DOPENSSL_ROOT_DIR=...`.
+ Building OpenSSL from source via MSVC is out of scope.
## Tests
diff --git a/iotdb-client/client-cpp/README_zh.md
b/iotdb-client/client-cpp/README_zh.md
index 5f12c71f28c..7c4326d661d 100644
--- a/iotdb-client/client-cpp/README_zh.md
+++ b/iotdb-client/client-cpp/README_zh.md
@@ -236,14 +236,18 @@ Maven 构建会把 SDK 安装到 `target/install/`，并生成
| CMake 变量 | Maven 属性 |
|------------|------------|
-| `WITH_SSL` | `with.ssl`，例如 `-Dwith.ssl=ON` |
+| `WITH_SSL` | `with.ssl`（默认 `ON`，关闭用 `-Dwith.ssl=OFF`） |
| `IOTDB_OFFLINE` | `iotdb.offline` |
| `BUILD_TESTING` | `build.tests` |
| `IOTDB_DEPS_DIR` | `iotdb.deps.dir` |
| `BOOST_INCLUDEDIR` | `boost.include.dir` |
| `CMAKE_BUILD_TYPE` | `cmake.build.type`，例如 `-Dcmake.build.type=Debug` |
-直接使用 CMake 时传入 `-DWITH_SSL=ON`、`-DIOTDB_OFFLINE=ON` 等即可。
+SSL 默认开启（`WITH_SSL=ON`）。所捆绑的 Apache Thrift 0.23 同时支持 OpenSSL 1.x
+与 3.x，因此直接使用系统的 OpenSSL（任意版本）。CMake 通过 `find_package(OpenSSL)`
+解析系统 OpenSSL，找不到时回退到从源码构建 OpenSSL 3.5.0；并会把所用的 OpenSSL
+动态库一并复制到产物 `lib/` 目录。Windows 可用 `choco install openssl` 安装。
+直接使用 CMake 时传入 `-DWITH_SSL=OFF`、`-DIOTDB_OFFLINE=ON` 等即可。
Debug 构建请在配置阶段传入 `-DCMAKE_BUILD_TYPE=Debug`。Windows 使用 Visual
Studio 生成器时也需要传入该选项，以便内置 Thrift 静态库使用 Debug MSVC 运行时；
随后用 `cmake --build build --config Debug --target install` 构建安装。
diff --git a/iotdb-client/client-cpp/cmake/FetchBuildTools.cmake
b/iotdb-client/client-cpp/cmake/FetchBuildTools.cmake
index c9d7482e906..866cc553954 100644
--- a/iotdb-client/client-cpp/cmake/FetchBuildTools.cmake
+++ b/iotdb-client/client-cpp/cmake/FetchBuildTools.cmake
@@ -253,8 +253,23 @@ if(NOT FLEX_EXECUTABLE)
endif()
message(STATUS "[BuildTools] flex = ${FLEX_EXECUTABLE}")
-# bison
+# bison - Thrift 0.23's grammar build uses bison >= 3.7 features (e.g. the
+# --file-prefix-map option), so reject an older system bison (manylinux_2_28
+# ships 3.0.4) and build ${BISON_VERSION} from source instead.
+set(_bison_min_version "3.7")
find_program(BISON_EXECUTABLE bison)
+if(BISON_EXECUTABLE)
+ execute_process(COMMAND "${BISON_EXECUTABLE}" --version
+ OUTPUT_VARIABLE _bison_ver_out ERROR_QUIET
+ OUTPUT_STRIP_TRAILING_WHITESPACE)
+ string(REGEX MATCH "[0-9]+\\.[0-9]+(\\.[0-9]+)?" _bison_ver
"${_bison_ver_out}")
+ if(_bison_ver AND _bison_ver VERSION_LESS _bison_min_version)
+ message(STATUS
+ "[BuildTools] system bison ${_bison_ver} <
${_bison_min_version} "
+ "(too old for Thrift ${THRIFT_VERSION}); building
${BISON_VERSION} from source")
+ unset(BISON_EXECUTABLE CACHE)
+ endif()
+endif()
if(NOT BISON_EXECUTABLE)
_iotdb_resolve_tarball(_bison_tarball "bison-${BISON_VERSION}.tar.gz"
"${_bison_url}")
_iotdb_build_autotools(bison "${_bison_tarball}" "bison-${BISON_VERSION}")
diff --git a/iotdb-client/client-cpp/cmake/FetchOpenSSL.cmake
b/iotdb-client/client-cpp/cmake/FetchOpenSSL.cmake
index 575e2803f2b..aaf41b89be4 100644
--- a/iotdb-client/client-cpp/cmake/FetchOpenSSL.cmake
+++ b/iotdb-client/client-cpp/cmake/FetchOpenSSL.cmake
@@ -18,14 +18,16 @@
# =============================================================================
# FetchOpenSSL.cmake (only included when WITH_SSL=ON)
#
+# Apache Thrift 0.23 (bundled by this client) builds against OpenSSL 1.x and
3.x,
+# so any system OpenSSL is used as-is, whatever its version.
+#
# Resolution order:
# 1. find_package(OpenSSL) - any system / vendor install is taken as-is.
-# 2. On Linux/macOS:
-# use tarball ${IOTDB_OS_DEPS_DIR}/openssl-${OPENSSL_VERSION}.tar.gz
+# 2. On Linux/macOS, when no system OpenSSL is present:
+# use tarball
${IOTDB_OS_DEPS_DIR}/openssl-${OPENSSL_FALLBACK_VERSION}.tar.gz
# or download from openssl.org when not in offline mode, then
-# ./Configure && make && make install_sw into
${CMAKE_BINARY_DIR}/_deps/openssl.
-# 3. On Windows: emit a FATAL_ERROR with instructions to run the bundled
-# Win64OpenSSL installer (or any other prebuilt OpenSSL); building
+# ./config && make && make install_sw into
${CMAKE_BINARY_DIR}/_deps/openssl.
+# 3. On Windows: emit a FATAL_ERROR asking for a prebuilt OpenSSL; building
# OpenSSL from source on MSVC is out of scope.
#
# Side effects:
@@ -33,24 +35,35 @@
# so callers can just link against them.
# =============================================================================
-set(OPENSSL_VERSION "3.5.0" CACHE STRING "OpenSSL version to fetch when
missing")
+# Version built from source when no system OpenSSL is found. Named distinctly
+# from find_package's OPENSSL_VERSION output variable to avoid collisions.
+set(OPENSSL_FALLBACK_VERSION "3.5.0"
+ CACHE STRING "OpenSSL version built from source when no system OpenSSL is
found")
+
+# Build OpenSSL from source even if a system one exists. Used by the Linux
+# packaging build, whose AlmaLinux 8 baseline ships OpenSSL 1.1.1 (EOL, not
+# Apache-2.0, must not be redistributed) - we build 3.x there instead.
+option(IOTDB_OPENSSL_FROM_SOURCE
+ "Ignore any system OpenSSL and build OpenSSL
${OPENSSL_FALLBACK_VERSION} from source" OFF)
-find_package(OpenSSL QUIET)
-if(OpenSSL_FOUND)
- message(STATUS "[OpenSSL] using system OpenSSL
${OPENSSL_VERSION_MAJOR}.${OPENSSL_VERSION_MINOR}")
- return()
+if(NOT IOTDB_OPENSSL_FROM_SOURCE)
+ find_package(OpenSSL QUIET)
+ if(OpenSSL_FOUND)
+ message(STATUS "[OpenSSL] using system OpenSSL ${OPENSSL_VERSION}")
+ return()
+ endif()
endif()
if(WIN32)
message(FATAL_ERROR
"[OpenSSL] WITH_SSL=ON but no OpenSSL was found on Windows. "
- "Please run third-party/windows/Win64OpenSSL-3_5_0.exe (or any "
- "OpenSSL installer), then re-run the configure step with "
- "-DOPENSSL_ROOT_DIR=<install_path>.")
+ "Please install a prebuilt OpenSSL (e.g. 'choco install openssl'),
"
+ "then re-run the configure step with
-DOPENSSL_ROOT_DIR=<install_path>. "
+ "Pass -DWITH_SSL=OFF to build without SSL.")
endif()
-# --- Linux / macOS fallback: build from source ---------------------------
-set(_ossl_tarname "openssl-${OPENSSL_VERSION}.tar.gz")
+# --- Linux / macOS: build OpenSSL ${OPENSSL_FALLBACK_VERSION} from source -
+set(_ossl_tarname "openssl-${OPENSSL_FALLBACK_VERSION}.tar.gz")
set(_ossl_tarball "${IOTDB_OS_DEPS_DIR}/${_ossl_tarname}")
if(NOT EXISTS "${_ossl_tarball}")
@@ -71,9 +84,9 @@ if(NOT EXISTS "${_ossl_tarball}")
endif()
set(_ossl_root "${CMAKE_BINARY_DIR}/_deps/openssl")
-set(_ossl_src "${_ossl_root}/src/openssl-${OPENSSL_VERSION}")
+set(_ossl_src "${_ossl_root}/src/openssl-${OPENSSL_FALLBACK_VERSION}")
set(_ossl_inst "${_ossl_root}/install")
-set(_ossl_stamp "${_ossl_root}/.built-${OPENSSL_VERSION}")
+set(_ossl_stamp "${_ossl_root}/.built-${OPENSSL_FALLBACK_VERSION}")
if(NOT EXISTS "${_ossl_stamp}")
file(REMOVE_RECURSE "${_ossl_root}/src")
@@ -88,12 +101,15 @@ if(NOT EXISTS "${_ossl_stamp}")
endif()
message(STATUS "[OpenSSL] configuring -> ${_ossl_inst}")
+ # ./config auto-detects the platform target. Build SHARED libraries
+ # (libssl.so.3 / libcrypto.so.3) so they can be bundled next to
+ # libiotdb_session and shipped as the SDK's OpenSSL runtime.
execute_process(
- COMMAND ./Configure --prefix=${_ossl_inst}
--openssldir=${_ossl_inst}/ssl no-shared
+ COMMAND ./config --prefix=${_ossl_inst}
--openssldir=${_ossl_inst}/ssl shared
WORKING_DIRECTORY "${_ossl_src}"
RESULT_VARIABLE _rc)
if(NOT _rc EQUAL 0)
- message(FATAL_ERROR "[OpenSSL] Configure failed (rc=${_rc})")
+ message(FATAL_ERROR "[OpenSSL] config failed (rc=${_rc})")
endif()
message(STATUS "[OpenSSL] building (-j${_jobs})")
@@ -116,6 +132,6 @@ if(NOT EXISTS "${_ossl_stamp}")
endif()
set(OPENSSL_ROOT_DIR "${_ossl_inst}" CACHE PATH "OpenSSL root" FORCE)
-set(OPENSSL_USE_STATIC_LIBS ON)
+set(OPENSSL_USE_STATIC_LIBS OFF)
find_package(OpenSSL REQUIRED)
-message(STATUS "[OpenSSL] built locally at ${OPENSSL_ROOT_DIR}")
+message(STATUS "[OpenSSL] built locally (shared) at ${OPENSSL_ROOT_DIR}")
diff --git a/iotdb-client/client-cpp/cmake/FetchThrift.cmake
b/iotdb-client/client-cpp/cmake/FetchThrift.cmake
index f26ad643ff4..d69b2a47ad9 100644
--- a/iotdb-client/client-cpp/cmake/FetchThrift.cmake
+++ b/iotdb-client/client-cpp/cmake/FetchThrift.cmake
@@ -100,7 +100,7 @@ endif()
# binary / library can immediately drive code generation and linking.
# ---------------------------------------------------------------------------
set(_thrift_cmake_args
- # CMake 4.x rejects Thrift 0.21's cmake_minimum_required(3.0); set
policy first.
+ # CMake 4.x rejects Thrift's old cmake_minimum_required(3.x); set
policy first.
"-DCMAKE_POLICY_VERSION_MINIMUM=3.5"
"-DCMAKE_INSTALL_PREFIX=${_thrift_install}"
"-DCMAKE_BUILD_TYPE=${_thrift_build_config}"
@@ -138,6 +138,15 @@ endif()
if(WITH_SSL)
list(APPEND _thrift_cmake_args "-DWITH_OPENSSL=ON")
+ # Build Thrift's TSSLSocket against the same OpenSSL that iotdb_session
links
+ # and bundles, so the runtime libraries match. find_package does not set
+ # OPENSSL_ROOT_DIR itself, so derive it from the resolved include dir.
+ if(OPENSSL_ROOT_DIR)
+ list(APPEND _thrift_cmake_args
"-DOPENSSL_ROOT_DIR=${OPENSSL_ROOT_DIR}")
+ elseif(OPENSSL_INCLUDE_DIR)
+ get_filename_component(_thrift_ossl_root "${OPENSSL_INCLUDE_DIR}"
DIRECTORY)
+ list(APPEND _thrift_cmake_args
"-DOPENSSL_ROOT_DIR=${_thrift_ossl_root}")
+ endif()
else()
list(APPEND _thrift_cmake_args "-DWITH_OPENSSL=OFF")
endif()
@@ -152,7 +161,15 @@ if(IOTDB_USE_CXX11_ABI)
else()
set(_thrift_abi_stamp "-abidefault")
endif()
-set(_thrift_stamp
"${_thrift_build}/.built-${THRIFT_VERSION}-${_thrift_build_config}-mdll${_thrift_abi_stamp}")
+# Encode WITH_SSL in the stamp: toggling SSL changes WITH_OPENSSL, so a cached
+# build of the opposite flavour must not be reused (otherwise TSSLSocket is
+# missing/extra at link time).
+if(WITH_SSL)
+ set(_thrift_ssl_stamp "-ssl")
+else()
+ set(_thrift_ssl_stamp "-nossl")
+endif()
+set(_thrift_stamp
"${_thrift_build}/.built-${THRIFT_VERSION}-${_thrift_build_config}-mdll${_thrift_abi_stamp}${_thrift_ssl_stamp}")
if(NOT EXISTS "${_thrift_stamp}")
file(MAKE_DIRECTORY "${_thrift_build}")
message(STATUS "[Thrift] configuring ${_thrift_dirname}")
diff --git a/iotdb-client/client-cpp/cmake/InstallOpenSSLRuntime.cmake
b/iotdb-client/client-cpp/cmake/InstallOpenSSLRuntime.cmake
new file mode 100644
index 00000000000..f3e181b8e8f
--- /dev/null
+++ b/iotdb-client/client-cpp/cmake/InstallOpenSSLRuntime.cmake
@@ -0,0 +1,121 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+# =============================================================================
+# InstallOpenSSLRuntime.cmake (only used when WITH_SSL=ON)
+#
+# Bundles the OpenSSL shared libraries that iotdb_session links against into
the
+# package lib/ directory, so the published SDK is self-contained and runs on
+# machines that do not have OpenSSL installed.
+#
+# Relies on a prior find_package(OpenSSL) having populated
+# OPENSSL_SSL_LIBRARY / OPENSSL_CRYPTO_LIBRARY / OPENSSL_ROOT_DIR /
+# OPENSSL_VERSION_MAJOR.
+#
+# When OpenSSL was linked statically (the from-source fallback uses no-shared),
+# there is nothing to bundle: those objects are already inside
libiotdb_session.
+# =============================================================================
+
+# Windows: find_package resolves the import .lib; the runtime DLLs live in
+# <root>/bin. Collect them, filtering by major version so installs that ship
+# several ABIs side by side (e.g. libssl-1_1-x64.dll + libssl-3-x64.dll) only
+# bundle the one we actually linked.
+function(_iotdb_collect_openssl_windows_dlls _out_var)
+ set(_roots "")
+ if(OPENSSL_ROOT_DIR)
+ list(APPEND _roots "${OPENSSL_ROOT_DIR}")
+ endif()
+ foreach(_implib IN LISTS OPENSSL_SSL_LIBRARY OPENSSL_CRYPTO_LIBRARY
OPENSSL_LIBRARIES)
+ if(_implib AND EXISTS "${_implib}")
+ # Walk up from the import lib (.../lib, .../lib/VC/x64/MD, ...) to
find
+ # a directory that owns a bin/ holding the DLLs.
+ get_filename_component(_dir "${_implib}" DIRECTORY)
+ list(APPEND _roots "${_dir}")
+ foreach(_up RANGE 1 4)
+ get_filename_component(_dir "${_dir}" DIRECTORY)
+ list(APPEND _roots "${_dir}")
+ endforeach()
+ endif()
+ endforeach()
+ list(REMOVE_DUPLICATES _roots)
+
+ set(_dlls "")
+ set(_seen_names "")
+ foreach(_root IN LISTS _roots)
+ if(_root AND IS_DIRECTORY "${_root}")
+ file(GLOB _found
+ "${_root}/bin/libssl-${OPENSSL_VERSION_MAJOR}*.dll"
+ "${_root}/bin/libcrypto-${OPENSSL_VERSION_MAJOR}*.dll"
+ "${_root}/libssl-${OPENSSL_VERSION_MAJOR}*.dll"
+ "${_root}/libcrypto-${OPENSSL_VERSION_MAJOR}*.dll")
+ # The same DLL can appear under several candidate roots (e.g. bin/
and
+ # the install root); keep only the first occurrence of each
filename.
+ foreach(_dll IN LISTS _found)
+ get_filename_component(_name "${_dll}" NAME)
+ if(NOT _name IN_LIST _seen_names)
+ list(APPEND _seen_names "${_name}")
+ list(APPEND _dlls "${_dll}")
+ endif()
+ endforeach()
+ endif()
+ endforeach()
+ set(${_out_var} "${_dlls}" PARENT_SCOPE)
+endfunction()
+
+function(iotdb_install_openssl_runtime)
+ if(WIN32)
+ _iotdb_collect_openssl_windows_dlls(_dlls)
+ if(NOT _dlls)
+ message(STATUS
+ "[OpenSSL] no runtime DLLs found to bundle; ensure the
OpenSSL "
+ "bin/ directory is on PATH when running the SDK")
+ return()
+ endif()
+ foreach(_dll IN LISTS _dlls)
+ message(STATUS "[OpenSSL] bundling runtime library into lib/:
${_dll}")
+ endforeach()
+ install(FILES ${_dlls} DESTINATION lib)
+ return()
+ endif()
+
+ # Linux / macOS: OPENSSL_*_LIBRARY is the developer name (libssl.so /
+ # libssl.dylib), usually a symlink to the SONAME (libssl.so.3 / .1.1).
+ # FOLLOW_SYMLINK_CHAIN installs the whole chain with the symlinks
preserved,
+ # so the loader finds the SONAME the binary records. Static archives (.a)
+ # are skipped: they are already linked into libiotdb_session.
+ set(_files_arg "")
+ set(_have_libs OFF)
+ foreach(_lib IN LISTS OPENSSL_SSL_LIBRARY OPENSSL_CRYPTO_LIBRARY)
+ if(_lib AND EXISTS "${_lib}" AND NOT _lib MATCHES "\\.a$")
+ string(APPEND _files_arg " \"${_lib}\"")
+ set(_have_libs ON)
+ message(STATUS "[OpenSSL] bundling runtime library into lib/:
${_lib}")
+ endif()
+ endforeach()
+
+ if(NOT _have_libs)
+ message(STATUS
+ "[OpenSSL] no shared runtime libraries to bundle "
+ "(OpenSSL linked statically); SDK is self-contained")
+ return()
+ endif()
+
+ install(CODE
+ "file(INSTALL DESTINATION \"\${CMAKE_INSTALL_PREFIX}/lib\"
+ TYPE SHARED_LIBRARY FOLLOW_SYMLINK_CHAIN
+ FILES ${_files_arg})")
+endfunction()
diff --git a/iotdb-client/client-cpp/examples/CMakeLists.txt
b/iotdb-client/client-cpp/examples/CMakeLists.txt
index 0b77bce5544..4184199847f 100644
--- a/iotdb-client/client-cpp/examples/CMakeLists.txt
+++ b/iotdb-client/client-cpp/examples/CMakeLists.txt
@@ -118,6 +118,21 @@ set(_example_targets
tree_example
table_example)
+# OpenSSL runtime libraries bundled in the SDK lib/ (libssl / libcrypto). When
+# building against an unpacked package, copy them next to each example binary
so
+# the examples run without a system OpenSSL - libiotdb_session records them as
+# NEEDED and resolves them via its $ORIGIN runtime path.
+set(_iotdb_sdk_ssl_runtime "")
+if(NOT _iotdb_examples_in_tree)
+ file(GLOB _iotdb_sdk_ssl_runtime
+ "${IOTDB_SDK_ROOT}/lib/libssl*.so*"
+ "${IOTDB_SDK_ROOT}/lib/libcrypto*.so*"
+ "${IOTDB_SDK_ROOT}/lib/libssl*.dylib"
+ "${IOTDB_SDK_ROOT}/lib/libcrypto*.dylib"
+ "${IOTDB_SDK_ROOT}/lib/libssl*.dll"
+ "${IOTDB_SDK_ROOT}/lib/libcrypto*.dll")
+endif()
+
foreach(_t IN LISTS _example_targets)
IF(WITH_SSL)
TARGET_LINK_LIBRARIES(${_t} PRIVATE "${_iotdb_link_lib}" OpenSSL::SSL
OpenSSL::Crypto)
@@ -128,6 +143,13 @@ foreach(_t IN LISTS _example_targets)
TARGET_LINK_LIBRARIES(${_t} PRIVATE pthread)
ENDIF()
+ # The packaged libiotdb_session records the bundled OpenSSL libs as
DT_NEEDED;
+ # point the linker at the SDK lib/ so it can resolve them without a system
+ # OpenSSL present.
+ if(UNIX AND NOT _iotdb_examples_in_tree)
+ target_link_directories(${_t} PRIVATE "${IOTDB_SDK_ROOT}/lib")
+ endif()
+
# Run from the build output directory without setting LD_LIBRARY_PATH / PATH.
if(UNIX)
set_target_properties(${_t} PROPERTIES
@@ -145,6 +167,12 @@ foreach(_t IN LISTS _example_targets)
COMMAND ${CMAKE_COMMAND} -E copy_if_different
"${_iotdb_runtime}" $<TARGET_FILE_DIR:${_t}>
COMMENT "Copy IoTDB runtime library next to ${_t}")
+ foreach(_ssl_lib IN LISTS _iotdb_sdk_ssl_runtime)
+ add_custom_command(TARGET ${_t} POST_BUILD
+ COMMAND ${CMAKE_COMMAND} -E copy_if_different
+ "${_ssl_lib}" $<TARGET_FILE_DIR:${_t}>
+ COMMENT "Copy bundled OpenSSL runtime next to ${_t}")
+ endforeach()
elseif(WIN32)
message(WARNING "Missing ${_iotdb_runtime}; copy iotdb_session.dll
manually before running ${_t}.")
endif()
@@ -166,6 +194,13 @@ if(EXISTS "${_iotdb_runtime}")
COMMAND ${CMAKE_COMMAND} -E copy_if_different
"${_iotdb_runtime}" "${_example_dist_dir}/")
endif()
+# Stage the bundled OpenSSL runtime too, so a copied dist/ runs on a machine
+# without a system OpenSSL.
+foreach(_ssl_lib IN LISTS _iotdb_sdk_ssl_runtime)
+ add_custom_command(TARGET example-dist POST_BUILD
+ COMMAND ${CMAKE_COMMAND} -E copy_if_different
+ "${_ssl_lib}" "${_example_dist_dir}/")
+endforeach()
if(IOTDB_EXAMPLES_REGISTER_TESTS)
set(_runnable_example_targets
diff --git a/iotdb-client/client-cpp/examples/README.md
b/iotdb-client/client-cpp/examples/README.md
index 295aa29bdbe..763ec693bee 100644
--- a/iotdb-client/client-cpp/examples/README.md
+++ b/iotdb-client/client-cpp/examples/README.md
@@ -53,7 +53,7 @@ publishes one zip per platform/toolchain:
| macOS arm64 | `macos-aarch64` |
| Windows (match your Visual Studio version) | `windows-x86_64-msvc14.1` ...
`msvc14.4` |
-The current build compiles Thrift 0.21 from source at CMake configure time.
+The current build compiles Thrift 0.23 from source at CMake configure time.
Legacy `-Diotdb-tools-thrift.version=...` flags applied to the **old**
pre-built Thrift workflow only. Linux release packages are built in the
`manylinux_2_28` container and require glibc 2.28 or newer. See
diff --git a/iotdb-client/client-cpp/examples/README_zh.md
b/iotdb-client/client-cpp/examples/README_zh.md
index 435b58fe9e6..4adc38a3fc7 100644
--- a/iotdb-client/client-cpp/examples/README_zh.md
+++ b/iotdb-client/client-cpp/examples/README_zh.md
@@ -52,7 +52,7 @@ CI
发版（[client-cpp-package.yml](../../.github/workflows/client-cpp-package.
| macOS arm64 | `macos-aarch64` |
| Windows + 与工程相同的 VS 版本 | `windows-x86_64-msvc14.1` ... `msvc14.4` |
-当前 CMake 构建在配置阶段从源码编译 Thrift 0.21，**不再**通过
+当前 CMake 构建在配置阶段从源码编译 Thrift 0.23，**不再**通过
`-Diotdb-tools-thrift.version=0.14.1.1-gcc4-SNAPSHOT` 等旧参数控制 glibc；
Linux 发版包在 `manylinux_2_28` 容器中构建，部署机需要 glibc 2.28 或更新版本。
详见 [client-cpp README](../../iotdb-client/client-cpp/README.md)。
diff --git a/iotdb-client/client-cpp/pom.xml b/iotdb-client/client-cpp/pom.xml
index b5b97e63792..04f7fa1bd2d 100644
--- a/iotdb-client/client-cpp/pom.xml
+++ b/iotdb-client/client-cpp/pom.xml
@@ -49,7 +49,8 @@
<cmake.install.prefix>${project.build.directory}/install</cmake.install.prefix>
<iotdb.deps.dir>${project.basedir}/third-party</iotdb.deps.dir>
<iotdb.offline>OFF</iotdb.offline>
- <with.ssl>OFF</with.ssl>
+ <with.ssl>ON</with.ssl>
+ <iotdb.openssl.from.source>OFF</iotdb.openssl.from.source>
<iotdb.cxx11.abi/>
<!-- Switched to OFF by the .skipTests profile below. -->
<build.tests>ON</build.tests>
@@ -112,6 +113,7 @@
<option>-DCMAKE_INSTALL_PREFIX=${cmake.install.prefix}</option>
<option>-DBUILD_TESTING=${build.tests}</option>
<option>-DWITH_SSL=${with.ssl}</option>
+
<option>-DIOTDB_OPENSSL_FROM_SOURCE=${iotdb.openssl.from.source}</option>
<option>-DIOTDB_OFFLINE=${iotdb.offline}</option>
<option>-DIOTDB_DEPS_DIR=${iotdb.deps.dir}</option>
<option>-DIOTDB_USE_CXX11_ABI=${iotdb.cxx11.abi}</option>
diff --git a/iotdb-client/client-cpp/src/assembly/client-cpp.xml
b/iotdb-client/client-cpp/src/assembly/client-cpp.xml
index af7184f3fc4..3a6a6313641 100644
--- a/iotdb-client/client-cpp/src/assembly/client-cpp.xml
+++ b/iotdb-client/client-cpp/src/assembly/client-cpp.xml
@@ -52,6 +52,8 @@
<directory>${project.build.directory}/package-metadata</directory>
<includes>
<include>third_party/DEPENDENCIES.md</include>
+ <include>third_party/NOTICE</include>
+ <include>third_party/licenses/**</include>
</includes>
<outputDirectory>${file.separator}</outputDirectory>
</fileSet>
diff --git
a/iotdb-client/client-cpp/src/assembly/package-metadata/third_party/DEPENDENCIES.md
b/iotdb-client/client-cpp/src/assembly/package-metadata/third_party/DEPENDENCIES.md
index e921c7eb948..e321c6fe984 100644
---
a/iotdb-client/client-cpp/src/assembly/package-metadata/third_party/DEPENDENCIES.md
+++
b/iotdb-client/client-cpp/src/assembly/package-metadata/third_party/DEPENDENCIES.md
@@ -20,15 +20,28 @@
-->
# Third-party Dependencies
-The release library is built with the following third-party components. Some
-components are linked into the produced IoTDB C++ session library; this file is
-included for provenance.
+## Redistributed in this package
+
+These components are statically linked into the `iotdb_session` library, or
+bundled as shared libraries, and are therefore part of the binary distribution.
+Their licenses are Category A (Apache-2.0 / Boost). Attribution is provided in
+the [`NOTICE`](NOTICE) file in this directory; non-Apache license texts are
under
+[`licenses/`](licenses). Apache-2.0 components are covered by the top-level
+`LICENSE` file.
+
+| Component | Version | How | License |
+| --- | --- | --- | --- |
+| Apache Thrift | 0.23.0 | statically linked | Apache License 2.0 |
+| Boost | 1.60.0 on Linux/Windows, 1.84.0 on macOS by default | statically
linked (header-only) | Boost Software License 1.0 |
+| OpenSSL | 3.x: system OpenSSL 3.x when present, else 3.5.0 built from source
(`WITH_SSL=ON`, default) | bundled shared libs in `lib/` | Apache License 2.0 |
+
+## Build-time only (not redistributed)
+
+These tools are used only to build Thrift / generate code; none of their code
+is included in the distributed library.
| Component | Version | License |
| --- | --- | --- |
-| Apache Thrift | 0.21.0 | Apache License 2.0 |
-| Boost | 1.60.0 on Linux/Windows, 1.84.0 on macOS by default | Boost Software
License 1.0 |
-| OpenSSL | 3.5.0 when `WITH_SSL=ON` | Apache License 2.0 |
| GNU m4 | 1.4.19 on Linux build bootstrap | GPL-3.0-or-later |
| GNU flex | 2.6.4 on Linux build bootstrap | BSD-style flex license |
| GNU bison | 3.8 on Linux build bootstrap | GPL-3.0-or-later |
diff --git
a/iotdb-client/client-cpp/src/assembly/package-metadata/third_party/NOTICE
b/iotdb-client/client-cpp/src/assembly/package-metadata/third_party/NOTICE
new file mode 100644
index 00000000000..4da431faa06
--- /dev/null
+++ b/iotdb-client/client-cpp/src/assembly/package-metadata/third_party/NOTICE
@@ -0,0 +1,34 @@
+Apache IoTDB C++ Session Client
+Bundled / statically linked third-party components
+==================================================
+
+In addition to the Apache IoTDB code (covered by the top-level LICENSE and
+NOTICE files), this binary distribution statically links or bundles the
+third-party components listed below. Components licensed under the Apache
+License, Version 2.0 are covered by the top-level LICENSE file; other license
+texts are reproduced under third_party/licenses/.
+
+------------------------------------------------------------------------------
+Apache Thrift (statically linked into the iotdb_session library)
+Licensed under the Apache License, Version 2.0 (see the top-level LICENSE).
+
+Apache Thrift
+Copyright (C) 2006 - 2019, The Apache Software Foundation
+
+This product includes software developed at
+The Apache Software Foundation (http://www.apache.org/).
+
+------------------------------------------------------------------------------
+OpenSSL (bundled shared libraries: libssl / libcrypto, present only when the
+SDK is built with SSL support)
+Copyright 1999-2025 The OpenSSL Project Authors. All Rights Reserved.
+Licensed under the Apache License, Version 2.0 (see the top-level LICENSE).
+
+------------------------------------------------------------------------------
+Boost C++ Libraries (header-only; used at build time to compile Apache Thrift
+and the iotdb_session library, so portions may be inlined into the shipped
+binary)
+Distributed under the Boost Software License, Version 1.0
+(see third_party/licenses/LICENSE-Boost-1.0). Here "Version 1.0" is the license
+version -- the Boost Software License has only ever had this single version --
+and is unrelated to the Boost library release that was compiled in.
diff --git
a/iotdb-client/client-cpp/src/assembly/package-metadata/third_party/licenses/LICENSE-Boost-1.0
b/iotdb-client/client-cpp/src/assembly/package-metadata/third_party/licenses/LICENSE-Boost-1.0
new file mode 100644
index 00000000000..36b7cd93cdf
--- /dev/null
+++
b/iotdb-client/client-cpp/src/assembly/package-metadata/third_party/licenses/LICENSE-Boost-1.0
@@ -0,0 +1,23 @@
+Boost Software License - Version 1.0 - August 17th, 2003
+
+Permission is hereby granted, free of charge, to any person or organization
+obtaining a copy of the software and accompanying documentation covered by
+this license (the "Software") to use, reproduce, display, distribute,
+execute, and transmit the Software, and to prepare derivative works of the
+Software, and to permit third-parties to whom the Software is furnished to
+do so, all subject to the following:
+
+The copyright notices in the Software and this entire statement, including
+the above license grant, this restriction and the following disclaimer,
+must be included in all copies of the Software, in whole or in part, and
+all derivative works of the Software, unless such copies or derivative
+works are solely in the form of machine-executable object code generated by
+a source language processor.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE, TITLE AND NON-INFRINGEMENT. IN NO EVENT
+SHALL THE COPYRIGHT HOLDERS OR ANYONE DISTRIBUTING THE SOFTWARE BE LIABLE
+FOR ANY DAMAGES OR OTHER LIABILITY, WHETHER IN CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.
diff --git a/iotdb-client/client-cpp/third-party/README.md
b/iotdb-client/client-cpp/third-party/README.md
index 313a6fb79a1..4cbdd1ed569 100644
--- a/iotdb-client/client-cpp/third-party/README.md
+++ b/iotdb-client/client-cpp/third-party/README.md
@@ -68,8 +68,8 @@ Alternatively copy files manually from the URLs listed in
| Platform | Typical files |
|------------|---------------|
-| `linux/` | `thrift-0.21.0.tar.gz`, `boost_1_60_0.tar.gz`,
`m4-1.4.19.tar.gz`, `flex-2.6.4.tar.gz`, `bison-3.8.tar.gz` (+
`openssl-3.5.0.tar.gz` when `WITH_SSL=ON`) |
-| `mac/` | `thrift-0.21.0.tar.gz`, `boost_1_60_0.tar.gz` (Xcode CLT
usually provides m4/flex/bison) |
-| `windows/` | `thrift-0.21.0.tar.gz`, `boost_1_60_0.tar.gz`,
`win_flex_bison-2.5.25.zip` (or any `win_flex_bison*.zip`; skip if flex/bison
already on `PATH`) |
+| `linux/` | `thrift-0.23.0.tar.gz`, `boost_1_60_0.tar.gz`,
`m4-1.4.19.tar.gz`, `flex-2.6.4.tar.gz`, `bison-3.8.tar.gz` (+
`openssl-3.5.0.tar.gz` only when `WITH_SSL=ON` and no system OpenSSL is
present) |
+| `mac/` | `thrift-0.23.0.tar.gz`, `boost_1_60_0.tar.gz` (Xcode CLT
usually provides m4/flex/bison) |
+| `windows/` | `thrift-0.23.0.tar.gz`, `boost_1_60_0.tar.gz`,
`win_flex_bison-2.5.25.zip` (or any `win_flex_bison*.zip`; skip if flex/bison
already on `PATH`) |
Download URLs: see the *Offline build* table in [`README.md`](../README.md).
diff --git a/pom.xml b/pom.xml
index 7561fa72772..3e0aa631a45 100644
--- a/pom.xml
+++ b/pom.xml
@@ -785,6 +785,9 @@
<exclude>**/*.cvs</exclude>
<!-- licenses -->
<exclude>licenses/*</exclude>
+ <!-- bundled third-party NOTICE / license texts
for the C++ client package -->
+
<exclude>**/package-metadata/third_party/NOTICE</exclude>
+
<exclude>**/package-metadata/third_party/licenses/**</exclude>
<!-- only for Travis CI with WinOS-->
<exclude>hadoopbin</exclude>
<exclude>windowssystem32</exclude>
