📝 adding how to use ament_generate_version_header #6115
Description
Issue Type
- 🐛 Bug / Problem
- ✏️ Typo / Grammar
- 📖 Outdated Content
- 🚀 Enhancement
Generated by Generative AI
No response
Distribution
No response
Description
see ros2/examples#432 (comment)
C and C++ language based project such as rclcpp, rcl, and rmw have API version files that are automatically generated by pacakge.xml and https://github.com/ament/ament_cmake/blob/rolling/ament_cmake_gen_version_h/cmake/ament_generate_version_header.cmake
Version macros like RCLCPP_VERSION, RCL_VERSION, and RMW_VERSION are auto-generated and useful for API negotiation in user applications, but they're not documented anywhere in the ROS 2 documentation (https://github.com/ros2/ros2_documentation).
Even though ROS 2 guarantees ABI compatibility within the same distribution, new interfaces and features can be backported. This means that within a single distro, there could be different API versions available. In such cases, these version check macros are really helpful for ensuring user application integrity by allowing developers to check if a new feature is available before using it.
Affected Pages/Sections
https://docs.ros.org/en/rolling/How-To-Guides/Ament-CMake-Documentation.html
Screenshots or Examples (if applicable)
No response
Suggested Fix
Add documentation in the Ament CMake Documentation explaining the auto-generated version macros (RCLCPP_VERSION, RCL_VERSION, RMW_VERSION, etc.) and how to use them for API negotiation. This would help developers write portable code that can check for specific API versions, which is especially useful when new features are backported within the same distribution.
Additional Context
No response