This is an automated email from the ASF dual-hosted git repository.
sijie pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-pulsar.git
The following commit(s) were added to refs/heads/master by this push:
new f221b26 Improved instruction for getting started with C++ client lib
(#1975)
f221b26 is described below
commit f221b2652e51e5a539da0431cb27d2520e748a7e
Author: Matteo Merli <[email protected]>
AuthorDate: Mon Jun 18 00:34:42 2018 -0700
Improved instruction for getting started with C++ client lib (#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).
---
site/_data/sidebar.yaml | 2 +
site/docs/latest/clients/Cpp.md | 128 +++++++--------------
.../{clients/Cpp.md => project/CompileCpp.md} | 76 +-----------
3 files changed, 44 insertions(+), 162 deletions(-)
diff --git a/site/_data/sidebar.yaml b/site/_data/sidebar.yaml
index bf8d566..81578ba 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 d153be9..34f36ed 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/clients/Cpp.md
b/site/docs/latest/project/CompileCpp.md
similarity index 62%
copy from site/docs/latest/clients/Cpp.md
copy to site/docs/latest/project/CompileCpp.md
index d153be9..69fcd28 100644
--- a/site/docs/latest/clients/Cpp.md
+++ b/site/docs/latest/project/CompileCpp.md
@@ -1,5 +1,5 @@
---
-title: The Pulsar C++ client
+title: Building Pulsar C++ client
tags: [client, cpp]
---
@@ -24,12 +24,6 @@ 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**.
@@ -124,71 +118,3 @@ $ cd pulsar-client-cpp
$ cmake .
$ make
```
-
-## Connection URLs
-
-{% include explanations/client-url.md %}
-
-## Consumer
-
-```c++
-Client client("pulsar://localhost:6650");
-
-Consumer consumer;
-Result result = client.subscribe("persistent://public/default/my-topic",
"my-subscribtion-name", consumer);
-if (result != ResultOk) {
- LOG_ERROR("Failed to subscribe: " << result);
- return -1;
-}
-
-Message msg;
-
-while (true) {
- consumer.receive(msg);
- LOG_INFO("Received: " << msg << " with payload '" <<
msg.getDataAsString() << "'");
-
- consumer.acknowledge(msg);
-}
-
-client.close();
-```
-
-
-## Producer
-
-```cpp
-Client client("pulsar://localhost:6650");
-
-Producer producer;
-Result result = client.createProducer("persistent://public/default/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++){
- Message msg = MessageBuilder().setContent("my-message").build();
- Result res = producer.send(msg);
- LOG_INFO("Message sent: " << res);
-}
-client.close();
-```
-
-## Authentication
-
-```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.setTlsAllowInsecureConnection(false);
-AuthenticationPtr auth = pulsar::AuthFactory::create("/path/to/libauthtls.so",
params);
-config.setAuth(auth);
-
-Client client("pulsar+ssl://my-broker.com:6651",config);
-```
--
To stop receiving notification emails like this one, please contact
[email protected].
