This is an automated email from the ASF dual-hosted git repository.
hjf pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/pulsar.git
The following commit(s) were added to refs/heads/master by this push:
new 11b9359 [ISSUE 8477][docs] Duplicate info of using C++ in Pulsar
(#8919)
11b9359 is described below
commit 11b935930e8f041991a4d51baee20203fb28810b
Author: sijia-w <53718687+siji...@users.noreply.github.com>
AuthorDate: Thu Dec 24 11:07:58 2020 +0100
[ISSUE 8477][docs] Duplicate info of using C++ in Pulsar (#8919)
* fix 8477 doc issue
* update
* Update client-libraries-cpp.md
* update sidebars
---
site2/docs/client-libraries-cpp.md | 158 ++++++++++++++++++++++++++++++-------
site2/docs/developing-cpp.md | 100 -----------------------
site2/website/sidebars.json | 3 +-
3 files changed, 130 insertions(+), 131 deletions(-)
diff --git a/site2/docs/client-libraries-cpp.md
b/site2/docs/client-libraries-cpp.md
index c2c209a..c495f19 100644
--- a/site2/docs/client-libraries-cpp.md
+++ b/site2/docs/client-libraries-cpp.md
@@ -14,40 +14,100 @@ Pulsar C++ client is supported on **Linux** and **MacOS**
platforms.
[Doxygen](http://www.doxygen.nl/)-generated API docs for the C++ client are
available [here](/api/cpp).
+## System requirements
+
+You need to install the following components before using the C++ client:
+
+* [CMake](https://cmake.org/)
+* [Boost](http://www.boost.org/)
+* [Protocol Buffers](https://developers.google.com/protocol-buffers/) 2.6
+* [libcurl](https://curl.haxx.se/libcurl/)
+* [Google Test](https://github.com/google/googletest)
+
## Linux
+### Compilation
+
+1. Clone the Pulsar repository.
+
+```shell
+$ git clone https://github.com/apache/pulsar
+```
+
+2. Install all necessary dependencies.
+
+```shell
+$ apt-get install cmake libssl-dev libcurl4-openssl-dev liblog4cxx-dev \
+ libprotobuf-dev protobuf-compiler libboost-all-dev google-mock libgtest-dev
libjsoncpp-dev
+```
+
+3. 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 ./googlemock/gtest/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
+```
+
+4. Compile the Pulsar client library for C++ inside the Pulsar repository.
+
+```shell
+$ cd pulsar-client-cpp
+$ cmake .
+$ make
+```
+
+After you install the components successfully, the files `libpulsar.so` and
`libpulsar.a` are in the `lib` folder of the repository. The tools
`perfProducer` and `perfConsumer` are in the `perf` directory.
+
+### Install Dependencies
+
> Since 2.1.0 release, Pulsar ships pre-built RPM and Debian packages. You can
> download and install those packages directly.
-Four kind of libraries `libpulsar.so` / `libpulsarnossl.so` / `libpulsar.a` /
`libpulsarwithdeps.a` are included in your `/usr/lib` after rpm/deb download
and install.
-By default, they are build under code path `${PULSAR_HOME}/pulsar-client-cpp`,
using command
- `cmake . -DBUILD_TESTS=OFF -DLINK_STATIC=ON && make pulsarShared
pulsarSharedNossl pulsarStatic pulsarStaticWithDeps -j 3`
-These libraries rely on some other libraries, if you want to get detailed
version of dependencies libraries, please reference
[these](https://github.com/apache/pulsar/blob/master/pulsar-client-cpp/pkg/rpm/Dockerfile)
[files](https://github.com/apache/pulsar/blob/master/pulsar-client-cpp/pkg/deb/Dockerfile).
+After you download and install RPM or DEB, the `libpulsar.so`,
`libpulsarnossl.so`, `libpulsar.a`, and `libpulsarwithdeps.a` libraries are in
your `/usr/lib` directory.
+
+By default, they are built in code path `${PULSAR_HOME}/pulsar-client-cpp`.
You can build with the command below.
+
+ `cmake . -DBUILD_TESTS=OFF -DLINK_STATIC=ON && make pulsarShared
pulsarSharedNossl pulsarStatic pulsarStaticWithDeps -j 3`.
+
+These libraries rely on some other libraries. If you want to get detailed
version of dependencies, see
[RPM](https://github.com/apache/pulsar/blob/master/pulsar-client-cpp/pkg/rpm/Dockerfile)
or
[DEB](https://github.com/apache/pulsar/blob/master/pulsar-client-cpp/pkg/deb/Dockerfile)
files.
+
+1. `libpulsar.so` is a shared library, containing statically linked `boost`
and `openssl`. It also dynamically links all other necessary libraries. You can
use this Pulsar library with the command below.
-1. `libpulsar.so` is the Shared library, it contains statically linked `boost`
and `openssl`, and will also dynamically link all other needed libraries.
-The command the when use this pulsar library is like this:
```bash
g++ --std=c++11 PulsarTest.cpp -o test /usr/lib/libpulsar.so
-I/usr/local/ssl/include
```
-2. `libpulsarnossl.so` is the Shared library that similar to `libpulsar.so`
except that the library `openssl` and `crypto` are dynamically linked.
-The command the when use this pulsar library is like this:
+2. `libpulsarnossl.so` is a shared library, similar to `libpulsar.so` except
that the libraries `openssl` and `crypto` are dynamically linked. You can use
this Pulsar library with the command below.
+
```bash
g++ --std=c++11 PulsarTest.cpp -o test /usr/lib/libpulsarnossl.so -lssl
-lcrypto -I/usr/local/ssl/include -L/usr/local/ssl/lib
```
-3. `libpulsar.a` is the Static library, it need to load some dependencies
library when using it.
-The command the when use this pulsar library is like this:
+3. `libpulsar.a` is a static library. You need to load dependencies before
using this library. You can use this Pulsar library with the command below.
+
```bash
g++ --std=c++11 PulsarTest.cpp -o test /usr/lib/libpulsar.a -lssl -lcrypto
-ldl -lpthread -I/usr/local/ssl/include -L/usr/local/ssl/lib -lboost_system
-lboost_regex -lcurl -lprotobuf -lzstd -lz
```
-4. `libpulsarwithdeps.a` is the Static library, base on `libpulsar.a`, and
archived in the dependencies libraries of `libboost_regex`, `libboost_system`,
`libcurl`, `libprotobuf`, `libzstd` and `libz`,
-The command the when use this pulsar library is like this:
+4. `libpulsarwithdeps.a` is a static library, based on `libpulsar.a`. It is
archived in the dependencies of `libboost_regex`, `libboost_system`, `libcurl`,
`libprotobuf`, `libzstd` and `libz`. You can use this Pulsar library with the
command below.
+
```bash
g++ --std=c++11 PulsarTest.cpp -o test /usr/lib/libpulsarwithdeps.a -lssl
-lcrypto -ldl -lpthread -I/usr/local/ssl/include -L/usr/local/ssl/lib
```
-`libpulsarwithdeps.a` does not include library openssl related libraries:
`libssl` and `libcrypto`, because these 2 library is related to security,
-by using user local system provided version is more reasonable, and more easy
for user to handling security issue and library upgrade.
+The `libpulsarwithdeps.a` does not include library openssl related libraries
`libssl` and `libcrypto`, because these two libraries are related to security.
It is more reasonable and easier to use the versions provided by the local
system to handle security issues and upgrade libraries.
### Install RPM
@@ -65,7 +125,7 @@ by using user local system provided version is more
reasonable, and more easy fo
$ rpm -ivh apache-pulsar-client*.rpm
```
-After install, Pulsar libraries will be placed under `/usr/lib`.
+After you install RPM successfully, Pulsar libraries are in the `/usr/lib`
directory.
### Install Debian
@@ -76,23 +136,22 @@ After install, Pulsar libraries will be placed under
`/usr/lib`.
| [client]({{pulsar:deb:client}}) | [asc]({{pulsar:dist_deb:client}}.asc),
[sha512]({{pulsar:dist_deb:client}}.sha512) |
| [client-devel]({{pulsar:deb:client-devel}}) |
[asc]({{pulsar:dist_deb:client-devel}}.asc),
[sha512]({{pulsar:dist_deb:client-devel}}.sha512) |
-2. Install the package using the following command:
+2. Install the package using the following command.
```bash
$ apt install ./apache-pulsar-client*.deb
```
-After install, Pulsar libraries will be placed under `/usr/lib`.
+After you install DEB successfully, Pulsar libraries are in the `/usr/lib`
directory.
### Build
-> If you want to build RPM and Debian packages from the latest master, follow
the instructions below. All the instructions are run at the root directory of
your cloned Pulsar repository.
+> If you want to build RPM and Debian packages from the latest master, follow
the instructions below. You should run all the instructions at the root
directory of your cloned Pulsar repository.
There are recipes that build RPM and Debian packages containing a
-statically linked `libpulsar.so` / `libpulsarnossl.so` / `libpulsar.a` /
`libpulsarwithdeps.a` with all the required
-dependencies.
+statically linked `libpulsar.so` / `libpulsarnossl.so` / `libpulsar.a` /
`libpulsarwithdeps.a` with all required dependencies.
-To build the C++ library packages, build the Java packages first.
+To build the C++ library packages, you need to build the Java packages first.
```shell
mvn install -DskipTests
@@ -100,12 +159,12 @@ mvn install -DskipTests
#### RPM
+To build the RPM inside a Docker container, use the command below. The RPMs
are in the `pulsar-client-cpp/pkg/rpm/RPMS/x86_64/` path.
+
```shell
pulsar-client-cpp/pkg/rpm/docker-build-rpm.sh
```
-This builds the RPM inside a Docker container and it leaves the RPMs in
`pulsar-client-cpp/pkg/rpm/RPMS/x86_64/`.
-
| Package name | Content |
|-----|-----|
| pulsar-client | Shared library `libpulsar.so` and `libpulsarnossl.so` |
@@ -120,7 +179,7 @@ To build Debian packages, enter the following command.
pulsar-client-cpp/pkg/deb/docker-build-deb.sh
```
-Debian packages are created at `pulsar-client-cpp/pkg/deb/BUILD/DEB/`.
+Debian packages are created in the `pulsar-client-cpp/pkg/deb/BUILD/DEB/` path.
| Package name | Content |
|-----|-----|
@@ -129,6 +188,45 @@ Debian packages are created at
`pulsar-client-cpp/pkg/deb/BUILD/DEB/`.
## MacOS
+### Compilation
+
+1. Clone the Pulsar repository.
+
+```shell
+$ git clone https://github.com/apache/pulsar
+```
+
+2. Install all 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
+```
+
+3. Compile the Pulsar client library in the repository that you cloned.
+
+```shell
+$ cd pulsar-client-cpp
+$ cmake .
+$ make
+```
+
+### Install `libpulsar`
+
Pulsar releases are available in the [Homebrew](https://brew.sh/) core
repository. You can install the C++ client library with the following command.
The package is installed with the library and headers.
```shell
@@ -137,7 +235,7 @@ brew install libpulsar
## Connection URLs
-To connect to Pulsar using client libraries, you need to specify a Pulsar
protocol URL.
+To connect Pulsar using client libraries, you need to specify a Pulsar
protocol URL.
Pulsar protocol URLs are assigned to specific clusters, you can use the Pulsar
URI scheme. The default port is `6650`. The following is an example for
localhost.
@@ -145,7 +243,7 @@ Pulsar protocol URLs are assigned to specific clusters, you
can use the Pulsar U
pulsar://localhost:6650
```
-In a Pulsar cluster in production, the URL looks as follows:
+In a Pulsar cluster in production, the URL looks as follows.
```http
pulsar://pulsar.us-west.example.com:6650
```
@@ -156,7 +254,8 @@ pulsar+ssl://pulsar.us-west.example.com:6651
```
## Create a consumer
-To connect to Pulsar as a consumer, you need to create a consumer on the C++
client. The following is an example.
+
+To use Pulsar as a consumer, you need to create a consumer on the C++ client.
The following is an example.
```c++
Client client("pulsar://localhost:6650");
@@ -182,7 +281,8 @@ client.close();
```
## Create a producer
-To connect to Pulsar as a producer, you need to create a producer on the C++
client. The following is an example.
+
+To use Pulsar as a producer, you need to create a producer on the C++ client.
The following is an example.
```c++
Client client("pulsar://localhost:6650");
@@ -249,4 +349,4 @@ ConsumerConfiguration consumerConf;
Consumer consumer;
consumerConf.setSchema(SchemaInfo(AVRO, "Avro", exampleSchema));
client.subscribe("topic-avro", "sub-2", consumerConf, consumer)
-```
\ No newline at end of file
+```
diff --git a/site2/docs/developing-cpp.md b/site2/docs/developing-cpp.md
deleted file mode 100644
index 9f1c3a8..0000000
--- a/site2/docs/developing-cpp.md
+++ /dev/null
@@ -1,100 +0,0 @@
----
-id: develop-cpp
-title: Building Pulsar C++ client
-sidebar_label: Building Pulsar C++ client
----
-
-## 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 https://github.com/apache/pulsar
-```
-
-### Linux
-
-First, install all of the necessary dependencies:
-
-```shell
-$ apt-get install cmake libssl-dev libcurl4-openssl-dev liblog4cxx-dev \
- libprotobuf-dev protobuf-compiler 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 ./googlemock/gtest/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
-```
diff --git a/site2/website/sidebars.json b/site2/website/sidebars.json
index 78597d7..ca78199 100644
--- a/site2/website/sidebars.json
+++ b/site2/website/sidebars.json
@@ -143,8 +143,7 @@
"develop-tools",
"develop-binary-protocol",
"develop-schema",
- "develop-load-manager",
- "develop-cpp"
+ "develop-load-manager"
],
"Reference": [
"reference-terminology",
