prepare 2.8.0 release

.circleci/config.yml

@@ -80,13 +80,14 @@ jobs:
           name: Build
           command: |
             mkdir build && cd build
-            cmake -D CMAKE_BUILD_TYPE=Release -D REDIS_STORE=ON ..
-            cmake --build .
+            cmake -D CMAKE_BUILD_TYPE=Release -D REDIS_STORE=ON -D ENABLE_CMAKE_PROJECT_TESTS=ON -D CMAKE_INSTALL_PREFIX=./INSTALL ..
+            cmake --build . --target install
       - run:
           name: Unit test
           command: |
             cd build
             GTEST_OUTPUT="xml:$(pwd)/../reports/" make test
+
       - store_test_results:
           path: reports
 
@@ -116,8 +117,8 @@ jobs:
             export CC=/usr/bin/clang-11
             export CXX=/usr/bin/clang++-11
             mkdir build && cd build
-            cmake -D CMAKE_BUILD_TYPE=Release -D REDIS_STORE=ON ..
-            cmake --build .
+            cmake -D CMAKE_BUILD_TYPE=Release -D REDIS_STORE=ON -D ENABLE_CMAKE_PROJECT_TESTS=ON -D CMAKE_INSTALL_PREFIX=./INSTALL ..
+            cmake --build . --target install
       - run:
           name: Unit test
           command: |
@@ -170,8 +171,8 @@ jobs:
           name: Build
           command: |
             mkdir build && cd build
-            cmake -D REDIS_STORE=ON ..
-            cmake --build .
+            cmake -D REDIS_STORE=ON -D ENABLE_CMAKE_PROJECT_TESTS=ON CMAKE_INSTALL_PREFIX=./INSTALL ..
+            cmake --build . --target install
       - run:
           name: Test
           command: |
@@ -202,8 +203,8 @@ jobs:
           name: Build
           command: |
             mkdir build && cd build
-            cmake -D REDIS_STORE=ON ..
-            cmake --build .
+            cmake -D REDIS_STORE=ON -D ENABLE_CMAKE_PROJECT_TESTS=ON -D CMAKE_INSTALL_PREFIX=./INSTALL ..
+            cmake --build . --target install
       - run:
           name: Test
           command: |

.ldrelease/build.ps1

