Support customize vcpkg directory when INTEGRATE_VCPKG is ON (apache#417

)

### Motivation

Currently when INTEGRATE_VCPKG is ON, the CMAKE_TOOLCHAIN_FILE variable
is always a subdirectory of `${CMAKE_SOURCE_DIR}/vcpkg`. We can only
customize the vcpkg directory when INTEGRATE_VCPKG is OFF, while the
legacy CMake logic is incompatible with this way.

### Modifications

When INTEGRATE_VCPKG is ON, only set CMAKE_TOOLCHAIN_FILE if it's not
defined. The workflow and README are updated for it.

.github/workflows/ci-pr-validation.yaml

@@ -114,6 +114,11 @@ jobs:
           cmake . -DINTEGRATE_VCPKG=ON -DBUILD_TESTS=ON -DBUILD_PERF_TOOLS=ON
           cmake --build . -j8
 
+      - name: Verify custom vcpkg installation
+        run: |
+          mv vcpkg /tmp/
+          cmake -B build -DINTEGRATE_VCPKG=ON -DCMAKE_TOOLCHAIN_FILE="/tmp/vcpkg/scripts/buildsystems/vcpkg.cmake"
+
   cpp20-build:
     name: Build with the C++20 standard
     needs: formatting-check

CMakeLists.txt

@@ -24,7 +24,9 @@ option(USE_ASIO "Use Asio instead of Boost.Asio" OFF)
 option(INTEGRATE_VCPKG "Integrate with Vcpkg" OFF)
 if (INTEGRATE_VCPKG)
     set(USE_ASIO ON)
-    set(CMAKE_TOOLCHAIN_FILE "${CMAKE_SOURCE_DIR}/vcpkg/scripts/buildsystems/vcpkg.cmake")
+    if (NOT CMAKE_TOOLCHAIN_FILE)
+        set(CMAKE_TOOLCHAIN_FILE "${CMAKE_SOURCE_DIR}/vcpkg/scripts/buildsystems/vcpkg.cmake")
+    endif ()
 endif ()
 
 option(BUILD_TESTS "Build tests" ON)

README.md

@@ -47,6 +47,8 @@ Since it's integrated with vcpkg, see [vcpkg#README](https://github.com/microsof
 
 ### How to build from source
 
+The simplest way is to clone this project with the vcpkg submodule.
+
 ```bash
 git clone https://github.com/apache/pulsar-client-cpp.git
 cd pulsar-client-cpp
@@ -57,6 +59,17 @@ cmake --build build -j8
 
 The 1st step will download vcpkg and then install all dependencies according to the version description in [vcpkg.json](./vcpkg.json). The 2nd step will build the Pulsar C++ libraries under `./build/lib/`, where `./build` is the CMake build directory.
 
+> You can also add the CMAKE_TOOLCHAIN_FILE option if your system already have vcpkg installed.
+>
+> ```bash
+> git clone https://github.com/apache/pulsar-client-cpp.git
+> cd pulsar-client-cpp
+> # For example, you can install vcpkg in /tmp/vcpkg
+> cd /tmp && git clone https://github.com/microsoft/vcpkg.git && cd -
+> cmake -B build -DINTEGRATE_VCPKG=ON -DCMAKE_TOOLCHAIN_FILE="/tmp/vcpkg/scripts/buildsystems/vcpkg.cmake"
+> cmake --build build -j8
+> ```
+
 After the build, the hierarchy of the `build` directory will be:
 
 ```