You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@pulsar.apache.org by GitBox <gi...@apache.org> on 2022/09/11 16:48:51 UTC
[GitHub] [pulsar] PragmaTwice commented on a diff in pull request #17580: [improve][doc] Simplify the Install section and promote a top-level "Installation" title
PragmaTwice commented on code in PR #17580:
URL: https://github.com/apache/pulsar/pull/17580#discussion_r967856949
##########
site2/docs/client-libraries-cpp.md:
##########
@@ -4,298 +4,192 @@ title: Pulsar C++ client
sidebar_label: "C++"
---
-You can use Pulsar C++ client to create Pulsar producers and consumers in C++.
+````mdx-code-block
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+````
-All the methods in producer, consumer, and reader of a C++ client are thread-safe.
+You can use a Pulsar C++ client to create producers, consumers, and readers.
-## Supported platforms
+All the methods in producer, consumer, and reader of a C++ client are thread-safe. You can read the Doxygen-generated [API docs](/api/cpp) for the C++ client
-Pulsar C++ client is supported on **Linux**, **macOS** and **Windows** platforms.
+## Installation
-Doxygen-generated API docs for the C++ client are available [here](/api/cpp).
+### Brew
-## Linux
+Install the latest tagged version with the library and headers:
-:::note
-
-You can choose one of the following installation methods based on your needs: Compilation, Install RPM or Install Debian.
-
-:::
-
-### Compilation
-
-#### 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/) >= 3
-* [libcurl](https://curl.se/libcurl/)
-* [Google Test](https://github.com/google/googletest)
-
-1. Clone the Pulsar repository.
-
-```shell
-git clone https://github.com/apache/pulsar
+```bash
+brew install libpulsar
```
-2. Install all necessary dependencies.
+For more information, read [libpulsar formula's homepage](https://formulae.brew.sh/formula/libpulsar).
-```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).
+### Deb
-```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/
+1. Download any one of the Deb packages:
-# less than 1.18.0
-cd /usr/src/gtest
-sudo cmake .
-sudo make
-sudo cp libgtest.a /usr/lib
+<Tabs>
+<TabItem value="client">
-cd /usr/src/gmock
-sudo cmake .
-sudo make
-sudo cp libgmock.a /usr/lib
+```bash
+wget @pulsar:deb:client@
```
-4. Compile the Pulsar client library for C++ inside the Pulsar repository.
+</TabItem>
+<TabItem value="client-devel">
-```shell
-cd pulsar-client-cpp
-cmake .
-make
+```bash
+wget @pulsar:deb:client-devel@
```
-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.
+</TabItem>
+</Tabs>
-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.
+2. Install the package using the following command:
-By default, they are built-in code path `${PULSAR_HOME}/pulsar-client-cpp`. You can build with the command below.
-
- ```bash
- cmake . -DBUILD_TESTS=OFF -DLINK_STATIC=ON && make pulsarShared pulsarSharedNossl pulsarStatic pulsarStaticWithDeps -j 3
- ```
+```bash
+apt install ./apache-pulsar-client*.deb
+```
-These libraries rely on some other libraries. If you want to get a 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.
+Now, you can see Pulsar C++ client libraries installed under the `/usr/lib` directory.
-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.
+### RPM
-```bash
- g++ --std=c++11 PulsarTest.cpp -o test /usr/lib/libpulsar.so -I/usr/local/ssl/include
-```
+1. Download any one of the RPM packages:
-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.
+<Tabs>
+<TabItem value="client">
```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
+wget @pulsar:dist_rpm:client@
```
-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.
+</TabItem>
+<TabItem value="client-debuginfo">
```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
+wget @pulsar:dist_rpm:client-debuginfo@
```
-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.
+</TabItem>
+<TabItem value="client-devel">
```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
+wget @pulsar:dist_rpm:client-devel@
```
-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.
+</TabItem>
+</Tabs>
-### Install RPM
-
-1. Download an RPM package from the links in the table.
-
-| Link | Crypto files |
-|------|--------------|
-| [client](@pulsar:dist_rpm:client@) | [asc](@pulsar:dist_rpm:client@.asc), [sha512](@pulsar:dist_rpm:client@.sha512) |
-| [client-debuginfo](@pulsar:dist_rpm:client-debuginfo@) | [asc](@pulsar:dist_rpm:client-debuginfo@.asc), [sha512](@pulsar:dist_rpm:client-debuginfo@.sha512) |
-| [client-devel](@pulsar:dist_rpm:client-devel@) | [asc](@pulsar:dist_rpm:client-devel@.asc), [sha512](@pulsar:dist_rpm:client-devel@.sha512) |
-
-2. Install the package using the following command.
+2. Install the package using the following command:
```bash
rpm -ivh apache-pulsar-client*.rpm
```
-After you install RPM successfully, Pulsar libraries are in the `/usr/lib` directory, for example：
-
-```bash
-lrwxrwxrwx 1 root root 18 Dec 30 22:21 libpulsar.so -> libpulsar.so.2.9.1
-lrwxrwxrwx 1 root root 23 Dec 30 22:21 libpulsarnossl.so -> libpulsarnossl.so.2.9.1
-```
+Now, you can see Pulsar C++ client libraries installed under the `/usr/lib` directory.
:::note
-If you get the error that `libpulsar.so: cannot open shared object file: No such file or directory` when starting Pulsar client, you may need to run `ldconfig` first.
+If you get the error like "libpulsar.so: cannot open shared object file: No such file or directory" when starting Pulsar client, you need to run `ldconfig` first.
:::
-2. Install the GCC and g++ using the following command, otherwise errors would occur in installing Node.js.
-
-```bash
-sudo yum -y install gcc automake autoconf libtool make
-sudo yum -y install gcc-c++
-```
-
-### Install Debian
-
-1. Download a Debian package from the links in the table.
-
-| Link | Crypto files |
-|------|--------------|
-| [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) |
+### Source
-2. Install the package using the following command.
+1. Clone the Pulsar repository and switch to the working directory `pulsar-client-cpp`:
```bash
-apt install ./apache-pulsar-client*.deb
+git clone https://github.com/apache/pulsar
+cd pulsar
+cd pulsar-client-cpp
```
-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. You must 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 required dependencies.
+2. Install dependencies:
-To build the C++ library packages, you need to build the Java packages first.
+<Tabs>
+<TabItem value="Linux">
-```shell
-mvn install -DskipTests
-```
+```bash
+apt install cmake libssl-dev libcurl4-openssl-dev liblog4cxx-dev libprotobuf-dev protobuf-compiler libboost-all-dev google-mock libgtest-dev libjsoncpp-dev
-#### RPM
+# libgtest-dev version is 1.18.0 or above
Review Comment:
Do users of this c++ client need gtest? Or only developers of the c++ client itself need it?
##########
site2/docs/client-libraries-cpp.md:
##########
@@ -4,298 +4,192 @@ title: Pulsar C++ client
sidebar_label: "C++"
---
-You can use Pulsar C++ client to create Pulsar producers and consumers in C++.
+````mdx-code-block
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+````
-All the methods in producer, consumer, and reader of a C++ client are thread-safe.
+You can use a Pulsar C++ client to create producers, consumers, and readers.
-## Supported platforms
+All the methods in producer, consumer, and reader of a C++ client are thread-safe. You can read the Doxygen-generated [API docs](/api/cpp) for the C++ client
-Pulsar C++ client is supported on **Linux**, **macOS** and **Windows** platforms.
+## Installation
-Doxygen-generated API docs for the C++ client are available [here](/api/cpp).
+### Brew
-## Linux
+Install the latest tagged version with the library and headers:
-:::note
-
-You can choose one of the following installation methods based on your needs: Compilation, Install RPM or Install Debian.
-
-:::
-
-### Compilation
-
-#### 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/) >= 3
-* [libcurl](https://curl.se/libcurl/)
-* [Google Test](https://github.com/google/googletest)
-
-1. Clone the Pulsar repository.
-
-```shell
-git clone https://github.com/apache/pulsar
+```bash
+brew install libpulsar
```
-2. Install all necessary dependencies.
+For more information, read [libpulsar formula's homepage](https://formulae.brew.sh/formula/libpulsar).
-```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).
+### Deb
-```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/
+1. Download any one of the Deb packages:
-# less than 1.18.0
-cd /usr/src/gtest
-sudo cmake .
-sudo make
-sudo cp libgtest.a /usr/lib
+<Tabs>
+<TabItem value="client">
-cd /usr/src/gmock
-sudo cmake .
-sudo make
-sudo cp libgmock.a /usr/lib
+```bash
+wget @pulsar:deb:client@
```
-4. Compile the Pulsar client library for C++ inside the Pulsar repository.
+</TabItem>
+<TabItem value="client-devel">
-```shell
-cd pulsar-client-cpp
-cmake .
-make
+```bash
+wget @pulsar:deb:client-devel@
```
-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.
+</TabItem>
+</Tabs>
-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.
+2. Install the package using the following command:
-By default, they are built-in code path `${PULSAR_HOME}/pulsar-client-cpp`. You can build with the command below.
-
- ```bash
- cmake . -DBUILD_TESTS=OFF -DLINK_STATIC=ON && make pulsarShared pulsarSharedNossl pulsarStatic pulsarStaticWithDeps -j 3
- ```
+```bash
+apt install ./apache-pulsar-client*.deb
+```
-These libraries rely on some other libraries. If you want to get a 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.
+Now, you can see Pulsar C++ client libraries installed under the `/usr/lib` directory.
-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.
+### RPM
-```bash
- g++ --std=c++11 PulsarTest.cpp -o test /usr/lib/libpulsar.so -I/usr/local/ssl/include
-```
+1. Download any one of the RPM packages:
-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.
+<Tabs>
+<TabItem value="client">
```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
+wget @pulsar:dist_rpm:client@
```
-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.
+</TabItem>
+<TabItem value="client-debuginfo">
```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
+wget @pulsar:dist_rpm:client-debuginfo@
```
-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.
+</TabItem>
+<TabItem value="client-devel">
```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
+wget @pulsar:dist_rpm:client-devel@
```
-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.
+</TabItem>
+</Tabs>
-### Install RPM
-
-1. Download an RPM package from the links in the table.
-
-| Link | Crypto files |
-|------|--------------|
-| [client](@pulsar:dist_rpm:client@) | [asc](@pulsar:dist_rpm:client@.asc), [sha512](@pulsar:dist_rpm:client@.sha512) |
-| [client-debuginfo](@pulsar:dist_rpm:client-debuginfo@) | [asc](@pulsar:dist_rpm:client-debuginfo@.asc), [sha512](@pulsar:dist_rpm:client-debuginfo@.sha512) |
-| [client-devel](@pulsar:dist_rpm:client-devel@) | [asc](@pulsar:dist_rpm:client-devel@.asc), [sha512](@pulsar:dist_rpm:client-devel@.sha512) |
-
-2. Install the package using the following command.
+2. Install the package using the following command:
```bash
rpm -ivh apache-pulsar-client*.rpm
```
-After you install RPM successfully, Pulsar libraries are in the `/usr/lib` directory, for example：
-
-```bash
-lrwxrwxrwx 1 root root 18 Dec 30 22:21 libpulsar.so -> libpulsar.so.2.9.1
-lrwxrwxrwx 1 root root 23 Dec 30 22:21 libpulsarnossl.so -> libpulsarnossl.so.2.9.1
-```
+Now, you can see Pulsar C++ client libraries installed under the `/usr/lib` directory.
:::note
-If you get the error that `libpulsar.so: cannot open shared object file: No such file or directory` when starting Pulsar client, you may need to run `ldconfig` first.
+If you get the error like "libpulsar.so: cannot open shared object file: No such file or directory" when starting Pulsar client, you need to run `ldconfig` first.
:::
-2. Install the GCC and g++ using the following command, otherwise errors would occur in installing Node.js.
-
-```bash
-sudo yum -y install gcc automake autoconf libtool make
-sudo yum -y install gcc-c++
-```
-
-### Install Debian
-
-1. Download a Debian package from the links in the table.
-
-| Link | Crypto files |
-|------|--------------|
-| [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) |
+### Source
-2. Install the package using the following command.
+1. Clone the Pulsar repository and switch to the working directory `pulsar-client-cpp`:
```bash
-apt install ./apache-pulsar-client*.deb
+git clone https://github.com/apache/pulsar
+cd pulsar
+cd pulsar-client-cpp
```
-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. You must 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 required dependencies.
+2. Install dependencies:
-To build the C++ library packages, you need to build the Java packages first.
+<Tabs>
+<TabItem value="Linux">
-```shell
-mvn install -DskipTests
-```
+```bash
+apt install cmake libssl-dev libcurl4-openssl-dev liblog4cxx-dev libprotobuf-dev protobuf-compiler libboost-all-dev google-mock libgtest-dev libjsoncpp-dev
-#### RPM
+# libgtest-dev version is 1.18.0 or above
Review Comment:
Do users of this c++ client need gtest? Or only developers of the c++ client need it?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@pulsar.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org