| <!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.8"/> |
| <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.8 --> |
| <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__r_e_a_d_m_e"></a></p> |
| <h1>Pulsar C++ client library</h1> |
| <p>Pulsar C++ clients support a variety of Pulsar features to enable building applications connecting to your Pulsar cluster.</p> |
| <p>For the supported Pulsar features, see <a href="https://pulsar.apache.org/client-feature-matrix/">Client Feature Matrix</a>.</p> |
| <p>For how to use APIs to publish and consume messages, see <a href="https://github.com/apache/pulsar-client-cpp/tree/main/examples">examples</a>.</p> |
| <h2>Import the library into your project</h2> |
| <h3>CMake with vcpkg integration</h3> |
| <p>Navigate to <a href="./vcpkg-example">vcpkg-example</a> for how to import the <code>pulsar-client-cpp</code> into your project via vcpkg.</p> |
| <h3>Download pre-built binaries</h3> |
| <p>For non-vcpkg projects, you can download pre-built binaries from the <a href="https://pulsar.apache.org/download/#pulsar-c-client">official release page</a>.</p> |
| <h2>Generate the API documents</h2> |
| <p>Pulsar C++ client uses <a href="https://www.doxygen.nl">doxygen</a> to build API documents. After installing <code>doxygen</code>, you only need to run <code>doxygen</code> to generate the API documents whose main page is under the <code>doxygen/html/index.html</code> path.</p> |
| <h2>Build with vcpkg</h2> |
| <p>Since it's integrated with vcpkg, see <a href="https://github.com/microsoft/vcpkg#readme">vcpkg::README</a> for the requirements. See LEGACY_BUILD if you want to manage dependencies by yourself or you cannot install vcpkg in your own environment.</p> |
| <h3>How to build from source</h3> |
| <p>The simplest way is to clone this project with the vcpkg submodule.</p> |
| <div class="fragment"><div class="line">git clone https://github.com/apache/pulsar-client-cpp.git</div> |
| <div class="line">cd pulsar-client-cpp</div> |
| <div class="line">git submodule update --init --recursive</div> |
| <div class="line">cmake -B build -DINTEGRATE_VCPKG=ON</div> |
| <div class="line">cmake --build build -j8</div> |
| </div><!-- fragment --><p>The 1st step will download vcpkg and then install all dependencies according to the version description in <a href="./vcpkg.json">vcpkg.json</a>. The 2nd step will build the Pulsar C++ libraries under <code>./build/lib/</code>, where <code>./build</code> is the CMake build directory.</p> |
| <blockquote class="doxtable"> |
| <p>‍You can also add the CMAKE_TOOLCHAIN_FILE option if your system already have vcpkg installed.</p> |
| <div class="fragment"><div class="line">git clone https://github.com/apache/pulsar-client-cpp.git</div> |
| <div class="line">cd pulsar-client-cpp</div> |
| <div class="line"># For example, you can install vcpkg in /tmp/vcpkg</div> |
| <div class="line">cd /tmp && git clone https://github.com/microsoft/vcpkg.git && cd -</div> |
| <div class="line">cmake -B build -DINTEGRATE_VCPKG=ON -DCMAKE_TOOLCHAIN_FILE="/tmp/vcpkg/scripts/buildsystems/vcpkg.cmake"</div> |
| <div class="line">cmake --build build -j8</div> |
| </div><!-- fragment --> </blockquote> |
| <p>After the build, the hierarchy of the <code>build</code> directory will be:</p> |
| <div class="fragment"><div class="line">build/</div> |
| <div class="line"> include/ -- extra C++ headers</div> |
| <div class="line"> lib/ -- libraries</div> |
| <div class="line"> tests/ -- test executables</div> |
| <div class="line"> examples/ -- example executables</div> |
| <div class="line"> generated/</div> |
| <div class="line"> lib/ -- protobuf source files for PulsarApi.proto</div> |
| <div class="line"> tests/ -- protobuf source files for *.proto used in tests</div> |
| </div><!-- fragment --><h3>How to install</h3> |
| <p>To install the C++ headers and libraries into a specific path, e.g. <code>/tmp/pulsar</code>, run the following commands:</p> |
| <div class="fragment"><div class="line">cmake -B build -DINTEGRATE_VCPKG=ON -DCMAKE_INSTALL_PREFIX=/tmp/pulsar</div> |
| <div class="line">cmake --build build -j8 --target install</div> |
| </div><!-- fragment --><p>For example, on macOS you will see:</p> |
| <div class="fragment"><div class="line">/tmp/pulsar/</div> |
| <div class="line"> include/pulsar -- C/C++ headers</div> |
| <div class="line"> lib/</div> |
| <div class="line"> libpulsar.a -- Static library</div> |
| <div class="line"> libpulsar.dylib -- Dynamic library</div> |
| </div><!-- fragment --><h3>Tests</h3> |
| <p>Tests are built by default. You should execute <a href="./run-unit-tests.sh">run-unit-tests.sh</a> to run tests locally.</p> |
| <p>If you don't want to build the tests, disable the <code>BUILD_TESTS</code> option:</p> |
| <div class="fragment"><div class="line">cmake -B build -DINTEGRATE_VCPKG=ON -DBUILD_TESTS=OFF</div> |
| <div class="line">cmake --build build -j8</div> |
| </div><!-- fragment --><h3>Build perf tools</h3> |
| <p>If you want to build the perf tools, enable the <code>BUILD_PERF_TOOLS</code> option:</p> |
| <div class="fragment"><div class="line">cmake -B build -DINTEGRATE_VCPKG=ON -DBUILD_PERF_TOOLS=ON</div> |
| <div class="line">cmake --build build -j8</div> |
| </div><!-- fragment --><p>Then the perf tools will be built under <code>./build/perf/</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>Wireshark Dissector</h2> |
| <p>See the <a href="wireshark/">wireshark</a> directory for details.</p> |
| <h2>Requirements for Contributors</h2> |
| <p>It's required 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> <b>11</b> to format files. <code>make format</code> automatically formats the files.</p> |
| <p>For Ubuntu users, you can install <code>clang-format-11</code> via <code>apt install clang-format-11</code>. For other users, run <code>./build-support/docker-format.sh</code> if you have Docker installed.</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> |
| <p>If your contribution adds Pulsar features for C++ clients, you need to update both the <a href="https://pulsar.apache.org/docs/client-libraries/">Pulsar docs</a> and the <a href="https://pulsar.apache.org/client-feature-matrix/">Client Feature Matrix</a>. See <a href="https://pulsar.apache.org/contribute/site-intro/#pages">Contribution Guide</a> for more details. </p> |
| </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.8 |
| </small></address> |
| </body> |
| </html> |
