ROS下的CMakeList.txt编写

目录

一、 概述

CMake构建系统通过ROS包中的CMakeList.txt来构建软件包。互相依赖的包都包含一个或者多个CMakeList.txt来描述如何编译代码和如何安装。在catkin 项目中，CMakeList.txt 符合标准的vanilla CMakeList.txt 格式，但稍微有点不同。

二、 整体结构和命令一览

在编写CMakeLists.txt时必须遵循特定的格式，否则软件包将无法正确构建和编译。一个完整的ROS下CMakeList.txt由下面内容组成
1. 所需CMake版本（cmake_minimum_required）
2. 软件包名称（project（）)
3. 查找构建所需的其他CMake / Catkin软件包（find_package（））
4. 启用Python模块支持（catkin_python_setup（））
5. 消息/服务/动作生成器（add_message_files（），add_service_files（），add_action_files（））
6. 生成消息/服务/动作等自定义消息（generate_messages（））
7. 指定包的构建信息输出（catkin_package（））
8. 要建立的库/可执行文件（add_library（）/ add_executable（）/ target_link_libraries（））
9. 测试（catkin_add_gtest（））
10. 安装规则（install（））

三、 CMake版本

CMakeLists.txt文件必须以CMake的版本开头。下面表示的是Catkin需要2.8.3或更高的版本。

cmake_minimum_required(VERSION 2.8.3)

四、 软件包名称

继而需要指定CMake工程名，一般取作包名。例如我们的项目名叫做robot_brain

project(robot_brain)

而在CMake中，可以在CMake文本中使用变量${PROJECT_NAME}来引用项目名称。

五、 查找相关的CMake包

接下来我们要用find_package指令来指定在构建项目过程中依赖了哪些其他的包，在ROS中，catkin必备依赖,所以雷打不打地我们写上catkin REQUIRED：

find_package(catkin REQUIRED)

在此基础上，如果我们还需要依赖其他包（或者组件），我们就在 上述的包后面继续添加包（组件）名即可：

find_package(catkin REQUIRED COMPONENTS nodelet)

或者可以写成

find_package(catkin REQUIRED)
find_package(nodelet REQUIRED)

值得注意一点的是：这里添加的包用于构建包使用，而不是添加运行时依赖项。

你也可以做：

find_package(catkin REQUIRED)
find_package(nodelet REQUIRED)

如何写，看个人习惯吧，如果不考虑篇幅，其实我更喜欢把所有包（组件）列成一列，直观。在普通的CMakeLists.txt中是没有find_package()的，那么，catkin中的这个语句有啥作用呢？

5.1 那find_package()作何用？

如果CMake通过find_package找到一个包，则会自动生成有关包所在路径的CMake环境变量，环境变量描述了包中头文件的位置，源文件的位置，包所依赖的库以及这些库的路径。
这些变量名称以< PACKAGE NAME >_< PROPERTY >的形式出现：
- < NAME >_FOUND - 如果找到库，则设置为true，否则为false
- < NAME > _INCLUDE_DIRS或 _INCLUDES - 包导出的包含路径
- < NAME > _LIBRARIES或 _LIBS - 由包导出的库
- < NAME > _DEFINITIONS - ？
- …

5.2为啥Catkin包是组件形式？

实际上，Catkin的包并不是catkin的真正组成部分。而catkin采用CMake的组件功能，主要是为了节省打字时间。
将Catkin的包作为一种组件看待是很有好处的，当你找到包的时候，各种以catkin为前缀的添加到CMakeLists.txt中了。以前述nodelet包为例：

find_package（catkin REQUIRED COMPONENTS nodelet）

catkin执行到这个语句时，就会导出的nodelet的include路径，库等也添加到catkin前缀的变量中。例如，catkin_INCLUDE_DIRS不仅包含catkin的include路径，还包含了nodelet，这在后面会用到。
当然，我们可以只选择找nodelet的：

find_package（nodelet）

很可惜这样的做法会令nodelet路径，库等不会被添加到catkin变量中，从而生成了例如nodelet_INCLUDE_DIRS，nodelet_LIBRARIES这样的变量等。

5.3Boost库

如果使用C ++和Boost，则需要用find_package()来找Boost库，并指定Boost中的组件。 举个栗子，如果想使用Boost线程，就可以写成：

find_package（Boost REQUIRED COMPONENTS thread）

六、catkin_package()

catkin_package()是一个catkin提供的CMake宏，用于将catkin特定的信息信息输出到构建系统上，用于生成pkg配置文件以及CMake文件。

这个命令必须在add_library()或者add_executable()之前调用，该函数有5个可选参数：

• INCLUDE_DIRS - 导出包的include路径
• LIBRARIES - 导出项目中的库
• CATKIN_DEPENDS - 该项目依赖的其他catkin项目
• DEPENDS - 该项目所依赖的非catkin CMake项目。
• CFG_EXTRAS - 其他配置选项

举个栗子：

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

