feat: preliminary find_package support

Author: cwaldren-ld

.github/actions/cmake-test/action.yml

@@ -12,7 +12,6 @@ inputs:
     description: 'Boost toolset'
     required: false
 
-
 runs:
   using: composite
   steps:
@@ -36,6 +35,15 @@ runs:
         # along in the same manner to those test projects via the command line.
         BOOST_ROOT: ${{ steps.install-boost.outputs.BOOST_ROOT }}
         OPENSSL_ROOT_DIR: ${{ steps.install-openssl.outputs.OPENSSL_ROOT_DIR }}
+        CMAKE_INSTALL_PREFIX: ../LAUNCHDARKLY_INSTALL
+    - name: Build the SDK
+      shell: bash
+      run: |
+        cmake --build build
+    - name: Install the SDK
+      shell: bash
+      run: |
+        cmake --install build
     - name: Run CMake Integration Tests
       shell: bash
       run: |

CMakeLists.txt

@@ -6,7 +6,7 @@ cmake_minimum_required(VERSION 3.19)
 include(CMakeDependentOption)
 
 project(
-        LaunchDarklyCPPSDKs
+        launchdarkly
         VERSION 0.1
         DESCRIPTION "LaunchDarkly C++ SDK Monorepo (Server/Client)"
         LANGUAGES CXX C
@@ -21,8 +21,6 @@ if (POLICY CMP0144)
     cmake_policy(SET CMP0144 NEW)
 endif ()
 
-include(GNUInstallDirs)
-
 option(BUILD_TESTING "Top-level switch for testing. Turn off to disable unit and contract tests." ON)
 
 option(LD_BUILD_SHARED_LIBS "Build the SDKs as shared libraries" OFF)
@@ -155,12 +153,20 @@ endif ()
 
 set(Boost_USE_MULTITHREADED ON)
 set(Boost_USE_STATIC_RUNTIME OFF)
+
+if (POLICY CMP0167)
+    # TODO: Update to use the Boost project's cmake config directly, since FindBoost was deprecated in
+    # cmake >= 3.30.
+    cmake_policy(SET CMP0167 OLD)
+endif ()
+
 find_package(Boost 1.81 REQUIRED COMPONENTS json url coroutine)
 message(STATUS "LaunchDarkly: using Boost v${Boost_VERSION}")
 
-include(${CMAKE_FILES}/certify.cmake)
+set(FOXY_BUILD_TESTING OFF)
 add_subdirectory(vendor/foxy)
 
+
 # Common, internal, and server-sent-events are built as "object" libraries.
 add_subdirectory(libs/common)
 add_subdirectory(libs/internal)
@@ -185,3 +191,36 @@ if (LD_BUILD_EXAMPLES)
     message(STATUS "LaunchDarkly: building examples")
     add_subdirectory(examples)
 endif ()
+
+
+# Support installation of a cmake package.
+include(CMakePackageConfigHelpers)
+include(GNUInstallDirs)
+
+write_basic_package_version_file(
+        "${CMAKE_CURRENT_BINARY_DIR}/launchdarklyConfigVersion.cmake"
+        COMPATIBILITY SameMajorVersion
+)
+
+install(FILES
+        "${CMAKE_CURRENT_SOURCE_DIR}/cmake/launchdarklyConfig.cmake"
+        "${CMAKE_CURRENT_BINARY_DIR}/launchdarklyConfigVersion.cmake"
+        DESTINATION "${CMAKE_INSTALL_DATADIR}/cmake/launchdarkly"
+)
+
+configure_file(
+        ${CMAKE_CURRENT_SOURCE_DIR}/cmake/launchdarkly.pc.in
+        ${CMAKE_CURRENT_BINARY_DIR}/launchdarkly.pc
+)
+
+install(
+        FILES ${CMAKE_CURRENT_BINARY_DIR}/launchdarkly.pc
+        DESTINATION ${CMAKE_INSTALL_LIBDIR}/pkgconfig
+)
+
+
+install(
+        EXPORT launchdarklyTargets
+        NAMESPACE launchdarkly::
+        DESTINATION "${CMAKE_INSTALL_DATADIR}/cmake/launchdarkly"
+)

README.md

@@ -49,7 +49,7 @@ GoogleTest is used for testing.
 
 For information on integrating an SDK package please refer to the SDK specific README.
 
-## CMake Usage
+## CMake Options
 
 Various CMake options are available to customize the client/server SDK builds.
 
@@ -66,30 +66,59 @@ Various CMake options are available to customize the client/server SDK builds.
 | `LD_DYNAMIC_LINK_OPENSSL`     | Whether OpenSSL is dynamically linked or not.                                                                                                                                                                                                                            | Off  (static link)                                     | N/A                                       |
 | `LD_BUILD_REDIS_SUPPORT`      | Whether the server-side Redis Source is built or not.                                                                                                                                                                                                                    | Off                                                    | N/A                                       |
 
-**Note:** _if building the SDKs as shared libraries, then unit tests won't be able to link correctly since the SDK's C++
-symbols aren't exposed. To run unit tests, build a static library._
-
 > [!WARNING]   
 > When building shared libraries C++ symbols are not exported, only the C API will be exported. This is because C++ does
-> not have a stable ABI.
+> not have a stable ABI. For this reason, the SDK's unit tests are not built in shared library mode.
+
+## Building the SDK from Source
 
-Basic usage example:
+To configure the SDK's CMake project:
 
 ```bash
-mkdir -p build && cd build
-cmake -G"Unix Makefiles" ..
+# Use 'make' as the build system.
+cmake -B build -S . -G"Unix Makefiles"
 ```
 
-Slightly more advanced example - build shared libraries, and don't build any of the testing components:
+To pass in config options defined in the table above, add them using `-D`:
 
 ```bash
-mkdir -p build  && cd build
-cmake -G"Unix Makefiles" -DLD_BUILD_SHARED_LIBS=On -DBUILD_TESTING=Off ..
+# Use 'make' as the build system, build shared libs, and disable testing.
+cmake -B build -S . -G"Unix Makefiles" \
+                    -DLD_BUILD_SHARED_LIBS=On \
+                    -DBUILD_TESTING=Off ..
 ```
 
 The example uses `make`, but you might instead use [Ninja](https://ninja-build.org/),
 MSVC, [etc.](https://cmake.org/cmake/help/latest/manual/cmake-generators.7.html)
 
+## Incorporating the SDK via `add_subdirectory`
+
+The SDK can be incorporated into an existing application using CMake via `add_subdirectory.`.
+
+```cmake
+# Set SDK build options, for example:
+set(LD_BUILD_SHARED_LIBS On)
+
+add_subdirectory(path-to-cpp-sdks-repo)
+target_link_libraries(your-app PRIVATE launchdarkly::client)
+# ... or launchdarkly::server
+````
+
+## Incorporating the SDK via `find_package`
+
+> [!WARNING]   
+> Preliminary support for `find_package` is available. The package configuration is subject to change, do not expect it
+> to be stable as long as this notice is present.
+
+If you've installed the SDK on the build system via `cmake --install`, you can consume it from
+the target application like so:
+
+```cmake
+find_package(launchdarkly REQUIRED)
+target_link_libraries(your-app PRIVATE launchdarkly::launchdarkly-cpp-client)
+# ... or launchdarkly::launchdarkly-cpp-server
+```
+
 ## LaunchDarkly overview
 
 [LaunchDarkly](https://www.launchdarkly.com) is a feature management platform that serves trillions of feature flags

cmake-tests/CMakeLists.txt

@@ -1,2 +1,3 @@
 include(declareProjectTest.cmake)
+add_subdirectory(test_find_package)
 add_subdirectory(test_add_subdirectory)

cmake-tests/README.md

@@ -62,3 +62,10 @@ Additionally, certain variables must be forwarded to each test project CMake con
 
 Checks that a project can include the SDK as a sub-project, via `add_subdirectory`.
 This would be a likely use-case when the repo is a submodule of another project.
+
+### cmake_projects/test_find_package
+
+Checks that a project can include the SDK via `find_package(ldserverapi)`.
+This would be a likely use-case if the SDK was installed on the system by the user.
+
+**NOTE:** Requires SDK to be installed.

cmake-tests/declareProjectTest.cmake

@@ -75,9 +75,10 @@ macro(declare_find_package_test name)
             NAME ${test_prefix}_configure
             COMMAND
             ${CMAKE_COMMAND}
-            # Since project/CMakeLists.txt uses find_package(), it needs to know where to find
-            # ldserverapiConfig.cmake. That can be found where the SDK is installed, which is CMAKE_INSTALL_PREFIX.
-            -DCMAKE_PREFIX_PATH=${CMAKE_INSTALL_PREFIX}
+            # The project under test is going to use find_package() to find the launchdarkly SDK. The package config
+            # is going to in turn find_package() for boost. So, we need to pass in the location of the SDK's package
+            # config file, as well as boost's.
+            "-DCMAKE_PREFIX_PATH=${CMAKE_INSTALL_PREFIX};${BOOST_ROOT}"
             ${CMAKE_CURRENT_SOURCE_DIR}/project
     )
 

cmake-tests/test_find_package/CMakeLists.txt

@@ -0,0 +1,3 @@
+# This test assumes that the SDK has been installed at CMAKE_INSTALL_PREFIX.
+declare_find_package_test(test_find_package)
+add_build_step(test_find_package)

cmake-tests/test_find_package/project/CMakeLists.txt

@@ -0,0 +1,12 @@
+cmake_minimum_required(VERSION 3.19)
+
+project(UseFindPackageTest)
+
+find_package(launchdarkly REQUIRED)
+
+add_executable(use_find_package_server main_server.cpp)
+target_link_libraries(use_find_package_server launchdarkly::launchdarkly-cpp-server)
+
+
+add_executable(use_find_package_client main_client.cpp)
+target_link_libraries(use_find_package_client launchdarkly::launchdarkly-cpp-client)

cmake-tests/test_find_package/project/main_client.cpp

@@ -0,0 +1,25 @@
+#include <launchdarkly/client_side/client.hpp>
+#include <launchdarkly/context_builder.hpp>
+
+#include <cstring>
+#include <iostream>
+
+using namespace launchdarkly;
+using namespace launchdarkly::client_side;
+
+int main() {
+    auto config = ConfigBuilder("sdk-key").Build();
+    if (!config) {
+        std::cout << "error: config is invalid: " << config.error() << '\n';
+        return 1;
+    }
+
+    auto context =
+      ContextBuilder().Kind("user", "example-user-key").Name("Sandy").Build();
+
+    auto client = Client(std::move(*config), std::move(context));
+
+    client.StartAsync();
+
+    std::cout << client.Initialized() << '\n';
+}

cmake-tests/test_find_package/project/main_server.cpp

@@ -0,0 +1,23 @@
+#include <launchdarkly/server_side/client.hpp>
+#include <launchdarkly/server_side/config/config_builder.hpp>
+
+#include <cstring>
+#include <iostream>
+
+using namespace launchdarkly;
+using namespace launchdarkly::server_side;
+
+int main() {
+    auto config = ConfigBuilder("sdk-key").Build();
+    if (!config) {
+        std::cout << "error: config is invalid: " << config.error() << '\n';
+        return 1;
+    }
+
+    auto client = Client(std::move(*config));
+
+    client.StartAsync();
+
+    std::cout << client.Initialized() << '\n';
+
+}