| <!-- |
| |
| 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. |
| |
| --> |
| # Apache IoTDB C++ Client |
| |
| The C++ client is built by a single top-level `CMakeLists.txt` in this |
| directory. The outer Maven POM is a thin wrapper that invokes CMake; you can |
| also build the client standalone with just `cmake` if you don't have Maven |
| available. |
| |
| ## Build layout at a glance |
| |
| ``` |
| iotdb-client/client-cpp/ |
| ├── CMakeLists.txt # single entry point - manages everything |
| ├── cmake/ # helpers (FetchBoost / FetchThrift / ...) |
| ├── third-party/ # local tarball cache (one sub-dir per OS) |
| │ ├── linux/ mac/ windows/ |
| ├── src/include/ # public API headers (installed to include/) |
| ├── src/session/ # Session, Tablet, and C API implementation (.cpp) |
| ├── src/rpc/ # Thrift RPC layer (private, not installed) |
| ├── test/ # Catch2-based integration tests |
| └── pom.xml # Maven wrapper (cmake-maven-plugin) |
| ``` |
| |
| During configure CMake will, in order: |
| |
| 1. Resolve Boost headers (`find_package` → local `third-party/<os>/` tarball → |
| download from `archives.boost.io` when not in offline mode). |
| 2. On Linux/macOS, ensure `m4` / `flex` / `bison` are available; if not, |
| build them from local tarballs into `build/tools/bin` (no `sudo` |
| required). |
| 3. Build a static Apache Thrift from source (tarball cache → download fallback). |
| 4. Run the produced `thrift` compiler on |
| `iotdb-protocol/thrift-{commons,datanode}/src/main/thrift/*.thrift`. |
| 5. Compile `iotdb_session` (the C/C++ session library) and, optionally, |
| the Catch2 integration test binaries. |
| 6. `cmake --install` lays out the SDK under `target/install/{include,lib}`, |
| which Maven's assembly step packages into a zip. |
| |
| ## Build matrix |
| |
| | Goal | Command | |
| |-------------------------------|--------------------------------------------------------------------------------------------------------| |
| | Library only (Linux/macOS) | `mvn -P with-cpp -pl iotdb-client/client-cpp -am -DskipTests package` | |
| | Library only (Windows / MSVC) | `mvn -P with-cpp -pl iotdb-client/client-cpp -am -DskipTests "-Dboost.include.dir=C:\boost_1_88_0" package` | |
| | Library + ITs (Linux/macOS) | `mvn clean install -P with-cpp -pl distribution,iotdb-client/client-cpp -am` then `mvn -P with-cpp -pl iotdb-client/client-cpp -am verify` | |
| | Direct CMake (no Maven) | `cmake -S iotdb-client/client-cpp -B build && cmake --build build --target install` | |
| |
| The Maven build sets `cmake.install.prefix` to `target/install/`. Output zips |
| land at `iotdb-client/client-cpp/target/iotdb-session-cpp-<version>-<classifier>.zip` |
| (with a package root directory and a `.sha512` checksum generated alongside), |
| where `<classifier>` defaults to the OS name (for example `linux-x86_64`) and |
| can be overridden with `-Dclient.cpp.package.classifier=...` when building |
| multiple toolchains on the same platform. |
| |
| ### Release packages (CI) |
| |
| The [C++ Client package](../../.github/workflows/client-cpp-package.yml) workflow |
| builds one zip per platform/toolchain. Pick the artifact that matches your |
| deployment environment: |
| |
| | Target environment | Zip classifier (suffix) | |
| |--------------------|-------------------------| |
| | Linux x86_64, glibc >= 2.28 | `linux-x86_64-glibc2.28` | |
| | Linux aarch64, glibc >= 2.28 | `linux-aarch64-glibc2.28` | |
| | macOS x86_64 | `macos-x86_64` | |
| | macOS arm64 | `macos-aarch64` | |
| | Windows + Visual Studio 2017 | `windows-x86_64-msvc14.1` | |
| | Windows + Visual Studio 2019 | `windows-x86_64-msvc14.2` | |
| | Windows + Visual Studio 2022 | `windows-x86_64-msvc14.3` | |
| | Windows + Visual Studio 2026 | `windows-x86_64-msvc14.4` | |
| |
| Example file name: |
| `iotdb-session-cpp-1.3.7-SNAPSHOT-linux-x86_64-glibc2.28.zip`. |
| |
| **Linux package choice:** The CI Linux packages are built in manylinux_2_28 |
| containers, so use them on hosts with glibc 2.28 or newer. Build locally with |
| the same Maven/CMake options if you need a different baseline. |
| |
| Thrift **0.21.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; |
| with the current CMake build, compatibility is determined by the **compiler |
| and OS used to build** the SDK, not by that Maven property. |
| |
| ### Local build for a specific classifier |
| |
| Linux x86_64 (glibc 2.28 baseline): |
| |
| ```bash |
| mvn -P with-cpp -pl iotdb-client/client-cpp -am -DskipTests \ |
| -Dclient.cpp.package.classifier=linux-x86_64-glibc2.28 package |
| ``` |
| |
| Windows (match the Visual Studio version you use to build your application): |
| |
| ```powershell |
| # Visual Studio 2022 (default on recent Windows) |
| mvn -P with-cpp -pl iotdb-client/client-cpp -am -DskipTests package |
| |
| # Visual Studio 2019 |
| mvn -P with-cpp -pl iotdb-client/client-cpp -am -DskipTests ` |
| "-Dcmake.generator=Visual Studio 16 2019" ` |
| -Dclient.cpp.package.classifier=windows-x86_64-msvc14.2 package |
| |
| # Visual Studio 2017 (CMake uses -A x64 on Windows automatically) |
| mvn -P with-cpp -pl iotdb-client/client-cpp -am -DskipTests ` |
| "-Dcmake.generator=Visual Studio 15 2017" ` |
| -Dclient.cpp.package.classifier=windows-x86_64-msvc14.1 package |
| |
| # Debug build |
| mvn -P with-cpp -pl iotdb-client/client-cpp -am -DskipTests ` |
| "-Dcmake.build.type=Debug" package |
| ``` |
| |
| On Windows, the build passes `-DCMAKE_GENERATOR_PLATFORM=x64` so Visual Studio |
| generators target **x64** (VS2017 otherwise defaults to Win32). |
| |
| ## CMake options |
| |
| The table below lists CMake cache variables. When building through **Maven**, |
| pass them as Maven properties (the POM maps them to `-D` options for CMake): |
| |
| | CMake variable | Maven property (`-D...`) | |
| |----------------|--------------------------| |
| | `WITH_SSL` | `with.ssl` (e.g. `-Dwith.ssl=ON`) | |
| | `IOTDB_OFFLINE` | `iotdb.offline` | |
| | `BUILD_TESTING` | `build.tests` | |
| | `IOTDB_DEPS_DIR` | `iotdb.deps.dir` | |
| | `BOOST_INCLUDEDIR` | `boost.include.dir` (legacy alias) | |
| |
| For a **standalone** `cmake` configure, pass `-DWITH_SSL=ON`, `-DIOTDB_OFFLINE=ON`, |
| etc. directly. |
| |
| | Option | Default | Purpose | |
| |-----------------------|----------------------------------|----------------------------------------------------------------------------------------------------------| |
| | `WITH_SSL` | `OFF` | Link against OpenSSL. 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. | |
| | `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. | |
| |
| ## Online build (default) |
| |
| CMake will download any missing tarball at configure time. The first run is |
| slow (≈100 MB download + a Thrift build); subsequent runs reuse the |
| extracted artifacts under `build/_deps/`. |
| |
| ```bash |
| # Linux / macOS |
| mvn -P with-cpp -pl iotdb-client/client-cpp -am -DskipTests package |
| |
| # Windows (Developer Command Prompt for VS, PowerShell, or cmd) |
| mvn -P with-cpp -pl iotdb-client/client-cpp -am -DskipTests "-Dboost.include.dir=C:\boost_1_88_0" package |
| ``` |
| |
| ## Offline build |
| |
| 1. Pre-populate the platform-specific sub-directory under `third-party/`: |
| |
| | 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`) | |
| |
| 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> |
| - 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> |
| - GNU bison 3.8: <https://ftp.gnu.org/gnu/bison/bison-3.8.tar.gz> |
| - OpenSSL 3.5.0: <https://www.openssl.org/source/openssl-3.5.0.tar.gz> |
| |
| 2. Run the build with offline mode enabled: |
| |
| ```bash |
| mvn -P with-cpp -pl iotdb-client/client-cpp -am -DskipTests \ |
| -Diotdb.offline=ON package |
| ``` |
| |
| or, going straight through CMake: |
| |
| ```bash |
| cmake -S iotdb-client/client-cpp -B build -DIOTDB_OFFLINE=ON |
| cmake --build build --config Release --target install |
| ``` |
| |
| CI environments can share a single cache by setting |
| `-DIOTDB_DEPS_DIR=/path/to/cache` instead of copying tarballs around. |
| |
| ## Platform-specific notes |
| |
| ### Linux |
| |
| - Tested with GCC 7+ and Clang 9+. Anything that can compile Apache Thrift |
| 0.21.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; |
| the helper tools install under `build/tools/`. |
| - If you would rather use distro-provided tools (`apt install m4 flex |
| bison`), CMake will pick them up first. |
| |
| ### macOS |
| |
| - Xcode Command Line Tools provide `m4`, `flex`, `bison`, and `make`, |
| so the auto-build path normally skips them. |
| - Homebrew users can `brew install boost` to short-circuit `FetchBoost`. |
| |
| ### Windows |
| |
| Visual Studio **2017, 2019, 2022, or 2026** is supported for building the SDK. |
| Link your application against the zip built with the **same VS generation** you |
| use for your project. |
| |
| Prerequisites: |
| |
| 1. **Boost.** Download and extract |
| <https://archives.boost.io/release/1.88.0/source/boost_1_88_0.zip> |
| (any 1.60+ release will work). `iotdb_session` only needs Boost |
| headers, so running `bootstrap.bat` / `b2` is optional. Pass the |
| location with either `-Dboost.include.dir="C:\boost_1_88_0"` (Maven) |
| or `-DBOOST_ROOT="C:\boost_1_88_0"` (raw CMake). |
| 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. |
| |
| On Windows the SDK ships as **`iotdb_session.dll`** plus an import library |
| **`iotdb_session.lib`**, built with **`/MD`** (dynamic CRT, same as a |
| default Visual Studio application). Thrift is linked into the DLL; users |
| do not install separate Thrift headers or libraries. Place |
| `iotdb_session.dll` next to your `.exe` or on `PATH`. |
| |
| Auto-building m4/flex/bison from tarball is **not** supported on Windows; |
| 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: |
| |
| - **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. |
| |
| ## Tests |
| |
| Maven binds `cmake-maven-plugin`'s `test` goal to the `integration-test` |
| phase and runs `ctest`. `pre-integration-test` spawns a local IoTDB server |
| from `distribution/target/.../sbin/start-standalone.{sh,bat}`, so make sure |
| the distribution module is built first: |
| |
| ```bash |
| mvn clean install -P with-cpp -pl distribution,iotdb-client/client-cpp -am -DskipTests |
| mvn -P with-cpp -pl iotdb-client/client-cpp -am verify |
| ``` |
| |
| Running ctest directly (after a `mvn ... package` build) is also supported: |
| |
| ```bash |
| cd iotdb-client/client-cpp/target/build/test |
| ctest --output-on-failure |
| ``` |
| |
| ## Code formatting |
| |
| We use `clang-format` (pinned by the root POM as `clang.format.version`) |
| through Maven Spotless. **clang-format 17.0.6** is the version CI runs. |
| |
| ```bash |
| mvn -P with-cpp -pl iotdb-client/client-cpp spotless:check |
| mvn -P with-cpp -pl iotdb-client/client-cpp spotless:apply |
| ``` |
| |
| On JDK 8 the C++ Spotless profile is skipped automatically (Spotless's |
| clang-format integration requires Spotless 2.44+, which itself requires |
| JDK 11+). |
| |
| ## Package layout |
| |
| A successful `mvn ... package` produces |
| `target/iotdb-session-cpp-<version>-<classifier>.zip` with this layout: |
| |
| ``` |
| iotdb-session-cpp-<version>-<classifier>/ |
| |-- BUILD-INFO.txt |
| |-- VERSION |
| |-- cmake/ |
| |-- pkgconfig/ |
| |-- include/ |
| | |-- Session.h |
| | |-- SessionC.h |
| | `-- ... (public API headers only; no Thrift/Boost) |
| `-- lib/ |
| |-- libiotdb_session.{so,dylib} (Linux / macOS) |
| |-- iotdb_session.dll (Windows runtime) |
| `-- iotdb_session.lib (Windows import library for linking) |
| ``` |
| |
| Thrift is embedded inside `iotdb_session` on all platforms; it is not shipped |
| as a separate install artifact. |
| |
| ## Using the C++ client |
| |
| ```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(); |
| } |
| ``` |
| |
| Compile against the produced SDK: |
| |
| ```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 |
| ``` |
| |
| For full API documentation see the [C++ Native API guide](https://iotdb.apache.org/UserGuide/latest/API/Programming-Cpp-Native-API.html). |
