docs: update requirements and integration in README (#29)

Signed-off-by: ik <[email protected]>
openGemini · Sep 4, 2024 · d79c69c · d79c69c
1 parent 28a727a
commit d79c69c
Show file tree

Hide file tree

Showing 3 changed files with 349 additions and 6 deletions.
diff --git a/CONTRIBUTION.md b/CONTRIBUTION.md
@@ -0,0 +1 @@
+Coming soon...
diff --git a/README.md b/README.md
@@ -2,17 +2,187 @@
 
 ![License](https://img.shields.io/badge/license-Apache2.0-green) ![Language](https://img.shields.io/badge/language-C++-blue.svg) [![Version](https://img.shields.io/github/v/tag/opengemini/opengemini-client-cpp?label=release&color=blue)](https://github.com/opengemini/opengemini-client-cpp/releases)
 
+> ⚠️  **This repository is in pre-alpha stage, so not yet feature-complete. And the API has not been frozen, it may be changed on the course of the development.**
 
 English | [简体中文](README_CN.md)
 
 `opengemini-client-cpp` is a C++ client for OpenGemini
 
-> ⚠️  **This repository is in pre-alpha stage, so not yet feature-complete. And the API has not been frozen, it may be changed on the course of the development.**
+---
 
-## Design Doc
+- [Design Doc](#design-doc)
+- [About OpenGemini](#about-opengemini)
+- [Prerequisites](#prerequisites)
+- [Integration](#integration)
+    - [CMake FetchContent](#cmake-fetchcontent)
+    - [CMake FindPackage](#cmake-findpackage)
+    - [Header-Only](#header-only)
+- [Quick Start](#quick-start)
+- [Build From Source](#build-from-source)
+- [Configuration](#configuration)
+- [Contribute](#contribute)
 
+## Design Doc
 [OpenGemini Client Design Doc](https://github.com/openGemini/openGemini.github.io/blob/main/src/guide/develop/client_design.md)
 
 ## About OpenGemini
-
 OpenGemini is a cloud-native distributed time series database, find more information [here](https://github.com/openGemini/openGemini)
+
+## Prerequisites
+- **Building Environment**
+    - A compatible operating system: Linux, macOS, Windows
+    - A C++ compiler toolset that supports at least C++17 standard: GCC, Clang, MSVC
+    - [CMake](https://cmake.org/) 3.12 or later
+    - [Doxygen](https://www.doxygen.nl/) (*optional*, for generating documents)
+- **Dependencies**
+    - [Boost](https://github.com/boostorg/boost) 1.81 or later
+    - [{fmt}](https://github.com/fmtlib/fmt)
+    - [JSON](https://github.com/nlohmann/json)
+    - [OpenSSL](https://github.com/openssl/openssl) (*optional*, for using TLS protocol)
+    - [GoogleTest](https://github.com/google/googletest) (*optional*, for building unit tests)
+
+## Integration
+### CMake FetchContent
+It is recommended to integrate with OpenGeminiCxx using CMake's [FetchContent](https://cmake.org/cmake/help/latest/module/FetchContent.html).
+
+The library, along with any necessary dependencies(**excluding OpenSSL**), will be downloaded automatically, so you don't need to handle it yourself.
+
+You can including the following lines in your `CMakeLists.txt`:
+```cmake
+include(FetchContent)
+FetchContent_Declare(OpenGeminiCxx
+    GIT_REPOSITORY https://github.com/openGemini/opengemini-client-cpp
+    GIT_TAG        main
+)
+FetchContent_MakeAvailable(OpenGeminiCxx)
+```
+
+This will export the target `OpenGeminiCxx::Client` which you can link against to your own target like this:
+```cmake
+add_executable(YourApp main.cpp)
+target_link_libraries(YourApp PRIVATE OpenGeminiCxx::Client)
+```
+
+### CMake FindPackage
+You can also use CMake's `find_package()` function to integrate the library into your project.
+
+This means you need to [build and install](#build-from-source) OpenGeminiCxx on your system first.
+
+Then you can add the following lines in your `CMakeLists.txt`:
+```cmake
+find_package(OpenGeminiCxx REQUIRED)
+```
+
+This will export the target `OpenGeminiCxx::Client` which you can link against to your own target like this:
+```cmake
+add_executable(YourApp main.cpp)
+target_link_libraries(YourApp PRIVATE OpenGeminiCxx::Client)
+```
+
+### Header-Only
+> **Note:** Although OpenGeminiCxx can be use as a header-only library, we still recommend use the compiled library for improved build times.
+
+Download the [OpenGeminiCxx](https://github.com/openGemini/opengemini-client-cpp/releases), then add `/path/to/opengemini-client-cpp/include` to your project's including directories.
+
+You may also need to link against any necessary dependencies to your program manually, then you can include it directly in your source code with:
+```cpp
+#include <opengemini/Client.hpp>
+```
+
+## Quick Start
+Below are a few examples show how to use some of the main features of the library. For more example code, please check out `examples` directory;
+### Query data from the server
+```cpp
+#include <iostream>
+
+#include <opengemini/Client.hpp>
+#include <opengemini/ClientConfigBuilder.hpp>
+
+int main(int argc, char** argv)
+{
+    // Constructs an openGemini client object.
+    opengemini::Client client{ opengemini::ClientConfigBuilder()
+                                   // At least one server endpoint needed.
+                                   .AppendAddress({ "127.0.0.1", 8086 })
+                                   .Finalize() };
+
+    // Performs a query request and print the result, the operation will
+    // block until completes or an exception is thrown.
+    auto result = client.Query({
+        "ExampleDatabase",
+        "select * from ExampleMeasurement",
+    });
+    std::cout << result << std::endl;
+
+    return 0;
+}
+```
+
+### Write points to server
+```cpp
+#include <iostream>
+
+#include <opengemini/Client.hpp>
+#include <opengemini/ClientConfigBuilder.hpp>
+
+int main(int argc, char** argv)
+{
+    // Constructs an openGemini client object.
+    opengemini::Client client{ opengemini::ClientConfigBuilder()
+                                   // At least one server endpoint needed.
+                                   .AppendAddress({ "127.0.0.1", 8086 })
+                                   .Finalize() };
+
+    // Writes single point to server, the operation will
+    // block until completes or an exception is thrown.
+    client.Write("ExampleDatabase",
+                 {
+                     "ExampleMeasurement",
+                     {
+                         { "Weather", "sunny" },
+                         { "Humidity", 521 },
+                         { "Temperature", 38.1 },
+                     },
+                     std::chrono::system_clock::now(),
+                 });
+    return 0;
+}
+```
+
+## Build From Source
+Make sure all required build tools and dependencies **are installed** on your system, then you can download and build the OpenGeminiCxx library:
+```bash
+git clone https://github.com/openGemini/opengemini-client-cpp.git
+cd opengemini-client-cpp && mkdir build && cd build
+cmake ..
+make -j
+make install
+```
+
+If you want to enable TLS support, you can configure with `OPENGEMINI_ENABLE_SSL_SUPPORT` option:
+```bash
+cmake -DOPENGEMINI_ENABLE_SSL_SUPPORT=ON .. 
+```
+
+You can also control generation of unit tests with `OPENGEMINI_BUILD_TESTING` option:
+```bash
+cmake -DOPENGEMINI_BUILD_TESTING=ON .. 
+```
+
+For details of all the options see [CMake Options](#cmake-options).
+
+## Configuration
+### CMake Options
+|Option|Description|Default Value|
+|:---|:---|:---|
+|OPENGEMINI_ENABLE_SSL_SUPPORT|Enable OpenSSL support for using TLS (**OpenSSL required**)|OFF|
+|OPENGEMINI_BUILD_DOCUMENTATION|Build API documentation (**Doxygen required**)|OFF|
+|OPENGEMINI_BUILD_TESTING|Build unit tests (**GoogleTest required**)|OFF|
+|OPENGEMINI_BUILD_SHARED_LIBS|Build shared libraries instead of static ones. Only has effect if option `OPENGEMINI_BUILD_HEADER_ONLY_LIBS` is `OFF`| OFF|
+|OPENGEMINI_BUILD_EXAMPLE|Build examples|OFF|
+|OPENGEMINI_BUILD_HEADER_ONLY_LIBS|Build as header-only library|OFF|
+|OPENGEMINI_GENERATE_INSTALL_TARGET|Generate the install target, should not be set to `ON` if `OPENGEMINI_USE_FETCHCONTENT` is also `ON`|ON<br>(if is root project)|
+|OPENGEMINI_USE_FETCHCONTENT|Automatically using FetchContent if dependencies not found|OFF<br>(if is root project)|
+
+## Contribution
+Welcome to [join us](CONTRIBUTION.md).
diff --git a/README_CN.md b/README_CN.md
@@ -2,16 +2,188 @@
 
 ![License](https://img.shields.io/badge/开源许可证-Apache2.0-green) ![language](https://img.shields.io/badge/语言-C++-blue.svg) [![version](https://img.shields.io/github/v/tag/opengemini/opengemini-client-cpp?label=发行版本&color=blue)](https://github.com/opengemini/opengemini-client-cpp/releases)
 
+> ⚠️  **当前仓库仍处于早期开发阶段，功能特性尚未完成。目前提供的API接口不是稳定版本，可能随开发进程有所调整。**
+
 [English](README.md) | 简体中文
 
 `opengemini-client-cpp`是一个用 C++ 语言编写的 OpenGemini 客户端
 
-> ⚠️  **当前仓库仍处于早期开发阶段，功能特性尚未完成。目前提供的API接口不是稳定版本，可能随开发进程有所调整。**
+---
 
-## 设计文档
+- [设计文档](#设计文档)
+- [关于OpenGemini](#关于OpenGemini)
+- [前置条件](#前置条件)
+- [与项目集成](#与项目集成)
+    - [CMake FetchContent](#cmake-fetchcontent)
+    - [CMake FindPackage](#cmake-findpackage)
+    - [Header-Only](#header-only)
+- [快速上手](#快速上手)
+- [从源码构建](#从源码构建)
+- [配置选项](#配置选项)
+- [贡献](#贡献)
 
+## 设计文档
 [OpenGemini Client 设计文档](https://github.com/openGemini/openGemini.github.io/blob/main/src/zh/guide/develop/client_design.md)
 
 ## 关于 OpenGemini
-
 OpenGemini 是一款云原生分布式时序数据库。获取更多信息，请点击[这里](https://github.com/openGemini/openGemini)
+
+## 前置条件
+- **构建环境**
+    - 兼容的操作系统：Linux，macOS，Windows
+    - 支持C++17（或更新版本）的编译套件: GCC，Clang，MSVC
+    - [CMake](https://cmake.org/) 3.12或更高版本
+    - [Doxygen](https://www.doxygen.nl/) (*非必选*，用于生成文档)
+- **依赖库**
+    - [Boost](https://github.com/boostorg/boost) 1.81或更高版本
+    - [{fmt}](https://github.com/fmtlib/fmt)
+    - [JSON](https://github.com/nlohmann/json)
+    - [OpenSSL](https://github.com/openssl/openssl) (*非必选*，用于启用TLS协议支持)
+    - [GoogleTest](https://github.com/google/googletest) (*非必选*，用于构建单元测试)
+
+
+## 与项目集成
+### CMake FetchContent
+我们推荐使用CMake [FetchContent](https://cmake.org/cmake/help/latest/module/FetchContent.html) 来将OpenGeminiCxx集成到您的项目中。
+
+库自身和所有必要的依赖（除了OpenSSL）都会自动下载，不需要手动处理依赖。
+
+可以将下列代码添加至项目的`CMakeLists.txt`中：
+```cmake
+include(FetchContent)
+FetchContent_Declare(OpenGeminiCxx
+    GIT_REPOSITORY https://github.com/openGemini/opengemini-client-cpp
+    GIT_TAG        main
+)
+FetchContent_MakeAvailable(OpenGeminiCxx)
+```
+
+这将导出目标`OpenGeminiCxx::Client`，您可以将其链接到自己的目标中：
+```cmake
+add_executable(YourApp main.cpp)
+target_link_libraries(YourApp PRIVATE OpenGeminiCxx::Client)
+```
+
+### CMake FindPackage
+也可以使用CMake `find_package()` 函数来集成到项目中。
+
+这意味着您必须先在系统上[构建并安装](#从源码构建)OpenGeminiCxx。
+
+接着就可以将下列代码添加至`CMakeLists.txt`中：
+```cmake
+find_package(OpenGeminiCxx REQUIRED)
+```
+
+这将导出目标`OpenGeminiCxx::Client`，您可以将其链接到自己的目标中：
+```cmake
+add_executable(YourApp main.cpp)
+target_link_libraries(YourApp PRIVATE OpenGeminiCxx::Client)
+```
+
+### Header-Only
+> **注意：** 尽管OpenGeminiCxx可以当作纯头文件引用，但我们仍建议使用预编译好的版本以减少构建时间。
+
+下载[OpenGeminiCxx](https://github.com/openGemini/opengemini-client-cpp/releases)，然后将`/path/to/opengemini-client-cpp/include`添加至工程的包含路径中。
+
+然后就可以直接在源码中包含（可能需要手动将必要的依赖库链接到工程中）：
+```cpp
+#include <opengemini/Client.hpp>
+```
+
+## 快速上手
+下列示例代码简单演示了这个库的一些主要特性，您可以通过`examples`目录查看更多的示例代码。
+### 从服务端查询数据
+```cpp
+#include <iostream>
+
+#include <opengemini/Client.hpp>
+#include <opengemini/ClientConfigBuilder.hpp>
+
+int main(int argc, char** argv)
+{
+    // 构造OpenGemini客户端对象。
+    opengemini::Client client{ opengemini::ClientConfigBuilder()
+                                    // 需要至少指定一个服务端的端点
+                                   .AppendAddress({ "127.0.0.1", 8086 })
+                                   .Finalize() };
+
+    // 执行查询请求并直接将结果直接打印。
+    // 该操作将会一直阻塞，直到成功完成或抛出异常。
+    auto result = client.Query({
+        "ExampleDatabase",
+        "select * from ExampleMeasurement",
+    });
+    std::cout << result << std::endl;
+
+    return 0;
+}
+```
+
+### 向服务端写入点位
+```cpp
+#include <iostream>
+
+#include <opengemini/Client.hpp>
+#include <opengemini/ClientConfigBuilder.hpp>
+
+int main(int argc, char** argv)
+{
+    // 构造OpenGemini客户端对象。
+    opengemini::Client client{ opengemini::ClientConfigBuilder()
+                                    // 需要至少指定一个服务端的端点
+                                   .AppendAddress({ "127.0.0.1", 8086 })
+                                   .Finalize() };
+
+    // 向服务端写入单个点位。
+    // 该操作将会一直阻塞，直到成功完成或抛出异常。
+    client.Write("ExampleDatabase",
+                 {
+                     "ExampleMeasurement",
+                     {
+                         { "Weather", "sunny" },
+                         { "Humidity", 521 },
+                         { "Temperature", 38.1 },
+                     },
+                     std::chrono::system_clock::now(),
+                 });
+    return 0;
+}
+```
+
+## 从源码构建
+确保所有必要的构建工具和依赖库**已经安装**到您的系统上了，接着就可以下载并构建OpenGeminiCxx：
+```bash
+git clone https://github.com/openGemini/opengemini-client-cpp.git
+cd opengemini-client-cpp && mkdir build && cd build
+cmake ..
+make -j
+make install
+```
+
+如果想要启用TLS支持，可以使用选项`OPENGEMINI_ENABLE_SSL_SUPPORT`进行配置：
+```bash
+cmake -DOPENGEMINI_ENABLE_SSL_SUPPORT=ON .. 
+```
+
+也可以通过选项`OPENGEMINI_ENABLE_SSL_SUPPORT`来生成单元测试：
+```bash
+cmake -DOPENGEMINI_BUILD_TESTING=ON .. 
+```
+
+关于所有配置选项的详细信息，参见[CMake选项](#CMake选项)
+
+## 配置选项
+### CMake选项
+|选项|描述|默认值|
+|:---|:---|:---|
+|OPENGEMINI_ENABLE_SSL_SUPPORT|启用TLS支持（**需要OpenSSL**）|OFF|
+|OPENGEMINI_BUILD_DOCUMENTATION|构建API文档（**需要Doxygen**）|OFF|
+|OPENGEMINI_BUILD_TESTING|构建单元测试（**需要GoogleTest**）|OFF|
+|OPENGEMINI_BUILD_SHARED_LIBS|构建为动态库，仅当选项`OPENGEMINI_BUILD_HEADER_ONLY_LIBS`的值为`OFF`时生效| OFF|
+|OPENGEMINI_BUILD_EXAMPLE|构建样例代码|OFF|
+|OPENGEMINI_BUILD_HEADER_ONLY_LIBS|构建为header-only库|OFF|
+|OPENGEMINI_GENERATE_INSTALL_TARGET|生成安装目标，该选项和`OPENGEMINI_USE_FETCHCONTENT`选项的值不能同时为`ON`|ON<br>（当是根项目时）|
+|OPENGEMINI_USE_FETCHCONTENT|若无法找到依赖，则自动使用FetchContent|OFF<br>（当是根项目时）|
+
+## 贡献
+欢迎[加入我们](CONTRIBUTION.md)。