-
Notifications
You must be signed in to change notification settings - Fork 4
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
docs: update requirements and integration in README #29
Merged
Merged
Changes from all commits
Commits
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1 @@ | ||
Coming soon... |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -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 | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I think we should state in the title what this configuration is |
||
### 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). |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
good toc part, I think we'd better adapt this toc part to other repos @Chenxulin97