[ign ➡️ gz] Internal functions

[chapulina]

• Builds on top of [ign ➡️ gz] Internal parsed variables #245
• Part of CMake API from ign to gz gazebo-tooling/release-tools#719

Summary

Migrate functions that are internal to gz-cmake to use gz instead of ign. I considered private functions:

• Functions that have documentation saying that they're private
• Functions that are prefixed by _, even if their docs don't say they're private - I'm relying on convention here.
• A few other functions that I didn't see being used by other libraries. I updated the docs to mention they're private.

It is possible that downstream projects are relying on these functions and will be broken, but that's unlikely. I'd like to reduce our API surface by making as many functions private as possible. This way we can focus our tick-tock efforts into functions that we know are used by downstream projects.

Checklist

• Signed all commits for DCO
• Added tests
• 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.

🔸🔸🔸🔸🔸🔸🔸🔸🔸🔸🔸🔸🔸🔸🔸🔸🔸🔸🔸🔸🔸🔸🔸🔸🔸🔸🔸🔸🔸🔸🔸🔸🔸🔸🔸🔸🔸

[methylDragon]

I'm wondering if it'll make sense to also make function/macro-local variables explicitly private, both:

• because in the case of macros, they'll bubble up to the parent scope
• clarity when editing the function/macro body

:O

[chapulina]

make function/macro-local variables explicitly private

I tried to do that using the _ prefix, but that's just convention. Is there a way to enforce a private scope at the CMake level?

[methylDragon]

make function/macro-local variables explicitly private

I tried to do that using the _ prefix, but that's just convention. Is there a way to enforce a private scope at the CMake level?

Because CMake macros do inline text substitution, not really.. unless you define a function inside the macro (with the macro arg as part of the function name) and use that function. But at that point you might as well use a function 😬

Converting macros to functions naively can have follow on consequences though, because macro variables are parent scoped, but function variables are not, which, for this library at least, is probably a lot of work, and not too much of a priority imho. The _ convention is fine then 🤔

[chapulina]

The _ convention is fine then

I'll take this to mean that you're not requesting any changes from this PR, @methylDragon . Let me know if you find any issues with it.

[methylDragon]

The _ convention is fine then

I'll take this to mean that you're not requesting any changes from this PR, @methylDragon . Let me know if you find any issues with it.

Ah yes!

I think we're good to go? 🤞

Edit: The entire stack up to gazebo7 has built successfully with this version of CMake (: