Ask Your Question
4

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

asked 2013-06-22 00:10:18 -0500

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?

edit retag flag offensive close merge delete

2 Answers

Sort by ยป oldest newest most voted
1

answered 2013-06-22 05:41:17 -0500

joq gravatar image

updated 2014-08-13 11:38:10 -0500

Here is the currently recommended solution from the Catkin API docs.

It pretty closely matches your option 2. The pattern matching is not needed unless you have non-header files in your include/${PROJECT_NAME} tree, but avoiding any .svn subdirectories is needed with SVN repositories.

edit flag offensive delete link more

Comments

1

Link is broken, can you fix?

Carter12s gravatar imageCarter12s ( 2014-08-11 13:39:34 -0500 )edit
1
6

answered 2013-06-22 07:38:42 -0500

Dirk Thomas gravatar image

updated 2013-06-22 07:39:09 -0500

Regarding question 1.:

You should always install all your headers to the destination "include" - everything else would be not FHS compliant.

In your source space you could have your headers in (multiple) different locations. It is highly recommended to put them under "include" though.

You have to add them with include_directories() to make them usable for building targets in your own CMakeLists.txt file.

For other packages in the same workspace you "export" the same directories via catkin_package(INCLUDE_DIRS ...).

After being installed catkin expects that if you have listed any folder as INCLUDE_DIRS that you have installed all files to "include". Any package depending on your package should than use include_directories(${catkin_INCLUDE_DIRS}) or include_directories(${yourpkgname_INCLUDE_DIRS}) to add these include directories.

Generally you should always place your headers into a subfolder named after your package to avoid naming collisions. But the include_directories() always only point to "include" - not to "include/yourpkgname". That way you always import your code with the namespace prefix: #include <yourpkgname/myheader.h>.

edit flag offensive delete link more

Comments

Thanks, Dirk. I think I understand the semantics of catkin_package(INCLUDE_DIRS...) and include_directories() in devel-space. The only problem is that the documentation in http://ros.org/wiki/catkin/CMakeLists.txt seems to be wrong as the header files end up in the wrong directory. See joq's answer.

Johannes Meyer gravatar imageJohannes Meyer ( 2013-06-22 07:44:37 -0500 )edit

I have updated the Wiki page to reflect the correct install calls for headers as mentioned in your question as 2. and 3.: http://ros.org/wiki/catkin/CMakeLists.txt#Installing_header_files I would prefer the first as long as the subfolder equals the package name (which is highly recommended).

Dirk Thomas gravatar imageDirk Thomas ( 2013-06-22 19:32:34 -0500 )edit

Your Answer

Please start posting anonymously - your entry will be published after you log in or create a new account.

Add Answer

Question Tools

1 follower

Stats

Asked: 2013-06-22 00:10:18 -0500

Seen: 19,973 times

Last updated: Aug 13 '14