ROS catkin CMakeLists.txt

1. Overview

The file CMakeLists.txt is the input to the CMake build system for building software packages.

2. Overall Structure

CMakeLists.txt必须按照如下组织：
1. Required CMake Version (cmake_minimum_required)
2. Package Name (project())
3. Find other CMake/Catkin packages needed for build (find_package())
4. Enable Python module support (catkin_python_setup())
5. Message/Service/Action Generators (add_message_files(), add_service_files(), add_action_files())
6. Invoke message/service/action generation (generate_messages())
7. Specify package build info export (catkin_package())
8. Libraries/Executables to build (add_library()/add_executable()/target_link_libraries())
9. Tests to build (catkin_add_gtest())
10. Install rules (install())

3. CMake Version

需要的CMake最低版本

cmake_minimum_required(VERSION 2.8.3)

4. Package name

package name一般用于说明包的功能

project(robot_brain)

可以在CMakeLists.txt中任何地方使用这个变量${PROJECT_NAME}

5. Finding Dependent CMake Packages

查找其他cmake包用于编译我们自己的包，一般至少需要catkin

find_package(catkin REQUIRED)

如果只是用catkin包中的部分组件：

find_package(catkin REQUIRED COMPONENTS nodelet)

这里只是添加用于编译的包，不要添加运行时依赖包

5.1 find_package()

如果包成功找到了，一些CMake环境变量就会创建，比如：

• _FOUND - Set to true if the library is found, otherwise false
• _INCLUDE_DIRS or _INCLUDES - The include paths exported by the package
• _LIBRARIES or _LIBS - The libraries exported by the package
• _DEFINITIONS - ?

find_package(catkin REQUIRED COMPONENTS nodelet)

catkin_INCLUDE_DIRS contains the include paths not only for catkin but also for nodelet as well!

5.2 Boost

如果使用C++和Boost，比如需要 Boost threads：

find_package(Boost REQUIRED COMPONENTS thread)

6.catkin_package()

catkin_package() is a catkin-provided CMake macro.用于指导编译系统产生pkg-config and CMake文件。但是，这个函数必须在 add_library() or add_executable()之前调用，他有5个参数：
- INCLUDE_DIRS - The exported include paths (i.e. cflags) for the package
- LIBRARIES - The exported libraries from the project
- CATKIN_DEPENDS - Other catkin projects that this project depends on
- DEPENDS - Non-catkin CMake projects that this project depends on. For a better understanding, see this explanation.
- CFG_EXTRAS - Additional configuration options

例子

catkin_package(
   INCLUDE_DIRS include
   LIBRARIES ${PROJECT_NAME}
   CATKIN_DEPENDS roscpp nodelet
   DEPENDS eigen opencv)

7. Specifying Build Targets

Build targets can take many forms, but usually they represent one of two possibilties:

• Executable Target - programs we can run
• Library Target - libraries that can be used by executable targets at build and/or runtime

7.1 Target Naming

target name必须是唯一的，使用 set_target_properties()这个函数可改变一些target name的属性：

set_target_properties(rviz_image_view
                      PROPERTIES OUTPUT_NAME image_view
                      PREFIX "")

This will change the name of the target rviz_image_view to image_view in the build and install outputs.

7.2 自定义输出路径

例子：

set_target_properties(python_module_library
  PROPERTIES LIBRARY_OUTPUT_DIRECTORY ${CATKIN_DEVEL_PREFIX}/${CATKIN_PACKAGE_PYTHON_DESTINATION})

7.3 Include Paths and Library Paths

• Include Paths - Where can header files be found for the code (most common in C/C++) being built， 头文件路径
• Library Paths - Where are libraries located that executable target build against?， 库路径
• include_directories(, , …, )
• link_directories(, , …, )

例子：

include_directories(include ${Boost_INCLUDE_DIRS} ${catkin_INCLUDE_DIRS})

catkin中链接库使用：

link_directories(~/my_libs)

7.4 Executable Targets

指定可执行编译目标
例子：

add_executable(myProgram src/main.cpp src/some_file.cpp src/another_file.cpp)

7.5 Library Targets

指定要编译的库

add_library(${PROJECT_NAME} ${${PROJECT_NAME}_SRCS})

