sijie closed pull request #1975: Improved instruction for getting started with
C++ client lib
URL: https://github.com/apache/incubator-pulsar/pull/1975
This is a PR merged from a forked repository.
As GitHub hides the original diff on merge, it is displayed below for
the sake of provenance:
As this is a foreign pull request (from a fork), the diff is supplied
below (as it won't show otherwise due to GitHub magic):
diff --git a/site/_data/sidebar.yaml b/site/_data/sidebar.yaml
index bf8d5665f2..81578bad68 100644
--- 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
index d153be92e6..34f36edd03 100644
--- 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
new file mode 100644
index 0000000000..69fcd28c80
--- /dev/null
+++ 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
+```
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
us...@infra.apache.org
With regards,
Apache Git Services
