IoTDB C++ client examples

中文说明

Sample programs that link against the pre-built IoTDB C++ Session SDK (iotdb_session). Thrift and Boost are not required at application compile time; they are embedded inside the SDK shared library.

All examples connect to a running IoTDB instance (default 127.0.0.1:6667, user root / root).

Which SDK zip to use

Release CI (client-cpp-package.yml) publishes one zip per platform/toolchain: client-cpp-<version>-<classifier>.zip (zip root contains include/ and lib/).

The current build compiles Thrift 0.21 from source at CMake configure time. Legacy -Diotdb-tools-thrift.version=... flags applied to the old pre-built Thrift workflow only. On Linux, prefer glibc224 when your host has glibc ≥ 2.24 and you use the default g++. Use glibc217 only for glibc 2.17 systems or legacy ABI; on Ubuntu 22/24 you may need -D_GLIBCXX_USE_CXX11_ABI=0 when linking against glibc217. See client-cpp README.

SDK layout (after unpack)

The SDK zip produced by client-cpp contains public headers only and one shared library:

client/
├── include/
│   ├── Session.h
│   ├── Export.h
│   └── ...          (17 public headers; no thrift/ or boost/)
└── lib/
    ├── iotdb_session.dll + iotdb_session.lib   (Windows)
    ├── libiotdb_session.so                     (Linux)
    └── libiotdb_session.dylib                  (macOS)

Build the examples

Option A – Maven (recommended in this repo)

From the repository root:

mvn clean package -DskipTests -P with-cpp -pl example/client-cpp-example -am

Maven unpacks the SDK zip into example/client-cpp-example/target/client/ and runs CMake in target/. Binaries are under target/ (exact path depends on the generator; on Windows with Visual Studio: target/Release/).

Option B – CMake only (manual SDK)

1. Build or download the SDK and unpack it so client/include and client/lib exist (see layout above).
2. Copy src/*.{cpp,c} and src/CMakeLists.txt into one directory (or use src/ as the source tree and place client/ beside it).
3. Configure and build:

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build

Windows (Visual Studio generator):

cmake -S . -B build -A x64
cmake --build build --config Release

Each executable is built with the IoTDB runtime library copied next to the .exe / binary (POST_BUILD step). Linux/macOS binaries use $ORIGIN rpath so they resolve the .so / .dylib in the same directory.

Optional staging folder for deployment:

cmake --build build --target example-dist
# -> build/dist/ contains all example binaries + libiotdb_session.{so,dll,dylib}

Run on a clean machine (no compiler, no IoTDB SDK headers)

You only need:

1. A running IoTDB server reachable from the machine.
2. The example executable(s) and the IoTDB runtime library in the same directory (or on the system library path).

Copy either from build/.../Release/ (Windows) / build/ (Ninja/Make) or from build/dist/ after example-dist.

Windows

Files to copy

SessionExample.exe
iotdb_session.dll

(Repeat for the other example names if needed.)

Prerequisites on the target PC

• 64-bit Windows (examples are built x64).
• Microsoft Visual C++ Redistributable for Visual Studio 2015–2022
  (x64). The SDK and examples are built with /MD; the redistributable supplies vcruntime140.dll, msvcp140.dll, etc.
  Installing this package is enough—you do not need Visual Studio or the IoTDB SDK on the target machine.

Run

.\SessionExample.exe

If you see “The code execution cannot proceed because VCRUNRuntime140.dll was missing”, install the VC++ redistributable above.

You do not need a separate Thrift or Boost runtime; they are inside iotdb_session.dll.

Linux

Files to copy

SessionExample
libiotdb_session.so
chmod +x SessionExample

Prerequisites on the target machine

• glibc on the target must be ≥ the glibc version on the machine that built the SDK (backward compatible only in that direction).

Check build machine (record in release notes):

ldd --version | head -1
# e.g. ldd (Ubuntu GLIBC 2.35-0ubuntu3) 2.35

Check target machine:

ldd --version | head -1
# must be >= build glibc (same major.minor or newer)

See which GLIBC_ symbols the binary needs:

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

If the target glibc is too old, you'll get errors like version 'GLIBC_2.34' not found at runtime. Rebuild the SDK on an older distro (or in an older container) to widen compatibility.

Run (with .so beside the binary):

./SessionExample

If the shared library is not found:

export LD_LIBRARY_PATH=.
./SessionExample

No separate Thrift install is required.

macOS

Copy the example binary and libiotdb_session.dylib together. The target macOS version should be ≥ the deployment target used to build the SDK. Check with:

otool -L SessionExample

Development notes

• Windows: Application and SDK both use /MD (dynamic CRT). This matches a default Visual Studio project; link iotdb_session.lib, ship iotdb_session.dll.
• Linux: SDK is libiotdb_session.so; link it directly. Prefer shipping the .so next to your binary or setting RPATH to $ORIGIN.
• Examples assume IoTDB is listening on 127.0.0.1:6667; change host/port in the source if needed.

Project layout in this module

client-cpp-example/
├── pom.xml              # Maven: unpack SDK + invoke CMake
├── README.md
├── README_zh.md
└── src/
    ├── CMakeLists.txt
    ├── SessionExample.cpp
    ├── AlignedTimeseriesSessionExample.cpp
    ├── MultiSvrNodeClient.cpp
    └── tree_example.c

After mvn package, the runnable tree is under target/ (sources, client/, and CMake build output).