[CMAKE] Add support for CMake component deprecation and update the policy

.github/workflows/cmake_install.yml

@@ -29,6 +29,8 @@ jobs:
       - name: Build dependencies with vcpkg submodule
         run: |
           ./ci/setup_windows_ci_environment.ps1
+      - name: Run Install Functions Tests
+        run: ./ci/do_ci.ps1 cmake.install_functions.test
       - name: Run Tests
         run: ./ci/do_ci.ps1 cmake.install.test
       - name: Run DLL Tests
@@ -51,6 +53,8 @@ jobs:
       - name: Build dependencies with vcpkg submodule
         run: |
           ./ci/setup_windows_ci_environment.ps1
+      - name: Run Install Functions Tests
+        run: ./ci/do_ci.ps1 cmake.install_functions.test
       - name: Run Tests
         run: ./ci/do_ci.ps1 cmake.install.test
 
@@ -78,6 +82,8 @@ jobs:
         sudo -E apt-get update
         sudo -E apt-get install -y libabsl-dev libcurl4-openssl-dev zlib1g-dev nlohmann-json3-dev libprotobuf-dev libgrpc++-dev protobuf-compiler protobuf-compiler-grpc
         sudo -E ./ci/install_thirdparty.sh --install-dir /usr/local --tags-file third_party_release --packages "googletest;benchmark"
+    - name: Run Install Functions Tests
+      run: ./ci/do_ci.sh cmake.install_functions.test
     - name: Run Tests (static libs)
       env:
         BUILD_SHARED_LIBS: 'OFF'
@@ -108,6 +114,8 @@ jobs:
     - name: Install Dependencies
       run: |
         sudo -E ./ci/install_thirdparty.sh --install-dir /usr/local --tags-file install/cmake/third_party_latest
+    - name: Run Install Functions Tests
+      run: ./ci/do_ci.sh cmake.install_functions.test
     - name: Run Tests (static libs)
       env:
         BUILD_SHARED_LIBS: 'OFF'
@@ -138,6 +146,8 @@ jobs:
     - name: Install Dependencies
       run: |
         sudo -E ./ci/install_thirdparty.sh --install-dir /usr/local --tags-file install/cmake/third_party_stable
+    - name: Run Install Functions Tests
+      run: ./ci/do_ci.sh cmake.install_functions.test
     - name: Run Tests (static libs)
       env:
         BUILD_SHARED_LIBS: 'OFF'
@@ -172,6 +182,8 @@ jobs:
     - name: Install Dependencies
       run: |
         sudo -E ./ci/install_thirdparty.sh --install-dir /usr/local --tags-file install/cmake/third_party_minimum
+    - name: Run Install Functions Tests
+      run: ./ci/do_ci.sh cmake.install_functions.test
     - name: Run Tests (static libs)
       env:
           BUILD_SHARED_LIBS: 'OFF'
@@ -209,6 +221,8 @@ jobs:
         run: |
           conan install install/conan/conanfile_stable.txt --build=missing -of /home/runner/conan -s build_type=${BUILD_TYPE} -s compiler.cppstd=${CXX_STANDARD}
           conan cache clean --source --build
+      - name: Run Install Functions Tests
+        run: ./ci/do_ci.sh cmake.install_functions.test
       - name: Run Tests (static libs)
         env:
           BUILD_SHARED_LIBS: 'OFF'
@@ -248,6 +262,8 @@ jobs:
         run: |
           conan install install/conan/conanfile_latest.txt --build=missing -of /home/runner/conan -s build_type=${BUILD_TYPE} -s compiler.cppstd=${CXX_STANDARD}
           conan cache clean --source --build
+      - name: Run Install Functions Tests
+        run: ./ci/do_ci.sh cmake.install_functions.test
       - name: Run Tests (static libs)
         env:
           BUILD_SHARED_LIBS: 'OFF'
@@ -288,6 +304,8 @@ jobs:
       run: |
         conan install install/conan/conanfile_stable.txt --build=missing -of /Users/runner/conan -s build_type=${BUILD_TYPE} -s compiler.cppstd=${CXX_STANDARD}
         conan cache clean --source --build
