ROS Resources: Documentation | Support | Discussion Forum | Index | Service Status | ros @ Robotics Stack Exchange
Ask Your Question

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

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

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:

   INCLUDE_DIRS include
Other packages will include these headers using the `#include <package header.h="">` directive. On the other side, catkin documentation at []( 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 changed to

    install(DIRECTORY include/${PROJECT_NAME}/

    ? 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/

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

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

joq gravatar image

updated 2022-08-28 12:06:34 -0600

lucasw gravatar image

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

install(DIRECTORY include/${PROJECT_NAME}/

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



Link is broken, can you fix?

Carter12s gravatar image Carter12s  ( 2014-08-11 13:39:34 -0600 )edit

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

Dirk Thomas gravatar image

updated 2020-02-26 15:08:26 -0600

lucasw gravatar image

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 then 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


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 seems to be wrong as the header files end up in the wrong directory. See joq's answer.

Johannes Meyer gravatar image Johannes Meyer  ( 2013-06-22 07:44:37 -0600 )edit

I have updated the Wiki page to reflect the correct install calls for headers as mentioned in your question as 2. and 3.: I would prefer the first as long as the subfolder equals the package name (which is highly recommended).

Dirk Thomas gravatar image Dirk Thomas  ( 2013-06-22 19:32:34 -0600 )edit

Question Tools

1 follower


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

Seen: 26,354 times

Last updated: Aug 28 '22