Which is the correct way to install header files in catkin packages?

edit

It is common practice to place header files in a subdirectory of the package's include folder which has the same name as the package. The package exposes theses header files via its catkin_package() macro for dependent packages as it can be found in many catkin examples:

catkin_package(
   INCLUDE_DIRS include
   ...
)

Other packages will include these headers using the `#include <package header.h="">` directive. On the other side, catkin documentation at [ros.org](http://ros.org/wiki/catkin/CMakeLists.txt#Optional_Step:_Specifying_Installable_Targets) proposes the following cmake code to install header files contained in a package: md5-f68e7b950c4dd0a0dcb70833293102ff With this command header files are installed to `${CATKIN_PACKAGE_INCLUDE_DESTINATION}/package/header.h` which resolves to `${CMAKE_INSTALL_PREFIX}/include/package/package/header.h`.

1. Is there a mechanism in the generated cmake/pkg-config files that add ${CMAKE_INSTALL_PREFIX}/include/package as an include directory if another package depends on my package, so that the #include <package/header.h> directive will continue to work in install space? As far as I can see, this is not the case and all packages installed in /opt/ros/groovy only expose /opt/ros/groovy/include as include directory and not /opt/ros/groovy/include/package.

2. Should the example at ros.org changed to

   install(DIRECTORY include/${PROJECT_NAME}/
    DESTINATION ${CATKIN_PACKAGE_INCLUDE_DESTINATION}
    FILES_MATCHING PATTERN "*.h" PATTERN "*.hpp"
   )
   

   ? This is also the cmake fragment in the install section of the CMakeLists.txt generated by catkin_create_pkg.

3. Header files could be installed to CATKIN_GLOBAL_INCLUDE_DESTINATION instead:

   install(DIRECTORY include/
      DESTINATION ${CATKIN_GLOBAL_INCLUDE_DESTINATION}
      FILES_MATCHING PATTERN ".h" PATTERN ".hpp"
   )
   

Which of the three above "solutions" is the correct/preferred way to install header files in catkin packages or did I miss something here?