rosidl_generate_interfaces - Undocumented DEPENDENCIES option

[RFRIEDM-Trimble]

Bug report

Required Info:

• Operating System:
  ALL
• Installation type:
  ALL
• Version or commit hash:
  dbb005a - Latest humble as of July 10, 2022
• DDS implementation:
  ALL

Steps to reproduce issue

1. Create a custom message following ROS2 tutorial like so:

# Obstacle.msg
geometry_msgs/Point32 polygon
float32 size_uncertainty
uint8 obstacle_class

3. Don't supply the undocumented DEPENDENCIES option in the call to rosidl_generate_interfaces
   CMakeLists.txt

set(msg_files
  "msg/Obstacle.msg"
  )
  
rosidl_generate_interfaces(${PROJECT_NAME}
  ${msg_files}
  ${srv_files}
)

4. Run the node

ros2 run obstacle_publisher obstacle_publisher
    /home/paul/code/eclipse_ws/ROS2/install/obstacle_publisher/lib/obstacle_publisher/obstacle_publisher: symbol lookup error: 
    /home/paul/code/eclipse_ws/ROS2/install/obstacle_msgs/lib/libobstacle_msgs__rosidl_typesupport_fastrtps_cpp.so: 
    undefined symbol: _ZN13geometry_msgs3msg24typesupport_fastrtps_cpp27max_serialized_size_Point32ERbm

Expected behavior

The documentation should reflect the expected usage of DEPENDENCIES, so a user of the function knows when it should be used.

Actual behavior

DEPENDENCIES is not documented.

References

The example was copied from this ROS Answers Post
The fix I found was noted here.

[sloretz]

Where would you like the argument documented? It's currently only documented in the CMake comment above the macro

rosidl/rosidl_cmake/cmake/rosidl_generate_interfaces.cmake

Lines 36 to 38 in 5181196

	# :param DEPENDENCIES: the packages from which message types are
	# being used
	# :type DEPENDENCIES: list of strings

[RFRIEDM-Trimble]

The tutorials do not use existing messages as seen here.
https://docs.ros.org/en/rolling/Tutorials/Beginner-Client-Libraries/Custom-ROS2-Interfaces.html#cmakelists-txt

However, the extra "Use an existing interface definition" does demonstrate using DEPENDENCIES
https://docs.ros.org/en/rolling/Tutorials/Beginner-Client-Libraries/Single-Package-Define-And-Use-Interface.html#extra-use-an-existing-interface-definition
Additionally, the migration guide also includes a note about it.
https://docs.ros.org/en/rolling/The-ROS2-Project/Contributing/Migration-Guide.html?highlight=rosidl_generate_interfaces#update-the-cmakelists-txt-to-use-ament-cmake

I think there could be an additional clarification on the Implementing Custom Interfaces Wiki to explain what the DEPENDENCIES keyword does rather than just giving the boilerplate to the same level that the migration guide explains it.

[clalancette]

Since ros2/ros2_documentation#2350 , we do have documentation there, so I'm going to close this out. Feel free to reopen if you think we need to do something more here.

[RFRIEDM-Trimble]

The references above work well with me. Thank you.