Proposal - Use GNUInstallDirs for CMake Installation

[Ryanf55]

Feature request

This is a proposal to adopt GNUInstallDirs in ROS 2 CMake and a minimum CMake 3.14 version in the core ROS libraries.

Advantages

GNUInstallDirs is intended to be a platform-portable to manage installation of libraries, includes, and executables. Since they are standard CMake variables, this allows packaging maintainers rather than library authors to be responsible for handling platform-specific installation needs. An example of one such need is explained here for colcon, which was a behavior changed in humble, documented in the humble changelog, missed in the ament documentation, and confusing for library authors like myself.

GNUInstallDirs gives more flexibility to package maintainers, without burdening library authors with having to remember ROS specific ways to install a ROS package that only affect packaging.

Risks

It would result in code churn in the following places

• ROS-maintained Core libraries
• Generated examples with ros2 pkg create
• ROS tutorials

There are hints it might not work out of the box on Windows and RHEL.

Current Behavior

This comes from colcon's documentation:

target_include_directories(some_library_in_foo INTERFACE
  "$<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>"
  "$<INSTALL_INTERFACE:include/${PROJECT_NAME}>")
install(DIRECTORY include/ DESTINATION include/${PROJECT_NAME})

And, then from rclcpp's install

install(
  TARGETS ${PROJECT_NAME} EXPORT ${PROJECT_NAME}
  ARCHIVE DESTINATION lib
  LIBRARY DESTINATION lib
  RUNTIME DESTINATION bin
)

Desired Behavior

target_include_directories(some_library_in_foo INTERFACE
  "$<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>")
include(GNUInstallDirs)
install(DIRECTORY include/ DESTINATION ${CMAKE_INSTALL_INCLUDEDIR})
install(
  TARGETS ${PROJECT_NAME} EXPORT ${PROJECT_NAME}
  # Nodes must be installed here for ROS 2 CLI to recognize them
  RUNTIME DESTINATION ${CMAKE_INSTALL_LIBDIR}
  INCLUDES DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}
)

Note how now that library authors do not have to care about colcon wanting the debian binary includes to show up in /opt/ros/humble/include/${PROJECT_NAME}/${PROJECT_NAME}, it's the responsibility of the packaging system (bloom) to deal with this by setting CMAKE_INSTALL_INCLUDEDIR to include/${PROJECT_NAME}.

Implementation considerations

There are notes of issues on rhel and Windows with GNUInstallDirs.

Also, if ROS users can use CMake 3.23, which will happen in J-turtle, then FILE_SETS are the preferred route according to Craig Scott's book Professional CMake, however GNUInstallDirs is still used then.

Proposed order of operations

1. Review/modify/accept the proposal
2. Generate a proof of concept that can be tested on humble distros, including windows and rhel.
   According to :
3. Update the core libraries
4. Then, update the docs after the core per @clalancette
5. Update ROS2 CLI
6. ROS discourse announcement for other ROS library authors and package maintainers?

Related

ros2/ros2_documentation#3805
ros2/ros2cli#845

[Ryanf55]

Tagging @mikepurvis since he also was looking into this for ROSIDL.

[Ryanf55]

Another tidbit - on Windows, the DLL's need to be put in bin:
ros2/ros2_documentation#3805 (review)