Document best practice for building executables with `ament_cmake`

[nnmm]

The ament_cmake user documentation only has a section for building a library, but not for building a binary. Some parts are not straightforward to adapt to that use case, for instance:

• Is there still a use case for ament_export_targets? Since it has an option HAS_LIBRARY_TARGET I think it also does something useful when there's no library target, but I'm not sure what – the motivating example for ament_export_targets, i.e. to be able to do target_link_libraries(client_lib my_lib::my_lib) applies only to libraries.
• The text that goes over the install command, and the command itself, sounds like could be used as-is for binaries. That is not the case, since ros2 run doesn't find executables in bin, only in lib/${PROJECT_NAME}.¹

If someone answers the first question and points out additional things to mention, I can try writing that section.

¹ In fact, the install call in the docs has destinations lib and bin, shouldn't that have ${PROJECT_NAME} as well?

[clalancette]

Just so we are on the same page; you are talking about the documentation at https://index.ros.org/doc/ros2/Tutorials/Ament-CMake-Documentation/ , correct?

To answer your other questions:

* Is there still a use case for `ament_export_targets`? Since it has an option `HAS_LIBRARY_TARGET` I think it also does something useful when there's no library target, but I'm not sure what – the motivating example for `ament_export_targets`, i.e. to be able to do `target_link_libraries(client_lib my_lib::my_lib)` applies only to libraries.

I don't think there is a use for ament_export_targets when building a binary; as you said, it really only applies for things you may want to discover in downstream packages, like libraries.

* The text that goes over the `install` command, and the command itself, sounds like could be used as-is for binaries. That is not the case, since `ros2 run` doesn't find executables in `bin`, only in `lib/${PROJECT_NAME}`.¹

Your understanding is correct, the binaries need to be installed in lib/${PROJECT_NAME} for ros2 run to find them (like in https://github.com/ros2/examples/blob/6f79d5ca6461d5a356aba23aa97a7604662b68ac/rclcpp/topics/minimal_publisher/CMakeLists.txt). So we should recommend they go to lib/${PROJECT_NAME} by default. As a side note, I'll point out that the user can decide to put the binaries wherever they want; it's just if they want it to be found by ros2 run that they have to put it in a specific place.

If someone answers the first question and points out additional things to mention, I can try writing that section.

Great, happy to review contributions to the docs!

[nnmm]

Yes, that's the one I'm talking about. Thanks for confirming!

[nnmm]

I meant to ask: That we want binaries to live in lib doesn't mean we want DLLs to live there too? I see that they're considered RUNTIME by CMake, but is there a reason why do they need to go to bin instead of lib?

[clalancette]

I meant to ask: That we want binaries to live in lib doesn't mean we want DLLs to live there too? I see that they're considered RUNTIME by CMake, but is there a reason why do they need to go to bin instead of lib?

Sorry, I don't think I understand the question. We typically put both the binaries and the libraries in lib currently. It is possible for packages to ignore this convention and install their binaries in bin, but then they can't be found by ros2 run.

[nnmm]

I was referring to this note in the doc:

Windows dlls are treated as runtime artifacts and installed into the RUNTIME DESTINATION folder. It is therefore advised to not leave out the RUNTIME install even when developing libraries on Unix based systems.

And the code sample in the guide has RUNTIME DESTINATION bin in it. So I'm just curious why you wouldn't simply put everything in lib/${PROJECT_NAME}.

[clalancette]

And the code sample in the guide has RUNTIME DESTINATION bin in it. So I'm just curious why you wouldn't simply put everything in lib/${PROJECT_NAME}.

I'm not sure. But it looks like throughout the ROS 2 codebase, we do use RUNTIME DESTINATION bin. It may just be one of those oddities of Windows.