@@ -74,6 +74,7 @@ function Build-Sdk {
     Write-Host
     ExecuteOrFail {
         cmake -G "Visual Studio 16 2019" -A x64 `
+            -D ENABLE_CMAKE_PROJECT_TESTS=ON `
             -D BUILD_TESTING=${BUILD_TESTING} `
             -D BUILD_SHARED_LIBS=${BUILD_SHARED} `
             -D SKIP_DATABASE_TESTS=ON `

.ldrelease/build.sh

@@ -72,7 +72,7 @@ cd ..
 
 mkdir -p build-redis-static && cd build-redis-static
 mkdir -p release
-cmake -D SKIP_BASE_INSTALL=ON  -D REDIS_STORE=ON -D BUILD_TESTING=OFF -D CMAKE_INSTALL_PREFIX=./release ..
+cmake -D SKIP_BASE_INSTALL=ON -D REDIS_STORE=ON -D BUILD_TESTING=OFF -D CMAKE_INSTALL_PREFIX=./release ..
 cmake --build .
 cmake --build . --target install
 cd ..

.ldrelease/test.ps1

@@ -9,5 +9,5 @@ SetupVSToolsEnv -architecture amd64
 
 cd build-static
 $env:GTEST_OUTPUT="xml:${PSScriptRoot}/../reports/"
-ExecuteOrFail { cmake --build . --target RUN_TESTS }
+ExecuteOrFail { cmake -E env CTEST_OUTPUT_ON_FAILURE=1 cmake --build . --target RUN_TESTS }
 cd ..

CMakeLists.txt

@@ -1,3 +1,4 @@
+# 3.11 is required for basic FetchContent support.
 cmake_minimum_required(VERSION 3.11)
 
 # The launchdarkly/api.h header contains the SDK's version.
@@ -11,25 +12,63 @@ if(NOT DEFINED CMAKE_MATCH_1)
 endif()
 
 project(ldserverapi
-        VERSION ${CMAKE_MATCH_1}
-        DESCRIPTION "LaunchDarkly C Server SDK"
+    VERSION ${CMAKE_MATCH_1}
+    DESCRIPTION "LaunchDarkly C Server SDK"
 )
 
 message(STATUS "LaunchDarkly C Server SDK ${PROJECT_VERSION}")
 
-include(FetchContent)
-
-include(CMakeFiles/uthash.cmake)
-include(CMakeFiles/hexify.cmake)
-include(CMakeFiles/semver.cmake)
-include(CMakeFiles/sha1.cmake)
-include(CMakeFiles/timestamp.cmake)
+# Contains various Find files, code coverage, 3rd party library FetchContent scripts,
+# and the project's Package Configuration script.
+set(CMAKE_FILES "${CMAKE_CURRENT_SOURCE_DIR}/cmake")
 
+# Download 3rd party libraries.
+include(FetchContent)
+include(${CMAKE_FILES}/uthash.cmake)
+include(${CMAKE_FILES}/hexify.cmake)
+include(${CMAKE_FILES}/semver.cmake)
+include(${CMAKE_FILES}/sha1.cmake)
+include(${CMAKE_FILES}/timestamp.cmake)
+
+# Provide user configurable options.
+include(CMakeDependentOption)
+option(BUILD_TESTING "Enable C++ unit tests." ON)
+option(BUILD_TEST_SERVICE "Build the contract test service. Requires C++" OFF)
+option(REDIS_STORE "Build optional redis store support" OFF)
+option(COVERAGE "Add support for generating coverage reports" OFF)
+option(SKIP_DATABASE_TESTS "Do not test external store integrations" OFF)
+option(SKIP_BASE_INSTALL "Do not install the base library on install" OFF)
 
-include(CTest)
+# Add an option for enabling the "CMake Project Tests" (see tests/cmake_projects README).
+# These tests require testing to be enabled (BUILD_TESTING), but aren't unit tests, so are disabled by default.
+cmake_dependent_option(ENABLE_CMAKE_PROJECT_TESTS
+        "Test integration of SDK into other CMake projects" OFF
+        "BUILD_TESTING" OFF
+)
 
+# Emit variables for informational/debugging purposes.
+message(STATUS "LaunchDarkly - BUILD_TESTING: ${BUILD_TESTING}")
+message(STATUS "LaunchDarkly - BUILD_TEST_SERVICE: ${BUILD_TEST_SERVICE}")
+message(STATUS "LaunchDarkly - BUILD_SHARED_LIBS: ${BUILD_SHARED_LIBS}")
+message(STATUS "LaunchDarkly - REDIS_STORE: ${REDIS_STORE}")
+message(STATUS "LaunchDarkly - COVERAGE: ${COVERAGE}")
+message(STATUS "LaunchDarkly - SKIP_DATABASE_TESTS: ${SKIP_DATABASE_TESTS}")
+message(STATUS "LaunchDarkly - SKIP_BASE_INSTALL: ${SKIP_BASE_INSTALL}")
+message(STATUS "LaunchDarkly - ENABLE_CMAKE_PROJECT_TESTS: ${ENABLE_CMAKE_PROJECT_TESTS}")
+
+# The SDK uses two system packages, CURL and PCRE.
+# Use the CMAKE_FILES directory to find these packages first - necessary because FindPCRE is provided
+# with the SDK (while FindCURL is provided by CMake itself.)
+list(APPEND CMAKE_MODULE_PATH "${CMAKE_FILES}")
+find_package(CURL REQUIRED)
+find_package(PCRE REQUIRED)
 
+set(CMAKE_THREAD_PREFER_PTHREAD ON)
+set(THREADS_PREFER_PTHREAD_FLAG ON)
+find_package(Threads REQUIRED)
 
+# Build the unit test binary, and add all of the unit tests.
+include(CTest)
 if(BUILD_TESTING)
     set(gtest_force_shared_crt ON CACHE BOOL "" FORCE)
     configure_file(external/googletest/CMakeLists.txt.in
@@ -44,29 +83,16 @@ if(BUILD_TESTING)
             ${CMAKE_BINARY_DIR}/googletest-build EXCLUDE_FROM_ALL)
 
     enable_testing()
+
+    # Adds unit tests, and if enabled, cmake project tests.
     add_subdirectory(tests)
 endif()
 
-
-option(REDIS_STORE "Build optional redis store support" OFF)
-option(COVERAGE "Add support for generating coverage reports" OFF)
-option(SKIP_DATABASE_TESTS "Do not test external store integrations" OFF)
-option(SKIP_BASE_INSTALL "Do not install the base library on install" OFF)
-
-list(APPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/CMakeFiles")
-
+# Enable code coverage.
 if (COVERAGE)
-    include(CMakeFiles/CodeCoverage.cmake)
+    include(${CMAKE_FILES}/CodeCoverage.cmake)
     append_coverage_compiler_flags()
     setup_target_for_coverage_gcovr_html(NAME coverage)
-endif (COVERAGE)
-
-
-find_package(CURL REQUIRED)
-find_package(PCRE REQUIRED)
-
-if(NOT DEFINED MSVC)
-    set(LD_LIBRARIES pthread m)
 endif()
 
 set(LD_INCLUDE_PATHS
@@ -77,14 +103,6 @@ set(LD_INCLUDE_PATHS
     ${PCRE_INCLUDE_DIR}
 )
 
-if(APPLE)
-    set(LD_INCLUDE_PATHS ${LD_INCLUDE_PATHS} "/usr/local/include")
-endif(APPLE)
-
-if (REDIS_STORE)
-    add_subdirectory(stores/redis)
-endif (REDIS_STORE)
-
 file(GLOB SOURCES "src/*" "src/integrations/*" "third-party/src/*" "c-sdk-common/src/*")
 
 if(NOT DEFINED MSVC)
@@ -93,10 +111,9 @@ if(NOT DEFINED MSVC)
     )
 endif()
 
-set(LD_LIBRARIES ${LD_LIBRARIES} ${CURL_LIBRARIES} ${PCRE_LIBRARIES})
-
-# ldserverapi target -----------------------------------------------------------
-
+# Define the main ldserverapi target.
+# The 3rd party libs are included as object archives, so that static library users can include one
+# artifact, rather than the ldserverapi + these dependencies individually.
 add_library(ldserverapi
     $<TARGET_OBJECTS:hexify>
     $<TARGET_OBJECTS:semver>
@@ -105,22 +122,45 @@ add_library(ldserverapi
     ${SOURCES}
 )
 
+if(REDIS_STORE)
+    add_subdirectory(stores/redis)
+endif()
+
+# Allow linking against the target ldserverapi::ldserverapi when using find_package, or when
+# using add_subdirectory.
+add_library(ldserverapi::ldserverapi ALIAS ldserverapi)
+
 target_link_libraries(ldserverapi
     PRIVATE
         uthash
         hexify
         semver
         sha1
         timestamp
-        ${LD_LIBRARIES}
+        Threads::Threads
+        ${CURL_LIBRARIES}
+        ${PCRE_LIBRARIES}
 )
 
+if(NOT WIN32 AND NOT APPLE)
+    # Required for fmod function definition, which is implemented in libm (the c math library.)
+    # This is part of the c standard library on macOS, and apparently not required on Windows.
+    target_link_libraries(ldserverapi PRIVATE m)
+endif()
+
 target_include_directories(ldserverapi
-    PUBLIC  "include"
-            "c-sdk-common/include"
-    PRIVATE ${LD_INCLUDE_PATHS}
+        PUBLIC
+            # During the build phase, the SDK requires headers from the shared c-sdk-common subtree and the
+            # normal include directory.
+            $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
+            $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/c-sdk-common/include>
+            # Installed headers should all be lumped into a single include directory.
+            $<INSTALL_INTERFACE:include>
+        PRIVATE
+            ${LD_INCLUDE_PATHS}
 )
 
+# Setup compiler definitions.
 target_compile_definitions(ldserverapi
     PRIVATE -D LAUNCHDARKLY_CONCURRENCY_ABORT
             -D LAUNCHDARKLY_USE_ASSERT
@@ -157,22 +197,90 @@ if(BUILD_SHARED_LIBS)
 endif(BUILD_SHARED_LIBS)
 
 if(NOT SKIP_BASE_INSTALL)
-    INSTALL(
-        TARGETS     ldserverapi
-        DESTINATION lib
+    include(GNUInstallDirs)
+    include(CMakePackageConfigHelpers)
+
+    # All of these variables are defined relative to the build tree.
+    # Generally, the scheme used here is that files created in the build tree will be copied over to the install tree.
+    # This makes it simpler to support the add_subdirectory/find_package workflows in a unified manner.
+    set(LDSERVERSDK_CMAKE_CONFIG_DIR  "${CMAKE_CURRENT_BINARY_DIR}")
+
+    # Path of the (to be created) cmake version configuration.
+    set(LDSERVERSDK_CMAKE_VERSION_CONFIG_FILE "${LDSERVERSDK_CMAKE_CONFIG_DIR}/${PROJECT_NAME}ConfigVersion.cmake")
+
+    # Path of the (to be copied/renamed) cmake package configuration.
+    # This file already exists in the project's cmake directory, but is copied here so the install steps are uniform.
+    set(LDSERVERSDK_CMAKE_PROJECT_CONFIG_FILE "${LDSERVERSDK_CMAKE_CONFIG_DIR}/${PROJECT_NAME}Config.cmake")
+
+    # Path of the (to be created) cmake targets configuration.
+    set(LDSERVERSDK_CMAKE_PROJECT_TARGETS_FILE "${LDSERVERSDK_CMAKE_CONFIG_DIR}/${PROJECT_NAME}Targets.cmake")
+
+    # Arbitrary name of the targets file, which serves to contain the ldserverapi target.
+    # This file allows other projects to import the target for convenient usage.
+    set(LDSERVERSDK_EXPORT_NAME "${PROJECT_NAME}-targets")
+
+    # Generate a version config for the SDK.
+    write_basic_package_version_file(${LDSERVERSDK_CMAKE_VERSION_CONFIG_FILE}
+            VERSION ${PACKAGE_VERSION}
+            COMPATIBILITY SameMajorVersion
+    )
+
+    # Copy over the cmake project config to the build tree. If this scheme is later changed to generate the config
+    # using a template, rather than including the source directly in the repo as is currently the case,
+    # the installation won't need to change.
+    configure_file(${CMAKE_FILES}/${PROJECT_NAME}Config.cmake
+           ${LDSERVERSDK_CMAKE_PROJECT_CONFIG_FILE}
+            COPYONLY
+    )
+
+    # Instead of directly installing the library to a destination, associate it to an "export".
+    # The name of the export is arbitrary; it just needs to be consistent.
+    install(
+        TARGETS ${PROJECT_NAME}
+        EXPORT ${LDSERVERSDK_EXPORT_NAME}
     )
 
-    INSTALL(
-        DIRECTORY              ${PROJECT_SOURCE_DIR}/include/
-        DESTINATION            include
+    # Take the export and generate a new CMake file containing the targets contained within.
+    # This lives in the build tree, and MUST NOT BE INSTALLED, since paths are relative to the build tree,
+    # not the install tree.
+    export(EXPORT ${LDSERVERSDK_EXPORT_NAME}
+            FILE ${LDSERVERSDK_CMAKE_PROJECT_TARGETS_FILE} # <-- build tree
+            NAMESPACE ldserverapi::
+    )
+
+    # Do the same as the above, but for the install tree. This file will take the name
+    # <export-name>.cmake. This results in two different export files - one for the build tree (above)
+    # and one for the install tree (below.)
+    install(EXPORT ${LDSERVERSDK_EXPORT_NAME}
+        DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/ldserverapi
+        NAMESPACE ldserverapi::
+        FILE ${PROJECT_NAME}Targets.cmake
+    )
+
+    # Install SDK include directory.
+    install(
+        DIRECTORY              include/
+        DESTINATION            ${CMAKE_INSTALL_INCLUDEDIR}
         FILES_MATCHING PATTERN "*.h*"
     )
 
-    INSTALL(
-        DIRECTORY              ${PROJECT_SOURCE_DIR}/c-sdk-common/include/
-        DESTINATION            include
+    # Install c-sdk-common include directory.
+    install(
+        DIRECTORY              c-sdk-common/include/
+        DESTINATION            ${CMAKE_INSTALL_INCLUDEDIR}
         FILES_MATCHING PATTERN "*.h*"
     )
+
+    # Install the custom FindPCRE module, the project config, and the version config, all to the
+    # install tree's cmake/ldserverapi directory.
+    install(
+        FILES
+            ${CMAKE_FILES}/FindPCRE.cmake
+            ${LDSERVERSDK_CMAKE_PROJECT_CONFIG_FILE}
+            ${LDSERVERSDK_CMAKE_VERSION_CONFIG_FILE}
+        DESTINATION
+            ${CMAKE_INSTALL_LIBDIR}/cmake/ldserverapi
+    )
 endif()
 
 # test targets ----------------------------------------------------------------