Clarify C++ client build and usage docs

Author: hongzhi-gao

iotdb-client/client-cpp/README.md

@@ -95,7 +95,8 @@ example, link a `windows-x86_64-msvc14.3` package with Visual Studio 2022.
 
 Visual Studio users can either open the project folder and add the unpacked SDK
 directory to `CMAKE_PREFIX_PATH` in CMake cache settings, or configure from a
-Developer Command Prompt:
+Developer Command Prompt. Use the same configuration (`Release` or `Debug`) as
+the SDK package you unpacked, and copy the runtime DLL next to your executable:
 
 ```bat
 cmake -S . -B build -G "Visual Studio 17 2022" -A x64 ^
@@ -207,9 +208,9 @@ by default. Start IoTDB before running them.
 
 - Linux release packages are built in the `manylinux_2_28` container and require
   glibc 2.28 or newer.
-- Windows packages use the dynamic MSVC runtime (`/MD`). Install the Microsoft
-  Visual C++ Redistributable matching your Visual Studio generation on target
-  machines that do not already have it.
+- Windows Release packages use the dynamic MSVC runtime (`/MD`); Debug
+  packages use the debug runtime (`/MDd`) and are intended for local
+  development with a matching Debug application.
 - Put `libiotdb_session.so`, `libiotdb_session.dylib`, or `iotdb_session.dll`
   next to your executable, or configure the platform library search path. On
   Linux, keep the `libiotdb_session.so*` symlink chain together when copying
@@ -252,23 +253,78 @@ During configure CMake will, in order:
 6. `cmake --install` lays out the SDK under `target/install/{include,lib}`,
    which Maven's assembly step packages into a zip.
 
-### Build matrix
+### Maven build
 
-| Goal                          | Command                                                                                                |
-|-------------------------------|--------------------------------------------------------------------------------------------------------|
-| Library only (Linux/macOS)    | `mvn -P with-cpp -pl iotdb-client/client-cpp -am -DskipTests package`                                  |
-| Debug library (Linux/macOS)   | `mvn -P with-cpp -pl iotdb-client/client-cpp -am -DskipTests -Dcmake.build.type=Debug 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` |
-| Debug library (Windows / MSVC) | `mvn -P with-cpp -pl iotdb-client/client-cpp -am -DskipTests -Dcmake.build.type=Debug "-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 wrapper configures CMake, builds the SDK, installs it under
+`iotdb-client/client-cpp/target/install/`, and packages a zip at
+`iotdb-client/client-cpp/target/iotdb-session-cpp-<version>-<classifier>.zip`
+with a `.sha512` checksum generated alongside.
 
-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).
+Linux/macOS:
+
+```bash
+# Release
+mvn -P with-cpp -pl iotdb-client/client-cpp -am -DskipTests package
+
+# Debug
+mvn -P with-cpp -pl iotdb-client/client-cpp -am -DskipTests \
+  -Dcmake.build.type=Debug package
+```
+
+Windows PowerShell:
+
+```powershell
+# Release
+mvn -P with-cpp -pl iotdb-client/client-cpp -am -DskipTests `
+  "-Dboost.include.dir=C:\boost_1_88_0" package
+
+# Debug
+mvn -P with-cpp -pl iotdb-client/client-cpp -am -DskipTests `
+  "-Dcmake.build.type=Debug" `
+  "-Dboost.include.dir=C:\boost_1_88_0" package
+```
+
+Quote Maven `-D...` arguments that contain dots when running from PowerShell.
+For `cmd.exe`, keep each command on one line or use `^` for line continuation.
 The classifier can be overridden with `-Dclient.cpp.package.classifier=...` when
 building multiple toolchains on the same platform.
 
+### Direct CMake build
+
+Use direct CMake when you only need an installed SDK layout and do not need the
+Maven-generated zip/checksum.
+
+Linux/macOS:
+
+```bash
+# Release
+cmake -S iotdb-client/client-cpp -B build -DCMAKE_BUILD_TYPE=Release
+cmake --build build --target install
+
+# Debug
+cmake -S iotdb-client/client-cpp -B build -DCMAKE_BUILD_TYPE=Debug
+cmake --build build --target install
+```
+
+Windows with Visual Studio:
+
+```powershell
+# Release
+cmake -S iotdb-client/client-cpp -B build -G "Visual Studio 17 2022" -A x64 `
+  -DBOOST_ROOT="C:\boost_1_88_0"
+cmake --build build --config Release --target install
+
+# Debug
+cmake -S iotdb-client/client-cpp -B build -G "Visual Studio 17 2022" -A x64 `
+  -DCMAKE_BUILD_TYPE=Debug `
+  -DBOOST_ROOT="C:\boost_1_88_0"
+cmake --build build --config Debug --target install
+```
+
+For Visual Studio generators, `--config` selects the final SDK configuration.
+Set `CMAKE_BUILD_TYPE=Debug` during configure for Debug builds as well, because
+the top-level build uses it when building bundled third-party static libraries.
+
 ### Release packages (CI)
 
 The [C++ Client package](../../.github/workflows/client-cpp-package.yml) workflow
