[INSTALL] add cmake components to the package

[dbarker]

Fixes #3218

Overview

This PR introduces CMake COMPONENTS to the opentelemetry-cpp package. Components are essentially named groups of CMake targets and can be passed to the find_package function to more selectively include targets and dependencies.

For example, with this PR the following will only include the opentelemetry-cpp::api header only target and search for no other dependencies that may be needed by other targets of the package.

# only find and include the api target
find_package(opentelemetry-cpp CONFIG REQUIRED COMPONENTS api)

Using components like this provides developers more control over what targets and dependencies CMake includes and should help reduce the scope of dependency issues a developer may encounter when building their instrumented CMake projects against different versions/configurations of the installed opentelemetry-cpp package.

Please see the updated INSTALL.md file of this PR for the proposed components to targets mapping.

Backwards compatibility is covered by including all components and finding all dependencies when the developer does not pass any components to find_package as in the case below.

# include all targets and find all dependencies of the package
find_package(opentelemetry-cpp CONFIG REQUIRED)

Changes

1. Breaks up the single opentelemetry-cpp-target.cmake file into target files per component by updating the CMake install commands that create export sets in the CMakeLists.txt files for each of the targets.
2. Updates the opentelemetry-cpp-config.cmake to include a complete list of all components and all targets. This file now reacts to the opentelemetry-cpp_FIND_COMPONENTS list set by find_package when a developer adds the COMPONENTS arguments.
3. Updates the INSTALL.md file with the proposed components to targets mapping and guidance on usage.
4. TODO - add ci tests on the installed packages/components/targets.

For significant contributions please make sure you have completed the following items:

• CHANGELOG.md updated for non-trivial changes
• Unit tests have been added
• Changes in public API reviewed

[netlify]

✅ Deploy Preview for opentelemetry-cpp-api-docs canceled.

Name	Link
🔨 Latest commit	d2d2608
🔍 Latest deploy log	https://app.netlify.com/sites/opentelemetry-cpp-api-docs/deploys/677ed42ceefbb500083523a1

[dbarker]

Posting this as draft and seeking feedback. Interested in thoughts/concerns on the general approach and the proposed component to target mapping.

If the proposed changes look reasonable, I'd be happy to add the ci tests to verify the changes.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 88.16%. Comparing base (d19eb32) to head (d2d2608).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #3220   +/-   ##
=======================================
  Coverage   88.16%   88.16%           
=======================================
  Files         198      198           
  Lines        6224     6224           
=======================================
  Hits         5487     5487           
  Misses        737      737           

[marcalff]

Hi @owent , could you take a look at this change ? Thanks.

[dbarker]

The EXPORT_NAME property is set for all other installed targets, so setting here for the zipkin target.

[dbarker]

This list has been renamed to _OPENTELEMETRY_CPP_TARGETS above and the following targets have been added:

• resources - Existing target of the sdk
• in_memory_metric_exporter - Existing target of exporters/memory
• zipkin_trace_exporter - New EXPORT_NAME for the existing opentelemetry_exporter_zipkin_trace target

[dbarker]

@owent This is still a draft but I'm interested in your feedback before I go too much further. Here is a brief summary of work remaining and some open questions.

Work remaining:

1. Add support for transitive component dependencies (ie: find_package(opentelemetry-cpp COMPONENTS sdk) must automatically include the api component).
2. Add the find_dependency call for nlohmann/json in the cmake.config file
3. Ensure all components requiring the http client, curl, and json find those dependencies in the cmake config file
4. Add install verification tests to CI
   • Check for backwards compatibility with current cmake guidance.
   • Check that the appropriate targets are present after calling find_package(... COMPONENTS ...) on each component

Some open questions:

1. Aside from ensuring behavior of the current cmake guidance remains the same, are there any other backwards compatibility concerns?
2. Does the proposed mapping of target names to components in the INSTALL.md make sense?
   • I had considered a 1:1 mapping for targets to components but decided to group them by dependency/function instead. This way the components are more closely associated with the cmake build options (ie: WITH_OTLP_GRPC=ON will create the exporters_otlp_grpc component).
3. Are the proposed tests sufficient and is it reasonable to append these to the existing ci tests similar to verify_packages.sh script?

[dbarker]

Will likely move the components list and targets list to separate cmake files that can be included here. This along with a file that defines the component to component dependencies and component to thirdparty package dependencies will be helpful in testing.

[dbarker]

This export of the target file to the current binary directory appears unused and I've removed it. The PR only installs the target files for the components in the install directory.