| <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
| <html xmlns="http://www.w3.org/1999/xhtml" lang="en-US"> |
| <head> |
| <meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/> |
| <meta http-equiv="X-UA-Compatible" content="IE=11"/> |
| <meta name="generator" content="Doxygen 1.9.5"/> |
| <meta name="viewport" content="width=device-width, initial-scale=1"/> |
| <title>pulsar-client-cpp: pulsar-client-cpp</title> |
| <link href="tabs.css" rel="stylesheet" type="text/css"/> |
| <script type="text/javascript" src="jquery.js"></script> |
| <script type="text/javascript" src="dynsections.js"></script> |
| <link href="search/search.css" rel="stylesheet" type="text/css"/> |
| <script type="text/javascript" src="search/searchdata.js"></script> |
| <script type="text/javascript" src="search/search.js"></script> |
| <script type="text/javascript" src="darkmode_toggle.js"></script> |
| <link href="doxygen.css" rel="stylesheet" type="text/css" /> |
| </head> |
| <body> |
| <div id="top"><!-- do not remove this div, it is closed by doxygen! --> |
| <div id="titlearea"> |
| <table cellspacing="0" cellpadding="0"> |
| <tbody> |
| <tr id="projectrow"> |
| <td id="projectalign"> |
| <div id="projectname">pulsar-client-cpp |
| </div> |
| </td> |
| </tr> |
| </tbody> |
| </table> |
| </div> |
| <!-- end header part --> |
| <!-- Generated by Doxygen 1.9.5 --> |
| <script type="text/javascript"> |
| /* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&dn=expat.txt MIT */ |
| var searchBox = new SearchBox("searchBox", "search/",'.html'); |
| /* @license-end */ |
| </script> |
| <script type="text/javascript" src="menudata.js"></script> |
| <script type="text/javascript" src="menu.js"></script> |
| <script type="text/javascript"> |
| /* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&dn=expat.txt MIT */ |
| $(function() { |
| initMenu('',true,false,'search.php','Search'); |
| $(document).ready(function() { init_search(); }); |
| }); |
| /* @license-end */ |
| </script> |
| <div id="main-nav"></div> |
| </div><!-- top --> |
| <!-- window showing the filter options --> |
| <div id="MSearchSelectWindow" |
| onmouseover="return searchBox.OnSearchSelectShow()" |
| onmouseout="return searchBox.OnSearchSelectHide()" |
| onkeydown="return searchBox.OnSearchSelectKey(event)"> |
| </div> |
| |
| <!-- iframe showing the search results (closed by default) --> |
| <div id="MSearchResultsWindow"> |
| <div id="MSearchResults"> |
| <div class="SRPage"> |
| <div id="SRIndex"> |
| <div id="SRResults"></div> |
| <div class="SRStatus" id="Loading">Loading...</div> |
| <div class="SRStatus" id="Searching">Searching...</div> |
| <div class="SRStatus" id="NoMatches">No Matches</div> |
| </div> |
| </div> |
| </div> |
| </div> |
| |
| <div><div class="header"> |
| <div class="headertitle"><div class="title">pulsar-client-cpp </div></div> |
| </div><!--header--> |
| <div class="contents"> |
| <div class="textblock"><p ><a class="anchor" id="md_README"></a></p> |
| <h1>Pulsar C++ client library</h1> |
| <ul> |
| <li>Requirements</li> |
| <li>Platforms</li> |
| <li>Compilation<ul> |
| <li>Compile on Ubuntu Server 16.04</li> |
| <li>Compile on Mac OS X</li> |
| <li>Compile on Windows (Visual Studio)</li> |
| </ul> |
| </li> |
| <li>Tests</li> |
| <li>Requirements for Contributors</li> |
| </ul> |
| <p >Examples for using the API to publish and consume messages can be found on <a href="https://github.com/apache/pulsar/tree/master/pulsar-client-cpp/examples">https://github.com/apache/pulsar/tree/master/pulsar-client-cpp/examples</a></p> |
| <h2>Requirements</h2> |
| <ul> |
| <li>A C++ compiler that supports C++11, like GCC >= 4.8</li> |
| <li>CMake >= 3.4</li> |
| <li><a href="http://www.boost.org/">Boost</a></li> |
| <li><a href="https://developers.google.com/protocol-buffers/">Protocol Buffer</a> >= 3</li> |
| <li><a href="https://curl.se/libcurl/">libcurl</a></li> |
| <li><a href="https://github.com/openssl/openssl">openssl</a></li> |
| </ul> |
| <p >It's recommended to use Protocol Buffer 2.6 because it's verified by CI, but 3.x also works.</p> |
| <p >The default supported <a href="include/pulsar/CompressionType.h">compression types</a> are:</p> |
| <ul> |
| <li><code>CompressionNone</code></li> |
| <li><code>CompressionLZ4</code></li> |
| </ul> |
| <p >If you want to enable other compression types, you need to install:</p> |
| <ul> |
| <li><code>CompressionZLib</code>: <a href="https://zlib.net/">zlib</a></li> |
| <li><code>CompressionZSTD</code>: <a href="https://github.com/facebook/zstd">zstd</a></li> |
| <li><code>CompressionSNAPPY</code>: <a href="https://github.com/google/snappy">snappy</a></li> |
| </ul> |
| <p >If you want to build and run the tests, you need to install <a href="https://github.com/google/googletest">GTest</a>. Otherwise, you need to add CMake option <code>-DBUILD_TESTS=OFF</code>.</p> |
| <p >If you don't want to build Python client since <code>boost-python</code> may not be easy to install, you need to add CMake option <code>-DBUILD_PYTHON_WRAPPER=OFF</code>.</p> |
| <p >If you want to use <code>ClientConfiguration::setLogConfFilePath</code>, you need to install the <a href="https://logging.apache.org/log4cxx">Log4CXX</a> and add CMake option <code>-DUSE_LOG4CXX=ON</code>.</p> |
| <h2>Platforms</h2> |
| <p >Pulsar C++ Client Library has been tested on:</p> |
| <ul> |
| <li>Linux</li> |
| <li>Mac OS X</li> |
| <li>Windows x64</li> |
| </ul> |
| <h2>Compilation</h2> |
| <h3>Compile within a Docker container</h3> |
| <p >You can compile the C++ client library within a Docker container that already contains all the required dependencies.</p> |
| <div class="fragment"><div class="line">./docker-build.sh</div> |
| </div><!-- fragment --><p >Run unit tests: </p><div class="fragment"><div class="line">./docker-tests.sh</div> |
| </div><!-- fragment --><h3>Compile on Ubuntu Server 16.04</h3> |
| <h4>Install all dependencies:</h4> |
| <div class="fragment"><div class="line">apt-get install -y g++ cmake libssl-dev libcurl4-openssl-dev liblog4cxx-dev \</div> |
| <div class="line"> libprotobuf-dev libboost-all-dev libgtest-dev google-mock \</div> |
| <div class="line"> protobuf-compiler python-setuptools</div> |
| </div><!-- fragment --><h4>Compile and install Google Test:</h4> |
| <div class="fragment"><div class="line">cd /usr/src/gtest</div> |
| <div class="line">sudo cmake .</div> |
| <div class="line">sudo make</div> |
| <div class="line">sudo cp *.a /usr/lib</div> |
| </div><!-- fragment --><h4>Compile and install Google Mock:</h4> |
| <div class="fragment"><div class="line">cd /usr/src/gmock</div> |
| <div class="line">sudo cmake .</div> |
| <div class="line">sudo make</div> |
| <div class="line">sudo cp *.a /usr/lib</div> |
| </div><!-- fragment --><h4>Compile Pulsar client library:</h4> |
| <div class="fragment"><div class="line">cd pulsar/pulsar-client-cpp</div> |
| <div class="line">cmake .</div> |
| <div class="line">make</div> |
| </div><!-- fragment --><h4>Checks</h4> |
| <h5>Client library will be placed in</h5> |
| <div class="fragment"><div class="line">lib/libpulsar.so</div> |
| <div class="line">lib/libpulsar.a</div> |
| </div><!-- fragment --><h5>Tools will be placed in</h5> |
| <div class="fragment"><div class="line">perf/perfProducer</div> |
| <div class="line">perf/perfConsumer</div> |
| </div><!-- fragment --><h3>Compile on Mac OS X</h3> |
| <h4>Install all dependencies:</h4> |
| <div class="fragment"><div class="line"># For openSSL</div> |
| <div class="line">brew install openssl</div> |
| <div class="line">export OPENSSL_INCLUDE_DIR=/usr/local/opt/openssl/include/</div> |
| <div class="line">export OPENSSL_ROOT_DIR=/usr/local/opt/openssl/</div> |
| <div class="line"> </div> |
| <div class="line"># For Protobuf</div> |
| <div class="line">brew install protobuf boost boost-python log4cxx jsoncpp</div> |
| <div class="line">// If you are using python3, you need to install boost-python3</div> |
| <div class="line"> </div> |
| <div class="line"># For gtest</div> |
| <div class="line">cd $HOME</div> |
| <div class="line">git clone https://github.com/google/googletest.git</div> |
| <div class="line">cd googletest</div> |
| <div class="line">cmake .</div> |
| <div class="line">make install</div> |
| <div class="line"># Refer gtest documentation in case you get stuck somewhere</div> |
| </div><!-- fragment --><h4>Compile Pulsar client library:</h4> |
| <div class="fragment"><div class="line">export PULSAR_PATH=<Path where you cloned pulsar repo></div> |
| <div class="line">cd ${PULSAR_PATH}/pulsar-client-cpp/</div> |
| <div class="line">cmake .</div> |
| <div class="line">make</div> |
| </div><!-- fragment --><h4>Checks</h4> |
| <h5>Client library will be placed in</h5> |
| <div class="fragment"><div class="line">${PULSAR_PATH}/pulsar-client-cpp/lib/libpulsar.dylib</div> |
| <div class="line">${PULSAR_PATH}/pulsar-client-cpp/lib/libpulsar.a</div> |
| </div><!-- fragment --><h5>Tools will be placed in:</h5> |
| <div class="fragment"><div class="line">${PULSAR_PATH}/pulsar-client-cpp/perf/perfProducer</div> |
| <div class="line">${PULSAR_PATH}/pulsar-client-cpp/perf/perfConsumer</div> |
| </div><!-- fragment --><h3>Compile on Windows</h3> |
| <h4>Install with <a href="https://github.com/microsoft/vcpkg">vcpkg</a></h4> |
| <p >It's highly recommended to use <code>vcpkg</code> for C++ package management on Windows. It's easy to install and well supported by Visual Studio (2015/2017/2019) and CMake. See <a href="https://github.com/microsoft/vcpkg#quick-start-windows">here</a> for quick start.</p> |
| <p >Take Windows 64-bit library as an example, you only need to run</p> |
| <div class="fragment"><div class="line">vcpkg install --feature-flags=manifests --triplet x64-windows</div> |
| </div><!-- fragment --><blockquote class="doxtable"> |
| <p >‍NOTE: For Windows 32-bit library, change <code>x64-windows</code> to <code>x86-windows</code>, see <a href="https://github.com/microsoft/vcpkg/blob/master/docs/users/triplets.md">here</a> for more details about the triplet concept in Vcpkg. </p> |
| </blockquote> |
| <p>The all dependencies, which are specified by <a href="vcpkg.json">vcpkg.json</a>, will be installed in <code>vcpkg_installed/</code> subdirectory,</p> |
| <p >With <code>vcpkg</code>, you only need to run two commands:</p> |
| <div class="fragment"><div class="line">cmake \</div> |
| <div class="line"> -B ./build \</div> |
| <div class="line"> -A x64 \</div> |
| <div class="line"> -DBUILD_PYTHON_WRAPPER=OFF -DBUILD_TESTS=OFF \</div> |
| <div class="line"> -DVCPKG_TRIPLET=x64-windows \</div> |
| <div class="line"> -DCMAKE_BUILD_TYPE=Release \</div> |
| <div class="line"> -S .</div> |
| <div class="line">cmake --build ./build --config Release</div> |
| </div><!-- fragment --><p >Then all artifacts will be built into <code>build</code> subdirectory.</p> |
| <blockquote class="doxtable"> |
| <p >‍<b>NOTE</b></p> |
| <ol type="1"> |
| <li>For Windows 32-bit, you need to use <code>-A Win32</code> and <code>-DVCPKG_TRIPLET=x86-windows</code>.</li> |
| <li>For MSVC Debug mode, you need to replace <code>Release</code> with <code>Debug</code> for both <code>CMAKE_BUILD_TYPE</code> variable and <code>--config</code> option. </li> |
| </ol> |
| </blockquote> |
| <h4>Install dependencies manually</h4> |
| <p >You need to install <a href="https://github.com/dlfcn-win32/dlfcn-win32">dlfcn-win32</a> in addition.</p> |
| <p >If you installed the dependencies manually, you need to run</p> |
| <div class="fragment"><div class="line">#If all dependencies are in your path, all that is necessary is</div> |
| <div class="line">${PULSAR_PATH}/pulsar-client-cpp/cmake .</div> |
| <div class="line"> </div> |
| <div class="line">#if all dependencies are not in your path, then passing in a PROTOC_PATH and CMAKE_PREFIX_PATH is necessary</div> |
| <div class="line">${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" .</div> |
| <div class="line"> </div> |
| <div class="line">#This will generate pulsar-cpp.sln. Open this in Visual Studio and build the desired configurations.</div> |
| </div><!-- fragment --><h4>Checks</h4> |
| <h5>Client libraries are available in the following places.</h5> |
| <div class="fragment"><div class="line">${PULSAR_PATH}/pulsar-client-cpp/build/lib/Release/pulsar.lib</div> |
| <div class="line">${PULSAR_PATH}/pulsar-client-cpp/build/lib/Release/pulsar.dll</div> |
| </div><!-- fragment --><h4>Examples</h4> |
| <h5>Add windows environment paths.</h5> |
| <div class="fragment"><div class="line">${PULSAR_PATH}/pulsar-client-cpp/build/lib/Release</div> |
| <div class="line">${PULSAR_PATH}/pulsar-client-cpp/vcpkg_installed</div> |
| </div><!-- fragment --><h5>Examples are available in.</h5> |
| <div class="fragment"><div class="line">${PULSAR_PATH}/pulsar-client-cpp/build/examples/Release</div> |
| </div><!-- fragment --><h2>Tests</h2> |
| <div class="fragment"><div class="line"># Source code</div> |
| <div class="line">${PULSAR_PATH}/pulsar-client-cpp/tests/</div> |
| <div class="line"> </div> |
| <div class="line"># Execution</div> |
| <div class="line"># Start standalone broker</div> |
| <div class="line">${PULSAR_PATH}/pulsar-test-service-start.sh</div> |
| <div class="line"> </div> |
| <div class="line"># Run the tests</div> |
| <div class="line">${PULSAR_PATH}/pulsar-client-cpp/tests/main</div> |
| <div class="line"> </div> |
| <div class="line"># When no longer needed, stop standalone broker</div> |
| <div class="line">${PULSAR_PATH}/pulsar-test-service-stop.sh</div> |
| </div><!-- fragment --><h2>Requirements for Contributors</h2> |
| <p >It's recommended to install <a href="https://llvm.org/builds/">LLVM</a> for <code>clang-tidy</code> and <code>clang-format</code>. Pulsar C++ client use <code>clang-format</code> 5.0 to format files, which is a little different with latest <code>clang-format</code>.</p> |
| <p >We welcome contributions from the open source community, kindly make sure your changes are backward compatible with GCC 4.8 and Boost 1.53.</p> |
| <h3>Install <code>clang-format</code> on macOS</h3> |
| <p ><code>homebrew-core</code> does not have <code>clang-format@5</code>. You can install <code>clang-format@5</code> on your macOS using the tap below. </p><div class="fragment"><div class="line"># Step 1: Add tap</div> |
| <div class="line">brew tap demogorgon314/clang-format</div> |
| <div class="line"> </div> |
| <div class="line"># Step 2: Install clang-format@5</div> |
| <div class="line">brew install clang-format@5</div> |
| </div><!-- fragment --> <h3>Install <code>clang-format</code> on Ubuntu 18.04</h3> |
| <p >You can find pre-built binaries on the LLVM website: <a href="https://releases.llvm.org/download.html#5.0.2">https://releases.llvm.org/download.html#5.0.2</a></p> |
| <p >Or you want to use apt install clang-format-5.0. </p><div class="fragment"><div class="line">sudo apt update</div> |
| <div class="line">sudo apt install clang-format-5.0</div> |
| </div><!-- fragment --> </div></div><!-- PageDoc --> |
| </div><!-- contents --> |
| <!-- start footer part --> |
| <hr class="footer"/><address class="footer"><small> |
| Generated by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.9.5 |
| </small></address> |
| </body> |
| </html> |