这表示包文件夹中的文件夹“include”是导出头文件的地方。 ${PROJECT_NAME}根据project中的内容生成，此处是rrobot_brain。“roscpp”+“nodelet”是用来构建/运行此程序包的catkin包，而“eigen”+“opencv”是用于构建/运行此程序包的非catkin包。

七、指定构建目标

构建目标可以有多种形式，但通常主要有以下两种：

• 执行文件目标 - 可以运行的程序
• 库目标 - 可在构建和/或运行时给可执行目标使用的库

7.1目标命名

值得重点关注的是，catkin中的构建目标的名称必须是唯一的，但是，但构建目标命名的唯一性只能在CMake内部进行。可以使用set_target_properties()函数将目标重命名为其他目标：
再举个栗子：

set_target_properties(rviz_image_view
                      PROPERTIES OUTPUT_NAME image_view
                      PREFIX "")

这时就将rviz_image_view的名称更改为image_view了。

7.2自定义输出目录

一般情况下，令输出目标目录保持默认就可以了，但有时遇到一些特定情况就得因地制宜。再再举个栗子，一个包含了Python bindings的库必须防止在不同的文件夹，才能够被导入Python中，因此可以通过下述方式进行：

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

7.3包含路径和库路径

在生成目标之前，请记得先写好包含路径和库路径，不然编译会失败。

• 包括路径 - 头文件
• 库路径 - 构建对象需要用到的库

include_directories（，，...，）
link_directories（，，...，）

7.3.1 include_directories()

include_directories()中的参数应该是调用find_package调用时生成的* _INCLUDE_DIRS变量。 如果使用catkin和Boost，那么include_directories()调用应该如下所示：

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

第一个参数“include”表示包中的include /目录也是路径的一部分。

7.3.2 link_directories（）

link_directories()函数可用于添加额外的库路径，但通常不推荐这样做，因为 所有catkin和CMake软件包在find_packaged时都会自动添加链接信息。 只需写target_link_libraries（）中就可以了。但真要写，就按照下面那样来写：

link_directories(~/my_libs)

7.4 可执行目标

要指定必须构建的可执行目标，我们必须使用add_executable（）CMake函数。

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

构建myProgram的目标可执行文件，3个源文件构建：src / main.cpp，src / some_file.cpp和src / another_file.cpp。

7.5 库目标

add_library() 用于指定要构建的库。

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

7.6 target_link_libraries()

