From 0a9dedc7c861da3bd5896cc9b769b65ad7666e56 Mon Sep 17 00:00:00 2001 From: Yunze Xu Date: Fri, 4 Nov 2022 01:21:34 +0800 Subject: [PATCH 1/3] Fix doxygen generation --- .gitignore | 1 + Doxyfile | 2 +- README.md | 4 ++++ 3 files changed, 6 insertions(+), 1 deletion(-) diff --git a/.gitignore b/.gitignore index 4fd7cf1b..ee4f28fb 100644 --- a/.gitignore +++ b/.gitignore @@ -72,6 +72,7 @@ compile_commands.json # doxygen files apidocs/ +doxygen/ # generated files generated/ diff --git a/Doxyfile b/Doxyfile index b3ac004d..749338b8 100644 --- a/Doxyfile +++ b/Doxyfile @@ -77,7 +77,7 @@ PROJECT_LOGO = # entered, it will be relative to the location where doxygen was started. If # left blank the current directory will be used. -OUTPUT_DIRECTORY = ../target/doxygen +OUTPUT_DIRECTORY = ./doxygen # If the CREATE_SUBDIRS tag is set to YES then doxygen will create 4096 sub- # directories (in 2 levels) under the output directory of each output format and diff --git a/README.md b/README.md index 9b0c2bfd..2089c29f 100644 --- a/README.md +++ b/README.md @@ -23,6 +23,10 @@ Examples for using the API to publish and consume messages can be found under the [examples](examples) folder. +## Generate the API documents + +Pulsar C++ client uses [doxygen](https://www.doxygen.nl) to build API documents. After installing `doxygen`, you only need to run `doxygen` to generate the API documents whose main page is under the `doxygen/html/index.html` path. + ## Requirements * A C++ compiler that supports C++11, like GCC >= 4.8 From b7000a099ac6bfc629206cdcc20998950993c81f Mon Sep 17 00:00:00 2001 From: Yunze Xu Date: Fri, 4 Nov 2022 01:46:10 +0800 Subject: [PATCH 2/3] Fix outdated MainPage --- Doxyfile | 4 +- README.md | 2 +- docs/MainPage.md | 180 ----------------------------------------------- 3 files changed, 3 insertions(+), 183 deletions(-) delete mode 100644 docs/MainPage.md diff --git a/Doxyfile b/Doxyfile index 749338b8..145948c3 100644 --- a/Doxyfile +++ b/Doxyfile @@ -809,7 +809,7 @@ WARN_LOGFILE = # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING # Note: If this tag is empty the current directory is searched. -INPUT = include docs/MainPage.md +INPUT = include ./README.md # This tag can be used to specify the character encoding of the source files # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses @@ -1001,7 +1001,7 @@ FILTER_SOURCE_PATTERNS = # (index.html). This can be useful if you have a project on for instance GitHub # and want to reuse the introduction page also for the doxygen output. -USE_MDFILE_AS_MAINPAGE = docs/MainPage.md +USE_MDFILE_AS_MAINPAGE = ./README.md #--------------------------------------------------------------------------- # Configuration options related to source browsing diff --git a/README.md b/README.md index 2089c29f..eb735409 100644 --- a/README.md +++ b/README.md @@ -21,7 +21,7 @@ # Pulsar C++ client library -Examples for using the API to publish and consume messages can be found under the [examples](examples) folder. +Examples for using the API to publish and consume messages can be found under the [examples](https://github.com/apache/pulsar-client-cpp/tree/main/examples) folder. ## Generate the API documents diff --git a/docs/MainPage.md b/docs/MainPage.md deleted file mode 100644 index 2115b9a9..00000000 --- a/docs/MainPage.md +++ /dev/null @@ -1,180 +0,0 @@ - - -# The Pulsar C++ client - -Welcome to the Doxygen documentation for [Pulsar](https://pulsar.apache.org/). - -## 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) - -## 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 libboost-all-dev libgtest-dev libjsoncpp-dev -``` - -Then compile and install [Google Test](https://github.com/google/googletest): - -```shell -$ git clone https://github.com/google/googletest.git && cd googletest -$ sudo cmake . -$ sudo make -$ sudo cp *.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 -$ git checkout release-1.12.1 -$ cmake . -$ make install -``` - -Then compile the Pulsar client library in the repo that you cloned: - -```shell -$ cd pulsar-client-cpp -$ cmake . -$ make -``` - -## Consumer - -```cpp -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); -``` - -## Code formatting -After you changed code, run auto-formatting by the following command. - -```bash -make format -``` -You need to have the following installed to use the auto-formatting. -* [clang-format 5.0](https://clang.llvm.org/) From 2ed50337d7a10c7319e79c709a879007e8896606 Mon Sep 17 00:00:00 2001 From: Yunze Xu Date: Fri, 4 Nov 2022 01:47:10 +0800 Subject: [PATCH 3/3] Fix outdated protobuf docs --- README.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/README.md b/README.md index eb735409..33df78a7 100644 --- a/README.md +++ b/README.md @@ -36,8 +36,6 @@ Pulsar C++ client uses [doxygen](https://www.doxygen.nl) to build API documents. * [libcurl](https://curl.se/libcurl/) * [openssl](https://github.com/openssl/openssl) -It's recommended to use Protocol Buffer 2.6 because it's verified by CI, but 3.x also works. - The default supported [compression types](include/pulsar/CompressionType.h) are: * `CompressionNone`