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.

[ros-discourse]

This issue has been mentioned on ROS Discourse. There might be relevant details there:

https://discourse.ros.org/t/ros-news-for-the-week-of-february-24th-2025/42296/1

[SuperGops7]

Hey team, can I take over resolving this issue?

[fujitatomoya]

@SuperGops7 of course and thanks for the contribution, i will assign this to you.

[quarkytale]

Some relevant text here too https://gazebosim.org/docs/latest/ros_gz_project_template_guide/#accessing-simulation-assets

[iBz-04]

hello team, can i also hop on with @SuperGops7 ? and work on it

[Ghadanur]

Hey team, Can I join in as well?

[kscottz]

@iBz-04 and @Ghadanur that's really at @SuperGops7's discretion. It may actually add more complexity than there needs to be for something like this.

There's more than enough work to go around:

• Restore Python tf2 Time tutorials
• Include ROS 2 Mirror Page