docs: update requirements and integration in README

Signed-off-by: ik <[email protected]>
openGemini · Aug 24, 2024 · d34690d · d34690d
1 parent 02e1555
commit d34690d
Show file tree

Hide file tree

Showing 2 changed files with 218 additions and 2 deletions.
diff --git a/README.md b/README.md
@@ -2,12 +2,118 @@
 
 ![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.**
+---
+
+- [Prerequisites](#prerequisites)
+- [Integration](#integration)
+    - [CMake FetchContent](#cmake-fetchcontent)
+    - [CMake FindPackage](#cmake-findpackage)
+    - [Header-Only](#header-only)
+- [Build From Source](#build-from-source)
+- [Configuration](#configuration)
+- [Design Doc](#design-doc)
+- [About OpenGemini](#about-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`:
+```
+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:
+```
+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`:
+```
+find_package(OpenGeminiCxx REQUIRED)
+```
+
+This will export the target `OpenGeminiCxx::Client` which you can link against to your own target like this:
+```
+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:
+```
+#include <opengemini/Client.hpp>
+```
+
+## 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:
+```
+$ 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:
+```
+$ cmake -DOPENGEMINI_ENABLE_SSL_SUPPORT=ON .. 
+```
+
+You can also control generation of unit tests with `OPENGEMINI_BUILD_TESTING` option:
+```
+$ cmake -DOPENGEMINI_BUILD_TESTING=ON .. 
+```
+
+For details of all the options see [Configuration](#configuration).
+
+## Configuration
+|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)|
 
 ## Design Doc
 
@@ -16,3 +122,4 @@ English | [简体中文](README_CN.md)
 ## About OpenGemini
 
 OpenGemini is a cloud-native distributed time series database, find more information [here](https://github.com/openGemini/openGemini)
+
diff --git a/README_CN.md b/README_CN.md
@@ -2,11 +2,119 @@
 
 ![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接口不是稳定版本，可能随开发进程有所调整。**
+---
+
+- [前置条件](#前置条件)
+- [与项目集成](#与项目集成)
+    - [CMake FetchContent](#cmake-fetchcontent)
+    - [CMake FindPackage](#cmake-findpackage)
+    - [Header-Only](#header-only)
+- [从源码构建](#从源码构建)
+- [配置选项](#配置选项)
+- [设计文档](#设计文档)
+- [关于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`中：
+```
+include(FetchContent)
+FetchContent_Declare(OpenGeminiCxx
+    GIT_REPOSITORY https://github.com/openGemini/opengemini-client-cpp
+    GIT_TAG        main
+)
+FetchContent_MakeAvailable(OpenGeminiCxx)
+```
+
+这将导出目标`OpenGeminiCxx::Client`，您可以将其链接到自己的目标中：
+```
+add_executable(YourApp main.cpp)
+target_link_libraries(YourApp PRIVATE OpenGeminiCxx::Client)
+```
+
+### CMake FindPackage
+也可以使用CMake `find_package()` 函数来集成到项目中。
+
+这意味着您必须先在系统上[构建并安装](#从源码构建)OpenGeminiCxx。
+
+接着就可以将下列代码添加至`CMakeLists.txt`中：
+```
+find_package(OpenGeminiCxx REQUIRED)
+```
+
+这将导出目标`OpenGeminiCxx::Client`，您可以将其链接到自己的目标中：
+```
+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`添加至工程的包含路径中。
+
+然后就可以直接在源码中包含（可能需要手动将必要的依赖库链接到工程中）：
+```
+#include <opengemini/Client.hpp>
+```
+
+## 从源码构建
+确保所有必要的构建工具和依赖库**已经安装**到您的系统上了，接着就可以下载并构建OpenGeminiCxx：
+```
+$ 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`进行配置：
+```
+$ cmake -DOPENGEMINI_ENABLE_SSL_SUPPORT=ON .. 
+```
+
+也可以通过选项`OPENGEMINI_ENABLE_SSL_SUPPORT`来生成单元测试：
+```
+$ cmake -DOPENGEMINI_BUILD_TESTING=ON .. 
+```
+
+关于所有配置选项的详细信息，参见[配置选项](#配置选项)
+
+## 配置选项
+|选项|描述|默认值|
+|:---|:---|:---|
+|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>（当是根项目时）|
 
 ## 设计文档
 
@@ -15,3 +123,4 @@
 ## 关于 OpenGemini
 
 OpenGemini 是一款云原生分布式时序数据库。获取更多信息，请点击[这里](https://github.com/openGemini/openGemini)
+