[docs] Add example for how to import the library

README.md

@@ -27,6 +27,132 @@ For the supported Pulsar features, see [Client Feature Matrix](https://pulsar.ap
 
 For how to use APIs to publish and consume messages, see [examples](https://github.com/apache/pulsar-client-cpp/tree/main/examples).
 
+## Import the library into your project
+
+### CMake with vcpkg integration
+
+Here is a simple tutorial to import `pulsar-client-cpp` into your project via vcpkg.
+
+First, create an empty directory `hello-pulsar-cpp` as the project directory and create the following files.
+
+`vcpkg.json`:
+
+```json
+{
+  "name": "hello-pulsar",
+  "version-string": "0.0.1",
+  "builtin-baseline": "dc1982367038cf09bfa455c239d7ebc2e687a056",
+  "dependencies": [
+    {
+      "name": "pulsar-client-cpp",
+      "version>=": "3.4.2"
+    }
+  ]
+}
+```
+
+`CMakeLists.txt`:
+
+```cmake
+cmake_minimum_required(VERSION 3.15)
+
+project(HelloPulsar CXX)
+
+set(CMAKE_CXX_STANDARD 11)
+
+find_package(unofficial-pulsar CONFIG)
+add_executable(main main.cc)
+target_link_libraries(main PRIVATE unofficial::pulsar::pulsar)
+```
+
+`main.cc` (an example for synchronous send and receive):
+
+```c++
+#include <pulsar/Client.h>
+using namespace pulsar;
+
+int main(int argc, char *argv[]) {
+  Client client{"pulsar://localhost:6650"};
+  auto topic = "topic";
+  Producer producer;
+  auto result = client.createProducer(topic, producer);
+  if (result != ResultOk) {
+    std::cerr << "Failed to create producer: " << result << std::endl;
+    return 1;
+  }
+  Consumer consumer;
+  result = client.subscribe(topic, "sub-name", consumer);
+  if (result != ResultOk) {
+    std::cerr << "Failed to subscribe: " << result << std::endl;
+    return 2;
+  }
+
+  constexpr int numMessages = 5;
+  for (int i = 0; i < numMessages; i++) {
+    MessageId msgId;
+    auto result = producer.send(
+        MessageBuilder().setContent("msg-" + std::to_string(i)).build(), msgId);
+    if (result == ResultOk) {
+      std::cout << "Sent " << i << " to " << msgId << std::endl;
+    } else {
+      std::cerr << "Failed to send " << i << ": " << result << std::endl;
+      return 3;
+    }
+  }
+
+  for (int i = 0; i < numMessages; i++) {
+    Message msg;
+    auto result = consumer.receive(msg, 3000);
+    if (result != ResultOk) {
+      std::cerr << "Failed to receive in 3 seconds: " << result << std::endl;
+      return 4;
+    }
+    std::cout << "Received " << msg.getDataAsString() << " from "
+              << msg.getMessageId() << std::endl;
+  }
+
+  client.close();
+  return 0;
+}
+```
+
+Then, run the following commands to build the project:
+
+```bash
+cmake -B build -DCMAKE_BUILD_TYPE=Release -DCMAKE_TOOLCHAIN_FILE=$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake
+cmake --build build
+```
+
+> **Note**:
+>
+> `VCPKG_ROOT` is the path to the vcpkg project. You can simply clone the project into the current directory like:
+>
+> ```bash
+> git clone https://github.com/microsoft/vcpkg.git
+> export VCPKG_ROOT=$PWD/vcpkg
+> ```
+>
+> See [Using vcpkg with CMake](https://github.com/microsoft/vcpkg?tab=readme-ov-file#using-vcpkg-with-cmake) for more details.
+
+Finally, you will have an executable `build/main`. Run the executable and you might see the outputs like:
+
+```
+Sent 0 to (1,0,-1,0)
+Sent 1 to (1,1,-1,0)
+Sent 2 to (1,2,-1,0)
+Sent 3 to (1,3,-1,0)
+Sent 4 to (1,4,-1,0)
+Received msg-0 from (1,0,-1,0)
+Received msg-1 from (1,1,-1,0)
+Received msg-2 from (1,2,-1,0)
+Received msg-3 from (1,3,-1,0)
+Received msg-4 from (1,4,-1,0)
+```
+
+### Download pre-built binaries
+
+For non-vcpkg projects, you can download pre-built binaries from the [official release page](https://pulsar.apache.org/download/#pulsar-c-client).
+
 ## 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.