[docs] Add example for how to import the library via vcpkg (#379)

README.md

@@ -27,6 +27,16 @@ 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
+
+Navigate to [vcpkg-example](./vcpkg-example) for how to import the `pulsar-client-cpp` into your project via vcpkg.
+
+### 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.

vcpkg-example/CMakeLists.txt

@@ -0,0 +1,18 @@
+cmake_minimum_required(VERSION 3.15)
+
+if (NOT CMAKE_TOOLCHAIN_FILE)
+    set(CMAKE_TOOLCHAIN_FILE "${CMAKE_SOURCE_DIR}/../vcpkg/scripts/buildsystems/vcpkg.cmake")
+endif ()
+if (VCPKG_TARGET_TRIPLET MATCHES ".*windows-static")
+    cmake_policy(SET CMP0091 NEW)
+    set(CMAKE_MSVC_RUNTIME_LIBRARY "MultiThreaded$<$<CONFIG:Debug>:Debug>")
+endif ()
+project(PulsarDemo CXX)
+
+if (NOT CMAKE_CXX_STANDARD)
+    set(CMAKE_CXX_STANDARD 11)
+endif ()
+
+find_package(unofficial-pulsar CONFIG)
+add_executable(main main.cc)
+target_link_libraries(main PRIVATE unofficial::pulsar::pulsar)

vcpkg-example/README.md

@@ -0,0 +1,52 @@
+# vcpkg-example
+
+A simple example vcpkg project that imported pulsar-client-cpp 3.4.2 as the dependency.
+
+## How to build
+
+Before running the commands below, ensure the vcpkg has been installed. If you have already downloaded the submodule of this project, just run the following commands. If you want to specify an existing vcpkg installation directory (assuming it's `VCPKG_ROOT`), add the `-DCMAKE_TOOLCHAIN_FILE=$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake` option to the 1st command.
+
+```bash
+cmake -B build
+cmake --build build
+```
+
+Then the `main` executable will be generated under `./build` for single-configuration generators or `build/Debug` for multi-configuration generators.
+
+## How to link release libraries
+
+By default, debug libraries are linked so that the executable can be debugged by debuggers. However, when used for production, release libraries should be linked for better performance.
+
+See [cmake-generators](https://cmake.org/cmake/help/latest/manual/cmake-generators.7.html) for the concept of CMake Generator.
+
+### Single-configuration generator
+
+With single-configuration generators like Unix Makefiles on Linux and macOS, you need to specify the `CMAKE_BUILD_TYPE`.
+
+```bash
+cmake -B build -DCMAKE_BUILD_TYPE=Release
+cmake --build build
+```
+
+The `main` executable will still be generated under the `./build` directory but release libraries are linked now.
+
+### Multi-configuration generator
+
+With multi-configuration generators like Visual Studio on Windows, you just need to specify the `--config` option.
+
+```bash
+cmake -B build
+cmake --build build --config Release
+```
+
+The `main` executable that links release libraries will be generated under the `./build/Release` directory.
+
+## Link static libraries on Windows
+
+The default vcpkg triplet is `x64-windows` on Windows. If you changed the triplet for static libraries, like `x64-windows-static`, you need to add a line before the `project(PulsarDemo CXX)` in CMakeLists.txt.
+
+```cmake
+set(CMAKE_MSVC_RUNTIME_LIBRARY "MultiThreaded$<$<CONFIG:Debug>:Debug>")
+```
+
+See [CMAKE_MSVC_RUNTIME_LIBRARY](https://cmake.org/cmake/help/latest/variable/CMAKE_MSVC_RUNTIME_LIBRARY.html) for details.

vcpkg-example/main.cc

@@ -0,0 +1,8 @@
+#include <pulsar/Client.h>
+using namespace pulsar;
+
+int main(int argc, char *argv[]) {
+    Client client{"pulsar://localhost:6650"};
+    client.close();
+    return 0;
+}

vcpkg-example/vcpkg.json

@@ -0,0 +1,11 @@
+{
+  "name": "vcpkg-pulsar-demo",
+  "version-string": "0.1.0",
+  "builtin-baseline": "38d1652f152d36481f2f4e8a85c0f1e14f3769f7",
+  "dependencies": [
+    {
+      "name": "pulsar-client-cpp",
+      "version>=": "3.4.2#1"
+    }
+  ]
+}