@@ -309,51 +365,32 @@ 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, matching the manylinux_2_28 release build):
+The default classifier is chosen from the host OS. Override it explicitly when
+you are building release artifacts for a specific target:
 
 ```bash
 mvn -P with-cpp -pl iotdb-client/client-cpp -am -DskipTests \
   -Dclient.cpp.package.classifier=linux-x86_64-glibc2.28 package
 ```
 
-Debug build:
-
-```bash
-mvn -P with-cpp -pl iotdb-client/client-cpp -am -DskipTests \
-  -Dcmake.build.type=Debug package
-```
-
-Direct CMake Debug builds use the same build type. On Linux/macOS, pass
-`-DCMAKE_BUILD_TYPE=Debug` during configure. On Windows with Visual Studio,
-also pass `-DCMAKE_BUILD_TYPE=Debug` during configure so the bundled Thrift
-static library is built with the Debug MSVC runtime, then build with
-`--config Debug`:
-
-```bash
-# Linux/macOS
-cmake -S iotdb-client/client-cpp -B build -DCMAKE_BUILD_TYPE=Debug
-cmake --build build --target install
-
-# Windows / Visual Studio
-cmake -S iotdb-client/client-cpp -B build -G "Visual Studio 17 2022" -A x64 -DCMAKE_BUILD_TYPE=Debug
-cmake --build build --config Debug --target install
-```
-
 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
+mvn -P with-cpp -pl iotdb-client/client-cpp -am -DskipTests `
+  "-Dboost.include.dir=C:\boost_1_88_0" 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
+  "-Dboost.include.dir=C:\boost_1_88_0" `
+  "-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
+  "-Dboost.include.dir=C:\boost_1_88_0" `
+  "-Dcmake.generator=Visual Studio 15 2017" `
+  "-Dclient.cpp.package.classifier=windows-x86_64-msvc14.1" package
 ```
 
 On Windows, the build passes `-DCMAKE_GENERATOR_PLATFORM=x64` so Visual Studio
@@ -401,25 +438,8 @@ 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
-```
-
-Standalone CMake uses the same online dependency resolution:
-
-```bash
-# Linux / macOS
-cmake -S iotdb-client/client-cpp -B build -DCMAKE_BUILD_TYPE=Release
-cmake --build build --target install
-
-# Windows / Visual Studio
-cmake -S iotdb-client/client-cpp -B build -G "Visual Studio 17 2022" -A x64
-cmake --build build --config Release --target install
-```
+Use the Maven or direct CMake commands above. Both build paths use the same
+online dependency resolution.
 
 ## Offline build
 
@@ -497,9 +517,10 @@ Prerequisites:
    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.lib`**. Release SDKs are built with **`/MD`** (dynamic CRT,
+same as a default Release Visual Studio application); Debug SDKs are built with
+**`/MDd`** and should be linked by Debug applications. 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;

iotdb-client/client-cpp/README_zh.md

@@ -223,7 +223,7 @@ CMake 的包装；没有 Maven 时也可以直接使用 CMake。
 | 只构建库（Linux/macOS） | `mvn -P with-cpp -pl iotdb-client/client-cpp -am -DskipTests package` |
 | 构建 Debug 库（Linux/macOS） | `mvn -P with-cpp -pl iotdb-client/client-cpp -am -DskipTests -Dcmake.build.type=Debug package` |
 | 只构建库（Windows / MSVC） | `mvn -P with-cpp -pl iotdb-client/client-cpp -am -DskipTests "-Dboost.include.dir=C:\boost_1_88_0" package` |
-| 构建 Debug 库（Windows / MSVC） | `mvn -P with-cpp -pl iotdb-client/client-cpp -am -DskipTests -Dcmake.build.type=Debug "-Dboost.include.dir=C:\boost_1_88_0" package` |
+| 构建 Debug 库（Windows / MSVC） | `mvn -P with-cpp -pl iotdb-client/client-cpp -am -DskipTests "-Dcmake.build.type=Debug" "-Dboost.include.dir=C:\boost_1_88_0" package` |
 | 直接使用 CMake | `cmake -S iotdb-client/client-cpp -B build && cmake --build build --target install` |
 
 Maven 构建会把 SDK 安装到 `target/install/`，并生成
@@ -250,11 +250,21 @@ Studio 生成器时也需要传入该选项，以便内置 Thrift 静态库使
 
 ```bash
 # Linux/macOS
+# Release
+cmake -S iotdb-client/client-cpp -B build -DCMAKE_BUILD_TYPE=Release
+cmake --build build --target install
+
+# Debug
 cmake -S iotdb-client/client-cpp -B build -DCMAKE_BUILD_TYPE=Debug
 cmake --build build --target install
 
 # Windows / Visual Studio
-cmake -S iotdb-client/client-cpp -B build -G "Visual Studio 17 2022" -A x64 -DCMAKE_BUILD_TYPE=Debug
+# Release
+cmake -S iotdb-client/client-cpp -B build -G "Visual Studio 17 2022" -A x64 -DBOOST_ROOT="C:\boost_1_88_0"
+cmake --build build --config Release --target install
+
+# Debug
+cmake -S iotdb-client/client-cpp -B build -G "Visual Studio 17 2022" -A x64 -DCMAKE_BUILD_TYPE=Debug -DBOOST_ROOT="C:\boost_1_88_0"
 cmake --build build --config Debug --target install
 ```