Add support for adding cmake extras to packages

[mjcarroll]

🎉 New feature

Closes #331

Summary

This addresses #331 in a slightly different way. Since changing the CMAKE_MODULE_PATH could have strange effects when it comes to resolving cmake files and precedence, this tracks more closely to how ament_package allows packages to add cmake functionality.

This adds support for a CONFIG_EXTRAS argument to gz_configure_project. In here, users can add cmake files (or templates) that will be sourced by all dependent packages.

I have added a simple demonstration of how this is expected to work here: gazebosim/gz-utils#97

I will have a more detailed example with the message generation workflow later.

Checklist

• Signed all commits for DCO
• Added tests
• Added example and/or tutorial
• Updated documentation (as needed)
• Updated migration guide (as needed)
• Consider updating Python bindings (if the library has them)
• codecheck passed (See contributing)
• All tests passed (See test coverage)
• While waiting for a review on your PR, please help review another open pull request to support the maintainers

Note to maintainers: Remember to use Squash-Merge and edit the commit message to match the pull request summary while retaining Signed-off-by messages.

[azeey]

The approach seems good to me. The only downside I see is that doing find_package(gz-cmake) will implicitly include all the cmake modules configured through CONFIG_EXTRA as opposed to each library using include to only include the modules they need. Since most libraries won't be using this feature, I don't think we'd need to worry too much about function/macro name clashes. We should probably have a naming convention though.

[mjcarroll]

The only downside I see is that doing find_package(gz-cmake) will implicitly include all the cmake modules configured through CONFIG_EXTRA as opposed to each library using include to only include the modules they need.

CONFIG_EXTRA files are scoped to the package that that they are defined in. gz-cmake itself shouldn't make use of this pattern because it installs and includes everything unconditionally.

[azeey]

The only downside I see is that doing find_package(gz-cmake) will implicitly include all the cmake modules configured through CONFIG_EXTRA as opposed to each library using include to only include the modules they need.

CONFIG_EXTRA files are scoped to the package that that they are defined in. gz-cmake itself shouldn't make use of this pattern because it installs and includes everything unconditionally.

So for example, if gz-physics added a module using CONFIG_EXTRA and I wanted to use it from gz-chrono, the module would only be included when I do find_package(gz-physics)?

[mjcarroll]

So for example, if gz-physics added a module using CONFIG_EXTRA and I wanted to use it from gz-chrono, the module would only be included when I do find_package(gz-physics)?

This is correct. Any downstream users will see your module when they did find_package(gz_chrono) as well, since gz-physics would be a dependency, and the find would be recursive.

I would think that the contents of the config extra should be exporting functions/macros, rather than raw cmake code, which should also help with any namespace pollution.

[azeey]

Sounds good! Probably still wise to have a naming convention that would avoid name clashes. One idea is to use the name of the project as a prefix somewhat like FetchContent.

[mjcarroll]

Probably still wise to have a naming convention that would avoid name clashes

I think it's probably good to have an idea of one, but I wouldn't want to impose it programmatically in case we ever want to do anything interesting like overriding cmake builtins or overriding gz-cmake functions in downstream packages.