[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. 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	98cc8cf
🔍 Latest deploy log	https://app.netlify.com/sites/opentelemetry-cpp-api-docs/deploys/67ecd54189577400088ad867

[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 89.56%. Comparing base (ab81479) to head (98cc8cf).
Report is 1 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #3220   +/-   ##
=======================================
  Coverage   89.56%   89.56%           
=======================================
  Files         210      210           
  Lines        6502     6502           
=======================================
  Hits         5823     5823           
  Misses        679      679           

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[marcalff]

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

[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?

[marcalff]

Impressive work.

Before going into the details, I have a comment on the general file structure for new code.

For example, for file cmake/install/test/src/test_api.cc.

This is a unit test in C++, which should build and pass if it is compiled with the proper installed headers and linked with the proper libraries (none in this case).

These is nothing CMake-ish about it, the same code with opentelemetry-cpp installed by a plain Makefile or an rpm package should work just the same.

Can all the C++ code under cmake/install/xxx be moved to install/xxx instead ?

To clarify:

File cmake/install/test/projects/component_tests/api/CMakeLists.txt stays where it is,
the only change is where INSTALL_TEST_SRC_DIR points to.

[dbarker]

Impressive work.

Before going into the details, I have a comment on the general file structure for new code.

For example, for file cmake/install/test/src/test_api.cc.

This is a unit test in C++, which should build and pass if it is compiled with the proper installed headers and linked with the proper libraries (none in case).

These is nothing CMake-ish about it, the same code with opentelemetry-cpp installed by a plain Makefile or an rpm package should work just the same.

Can all the C++ code under cmake/install/xxx be moved to install/xxx instead ?

To clarify:

File cmake/install/test/projects/component_tests/api/CMakeLists.txt stays where it is, the only change is where INSTALL_TEST_SRC_DIR points to.

Thanks for the feedback @marcalff. I've moved the install tests to opentelemetry-cpp/install/test/. The install/test directory has the build system independent smoke test .cc files in the src directory and cmake specific tests in the test/cmake directory. Let me know if this is better.

[dbarker]

Once you are a member, and to become an approver, please file a PR similar to this one:

Thanks for the invite Marc! Happy to accept. I'll submit the PRs this week.

[dbarker]

The opentelemetry-cpp project has community provided package manager support based on cmake with vcpkg, conan, and homebew. In addition it is possible to build against packages installed by brew (macos 14) and apt (Ubuntu 24.04).

I've added examples of building against thirdparty dependencies from each package manager to a new cmake install github workflow. I don't think these jobs should all be merged to main with this PR, but added them to help in review. These new jobs don't test the community portfile, conanfile, or recipe - just building against the dependencies installed by those managers.

Some notes on the community supported package managers:

• vckpg opentelemetry-cpp
  • The portfile doesn't appear to change to the opentelemetry-cpp-cmake.config installed. Risk may be low
• Conan opentelemetry-cpp
  • The current community provided conanfile.py creates its own cmake.config file and relies on the single cmake target file, so it would not be compatible with changes from this PR.
  • After some initial research it seems there is a path to write a conan file that preserves the opentelemetry-cpp-cmake.config and component target files. This work remains and there is some risk that the conan file would need to implement all of the component handling logic if preserving those installed files isn't possible.
• HomeBrew opentelemetry-cpp
  • The current community provided recipe appears to use the installed cmake files as is. Risk may be low.

Generally building with vckpg and conan seem to be great options going forward to standardize packaging for users, development, and ci. I'd advocate we move towards replacing the bespoke package build scripts in ./ci with one or both of these. The conan build helped catch several issues that were hidden by the ci install scripts (the zipkin test curl link issue and grpc client header issue were caught with conan builds).

[marcalff]

Do not merge (now) tag: To merge after opentelemetry-cpp 1.20 is released

[marcalff]

Did an extra review pass for:

• changes implemented since last review
• installation instructions
• build summary in CMake
• merge with the abseil flag removal
• pin cmake version to 3.x instead of 4.0

All LGTM, now merging.