[INSTALL] Unify cmake install functions and dynamically set component dependencies (open-telemetry#3368)

Author: dbarker

.github/workflows/ci.yml

@@ -57,6 +57,28 @@ jobs:
       run: |
         ./ci/do_ci.sh cmake.test
 
+  cmake_fetch_content_test:
+    name: CMake FetchContent usage with opentelemetry-cpp
+    runs-on: ubuntu-24.04
+    env:
+      CXX_STANDARD: '17'
+    steps:
+    - name: Harden the runner (Audit all outbound calls)
+      uses: step-security/harden-runner@0634a2670c59f64b4a01f0f96f84700a4088b9f0 # v2.12.0
+      with:
+        egress-policy: audit
+    - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      with:
+        submodules: 'recursive'
+    - name: setup
+      run: |
+        sudo -E ./ci/setup_ci_environment.sh
+        sudo -E ./ci/setup_cmake.sh
+        sudo -E ./ci/setup_googletest.sh
+    - name: run fetch content cmake test
+      run: |
+        ./ci/do_ci.sh cmake.fetch_content.test
+
   cmake_gcc_maintainer_sync_test:
     name: CMake gcc 14 (maintainer mode, sync)
     runs-on: ubuntu-24.04

CHANGELOG.md

@@ -42,6 +42,10 @@ Increment the:
 * [SDK] Aggregate identical metrics instruments and detect duplicates
   [#3358](https://github.com/open-telemetry/opentelemetry-cpp/pull/3358)
 
+* [INSTALL] Add CMake components to the opentelemetry-cpp package
+  [#3320](https://github.com/open-telemetry/opentelemetry-cpp/pull/3220)
+  [#3368](https://github.com/open-telemetry/opentelemetry-cpp/pull/3368)
+
 ## [1.20 2025-04-01]
 
 * [BUILD] Update opentelemetry-proto version

CMakeLists.txt

@@ -841,6 +841,8 @@ if(prometheus-cpp_FOUND)
 endif()
 message(STATUS "---------------------------------------------")
 
+include("${PROJECT_SOURCE_DIR}/cmake/otel-install-functions.cmake")
+
 include(CMakePackageConfigHelpers)
 
 if(DEFINED OPENTELEMETRY_BUILD_DLL)
@@ -914,39 +916,14 @@ include(cmake/opentelemetry-build-external-component.cmake)
 include(cmake/patch-imported-config.cmake)
 
 if(OPENTELEMETRY_INSTALL)
-  # Export cmake config and support find_packages(opentelemetry-cpp CONFIG)
-  # Write config file for find_packages(opentelemetry-cpp CONFIG)
-  set(INCLUDE_INSTALL_DIR "${CMAKE_INSTALL_INCLUDEDIR}")
-  configure_package_config_file(
-    "${CMAKE_CURRENT_LIST_DIR}/cmake/templates/opentelemetry-cpp-config.cmake.in"
-    "${CMAKE_CURRENT_BINARY_DIR}/cmake/${PROJECT_NAME}/${PROJECT_NAME}-config.cmake"
-    INSTALL_DESTINATION "${CMAKE_INSTALL_LIBDIR}/cmake/${PROJECT_NAME}"
-    PATH_VARS OPENTELEMETRY_ABI_VERSION_NO OPENTELEMETRY_VERSION PROJECT_NAME
-              INCLUDE_INSTALL_DIR CMAKE_INSTALL_LIBDIR)
-
-  # Write version file for find_packages(opentelemetry-cpp CONFIG)
-  write_basic_package_version_file(
-    "${CMAKE_CURRENT_BINARY_DIR}/cmake/${PROJECT_NAME}/${PROJECT_NAME}-config-version.cmake"
-    VERSION ${OPENTELEMETRY_VERSION}
-    COMPATIBILITY ExactVersion)
-
-  # Write the "BUILT_WITH_<dependency" flags for use in the
-  # opentelemetry-cpp-config.cmake
-  configure_file(
-    "${CMAKE_CURRENT_SOURCE_DIR}/cmake/templates/thirdparty-built-with-flags.cmake.in"
-    "${CMAKE_CURRENT_BINARY_DIR}/thirdparty-built-with-flags.cmake"
-    @ONLY)
-
-  install(
-    FILES
-      "${CMAKE_CURRENT_BINARY_DIR}/cmake/${PROJECT_NAME}/${PROJECT_NAME}-config.cmake"
-      "${CMAKE_CURRENT_BINARY_DIR}/cmake/${PROJECT_NAME}/${PROJECT_NAME}-config-version.cmake"
-      "${CMAKE_CURRENT_BINARY_DIR}/thirdparty-built-with-flags.cmake"
-      "${CMAKE_CURRENT_LIST_DIR}/cmake/component-definitions.cmake"
-      "${CMAKE_CURRENT_LIST_DIR}/cmake/thirdparty-dependency-definitions.cmake"
-      "${CMAKE_CURRENT_LIST_DIR}/cmake/find-package-support-functions.cmake"
-    DESTINATION "${CMAKE_INSTALL_LIBDIR}/cmake/${PROJECT_NAME}"
-    COMPONENT cmake-config)
+  # Install the cmake config and version files
+  otel_install_cmake_config()
+
+  # Install the components and associated files
+  otel_install_components()
+
+  # Install the thirdparty dependency definition file
+  otel_install_thirdparty_definitions()
 
   if(BUILD_PACKAGE)
     include(cmake/package.cmake)

INSTALL.md

@@ -151,21 +151,55 @@ If building and installing Protobuf and gRPC manually with cmake the
    $
    ```
 
-### Incorporating into an existing CMake Project
+### Incorporating into an external CMake Project
 
-To use the library from a CMake project, you can locate it directly with
- `find_package` and use the imported targets from generated package
- configurations. As of now, this will import targets for both API and SDK. In
- future, there may be separate packages for API and SDK which can be installed
- and imported separately according to need.
+There are two approaches to incoporate `opentelemetry-cpp` into
+ an external CMake project:
 
-```cmake
-# CMakeLists.txt
-find_package(opentelemetry-cpp CONFIG REQUIRED)
-...
-target_include_directories(foo PRIVATE ${OPENTELEMETRY_CPP_INCLUDE_DIRS})
-target_link_libraries(foo PRIVATE ${OPENTELEMETRY_CPP_LIBRARIES})
-```
+1. Build and install `opentelemetry-cpp` then use `find_package`
+ to import its targets
+
+   ```cmake
+   # Find all installed components and link all imported targets
+   find_package(opentelemetry-cpp CONFIG REQUIRED)
+   ...
+   target_include_directories(foo PRIVATE ${OPENTELEMETRY_CPP_INCLUDE_DIRS})
+   target_link_libraries(foo PRIVATE ${OPENTELEMETRY_CPP_LIBRARIES})
+   ```
+
+   ```cmake
+   # Find a specific component and link its imported target(s)
+   find_package(opentelemetry-cpp CONFIG REQUIRED COMPONENTS api)
+   ...
+   target_link_libraries(foo PRIVATE opentelemetry-cpp::api)
+   ```
+
+2. Use CMake's [FetchContent](https://cmake.org/cmake/help/latest/module/FetchContent.html)
+ module to fetch and build `opentelemetry-cpp` then make its targets available
+
+   ```cmake
+   # Fetch from an existing clone and build
+   include(FetchContent)
+   FetchContent_Declare(opentelemetry-cpp SOURCE_DIR "<path/to/opentelemetry-cpp>")
+   FetchContent_MakeAvailable(opentelemetry-cpp)
+   ...
+   target_link_libraries(foo PRIVATE opentelemetry-cpp::api)
+   ```
+
+   ```cmake
+   # Clone and build opentelemetry-cpp from a git tag
+   include(FetchContent)
+   FetchContent_Declare(
+   opentelemetry-cpp
+   GIT_REPOSITORY https://github.com/open-telemetry/opentelemetry-cpp.git
+   GIT_TAG        v1.20.0)
+   FetchContent_MakeAvailable(opentelemetry-cpp)
+   ...
+   target_link_libraries(foo PRIVATE opentelemetry-cpp::api)
+   ```
+
+In both cases the project's built or imported CMake targets will be
+ available in the `opentelemetry-cpp` namespace (ie: `opentelemetry-cpp::api`)
 
 #### Using opentelemetry-cpp package components
 

api/CMakeLists.txt

@@ -9,28 +9,20 @@ target_include_directories(
 
 set_target_properties(opentelemetry_api PROPERTIES EXPORT_NAME api)
 
-if(OPENTELEMETRY_INSTALL)
-  install(
-    TARGETS opentelemetry_api
-    EXPORT "${PROJECT_NAME}-api-target"
-    RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}
-    LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
-    ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR} COMPONENT api)
-
-  install(
-    DIRECTORY include/opentelemetry
-    DESTINATION include
-    COMPONENT api
-    FILES_MATCHING
-    PATTERN "*.h")
-
-  install(
-    EXPORT "${PROJECT_NAME}-api-target"
-    FILE "${PROJECT_NAME}-api-target.cmake"
-    NAMESPACE "${PROJECT_NAME}::"
-    DESTINATION "${CMAKE_INSTALL_LIBDIR}/cmake/${PROJECT_NAME}"
-    COMPONENT api)
+otel_add_component(
+  COMPONENT
+  api
+  TARGETS
+  opentelemetry_api
+  FILES_DIRECTORY
+  "include/opentelemetry"
+  FILES_DESTINATION
+  "include"
+  FILES_MATCHING
+  PATTERN
+  "*.h")
 
+if(OPENTELEMETRY_INSTALL)
   unset(TARGET_DEPS)
 endif()
 

ci/do_ci.sh

@@ -514,6 +514,45 @@ elif [[ "$1" == "cmake.install.test" ]]; then
          -S "${SRC_DIR}/install/test/cmake"
   ctest --output-on-failure
   exit 0
+elif [[ "$1" == "cmake.fetch_content.test" ]]; then
+  if [[ -n "${BUILD_SHARED_LIBS}" && "${BUILD_SHARED_LIBS}" == "ON" ]]; then
+    CMAKE_OPTIONS+=("-DBUILD_SHARED_LIBS=ON")
+    echo "BUILD_SHARED_LIBS is set to: ON"
+  else
+    CMAKE_OPTIONS+=("-DBUILD_SHARED_LIBS=OFF")
+    echo "BUILD_SHARED_LIBS is set to: OFF"
+  fi
+  CMAKE_OPTIONS+=("-DCMAKE_POSITION_INDEPENDENT_CODE=ON")
+
+  cd "${BUILD_DIR}"
+  rm -rf *
+  cmake "${CMAKE_OPTIONS[@]}"  \
+        -DCMAKE_INSTALL_PREFIX=${INSTALL_TEST_DIR} \
+        -DWITH_ABI_VERSION_1=OFF \
+        -DWITH_ABI_VERSION_2=ON \
+        -DWITH_METRICS_EXEMPLAR_PREVIEW=ON \
+        -DWITH_ASYNC_EXPORT_PREVIEW=ON \
+        -DWITH_THREAD_INSTRUMENTATION_PREVIEW=ON \
+        -DWITH_OTLP_GRPC_SSL_MTLS_PREVIEW=ON \
+        -DWITH_OTLP_RETRY_PREVIEW=ON \
+        -DWITH_OTLP_GRPC=OFF \
+        -DWITH_OTLP_HTTP=OFF \
+        -DWITH_OTLP_FILE=OFF \
+        -DWITH_OTLP_HTTP_COMPRESSION=OFF \
+        -DWITH_HTTP_CLIENT_CURL=OFF \
+        -DWITH_PROMETHEUS=OFF \
+        -DWITH_ZIPKIN=OFF \
+        -DWITH_ELASTICSEARCH=OFF \
+        -DWITH_EXAMPLES=OFF \
+        -DWITH_EXAMPLES_HTTP=OFF \
+        -DBUILD_W3CTRACECONTEXT_TEST=OFF \
+        -DOPENTELEMETRY_INSTALL=OFF \
+        -DOPENTELEMETRY_CPP_SRC_DIR="${SRC_DIR}" \
+        "${SRC_DIR}/install/test/cmake/fetch_content_test"
+  make -j $(nproc)
+  make test
+  exit 0
+
 elif [[ "$1" == "cmake.test_example_plugin" ]]; then
   # Build the plugin
   cd "${BUILD_DIR}"