target_link_libraries()来指定可执行目标链接的库。 通常在add_executable()调用之后完成。 如果找不到ros，则添加$ {catkin_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

请注意，在大多数情况中不需要使用link_directories（），因为find_package()自动拉入。

八、消息、服务和响应

　　消息（.msg），服务（.srv）和响应（.action）文件在ROS包构建和使用之前需要一个特殊的预处理器构建步骤。 这些宏的要点是生成编程语言特定的文件，以便可以利用其选择的编程语言中的消息，服务和动作。 构建系统将使用生成器（例如gencpp，genpy，genlisp等）生成绑定。

提供了三个宏来分别处理消息，服务和响应：

• add_message_files
• add_service_files
• add_action_files

而在之后必须在下面写下面宏，catkin时候会在devel的include文件夹中生成对应的头文件：

generate_messages()

8.1 使用条件

为了能够正常生成相应的文件，这些宏必须在catkin_package()宏之前，

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

在catkin_package()宏中写上CATKIN_DEPENDS message_runtime

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

并且在find_package()写上message_generation组件：

find_package(catkin REQUIRED COMPONENTS message_generation)

package.xml文件中加上

    <build_depend>message_generationbuild_depend>
    <run_depend>message_runtimerun_depend>

　　如果构建的对象依赖于其他需要构建消息/服务/响应的构建对象，则需要向目标catkin_EXPORTED_TARGETS添加明确的依赖关系，以便它们以正确的顺序构建。 这种情况比较常用，除非您的包真的不使用ROS的任何部分。 但这种依赖关系不能自动传递。 （some_target是由add_executable()设置的目标的名称）：

 add_dependencies(some_target${catkin_EXPORTED_TARGETS})

　　如果需要构建消息或服务的包以及使用这些消息和/或服务的可执行文件，则需要为自动生成的消息目标创建明确的依赖关系，以便以正确的顺序构建它们。 （some_target是由add_executable()设置的目标的名称）：

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

　　如果您的catkin包满足上述两个条件，则需要添加以下两个依赖关系，即：

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

8.2 例子

　　现在有两个依赖于std_msgs和sensor_msgs的消息MyMessage1.msg和MyMessage2.msg，还有一个自定义服务MyService.srv， message_program是使用这些消息和服务的指令，以及生成不使用自定义消息、服务的程序do_not_use_local_messages_program**catkin包，那么**CMakeLists.txt应该写成：

# 构建时依赖项
find_package(catkin REQUIRED COMPONENTS          
             message_generation 
             std_msgs 

# 声明要构建哪些消息
add_message_files(FILES
                  MyMessage1.msg
                  MyMessage2.msg)

# 声明构建哪些服务
add_service_files(FILES
                  MyService.srv)

# 声明生成上述消息、服务需要依赖的消息以及服务
generate_messages(DEPENDENCIES 
                    std_msgs 
                    sensor_msgs)

# 声明运行时依赖项
catkin_package(CATKIN_DEPENDS 
                message_runtime 
                std_msgs sensor_msgs)

# 声明构建生成的可执行文件名称以及依赖项
add_executable(message_program src/main.cpp)
add_dependencies(message_program ${${PROJECT_NAME}_EXPORTED_TARGETS} ${catkin_EXPORTED_TARGETS})

# 声明构建不需要使用自定义消息、服务的可执行文件
add_executable(does_not_use_local_messages_program src/main.cpp)
add_dependencies(does_not_use_local_messages_program ${catkin_EXPORTED_TARGETS})

如果要构建响应，则在包中“action”目录中创建有一个名为“MyAction.action”的文件，则必须将actionlib_msgs添加到使用catkin进行find_package的组件列表中，然后在CMakeList.txt中加上下面两行：

add_action_files(FILES
                 MyAction.action)

此外，该包必须具有对actionlib_msgs的构建依赖。

九、启用Python模块支持

　　如果catkin包使用一些Python模块，您应该创建一个setup.py文件，并在调用catkin_python_setup()之后调用generate_messages()和catkin_package()。

十、单位测试

　　有一个catkin-specific宏用于处理名为catkin_add_gtest（）的基于gtest的单元测试。

catkin_add_gtest（myUnitTest test / utest.cpp）

十一、可选步骤：指定可安装的目标

　　构建后，构建目标通常被放置在catkin工作区中。但有时候我们希望将目标安装到系统其他地方（有关安装路径的信息可以在REP 122中找到），以便其他人或本地文件夹可以使用它们来测试。换句话说，如果你想要做一个“make install”的代码，你需要指定目标应该生成到哪里。
这是使用CMake install()函数作为参数完成的：

目标 - 目标是安装
ARCHIVE DESTINATION - 静态库和DLL（Windows）.lib存根
LIBRARY DESTINATION - 非DLL共享库和模块
RUNTIME DESTINATION - 可执行目标和DLL（Windows）样式共享库

举个栗子：

install(TARGETS ${PROJECT_NAME}
  ARCHIVE DESTINATION ${CATKIN_PACKAGE_LIB_DESTINATION}
  LIBRARY DESTINATION ${CATKIN_PACKAGE_LIB_DESTINATION}
  RUNTIME DESTINATION ${CATKIN_PACKAGE_BIN_DESTINATION}
)

　　除了这些标准目标，一些文件必须安装到特殊文件夹。即一个包含Python绑定的库必须安装到不同的文件夹中才能在Python中导入：

install(TARGETS python_module_library
  ARCHIVE DESTINATION ${CATKIN_PACKAGE_PYTHON_DESTINATION}
  LIBRARY DESTINATION ${CATKIN_PACKAGE_PYTHON_DESTINATION}
)

11.1 安装Python可执行脚本

　　对于Python代码，安装规则看起来是不同的，因为没有使用add_library（）和add_executable（）函数，以便CMake确定哪些文件是目标以及它们是什么类型的目标。 而是在您的CMakeLists.txt文件中使用以下内容：
　　

catkin_install_python(PROGRAMS scripts/myscript
  DESTINATION ${CATKIN_PACKAGE_BIN_DESTINATION})

有关安装python脚本和模块的详细信息以及文件夹布局的最佳做法，请参见catkin手册。

　　如果您只安装Python脚本并且不提供任何模块，则不需要创建上述setup.py文件，也不需要调用catkin_python_setup（）。

11.2 安装头文件

　　标题文件也必须安装到“include”文件夹中，这通常是通过安装整个文件夹的文件来完成的（可选地，按文件名模式过滤，不包括SVN子文件夹）。 这可以通过如下所示的安装规则完成：

install(DIRECTORY include/ PROJECTNAME/DESTINATION P R O J E C T N A M E / D E S T I N A T I O N {CATKIN_PACKAGE_INCLUDE_DESTINATION}
PATTERN “.svn” EXCLUDE
)
或者如果包含的子文件夹与包名称不匹配：
install(DIRECTORY include/
DESTINATION ${CATKIN_GLOBAL_INCLUDE_DESTINATION}
PATTERN “.svn” EXCLUDE
)

11.3 安装roslaunch文件或其他资源

其他资源（如启动文件）可以安装到

$ {CATKIN_PACKAGE_SHARE_DESTINATION
install(DIRECTORY launch/
  DESTINATION ${CATKIN_PACKAGE_SHARE_DESTINATION}/launch
  PATTERN ".svn" EXCLUDE)

参考文章：
1.ROS中的CMakeLists.txt
2.catkinCMakeLists.txt