Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/shibd/pulsar-client-cpp
Apache Pulsar C++ client library
https://github.com/shibd/pulsar-client-cpp
Last synced: about 2 months ago
JSON representation
Apache Pulsar C++ client library
- Host: GitHub
- URL: https://github.com/shibd/pulsar-client-cpp
- Owner: shibd
- License: apache-2.0
- Fork: true (apache/pulsar-client-cpp)
- Created: 2022-10-07T11:08:51.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2024-08-21T13:02:45.000Z (3 months ago)
- Last Synced: 2024-08-22T10:48:51.034Z (3 months ago)
- Language: C++
- Homepage: https://pulsar.apache.org/
- Size: 6.27 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Security: SECURITY.md
Awesome Lists containing this project
README
# Pulsar C++ client library
Pulsar C++ clients support a variety of Pulsar features to enable building applications connecting to your Pulsar cluster.
For the supported Pulsar features, see [Client Feature Matrix](https://pulsar.apache.org/client-feature-matrix/).
For how to use APIs to publish and consume messages, see [examples](https://github.com/apache/pulsar-client-cpp/tree/main/examples).
## Generate the API documents
Pulsar C++ client uses [doxygen](https://www.doxygen.nl) to build API documents. After installing `doxygen`, you only need to run `doxygen` to generate the API documents whose main page is under the `doxygen/html/index.html` path.
## Requirements
- A C++ compiler that supports C++11, like GCC >= 4.8
- CMake >= 3.13
- [Boost](http://www.boost.org/)
- [Protocol Buffer](https://developers.google.com/protocol-buffers/) >= 3
- [libcurl](https://curl.se/libcurl/)
- [openssl](https://github.com/openssl/openssl)
The default supported [compression types](include/pulsar/CompressionType.h) are:
- `CompressionNone`
- `CompressionLZ4`
If you want to enable other compression types, you need to install:
- `CompressionZLib`: [zlib](https://zlib.net/)
- `CompressionZSTD`: [zstd](https://github.com/facebook/zstd)
- `CompressionSNAPPY`: [snappy](https://github.com/google/snappy)
If you want to build and run the tests, you need to install [GTest](https://github.com/google/googletest). Otherwise, you need to add CMake option `-DBUILD_TESTS=OFF`.
The [dependencies.yaml](./dependencies.yaml) file provides the recommended dependency versions, while you can still build from source with other dependency versions. If a dependency requires a higher C++ standard, e.g. C++14, you can specify the standard like:
```bash
cmake . -DCMAKE_CXX_STANDARD=14
```
> **Note**:
>
> On macOS, the default C++ standard is 17 because the latest Protobuf from Homebrew requires the C++17 support.
## Platforms
Pulsar C++ Client Library has been tested on:
- Linux
- Mac OS X
- Windows x64
## Compilation
### Clone
First of all, clone the source code:
```shell
git clone https://github.com/apache/pulsar-client-cpp
cd pulsar-client-cpp
```
### Compile on Ubuntu
#### Install all dependencies:
```shell
sudo apt-get update -y && sudo apt-get install -y g++ cmake libssl-dev libcurl4-openssl-dev \
libprotobuf-dev libboost-all-dev libgtest-dev libgmock-dev \
protobuf-compiler
```
#### Compile Pulsar client library:
```shell
cmake .
make
```
If you want to build performance tools, you need to run:
```shell
cmake . -DBUILD_PERF_TOOLS=ON
make
```
#### Checks
Client library will be placed in:
```
lib/libpulsar.so
lib/libpulsar.a
```
Examples will be placed in:
```
examples/
```
Tools will be placed in:
```
perf/perfProducer
perf/perfConsumer
```
### Compile on Mac OS X
#### Install all dependencies:
```shell
brew install cmake openssl protobuf boost googletest zstd snappy
```
#### Compile Pulsar client library:
```shell
cmake .
make
```
If you want to build performance tools, you need to run:
```shell
cmake . -DBUILD_PERF_TOOLS=ON
make
```
#### Checks
Client library will be placed in:
```
lib/libpulsar.dylib
lib/libpulsar.a
```
Examples will be placed in:
```
examples/
```
Tools will be placed in:
```
perf/perfProducer
perf/perfConsumer
```
### Compile on Windows
#### Install with [vcpkg](https://github.com/microsoft/vcpkg)
It's highly recommended to use `vcpkg` for C++ package management on Windows. It's easy to install and well supported by Visual Studio (2015/2017/2019) and CMake. See [here](https://github.com/microsoft/vcpkg#quick-start-windows) for quick start.
Take Windows 64-bit library as an example, you only need to run
```bash
vcpkg install --feature-flags=manifests --triplet x64-windows
```
> **NOTE**:
>
> For Windows 32-bit library, change `x64-windows` to `x86-windows`, see [here](https://github.com/microsoft/vcpkg/blob/master/docs/users/triplets.md) for more details about the triplet concept in Vcpkg.
The all dependencies, which are specified by [vcpkg.json](vcpkg.json), will be installed in `vcpkg_installed/` subdirectory,
With `vcpkg`, you only need to run two commands:
```bash
cmake \
-B ./build \
-A x64 \
-DBUILD_TESTS=OFF \
-DVCPKG_TRIPLET=x64-windows \
-DCMAKE_BUILD_TYPE=Release \
-S .
cmake --build ./build --config Release
```
Then all artifacts will be built into `build` subdirectory.
> **NOTE**:
>
> 1. For Windows 32-bit, you need to use `-A Win32` and `-DVCPKG_TRIPLET=x86-windows`.
> 2. For MSVC Debug mode, you need to replace `Release` with `Debug` for both `CMAKE_BUILD_TYPE` variable and `--config` option.
#### Install dependencies manually
You need to install [dlfcn-win32](https://github.com/dlfcn-win32/dlfcn-win32) in addition.
If you installed the dependencies manually, you need to run
```shell
#If all dependencies are in your path, all that is necessary is
cmake .
#if all dependencies are not in your path, then passing in a PROTOC_PATH and CMAKE_PREFIX_PATH is necessary
cmake -DPROTOC_PATH=C:/protobuf/bin/protoc -DCMAKE_PREFIX_PATH="C:/boost;C:/openssl;C:/zlib;C:/curl;C:/protobuf;C:/googletest;C:/dlfcn-win32" .
#This will generate pulsar-cpp.sln. Open this in Visual Studio and build the desired configurations.
```
#### Checks
Client library will be placed in:
```
build/lib/Release/pulsar.lib
build/lib/Release/pulsar.dll
```
#### Examples
Add Windows environment paths:
```
build/lib/Release
vcpkg_installed
```
Examples will be available in:
```
build/examples/Release
```
## Tests
```shell
# Execution
# Start standalone broker
./pulsar-test-service-start.sh
# Run the tests
cd tests
./pulsar-tests
# When no longer needed, stop standalone broker
./pulsar-test-service-stop.sh
```
## Wireshark Dissector
See the [wireshark](wireshark/) directory for details.
## Requirements for Contributors
It's required to install [LLVM](https://llvm.org/builds/) for `clang-tidy` and `clang-format`. Pulsar C++ client use `clang-format` **11** to format files. `make format` automatically formats the files.
For Ubuntu users, you can install `clang-format-11` via `apt install clang-format-11`. For other users, run `./build-support/docker-format.sh` if you have Docker installed.
We welcome contributions from the open source community, kindly make sure your changes are backward compatible with GCC 4.8 and Boost 1.53.
If your contribution adds Pulsar features for C++ clients, you need to update both the [Pulsar docs](https://pulsar.apache.org/docs/client-libraries/) and the [Client Feature Matrix](https://pulsar.apache.org/client-feature-matrix/). See [Contribution Guide](https://pulsar.apache.org/contribute/site-intro/#pages) for more details.