Improved instruction for getting started with C++ client lib (apache#…

…1975) ### Motivation Documentation for C++ library was mixed with instructions on how to build the library and how to use it. ### Modifications * Split the C++ client page in 2 parts, one for building and one for using * Added instructions to build RPM, which is much easier than build directly (since it builds in Docker with all dependencies installed).
ivankelly · Jun 18, 2018 · f221b26 · f221b26
1 parent fee34d0
commit f221b26
Show file tree

Hide file tree

Showing 3 changed files with 163 additions and 87 deletions.
diff --git a/site/_data/sidebar.yaml b/site/_data/sidebar.yaml
@@ -162,6 +162,8 @@ groups:
     endpoint: schema-storage
   - title: Modular load manager
     endpoint: ModularLoadManager
+  - title: Building Pulsar C++ client
+    endpoint: CompileCpp
 
 - title: Reference
   dir: reference

diff --git a/site/docs/latest/clients/Cpp.md b/site/docs/latest/clients/Cpp.md
@@ -24,106 +24,64 @@ tags: [client, cpp]
 
 -->
 
-<!-- source: https://github.com/apache/incubator-Âpulsar/tree/master/pulsar-client-cpp -->
-
-{% include admonition.html type='info' content="
-We welcome contributions from the open source community, kindly make sure your changes are backward compatible with gcc-4.4.7 and Boost 1.41.
-" %}
-
 ## Supported platforms
 
 The Pulsar C++ client has been successfully tested on **MacOS** and **Linux**.
 
-## System requirements
-
-You need to have the following installed to use the C++ client:
-
-* [CMake](https://cmake.org/)
-* [Boost](http://www.boost.org/)
-* [Protocol Buffers](https://developers.google.com/protocol-buffers/) 2.6
-* [Log4CXX](https://logging.apache.org/log4cxx)
-* [libcurl](https://curl.haxx.se/libcurl/)
-* [Google Test](https://github.com/google/googletest)
-* [JsonCpp](https://github.com/open-source-parsers/jsoncpp)
+## Linux
 
-## Compilation
+There are recipes that build RPM and Debian packages containing a
+statically linked `libpulsar.so` / `libpulsar.a` with all the required
+dependencies.
 
-There are separate compilation instructions for [MacOS](#macos) and [Linux](#linux). For both systems, start by cloning the Pulsar repository:
+To build the C++ library packages, first build the Java packages:
 
 ```shell
-$ git clone {{ site.pulsar_repo }}
+mvn install -DskipTests
 ```
 
-### Linux
-
-First, install all of the necessary dependencies:
+#### RPM
 
 ```shell
-$ apt-get install cmake libssl-dev libcurl4-openssl-dev liblog4cxx-dev \
-  libprotobuf-dev libboost-all-dev google-mock libgtest-dev libjsoncpp-dev
+pulsar-client-cpp/pkg/rpm/docker-build-rpm.sh
 ```
 
-Then compile and install [Google Test](https://github.com/google/googletest):
+This will build the RPM inside a Docker container and it will leave the RPMs
+in `pulsar-client-cpp/pkg/rpm/RPMS/x86_64/`.
 
-```shell
-# libgtest-dev version is 1.18.0 or above
-$ cd /usr/src/googletest
-$ sudo cmake .
-$ sudo make
-$ sudo cp ./googlemock/libgmock.a ./googletest/libgtest.a /usr/lib/
-
-# less than 1.18.0
-$ cd /usr/src/gtest
-$ sudo cmake .
-$ sudo make
-$ sudo cp libgtest.a /usr/lib
-
-$ cd /usr/src/gmock
-$ sudo cmake .
-$ sudo make
-$ sudo cp libgmock.a /usr/lib
-```
+| Package name | Content |
+|-----|-----|
+| pulsar-client | Shared library `libpulsar.so` |
+| pulsar-client-devel | Static library `libpulsar.a` and C++ and C headers |
+| pulsar-client-debuginfo | Debug symbols for `libpulsar.so` |
 
-Finally, compile the Pulsar client library for C++ inside the Pulsar repo:
+#### Deb
+
+To build Debian packages:
 
 ```shell
-$ cd pulsar-client-cpp
-$ cmake .
-$ make
+pulsar-client-cpp/pkg/deb/docker-build-deb.sh
 ```
 
-The resulting files, `libpulsar.so` and `libpulsar.a`, will be placed in the `lib` folder of the repo while two tools, `perfProducer` and `perfConsumer`, will be placed in the `perf` directory.
+Debian packages will be created at `pulsar-client-cpp/pkg/deb/BUILD/DEB/`
+
+| Package name | Content |
+|-----|-----|
+| pulsar-client | Shared library `libpulsar.so` |
+| pulsar-client-dev | Static library `libpulsar.a` and C++ and C headers |
 
-### MacOS
+## MacOS
 
-First, install all of the necessary dependencies:
+Use the [Homebrew](https://brew.sh/) supplied recipe to build the Pulsar
+client lib on MacOS.
 
 ```shell
-# OpenSSL installation
-$ brew install openssl
-$ export OPENSSL_INCLUDE_DIR=/usr/local/opt/openssl/include/
-$ export OPENSSL_ROOT_DIR=/usr/local/opt/openssl/
-
-# Protocol Buffers installation
-$ brew tap homebrew/versions
-$ brew install protobuf260
-$ brew install boost
-$ brew install log4cxx
-
-# Google Test installation
-$ git clone https://github.com/google/googletest.git
-$ cd googletest
-$ cmake .
-$ make install
+brew install https://raw.githubusercontent.com/apache/incubator-pulsar/master/pulsar-client-cpp/homebrew/libpulsar.rb
 ```
 
-Then compile the Pulsar client library in the repo that you cloned:
+If using Python 3 on MacOS, add the flag `--with-python3` to the above command.
 
-```shell
-$ cd pulsar-client-cpp
-$ cmake .
-$ make
-```
+This will install the package with the library and headers.
 
 ## Connection URLs
 
@@ -135,7 +93,7 @@ $ make
 Client client("pulsar://localhost:6650");
 
 Consumer consumer;
-Result result = client.subscribe("persistent://public/default/my-topic", "my-subscribtion-name", consumer);
+Result result = client.subscribe("my-topic", "my-subscribtion-name", consumer);
 if (result != ResultOk) {
     LOG_ERROR("Failed to subscribe: " << result);
     return -1;
@@ -145,7 +103,8 @@ Message msg;
 
 while (true) {
     consumer.receive(msg);
-    LOG_INFO("Received: " << msg << "  with payload '" << msg.getDataAsString() << "'");
+    LOG_INFO("Received: " << msg
+            << "  with payload '" << msg.getDataAsString() << "'");
 
     consumer.acknowledge(msg);
 }
@@ -156,18 +115,18 @@ client.close();
 
 ## Producer
 
-```cpp
+```c++
 Client client("pulsar://localhost:6650");
 
 Producer producer;
-Result result = client.createProducer("persistent://public/default/my-topic", producer);
+Result result = client.createProducer("my-topic", producer);
 if (result != ResultOk) {
     LOG_ERROR("Error creating producer: " << result);
     return -1;
 }
 
 // Publish 10 messages to the topic
-for(int i=0;i<10;i++){
+for (int i = 0; i < 10; i++){
     Message msg = MessageBuilder().setContent("my-message").build();
     Result res = producer.send(msg);
     LOG_INFO("Message sent: " << res);
@@ -180,15 +139,10 @@ client.close();
 ```cpp
 ClientConfiguration config = ClientConfiguration();
 config.setUseTls(true);
-std::string certfile = "/path/to/cacert.pem";
-
-ParamMap params;
-params["tlsCertFile"] = "/path/to/client-cert.pem";
-params["tlsKeyFile"]  = "/path/to/client-key.pem";
-config.setTlsTrustCertsFilePath(certfile);
+config.setTlsTrustCertsFilePath("/path/to/cacert.pem");
 config.setTlsAllowInsecureConnection(false);
-AuthenticationPtr auth = pulsar::AuthFactory::create("/path/to/libauthtls.so", params);
-config.setAuth(auth);
+config.setAuth(pulsar::AuthTls::create(
+            "/path/to/client-cert.pem", "/path/to/client-key.pem"););
 
-Client client("pulsar+ssl://my-broker.com:6651",config);
+Client client("pulsar+ssl://my-broker.com:6651", config);
 ```
diff --git a/site/docs/latest/project/CompileCpp.md b/site/docs/latest/project/CompileCpp.md
@@ -0,0 +1,120 @@
+---
+title: Building Pulsar C++ client
+tags: [client, cpp]
+---
+
+<!--
+
+    Licensed to the Apache Software Foundation (ASF) under one
+    or more contributor license agreements.  See the NOTICE file
+    distributed with this work for additional information
+    regarding copyright ownership.  The ASF licenses this file
+    to you under the Apache License, Version 2.0 (the
+    "License"); you may not use this file except in compliance
+    with the License.  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing,
+    software distributed under the License is distributed on an
+    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+    KIND, either express or implied.  See the License for the
+    specific language governing permissions and limitations
+    under the License.
+
+-->
+
+## Supported platforms
+
+The Pulsar C++ client has been successfully tested on **MacOS** and **Linux**.
+
+## System requirements
+
+You need to have the following installed to use the C++ client:
+
+* [CMake](https://cmake.org/)
+* [Boost](http://www.boost.org/)
+* [Protocol Buffers](https://developers.google.com/protocol-buffers/) 2.6
+* [Log4CXX](https://logging.apache.org/log4cxx)
+* [libcurl](https://curl.haxx.se/libcurl/)
+* [Google Test](https://github.com/google/googletest)
+* [JsonCpp](https://github.com/open-source-parsers/jsoncpp)
+
+## Compilation
+
+There are separate compilation instructions for [MacOS](#macos) and [Linux](#linux). For both systems, start by cloning the Pulsar repository:
+
+```shell
+$ git clone {{ site.pulsar_repo }}
+```
+
+### Linux
+
+First, install all of the necessary dependencies:
+
+```shell
+$ apt-get install cmake libssl-dev libcurl4-openssl-dev liblog4cxx-dev \
+  libprotobuf-dev libboost-all-dev google-mock libgtest-dev libjsoncpp-dev
+```
+
+Then compile and install [Google Test](https://github.com/google/googletest):
+
+```shell
+# libgtest-dev version is 1.18.0 or above
+$ cd /usr/src/googletest
+$ sudo cmake .
+$ sudo make
+$ sudo cp ./googlemock/libgmock.a ./googletest/libgtest.a /usr/lib/
+
+# less than 1.18.0
+$ cd /usr/src/gtest
+$ sudo cmake .
+$ sudo make
+$ sudo cp libgtest.a /usr/lib
+
+$ cd /usr/src/gmock
+$ sudo cmake .
+$ sudo make
+$ sudo cp libgmock.a /usr/lib
+```
+
+Finally, compile the Pulsar client library for C++ inside the Pulsar repo:
+
+```shell
+$ cd pulsar-client-cpp
+$ cmake .
+$ make
+```
+
+The resulting files, `libpulsar.so` and `libpulsar.a`, will be placed in the `lib` folder of the repo while two tools, `perfProducer` and `perfConsumer`, will be placed in the `perf` directory.
+
+### MacOS
+
+First, install all of the necessary dependencies:
+
+```shell
+# OpenSSL installation
+$ brew install openssl
+$ export OPENSSL_INCLUDE_DIR=/usr/local/opt/openssl/include/
+$ export OPENSSL_ROOT_DIR=/usr/local/opt/openssl/
+
+# Protocol Buffers installation
+$ brew tap homebrew/versions
+$ brew install protobuf260
+$ brew install boost
+$ brew install log4cxx
+
+# Google Test installation
+$ git clone https://github.com/google/googletest.git
+$ cd googletest
+$ cmake .
+$ make install
+```
+
+Then compile the Pulsar client library in the repo that you cloned:
+
+```shell
+$ cd pulsar-client-cpp
+$ cmake .
+$ make
+```