Skip to content

Files

pulsar-client-cpp

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
May 5, 2022
Dec 20, 2021
Sep 13, 2022
Jul 26, 2022
Sep 8, 2022
Sep 19, 2022
Sep 22, 2022
Mar 8, 2021
Sep 13, 2022
Sep 22, 2022
Nov 26, 2021
Aug 25, 2022
Sep 22, 2022
May 5, 2022
Jan 24, 2018
Sep 8, 2022
May 5, 2022
Jun 4, 2019
Aug 9, 2022
May 5, 2022
May 5, 2022
May 5, 2022
May 5, 2022
May 9, 2022
Jun 22, 2017
Jun 22, 2017
Aug 5, 2022
Nov 18, 2020
Aug 30, 2022
Sep 19, 2021

Pulsar C++ client library

Examples for using the API to publish and consume messages can be found on https://github.com/apache/pulsar/tree/master/pulsar-client-cpp/examples

Requirements

It's recommended to use Protocol Buffer 2.6 because it's verified by CI, but 3.x also works.

The default supported compression types are:

  • CompressionNone
  • CompressionLZ4

If you want to enable other compression types, you need to install:

  • CompressionZLib: zlib
  • CompressionZSTD: zstd
  • CompressionSNAPPY: snappy

If you want to build and run the tests, you need to install GTest. Otherwise, you need to add CMake option -DBUILD_TESTS=OFF.

If you don't want to build Python client since boost-python may not be easy to install, you need to add CMake option -DBUILD_PYTHON_WRAPPER=OFF.

If you want to use ClientConfiguration::setLogConfFilePath, you need to install the Log4CXX and add CMake option -DUSE_LOG4CXX=ON.

Platforms

Pulsar C++ Client Library has been tested on:

  • Linux
  • Mac OS X
  • Windows x64

Compilation

Compile within a Docker container

You can compile the C++ client library within a Docker container that already contains all the required dependencies.

./docker-build.sh

Run unit tests:

./docker-tests.sh

Compile on Ubuntu Server 20.04

Install all dependencies:

apt-get install -y g++ cmake libssl-dev libcurl4-openssl-dev liblog4cxx-dev \
                libprotobuf-dev libboost-all-dev  libgtest-dev google-mock \
                protobuf-compiler python3-setuptools

Compile and install Google Test:

cd /usr/src/gtest
sudo cmake .
sudo make

# Copy the libraries you just built to the OS library path.
# GTEST_LIB_PATH may be `/usr/src/gtest`, `/usr/src/gtest/lib` or other path you provided when building gtest above.
sudo cp ${GTEST_LIB_PATH}/*.a /usr/lib

Compile and install Google Mock:

cd /usr/src/gmock
sudo cmake .
sudo make

# Copy the libraries you just built to the OS library path.
# GMOCK_LIB_PATH may be `/usr/src/gmock`, `/usr/src/gmock/lib` or other path you provided when building gmock above.
sudo cp ${GMOCK_LIB_PATH}/*.a /usr/lib

Compile Pulsar client library:

cd pulsar/pulsar-client-cpp
cmake .
make

Checks

Client library will be placed in
lib/libpulsar.so
lib/libpulsar.a
Tools will be placed in
perf/perfProducer
perf/perfConsumer

Compile on Mac OS X

Install all dependencies:

# For openSSL
brew install openssl
export OPENSSL_INCLUDE_DIR=/usr/local/opt/openssl/include/
export OPENSSL_ROOT_DIR=/usr/local/opt/openssl/

# For Protobuf
brew install protobuf boost boost-python log4cxx jsoncpp
// If you are using python3, you need to install boost-python3

# For gtest
cd $HOME
git clone https://github.com/google/googletest.git
cd googletest
git checkout release-1.12.1
cmake .
make install
# Refer gtest documentation in case you get stuck somewhere

Compile Pulsar client library:

export PULSAR_PATH=<Path where you cloned pulsar repo>
cd ${PULSAR_PATH}/pulsar-client-cpp/
cmake .
make

Checks

Client library will be placed in
${PULSAR_PATH}/pulsar-client-cpp/lib/libpulsar.dylib
${PULSAR_PATH}/pulsar-client-cpp/lib/libpulsar.a
Tools will be placed in:
${PULSAR_PATH}/pulsar-client-cpp/perf/perfProducer
${PULSAR_PATH}/pulsar-client-cpp/perf/perfConsumer

Compile on Windows

Install with 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 for quick start.

Take Windows 64-bit library as an example, you only need to run

vcpkg install --feature-flags=manifests --triplet x64-windows

NOTE: For Windows 32-bit library, change x64-windows to x86-windows, see here for more details about the triplet concept in Vcpkg.

The all dependencies, which are specified by vcpkg.json, will be installed in vcpkg_installed/ subdirectory,

With vcpkg, you only need to run two commands:

cmake \
 -B ./build \
 -A x64 \
 -DBUILD_PYTHON_WRAPPER=OFF -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 in addition.

If you installed the dependencies manually, you need to run

#If all dependencies are in your path, all that is necessary is
${PULSAR_PATH}/pulsar-client-cpp/cmake .

#if all dependencies are not in your path, then passing in a PROTOC_PATH and CMAKE_PREFIX_PATH is necessary
${PULSAR_PATH}/pulsar-client-cpp/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 libraries are available in the following places.
${PULSAR_PATH}/pulsar-client-cpp/build/lib/Release/pulsar.lib
${PULSAR_PATH}/pulsar-client-cpp/build/lib/Release/pulsar.dll

Examples

Add windows environment paths.
${PULSAR_PATH}/pulsar-client-cpp/build/lib/Release
${PULSAR_PATH}/pulsar-client-cpp/vcpkg_installed
Examples are available in.
${PULSAR_PATH}/pulsar-client-cpp/build/examples/Release

Tests

# Source code
${PULSAR_PATH}/pulsar-client-cpp/tests/

# Execution
# Start standalone broker
${PULSAR_PATH}/pulsar-test-service-start.sh

# Run the tests
${PULSAR_PATH}/pulsar-client-cpp/tests/main

# When no longer needed, stop standalone broker
${PULSAR_PATH}/pulsar-test-service-stop.sh

Requirements for Contributors

It's required to install LLVM for clang-tidy and clang-format. Pulsar C++ client use clang-format 6.0+ to format files. make format automatically formats the files.

Use pulsar-client-cpp/docker-format.sh to ensure the C++ sources are correctly formatted.

We welcome contributions from the open source community, kindly make sure your changes are backward compatible with GCC 4.8 and Boost 1.53.