Document usage of ament_environment_hooks in ament cmake

[Ryanf55]

In Ament CMake, there is no documentation of the ament_environment_hooks function.

In gazebo, this is used to set environment variables up. There's two important files.
https://github.com/gazebosim/ros_gz_project_template/blob/55bea9ee564be6ac4ce76650abab3aa2ed18e0ee/ros_gz_example_gazebo/hooks/README.md?plain=1#L29

This is not only useful for gazebo, but for other purposes. For example, when applying fastdds XML profiles through environment variables, you can use the following:

my_pkg.dsv.in

set;RMW_IMPLEMENTATION;rmw_fastrtps_cpp
set;RMW_FASTRTPS_USE_QOS_FROM_XML;1
set;FASTRTPS_DEFAULT_PROFILES_FILE;my_dds_profile.xml

my_pkg.sh.in

export RMW_IMPLEMENTATION=rmw_fastrtps_cpp
export RMW_FASTRTPS_USE_QOS_FROM_XML=1
export FASTRTPS_DEFAULT_PROFILES_FILE="$COLCON_CURRENT_PREFIX/my_dds_profile.xml"

My team was struggling to understand the purpose of why we need to files to set up these variables, and it would have been easier to find the purpose of ament_environment_hooks if the documentation of this lived with the rest of ament cmake.

[christophebedard]

I agree that it would make sense to document this somewhere in https://docs.ros.org/en/rolling/How-To-Guides/Ament-CMake-Documentation.html. It could also mention ament_prepend_unique_value, although that's provided by ament_package.

PRs are welcome 😁

[kscottz]

Oooh, good catch @Ryanf55. This could save a lot of people a lot of time.

I'll see if I can't recruit a new contributor to take this on. The ROS GZ documentation gives a good high level overview.

I could almost see this landing in two spots, or at least landing as two sections that cross reference each other:

• First, the ament_cmake documentation itself with specific documentation of the feature.
• Second, a How-To guide with a title like, "How to Add Persistent Environment Variables to your ROS Workspace" or something like that to make it more obvious to the end-user.

I think it is non-obvious that this is a behavior that happens inside of ament_cmake. Naively, if I wanted this functionality, I would start grepping through setup.sh and start going down a rabbit hole.

[Ryanf55]

Makes sense. Yep, we can copy the docs with some RST magic and link them together.