# IoTDB C++ 客户端示例 [English](README.md) 本目录提供链接 **IoTDB C++ Session SDK**（`iotdb_session`）的示例程序。 应用侧编译 **不需要** 单独安装 Thrift 或 Boost 头文件/库，它们已封装在 SDK 共享库内部。 所有示例默认连接本机 IoTDB（`127.0.0.1:6667`，用户 `root` / 密码 `root`）。 | 示例 | 说明 | |------|------| | `SessionExample` | 树模型：建库建序列、写入、查询、删除 | | `AlignedTimeseriesSessionExample` | 对齐时间序列与模板 | | `MultiSvrNodeClient` | 多节点写入/查询循环 | | `tree_example` | C Session API（树模型） | ## 选择哪个 SDK 压缩包 CI 发版（[client-cpp-package.yml](../../.github/workflows/client-cpp-package.yml)） 会按平台/工具链打出多份 zip，文件名形如 `client-cpp--.zip`（解压后根目录即为 `include/` 与 `lib/`）。请按目标环境选择： | 目标环境 | classifier 后缀 | |----------|-----------------| | Linux x86_64，glibc ≥ 2.24，CXX11 ABI（**推荐**） | `linux-x86_64-glibc224` | | Linux aarch64，glibc ≥ 2.24，CXX11 ABI（**推荐**） | `linux-aarch64-glibc224` | | Linux x86_64，glibc ≥ 2.17，旧 libstdc++ ABI | `linux-x86_64-glibc217` | | Linux aarch64，glibc ≥ 2.17，旧 libstdc++ ABI | `linux-aarch64-glibc217` | | macOS x86_64 | `mac-x86_64` | | macOS arm64 | `mac-aarch64` | | Windows + 与工程相同的 VS 版本 | `windows-x86_64-vs2017` … `vs2026` | 当前 CMake 构建在配置阶段从源码编译 Thrift 0.21，**不再**通过 `-Diotdb-tools-thrift.version=0.14.1.1-gcc4-SNAPSHOT` 等旧参数控制 glibc； Linux 上若部署机 glibc ≥ 2.24 且使用系统默认 `g++`，请优先选用 **`glibc224`** 包。仅当目标机停留在 glibc 2.17（如 CentOS 7）或必须与旧 libstdc++ ABI 一致时， 选用 **`glibc217`** 包；在 Ubuntu 22/24 上链 `glibc217` 时常需 `-D_GLIBCXX_USE_CXX11_ABI=0`。详见 [client-cpp README](../../iotdb-client/client-cpp/README.md)。 ## SDK 目录结构（解压后） `client-cpp` 打出的 SDK 压缩包只包含 **公开头文件** 和 **一个共享库**： ``` client/ ├── include/ │ ├── Session.h │ ├── Export.h │ └── ... （17 个公开头；无 thrift/、boost/） └── lib/ ├── iotdb_session.dll + iotdb_session.lib （Windows） ├── libiotdb_session.so （Linux） └── libiotdb_session.dylib （macOS） ``` ## 编译示例 ### 方式 A：Maven（本仓库推荐） 在仓库根目录执行： ```bash mvn clean package -DskipTests -P with-cpp -pl example/client-cpp-example -am ``` Maven 会将 SDK 解压到 `example/client-cpp-example/target/client/`，并在 `target/` 下调用 CMake。可执行文件位于 `target/`（具体路径取决于生成器； Windows + Visual Studio 一般为 `target/Release/`）。 ### 方式 B：仅 CMake（手动准备 SDK） 1. 自行编译或下载 SDK，解压后保证存在 `client/include` 与 `client/lib`（见 上文目录结构）。 2. 将 `src/*.{cpp,c}` 与 `src/CMakeLists.txt` 放在同一目录（或保留 `src/` 结构，并在同级放置 `client/`）。 3. 配置并编译： ```bash cmake -S . -B build -DCMAKE_BUILD_TYPE=Release cmake --build build ``` Windows（Visual Studio 生成器）： ```powershell cmake -S . -B build -A x64 cmake --build build --config Release ``` 编译完成后，IoTDB 运行时库会通过 POST_BUILD 自动复制到 **与可执行文件相同 的目录**。Linux/macOS 可执行文件还设置了 `$ORIGIN` rpath，可在同目录加载 `.so` / `.dylib`。 可选：打部署包目录 ```bash cmake --build build --target example-dist # 生成 build/dist/，内含全部示例二进制 + libiotdb_session.{so,dll,dylib} ``` ## 在「干净机器」上运行（无需编译器、无需 SDK 头文件） 目标机器只需： 1. 可访问的 **IoTDB 服务**（已启动）。 2. **示例可执行文件** 与 **IoTDB 运行时库** 放在 **同一目录**（或位于系统 库搜索路径中）。 可从 `build/.../Release/`（Windows）或 `build/`（Ninja/Make）复制，也可在 执行 `example-dist` 后直接使用 `build/dist/`。 ### Windows **需要拷贝的文件** ``` SessionExample.exe iotdb_session.dll ``` （其他示例同理，可执行文件与 `iotdb_session.dll` 成对拷贝。） **目标机器前置条件** - **64 位 Windows**（示例为 x64 构建）。 - 安装 **[Microsoft Visual C++ 2015–2022 可再发行组件包（x64）](https://learn.microsoft.com/zh-cn/cpp/windows/latest-supported-vc-redist)**。 SDK 与示例均使用 **`/MD`**（动态 CRT），该安装包提供 `vcruntime140.dll`、 `msvcp140.dll` 等运行时。 **仅安装此 Redistributable 即可**，目标机 **不需要** Visual Studio，也 **不需要** IoTDB SDK 头文件或 Thrift/Boost。 **运行** ```powershell .\SessionExample.exe ``` 若提示缺少 `VCRUNTIME140.dll`，请安装上述 VC++ 可再发行包。 Thrift、Boost 已包含在 `iotdb_session.dll` 内，无需单独部署。 ### Linux **需要拷贝的文件** ``` SessionExample libiotdb_session.so chmod +x SessionExample ``` **目标机器前置条件** - 目标机的 **glibc 版本必须 ≥ 编译 SDK 时的 glibc 版本**（仅向后兼容： 新系统可跑旧库要求，旧系统不能跑需要更高 glibc 的二进制）。 在 **编译机** 上记录版本（建议写入发布说明）： ```bash ldd --version | head -1 # 例如：ldd (Ubuntu GLIBC 2.35-0ubuntu3) 2.35 ``` 在 **目标机** 上检查： ```bash ldd --version | head -1 # 版本号应 >= 编译机（同主版本次版本或更新） ``` 查看二进制依赖的最高 `GLIBC_` 符号： ```bash objdump -T SessionExample | grep GLIBC_ | sed 's/.*GLIBC_/GLIBC_/' | sort -Vu | tail -5 objdump -T libiotdb_session.so | grep GLIBC_ | sed 's/.*GLIBC_/GLIBC_/' | sort -Vu | tail -5 ``` 若目标 glibc 过旧，运行时会报错，例如 `version 'GLIBC_2.34' not found`。可在更旧的发行版（或旧版容器）上重新编译 SDK，以扩大兼容范围。 **运行**（`.so` 与可执行文件同目录）： ```bash ./SessionExample ``` 若找不到共享库： ```bash export LD_LIBRARY_PATH=. ./SessionExample ``` 无需单独安装 Thrift。 ### macOS 将示例可执行文件与 `libiotdb_session.dylib` 放在同一目录。目标 macOS 版本 应 **≥ 编译 SDK 时设置的 deployment target**。可用以下命令检查依赖： ```bash otool -L SessionExample ``` ## 开发说明 - **Windows**：应用与 SDK 均使用 **`/MD`**，与 Visual Studio 默认工程一致； 链接 `iotdb_session.lib`，部署时携带 `iotdb_session.dll`。 - **Linux**：直接链接 `libiotdb_session.so`；建议与可执行文件同目录发布，或 设置 `RPATH=$ORIGIN`。 - 示例默认连接 `127.0.0.1:6667`；如需修改地址/端口，请编辑对应源码。 ## 本模块目录结构 ``` client-cpp-example/ ├── pom.xml # Maven：解压 SDK + 调用 CMake ├── README.md # 英文说明 ├── README_zh.md # 中文说明（本文件） └── src/ ├── CMakeLists.txt ├── SessionExample.cpp ├── AlignedTimeseriesSessionExample.cpp ├── MultiSvrNodeClient.cpp └── tree_example.c ``` 执行 `mvn package` 后，可在 `target/` 下找到源码、`client/` SDK 与 CMake 构建产物。