7.6 target_link_libraries

语法为：

target_link_libraries(, , , ... )

例子：

add_executable(foo src/foo.cpp)
add_library(moo src/moo.cpp)
target_link_libraries(foo moo)  -- This links foo against libmoo.so

8. Messages, Services, and Action Targets

Messages (.msg), services (.srv), and actions (.action) files in ROS require a special preprocessor build step before being built and used by ROS packages. The point of these macros is to generate programming language-specific files so that one can utilize messages, services, and actions in their programming language of choice. The build system will generate bindings using all available generators (e.g. gencpp, genpy, genlisp, etc).

主要有三个宏：
- add_message_files
- add_service_files
- add_action_files
之后紧接着调用：
generate_messages()

8.1 Important Prerequisites/Constraints

必须在catkin_package()之前

find_package(catkin REQUIRED COMPONENTS ...)
add_message_files(...)
add_service_files(...)
add_action_files(...)
generate_messages(...)
catkin_package(...)
...

catkin_package() macro must have a CATKIN_DEPENDS dependency on message_runtime

catkin_package(
 ...
 CATKIN_DEPENDS message_runtime ...
 ...)

find_package() for the package message_generation, either alone or as a component of catkin:

 find_package(catkin REQUIRED COMPONENTS message_generation)

Your package.xml file must contain a build dependency on message_generation and a runtime dependency on message_runtime. This is not necessary if the dependencies are pulled in transitively from other packages.

If you have a target which (even transitively) depends on some other target that needs messages/services/actions to be built, you need to add an explicit dependency on target catkin_EXPORTED_TARGETS, so that they are built in the correct order. This case applies almost always, unless your package really doesn’t use any part of ROS. Unfortunately, this dependency cannot be automatically propagated

add_dependencies(some_target ${catkin_EXPORTED_TARGETS})

some_target is the name of the target set by add_executable()

If you have a package which builds messages and/or services as well as executables that use these, you need to create an explicit dependency on the automatically-generated message target so that they are built in the correct order

add_dependencies(some_target ${${PROJECT_NAME}_EXPORTED_TARGETS})

some_target is the name of the target set by add_executable()

If you your package satisfies both of the above conditions, you need to add both dependencies

add_dependencies(some_target ${${PROJECT_NAME}_EXPORTED_TARGETS} ${catkin_EXPORTED_TARGETS})

8.1 例子

在“msg”文件夹中有两个文件：”MyMessage1.msg” and “MyMessage2.msg”， 他们依赖的是 std_msgs and sensor_msgs，在“srv”文件中有一个文件：”MyService.srv”。定义一个可执行文件使用这个消息和服务，可执行文件does_not_use_local_messages_program使用的ROS提供的message和service，CMakeLists.txt如下：

 # Get the information about this package's buildtime dependencies
  find_package(catkin REQUIRED
    COMPONENTS message_generation std_msgs sensor_msgs)

  # Declare the message files to be built
  add_message_files(FILES
    MyMessage1.msg
    MyMessage2.msg
  )

  # Declare the service files to be built
  add_service_files(FILES
    MyService.srv
  )

  # Actually generate the language-specific message and service files
  generate_messages(DEPENDENCIES std_msgs sensor_msgs)

  # Declare that this catkin package's runtime dependencies
  catkin_package(
   CATKIN_DEPENDS message_runtime std_msgs sensor_msgs
  )

  # define executable using MyMessage1 etc.
  add_executable(message_program src/main.cpp)
  add_dependencies(message_program ${${PROJECT_NAME}_EXPORTED_TARGETS} ${catkin_EXPORTED_TARGETS})

  # define executable not using any messages/services provided by this package
  add_executable(does_not_use_local_messages_program src/main.cpp)
  add_dependencies(does_not_use_local_messages_program ${catkin_EXPORTED_TARGETS})

If, additionally, you want to build actionlib actions, and have an action specification file called “MyAction.action” in the “action” directory, you must add actionlib_msgs to the list of components which are find_packaged with catkin and add the following call before the call to generate_messages(…):

add_action_files(FILES
  MyAction.action
)

Furthermore the package must have a build dependency on actionlib_msgs.

参考文献：

http://wiki.ros.org/catkin/CMakeLists.txt