diff --git a/README.md b/README.md index 03957ce0..f0c13f07 100644 --- a/README.md +++ b/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. diff --git a/vcpkg b/vcpkg index b051745c..97dd2672 160000 --- a/vcpkg +++ b/vcpkg @@ -1 +1 @@ -Subproject commit b051745c68faa6f65c493371d564c4eb8af34dad +Subproject commit 97dd26728e3856ed1ab62ee74ee3a391d9c81d19 diff --git a/vcpkg-example/CMakeLists.txt b/vcpkg-example/CMakeLists.txt new file mode 100644 index 00000000..40eff936 --- /dev/null +++ b/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$<$: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) diff --git a/vcpkg-example/README.md b/vcpkg-example/README.md new file mode 100644 index 00000000..87336644 --- /dev/null +++ b/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 a 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$<$:Debug>") +``` + +See [CMAKE_MSVC_RUNTIME_LIBRARY](https://cmake.org/cmake/help/latest/variable/CMAKE_MSVC_RUNTIME_LIBRARY.html) for details. diff --git a/vcpkg-example/main.cc b/vcpkg-example/main.cc new file mode 100644 index 00000000..f4784faa --- /dev/null +++ b/vcpkg-example/main.cc @@ -0,0 +1,8 @@ +#include +using namespace pulsar; + +int main(int argc, char *argv[]) { + Client client{"pulsar://localhost:6650"}; + client.close(); + return 0; +} diff --git a/vcpkg-example/vcpkg.json b/vcpkg-example/vcpkg.json new file mode 100644 index 00000000..e48c7217 --- /dev/null +++ b/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" + } + ] +}