+    - name: Run Install Functions Tests
+      run: ./ci/do_ci.sh cmake.install_functions.test
     - name: Run Tests (static libs)
       env:
         BUILD_SHARED_LIBS: 'OFF'
@@ -320,6 +338,8 @@ jobs:
         brew install grpc
         brew install nlohmann-json
         brew install prometheus-cpp
+    - name: Run Install Functions Tests
+      run: ./ci/do_ci.sh cmake.install_functions.test
     - name: Run Tests (static libs)
       env:
         BUILD_SHARED_LIBS: 'OFF'

ci/do_ci.ps1

@@ -472,6 +472,33 @@ switch ($action) {
 
     exit 0
   }
+  "cmake.install_functions.test" {
+    Remove-Item -Recurse -Force "$BUILD_DIR\*"
+    Remove-Item -Recurse -Force "$INSTALL_TEST_DIR\*"
+    cd "$BUILD_DIR"
+    mkdir "$BUILD_DIR\install_functions_test"
+    cd "$BUILD_DIR\install_functions_test"
+    $INSTALL_FUNCTIONS_CMAKE_OPTIONS = @(
+      "-DVCPKG_TARGET_TRIPLET=x64-windows",
+      "-DCMAKE_TOOLCHAIN_FILE=$VCPKG_DIR/scripts/buildsystems/vcpkg.cmake"
+    )
+    $CMAKE_OPTIONS_STRING = $INSTALL_FUNCTIONS_CMAKE_OPTIONS -join " "
+    cmake "-DCMAKE_PREFIX_PATH=$INSTALL_TEST_DIR" `
+      "-DINSTALL_TEST_CMAKE_OPTIONS=$CMAKE_OPTIONS_STRING" `
+      "-DINSTALL_TEST_DIR=$INSTALL_TEST_DIR" `
+      "-DOPENTELEMETRY_SOURCE_DIR=$SRC_DIR" `
+      -S "$SRC_DIR\install\test\cmake\install_functions_test"
+    $exit = $LASTEXITCODE
+    if ($exit -ne 0) {
+      exit $exit
+    }
+    ctest -C Debug --output-on-failure
+    $exit = $LASTEXITCODE
+    if ($exit -ne 0) {
+      exit $exit
+    }
+    exit 0
+  }
   "cmake.dll.install.test" {
     cd "$BUILD_DIR"
     Remove-Item -Recurse -Force "$BUILD_DIR\*"

ci/do_ci.sh

@@ -457,6 +457,19 @@ elif [[ "$1" == "cmake.do_not_install.test" ]]; then
   cmake --build . "${CMAKE_BUILD_ARGS[@]}"
   ctest --output-on-failure
   exit 0
+elif [[ "$1" == "cmake.install_functions.test" ]]; then
+  cd "${BUILD_DIR}"
+  rm -rf *
+  rm -rf ${INSTALL_TEST_DIR}/*
+  export LD_LIBRARY_PATH="${INSTALL_TEST_DIR}/lib:$LD_LIBRARY_PATH"
+  mkdir -p "${BUILD_DIR}/install_functions_test"
+  cd "${BUILD_DIR}/install_functions_test"
+  cmake "-DCMAKE_PREFIX_PATH=${INSTALL_TEST_DIR}" \
+        "-DINSTALL_TEST_DIR=${INSTALL_TEST_DIR}" \
+        "-DOPENTELEMETRY_SOURCE_DIR=${SRC_DIR}" \
+        -S "${SRC_DIR}/install/test/cmake/install_functions_test"
+  ctest --output-on-failure
+  exit 0
 elif [[ "$1" == "cmake.install.test" ]]; then
   if [[ -n "${BUILD_SHARED_LIBS}" && "${BUILD_SHARED_LIBS}" == "ON" ]]; then
     CMAKE_OPTIONS+=("-DBUILD_SHARED_LIBS=ON")

cmake/find-package-support-functions.cmake

@@ -4,6 +4,46 @@
 include("${CMAKE_CURRENT_LIST_DIR}/component-definitions.cmake")
 include("${CMAKE_CURRENT_LIST_DIR}/thirdparty-dependency-definitions.cmake")
 
+#-------------------------------------------------------------------------
+# Function to resolve deprecated component names to their aliases.
+# Components without an alias are removed from the list
+#-------------------------------------------------------------------------
+function(resolve_deprecated_components requested_components_inout)
+  set(_result ${${requested_components_inout}})
+  foreach(_COMPONENT IN LISTS ${requested_components_inout})
+    if(_COMPONENT IN_LIST OTEL_DEPRECATED_COMPONENTS_LIST)
+      set(_replacement_var "COMPONENT_${_COMPONENT}_REPLACEMENT")
+      if(DEFINED ${_replacement_var})
+        message(DEPRECATION "opentelemetry-cpp: component `${_COMPONENT}` is deprecated, use `${${_replacement_var}}` instead.")
+        list(REMOVE_ITEM _result ${_COMPONENT})
+        list(APPEND _result ${${_replacement_var}})
+      else()
+        message(DEPRECATION "opentelemetry-cpp: component `${_COMPONENT}` is deprecated with no replacement.")
+        list(REMOVE_ITEM _result ${_COMPONENT})
+      endif()
+    endif()
+  endforeach()
+  list(REMOVE_DUPLICATES _result)
+  set(${requested_components_inout} "${_result}" PARENT_SCOPE)
+endfunction()
+
+#-------------------------------------------------------------------------
+# Function to set the <package>_<component>_FOUND variable for requested
+# deprecated component names that have a replacement component.
+#-------------------------------------------------------------------------
+function(set_deprecated_components_found requested_components_in)
+  foreach(_COMPONENT IN LISTS ${requested_components_in})
+    if(_COMPONENT IN_LIST OTEL_DEPRECATED_COMPONENTS_LIST)
+      set(_replacement_var "COMPONENT_${_COMPONENT}_REPLACEMENT")
+      if(DEFINED ${_replacement_var}
+         AND ${CMAKE_FIND_PACKAGE_NAME}_${${_replacement_var}}_FOUND)
+        set(${CMAKE_FIND_PACKAGE_NAME}_${_COMPONENT}_FOUND TRUE
+          CACHE BOOL "whether ${CMAKE_FIND_PACKAGE_NAME} deprecated component ${_COMPONENT} is found (via replacement ${${_replacement_var}})" FORCE)
+      endif()
+    endif()
+  endforeach()
+endfunction()
+
 #-------------------------------------------------------------------------
 # Function to get installed components.
 #-------------------------------------------------------------------------
@@ -33,7 +73,6 @@ function(get_dependent_components component_in dependent_components_out)
   set(${dependent_components_out} ${result} PARENT_SCOPE)
 endfunction()
 
-
 #-------------------------------------------------------------------------
 # Function to get requested components.
 #-------------------------------------------------------------------------
@@ -44,13 +83,15 @@ function(get_requested_components installed_components_in requested_components_o
     message(DEBUG "get_requested_components: No components explicitly requested. Importing all installed components including: ${result}")
     set(${requested_components_out} ${result} PARENT_SCOPE)
   else()
-    message(DEBUG "get_requested_components: Components requested: ${opentelemetry-cpp_FIND_COMPONENTS}")
-    foreach(_COMPONENT IN LISTS opentelemetry-cpp_FIND_COMPONENTS)
-        if(NOT ${_COMPONENT} IN_LIST OTEL_BUILT_COMPONENTS_LIST)
+    set(REQUESTED_COMPONENTS ${opentelemetry-cpp_FIND_COMPONENTS})
+    message(DEBUG "get_requested_components: Components requested: ${REQUESTED_COMPONENTS}")
+    resolve_deprecated_components(REQUESTED_COMPONENTS)
+    foreach(_COMPONENT IN LISTS REQUESTED_COMPONENTS)
+        if(NOT _COMPONENT IN_LIST OTEL_BUILT_COMPONENTS_LIST)
             message(ERROR " get_requested_components: Component `${_COMPONENT}` is not a built component of the opentelemetry-cpp package. Built components include: ${OTEL_BUILT_COMPONENTS_LIST}")
             return()
         endif()
-        if(NOT ${_COMPONENT} IN_LIST ${installed_components_in})
+        if(NOT _COMPONENT IN_LIST ${installed_components_in})
             message(ERROR " get_requested_components: Component `${_COMPONENT}` is supported by opentelemetry-cpp but not installed. Installed components include: ${${installed_components_in}}")
             return()
         endif()
@@ -69,7 +110,7 @@ endfunction()
 #-------------------------------------------------------------------------
 function(get_component_targets component_in targets_out)
   set(result "")
-  if(NOT ${component_in} IN_LIST OTEL_BUILT_COMPONENTS_LIST)
+  if(NOT component_in IN_LIST OTEL_BUILT_COMPONENTS_LIST)
       message(ERROR " get_component_targets: Component `${component_in}` component is not a built component of the opentelemetry-cpp package.")
   else()
     set(targets_var "COMPONENT_${component_in}_TARGETS")
@@ -116,7 +157,7 @@ endfunction()
 #-------------------------------------------------------------------------
 function (is_dependency_required dependency_in components_in is_required_out)
   foreach(_component IN LISTS ${components_in})
-    if(${dependency_in} IN_LIST COMPONENT_${_component}_THIRDPARTY_DEPENDS)
+    if(dependency_in IN_LIST COMPONENT_${_component}_THIRDPARTY_DEPENDS)
       set(${is_required_out} TRUE PARENT_SCOPE)
       return()
     endif()

cmake/otel-install-functions.cmake

@@ -6,6 +6,38 @@ include("${PROJECT_SOURCE_DIR}/cmake/thirdparty-dependency-config.cmake")
 # INTERNAL FUNCTIONS - do not call directly. Use the otel_* "Main" functions
 ########################################################################
 
+#-----------------------------------------------------------------------
+# _otel_check_component_name:
+#   1. Checks if the component name is valid and not already registered or deprecated.
+#   2. Checks if any of the deprecated names conflict with existing components or deprecated names.
+#
+#-----------------------------------------------------------------------
+function(_otel_check_component_name _COMPONENT_NAME _DEPRECATED_NAMES)
+  get_property(_COMPONENTS DIRECTORY ${PROJECT_SOURCE_DIR} PROPERTY OTEL_COMPONENTS_LIST)
+  get_property(_DEPRECATED_COMPONENTS DIRECTORY ${PROJECT_SOURCE_DIR} PROPERTY OTEL_DEPRECATED_COMPONENTS_LIST)
+
+  # Check if the component name is already registered or deprecated
+  if(_COMPONENT_NAME IN_LIST _COMPONENTS)
+    message(FATAL_ERROR
+      "_otel_check_component_name: COMPONENT ${_COMPONENT_NAME} has already been created")
+  elseif(_COMPONENT_NAME IN_LIST _DEPRECATED_COMPONENTS)
+    message(FATAL_ERROR
+      "_otel_check_component_name: COMPONENT ${_COMPONENT_NAME} is already registered as a deprecated name")
+  endif()
+
+  # Check if any of the deprecated names conflict with existing components or deprecated names
+  foreach(_DEPRECATED_NAME IN LISTS _DEPRECATED_NAMES)
+    if(_DEPRECATED_NAME STREQUAL _COMPONENT_NAME OR _DEPRECATED_NAME IN_LIST _COMPONENTS)
+      message(FATAL_ERROR
+        "_otel_check_component_name: DEPRECATED_NAME ${_DEPRECATED_NAME} conflicts with a component name")
+    endif()
+    if(_DEPRECATED_NAME IN_LIST _DEPRECATED_COMPONENTS)
+      message(FATAL_ERROR
+        "_otel_check_component_name: DEPRECATED_NAME ${_DEPRECATED_NAME} is already registered")
+    endif()
+  endforeach()
+endfunction()
+
 #-----------------------------------------------------------------------
 # _otel_set_component_properties:
 #   Sets the component properties used for install.
@@ -27,9 +59,6 @@ function(_otel_set_component_properties)
 
     # Add the component to the current components list
     get_property(existing_components DIRECTORY ${PROJECT_SOURCE_DIR} PROPERTY OTEL_COMPONENTS_LIST)
-    if(_PROPERTIES_COMPONENT IN_LIST existing_components)
-      message(FATAL_ERROR "  component ${_PROPERTIES_COMPONENT} has already been created.")
-    endif()
     list(APPEND existing_components "${_PROPERTIES_COMPONENT}")
     set_property(DIRECTORY ${PROJECT_SOURCE_DIR} PROPERTY OTEL_COMPONENTS_LIST "${existing_components}")
 
@@ -80,7 +109,7 @@ function(_otel_set_target_component_property _TARGET _COMPONENT)
   if(_TARGET_COMPONENT)
     message(FATAL_ERROR "  Target ${_TARGET} is already assigned to an opentelemetry-cpp COMPONENT ${_TARGET_COMPONENT}.")
   endif()
-  set_target_properties(${_TARGET} PROPERTIES INTERFACE_OTEL_COMPONENT_NAME ${_OTEL_ADD_COMP_COMPONENT})
+  set_target_properties(${_TARGET} PROPERTIES INTERFACE_OTEL_COMPONENT_NAME ${_COMPONENT})
 endfunction()
 
 #-----------------------------------------------------------------------
@@ -181,14 +210,14 @@ function(_otel_collect_component_dependencies _TARGET _COMPONENT OUT_COMPONENT_D
     endif()
 
     # Skip BUILD_INTERFACE targets
-    string(FIND "${_linked_target}" "$<BUILD_INTERFACE:" _is_build_interface)
+    string(FIND "${_linked_target}" "\$<BUILD_INTERFACE:" _is_build_interface)
     if(_is_build_interface GREATER -1)
       message(DEBUG "  - skipping BUILD_INTERFACE target: ${_linked_target}")
       continue()
     endif()
 
     # Handle targets in generator expressions
-    string(FIND "${_linked_target}" "$<" _is_generator_expression)
+    string(FIND "${_linked_target}" "\$<" _is_generator_expression)
     if(_is_generator_expression GREATER -1)
       # Find targets in generator expressions (there can be more than one per expression)
       string(REGEX MATCHALL "[A-Za-z0-9_\\-\\.]+(::[A-Za-z0-9_\\-\\.]+)*" _parsed_targets "${_linked_target}")
@@ -317,22 +346,27 @@ endfunction()
 
 #-----------------------------------------------------------------------
 # otel_add_component:
-#   Adds a component to the list of components to be installed. A component name and list of targest are required.
+#   Adds a component to the list of components to be installed. A component name and list of targets are required.
 #   Optional files can be added to the component by specifying a directory, destination and matching pattern.
 #   Each target is assigned to the component and its dependencies are identified based on the LINK_LIBRARIES property.
 #   An alias target is also created for each target in the form of PROJECT_NAME::TARGET_EXPORT_NAME.
+#   DEPRECATED_NAMES lists old component names that are redirected to this component with a deprecation warning.
+#
+#   TODO: add a DEPRECATED tag to support deprecated components that are still installed but will be removed in the future.
+#
 # Usage:
 #    otel_add_component(
 #      COMPONENT <component_name>
+#      [DEPRECATED_NAMES <old_name1> <old_name2> ...]
 #      TARGETS <target1> <target2> ...
-#      FILES_DIRECTORY <directory>
-#      FILES_DESTINATION <destination>
-#      FILES_MATCHING <matching>)
+#      [FILES_DIRECTORY <directory>
+#       FILES_DESTINATION <destination>
+#       FILES_MATCHING <matching>])
 #-----------------------------------------------------------------------
 function(otel_add_component)
-  set(optionArgs )
+  set(optionArgs DEPRECATED)
   set(oneValueArgs COMPONENT FILES_DIRECTORY FILES_DESTINATION)
-  set(multiValueArgs TARGETS FILES_MATCHING)
+  set(multiValueArgs TARGETS FILES_MATCHING DEPRECATED_NAMES)
   cmake_parse_arguments(_OTEL_ADD_COMP "${optionArgs}" "${oneValueArgs}" "${multiValueArgs}" "${ARGN}")
 
   if(NOT _OTEL_ADD_COMP_COMPONENT)
@@ -343,6 +377,8 @@ function(otel_add_component)
     message(FATAL_ERROR "otel_add_component: TARGETS is required")
   endif()
 
+  _otel_check_component_name(${_OTEL_ADD_COMP_COMPONENT} "${_OTEL_ADD_COMP_DEPRECATED_NAMES}")
+
   message(DEBUG "Add COMPONENT: ${_OTEL_ADD_COMP_COMPONENT}")
   set(_COMPONENT_DEPENDS "")
   set(_THIRDPARTY_DEPENDS "")
@@ -378,6 +414,16 @@ function(otel_add_component)
     FILES_MATCHING ${_OTEL_ADD_COMP_FILES_MATCHING}
     COMPONENT_DEPENDS ${_COMPONENT_DEPENDS}
     THIRDPARTY_DEPENDS ${_THIRDPARTY_DEPENDS})
+
+  foreach(_DEP_NAME IN LISTS _OTEL_ADD_COMP_DEPRECATED_NAMES)
+    get_property(_deprecated_components DIRECTORY ${PROJECT_SOURCE_DIR} PROPERTY OTEL_DEPRECATED_COMPONENTS_LIST)
+    list(APPEND _deprecated_components "${_DEP_NAME}")
+    set_property(DIRECTORY ${PROJECT_SOURCE_DIR} PROPERTY OTEL_DEPRECATED_COMPONENTS_LIST "${_deprecated_components}")
+    set_property(DIRECTORY ${PROJECT_SOURCE_DIR}
+      PROPERTY OTEL_COMPONENT_REPLACEMENT_${_DEP_NAME}
+      "${_OTEL_ADD_COMP_COMPONENT}")
+    message(DEBUG "  DEPRECATED_NAME: ${_DEP_NAME} -> ${_OTEL_ADD_COMP_COMPONENT}")
+  endforeach()
 endfunction()
 
 #-----------------------------------------------------------------------
@@ -420,6 +466,26 @@ function(otel_install_components)
     _otel_populate_component_thirdparty_depends_block(${_COMPONENT} OTEL_COMPONENTS_THIRDPARTY_DEPENDENCIES_BLOCK)
   endforeach()
 
+  get_property(OTEL_DEPRECATED_COMPONENTS_LIST DIRECTORY ${PROJECT_SOURCE_DIR} PROPERTY OTEL_DEPRECATED_COMPONENTS_LIST)
+
+  if(OTEL_DEPRECATED_COMPONENTS_LIST)
+     message(STATUS "Install DEPRECATED COMPONENT definitions:")
+  endif()
+
+  set(OTEL_COMPONENTS_REPLACEMENTS_BLOCK "")
+  foreach(_DEPRECATED_COMPONENT IN LISTS OTEL_DEPRECATED_COMPONENTS_LIST)
+    get_property(_REPLACEMENT_COMPONENT DIRECTORY ${PROJECT_SOURCE_DIR}
+      PROPERTY OTEL_COMPONENT_REPLACEMENT_${_DEPRECATED_COMPONENT})
+    message(STATUS "  Deprecated COMPONENT ${_DEPRECATED_COMPONENT}")
+    if(_REPLACEMENT_COMPONENT)
+      message(STATUS "    Replacement: ${_REPLACEMENT_COMPONENT}")
+      string(APPEND OTEL_COMPONENTS_REPLACEMENTS_BLOCK
+        "set(COMPONENT_${_DEPRECATED_COMPONENT}_REPLACEMENT ${_REPLACEMENT_COMPONENT})\n")
+    else()
+      message(FATAL_ERROR " no DEPRECATED_NAME on an installed component was found for ${_DEPRECATED_COMPONENT} -- deprecating components with no replacement is not currently supported.")
+    endif()
+  endforeach()
+
   configure_file(
     "${PROJECT_SOURCE_DIR}/cmake/templates/component-definitions.cmake.in"
     "${CMAKE_CURRENT_BINARY_DIR}/cmake/component-definitions.cmake"