Skip to content

Commit d7c5205

Browse files
hiiiikhiiiik
committed
docs: update requirements and integration in README
Signed-off-by: ik <[email protected]>
1 parent 02e1555 commit d7c5205

File tree

2 files changed

+282
-6
lines changed

2 files changed

+282
-6
lines changed

‎README.md

+168-3
Original file line numberDiff line numberDiff line change
@@ -2,17 +2,182 @@
22

33
![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)
44

5+
> ⚠️ **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.**
56
67
English | [简体中文](README_CN.md)
78

89
`opengemini-client-cpp` is a C++ client for OpenGemini
910

10-
> ⚠️ **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.**
11+
---
1112

12-
## Design Doc
13+
- [Design Doc](#design-doc)
14+
- [About OpenGemini](#about-opengemini)
15+
- [Prerequisites](#prerequisites)
16+
- [Integration](#integration)
17+
- [CMake FetchContent](#cmake-fetchcontent)
18+
- [CMake FindPackage](#cmake-findpackage)
19+
- [Header-Only](#header-only)
20+
- [Quick Start](#quick-start)
21+
- [Build From Source](#build-from-source)
22+
- [Configuration](#configuration)
1323

24+
## Design Doc
1425
[OpenGemini Client Design Doc](https://github.com/openGemini/openGemini.github.io/blob/main/src/guide/develop/client_design.md)
1526

1627
## About OpenGemini
17-
1828
OpenGemini is a cloud-native distributed time series database, find more information [here](https://github.com/openGemini/openGemini)
29+
30+
## Prerequisites
31+
- **Building Environment**
32+
- A compatible operating system: Linux, macOS, Windows
33+
- A C++ compiler toolset that supports at least C++17 standard: GCC, Clang, MSVC
34+
- [CMake](https://cmake.org/) 3.12 or later
35+
- [Doxygen](https://www.doxygen.nl/) (*optional*, for generating documents)
36+
- **Dependencies**
37+
- [Boost](https://github.com/boostorg/boost) 1.81 or later
38+
- [{fmt}](https://github.com/fmtlib/fmt)
39+
- [JSON](https://github.com/nlohmann/json)
40+
- [OpenSSL](https://github.com/openssl/openssl) (*optional*, for using TLS protocol)
41+
- [GoogleTest](https://github.com/google/googletest) (*optional*, for building unit tests)
42+
43+
## Integration
44+
### CMake FetchContent
45+
It is recommended to integrate with OpenGeminiCxx using CMake's [FetchContent](https://cmake.org/cmake/help/latest/module/FetchContent.html).
46+
47+
The library, along with any necessary dependencies(**excluding OpenSSL**), will be downloaded automatically, so you don't need to handle it yourself.
48+
49+
You can including the following lines in your `CMakeLists.txt`:
50+
```
51+
include(FetchContent)
52+
FetchContent_Declare(OpenGeminiCxx
53+
GIT_REPOSITORY https://github.com/openGemini/opengemini-client-cpp
54+
GIT_TAG main
55+
)
56+
FetchContent_MakeAvailable(OpenGeminiCxx)
57+
```
58+
59+
This will export the target `OpenGeminiCxx::Client` which you can link against to your own target like this:
60+
```
61+
add_executable(YourApp main.cpp)
62+
target_link_libraries(YourApp PRIVATE OpenGeminiCxx::Client)
63+
```
64+
65+
### CMake FindPackage
66+
You can also use CMake's `find_package()` function to integrate the library into your project.
67+
68+
This means you need to [build and install](#build-from-source) OpenGeminiCxx on your system first.
69+
70+
Then you can add the following lines in your `CMakeLists.txt`:
71+
```
72+
find_package(OpenGeminiCxx REQUIRED)
73+
```
74+
75+
This will export the target `OpenGeminiCxx::Client` which you can link against to your own target like this:
76+
```
77+
add_executable(YourApp main.cpp)
78+
target_link_libraries(YourApp PRIVATE OpenGeminiCxx::Client)
79+
```
80+
81+
### Header-Only
82+
> **Note:** Although OpenGeminiCxx can be use as a header-only library, we still recommend use the compiled library for improved build times.
83+
84+
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.
85+
86+
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:
87+
```
88+
#include <opengemini/Client.hpp>
89+
```
90+
91+
## Quick Start
92+
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;
93+
### Query data from the server
94+
```cpp
95+
#include <iostream>
96+
97+
#include <opengemini/Client.hpp>
98+
#include <opengemini/ClientConfigBuilder.hpp>
99+
100+
int main(int argc, char** argv)
101+
{
102+
// Constructs an openGemini client object.
103+
opengemini::Client client{ opengemini::ClientConfigBuilder()
104+
// At least one server endpoint needed.
105+
.AppendAddress({ "127.0.0.1", 8086 })
106+
.Finalize() };
107+
108+
// Performs a query request and print the result, the operation will
109+
// block until completes or an exception is thrown.
110+
auto result = client.Query({
111+
"ExampleDatabase",
112+
"select * from ExampleMeasurement",
113+
});
114+
std::cout << result << std::endl;
115+
116+
return 0;
117+
}
118+
```
119+
### Write points to the server
120+
```cpp
121+
#include <iostream>
122+
123+
#include <opengemini/Client.hpp>
124+
#include <opengemini/ClientConfigBuilder.hpp>
125+
126+
int main(int argc, char** argv)
127+
{
128+
// Constructs an openGemini client object.
129+
opengemini::Client client{ opengemini::ClientConfigBuilder()
130+
// At least one server endpoint needed.
131+
.AppendAddress({ "127.0.0.1", 8086 })
132+
.Finalize() };
133+
134+
// Writes single point to server, the operation will
135+
// block until completes or an exception is thrown.
136+
client.Write("ExampleDatabase",
137+
{
138+
"ExampleMeasurement",
139+
{
140+
{ "Weather", "sunny" },
141+
{ "Humidity", 521 },
142+
{ "Temperature", 38.1 },
143+
},
144+
std::chrono::system_clock::now(),
145+
});
146+
return 0;
147+
}
148+
```
149+
150+
## Build From Source
151+
Make sure all required build tools and dependencies **are installed** on your system, then you can download and build the OpenGeminiCxx library:
152+
```
153+
$ git clone https://github.com/openGemini/opengemini-client-cpp.git
154+
$ cd opengemini-client-cpp && mkdir build && cd build
155+
$ cmake ..
156+
$ make -j
157+
$ make install
158+
```
159+
160+
If you want to enable TLS support, you can configure with `OPENGEMINI_ENABLE_SSL_SUPPORT` option:
161+
```
162+
$ cmake -DOPENGEMINI_ENABLE_SSL_SUPPORT=ON ..
163+
```
164+
165+
You can also control generation of unit tests with `OPENGEMINI_BUILD_TESTING` option:
166+
```
167+
$ cmake -DOPENGEMINI_BUILD_TESTING=ON ..
168+
```
169+
170+
For details of all the options see [CMake Options](#cmake-options).
171+
172+
## Configuration
173+
### CMake Options
174+
|Option|Description|Default Value|
175+
|:---|:---|:---|
176+
|OPENGEMINI_ENABLE_SSL_SUPPORT|Enable OpenSSL support for using TLS (**OpenSSL required**)|OFF|
177+
|OPENGEMINI_BUILD_DOCUMENTATION|Build API documentation (**Doxygen required**)|OFF|
178+
|OPENGEMINI_BUILD_TESTING|Build unit tests (**GoogleTest required**)|OFF|
179+
|OPENGEMINI_BUILD_SHARED_LIBS|Build shared libraries instead of static ones. Only has effect if option `OPENGEMINI_BUILD_HEADER_ONLY_LIBS` is `OFF`| OFF|
180+
|OPENGEMINI_BUILD_EXAMPLE|Build examples|OFF|
181+
|OPENGEMINI_BUILD_HEADER_ONLY_LIBS|Build as header-only library|OFF|
182+
|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)|
183+
|OPENGEMINI_USE_FETCHCONTENT|Automatically using FetchContent if dependencies not found|OFF<br>(if is root project)|

‎README_CN.md

+114-3
Original file line numberDiff line numberDiff line change
@@ -2,16 +2,127 @@
22

33
![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)
44

5+
> ⚠️ **当前仓库仍处于早期开发阶段，功能特性尚未完成。目前提供的API接口不是稳定版本，可能随开发进程有所调整。**
6+
57
[English](README.md) | 简体中文
68

79
`opengemini-client-cpp`是一个用 C++ 语言编写的 OpenGemini 客户端
810

9-
> ⚠️ **当前仓库仍处于早期开发阶段，功能特性尚未完成。目前提供的API接口不是稳定版本，可能随开发进程有所调整。**
11+
---
1012

11-
## 设计文档
13+
- [设计文档](#设计文档)
14+
- [关于OpenGemini](#关于OpenGemini)
15+
- [前置条件](#前置条件)
16+
- [与项目集成](#与项目集成)
17+
- [CMake FetchContent](#cmake-fetchcontent)
18+
- [CMake FindPackage](#cmake-findpackage)
19+
- [Header-Only](#header-only)
20+
- [快速上手](#快速上手)
21+
- [从源码构建](#从源码构建)
22+
- [配置选项](#配置选项)
1223

24+
## 设计文档
1325
[OpenGemini Client 设计文档](https://github.com/openGemini/openGemini.github.io/blob/main/src/zh/guide/develop/client_design.md)
1426

1527
## 关于 OpenGemini
16-
1728
OpenGemini 是一款云原生分布式时序数据库。获取更多信息，请点击[这里](https://github.com/openGemini/openGemini)
29+
30+
## 前置条件
31+
- **构建环境**
32+
- 兼容的操作系统：Linux，macOS，Windows
33+
- 支持C++17（或更新版本）的编译套件: GCC，Clang，MSVC
34+
- [CMake](https://cmake.org/) 3.12或更高版本
35+
- [Doxygen](https://www.doxygen.nl/) (*非必选*，用于生成文档)
36+
- **依赖库**
37+
- [Boost](https://github.com/boostorg/boost) 1.81或更高版本
38+
- [{fmt}](https://github.com/fmtlib/fmt)
39+
- [JSON](https://github.com/nlohmann/json)
40+
- [OpenSSL](https://github.com/openssl/openssl) (*非必选*，用于启用TLS协议支持)
41+
- [GoogleTest](https://github.com/google/googletest) (*非必选*，用于构建单元测试)
42+
43+
44+
## 与项目集成
45+
### CMake FetchContent
46+
我们推荐使用CMake [FetchContent](https://cmake.org/cmake/help/latest/module/FetchContent.html) 来将OpenGeminiCxx集成到您的项目中。
47+
48+
库自身和所有必要的依赖（除了OpenSSL）都会自动下载，不需要手动处理依赖。
49+
50+
可以将下列代码添加至项目的`CMakeLists.txt`中：
51+
```
52+
include(FetchContent)
53+
FetchContent_Declare(OpenGeminiCxx
54+
GIT_REPOSITORY https://github.com/openGemini/opengemini-client-cpp
55+
GIT_TAG main
56+
)
57+
FetchContent_MakeAvailable(OpenGeminiCxx)
58+
```
59+
60+
这将导出目标`OpenGeminiCxx::Client`，您可以将其链接到自己的目标中：
61+
```
62+
add_executable(YourApp main.cpp)
63+
target_link_libraries(YourApp PRIVATE OpenGeminiCxx::Client)
64+
```
65+
66+
### CMake FindPackage
67+
也可以使用CMake `find_package()` 函数来集成到项目中。
68+
69+
这意味着您必须先在系统上[构建并安装](#从源码构建)OpenGeminiCxx。
70+
71+
接着就可以将下列代码添加至`CMakeLists.txt`中：
72+
```
73+
find_package(OpenGeminiCxx REQUIRED)
74+
```
75+
76+
这将导出目标`OpenGeminiCxx::Client`，您可以将其链接到自己的目标中：
77+
```
78+
add_executable(YourApp main.cpp)
79+
target_link_libraries(YourApp PRIVATE OpenGeminiCxx::Client)
80+
```
81+
82+
### Header-Only
83+
> **注意：** 尽管OpenGeminiCxx可以当作纯头文件引用，但我们仍建议使用预编译好的版本以减少构建时间。
84+
85+
下载[OpenGeminiCxx](https://github.com/openGemini/opengemini-client-cpp/releases)，然后将`/path/to/opengemini-client-cpp/include`添加至工程的包含路径中。
86+
87+
然后就可以直接在源码中包含（可能需要手动将必要的依赖库链接到工程中）：
88+
```
89+
#include <opengemini/Client.hpp>
90+
```
91+
92+
## 快速上手
93+
94+
95+
## 从源码构建
96+
确保所有必要的构建工具和依赖库**已经安装**到您的系统上了，接着就可以下载并构建OpenGeminiCxx：
97+
```
98+
$ git clone https://github.com/openGemini/opengemini-client-cpp.git
99+
$ cd opengemini-client-cpp && mkdir build && cd build
100+
$ cmake ..
101+
$ make -j
102+
$ make install
103+
```
104+
105+
如果想要启用TLS支持，可以使用选项`OPENGEMINI_ENABLE_SSL_SUPPORT`进行配置：
106+
```
107+
$ cmake -DOPENGEMINI_ENABLE_SSL_SUPPORT=ON ..
108+
```
109+
110+
也可以通过选项`OPENGEMINI_ENABLE_SSL_SUPPORT`来生成单元测试：
111+
```
112+
$ cmake -DOPENGEMINI_BUILD_TESTING=ON ..
113+
```
114+
115+
关于所有配置选项的详细信息，参见[CMake选项](#CMake选项)
116+
117+
## 配置选项
118+
### CMake选项
119+
|选项|描述|默认值|
120+
|:---|:---|:---|
121+
|OPENGEMINI_ENABLE_SSL_SUPPORT|启用TLS支持（**需要OpenSSL**）|OFF|
122+
|OPENGEMINI_BUILD_DOCUMENTATION|构建API文档（**需要Doxygen**）|OFF|
123+
|OPENGEMINI_BUILD_TESTING|构建单元测试（**需要GoogleTest**）|OFF|
124+
|OPENGEMINI_BUILD_SHARED_LIBS|构建为动态库，仅当选项`OPENGEMINI_BUILD_HEADER_ONLY_LIBS`的值为`OFF`时生效| OFF|
125+
|OPENGEMINI_BUILD_EXAMPLE|构建样例代码|OFF|
126+
|OPENGEMINI_BUILD_HEADER_ONLY_LIBS|构建为header-only库|OFF|
127+
|OPENGEMINI_GENERATE_INSTALL_TARGET|生成安装目标，该选项和`OPENGEMINI_USE_FETCHCONTENT`选项的值不能同时为`ON`|ON<br>（当是根项目时）|
128+
|OPENGEMINI_USE_FETCHCONTENT|若无法找到依赖，则自动使用FetchContent|OFF<br>（当是根项目时）|

0 commit comments

Comments
 (0)