feat: preliminary find_package support (#452)

This PR adds preliminary support for:
```cmake

find_package(launchdarkly REQUIRED)

target_link_libraries(app 
        PRIVATE 
        launchdarkly::{launchdarkly-cpp-server,launchdarkly-cpp-client}
)
```
It treats the C++ monorepo as the installable unit. In the very near
future, this will likely be refactored so that we have two packages. If
you want both on the same host, you'd need to install both (and there'd
be some redundancy.)

Currently there is only one version, `0.1.0`. This isn't updated by
release-please.

For these two reasons, I'm indicating that this is preliminary and
subject to change form.

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)
@@ -99,6 +97,14 @@ set(CMAKE_CXX_STANDARD 17)
 
 set(CMAKE_POSITION_INDEPENDENT_CODE ON)
 
+include(GNUInstallDirs)
+set(LD_TARGETS_EXPORT_NAME ${PROJECT_NAME}Targets)
+set(LD_CMAKE_CONFIG_DIR "${CMAKE_CURRENT_SOURCE_DIR}/cmake")
+set(LD_CONFIG_INSTALL_DIR "${CMAKE_INSTALL_DATADIR}/cmake/${PROJECT_NAME}")
+set(LD_CMAKE_PROJECT_CONFIG_FILE "${LD_CMAKE_CONFIG_DIR}/${PROJECT_NAME}Config.cmake")
+set(LD_CMAKE_VERSION_CONFIG_FILE "${CMAKE_CURRENT_BINARY_DIR}/${PROJECT_NAME}ConfigVersion.cmake")
+
+
 if (LD_BUILD_UNIT_TESTS)
     message(STATUS "LaunchDarkly: building unit tests")
     set(CMAKE_CXX_FLAGS_DEBUG "${CMAKE_CXX_FLAGS_DEBUG} -D_GLIBCXX_DEBUG")
@@ -155,12 +161,14 @@ endif ()
 
 set(Boost_USE_MULTITHREADED ON)
 set(Boost_USE_STATIC_RUNTIME OFF)
+
 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 +193,25 @@ if (LD_BUILD_EXAMPLES)
     message(STATUS "LaunchDarkly: building examples")
     add_subdirectory(examples)
 endif ()
+
+
+# Support installation of a cmake package.
+include(CMakePackageConfigHelpers)
+
+write_basic_package_version_file(
+        ${LD_CMAKE_VERSION_CONFIG_FILE}
+        COMPATIBILITY SameMajorVersion
+)
+
+install(FILES
+        ${LD_CMAKE_PROJECT_CONFIG_FILE}
+        ${LD_CMAKE_VERSION_CONFIG_FILE}
+        DESTINATION ${LD_CONFIG_INSTALL_DIR}
+)
+
+
+install(
+        EXPORT ${LD_TARGETS_EXPORT_NAME}
+        NAMESPACE ${PROJECT_NAME}::
+        DESTINATION ${LD_CONFIG_INSTALL_DIR}
+)

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';
+
+}