ROS源码分析--子话题-catkin

catkin简介

catkin是当前ROS的官方编译工具，每天都要接触到，因此有必要单独说说。
catkin编译基于CMake，源代码以package为单位组织，每个package必须包含package.xml和CMakeList.txt两个文件。

package.xml

catkin支持两种package.xml标签格式，格式1标准说明是REP-0127，格式2标准说明是REP-0140。后者是针对前者的一些缺点进行改进后的版本，因此更加被推荐使用。
在package.xml中主要包含以下信息：

• 描述信息（比如package的功能描述、维护者等）
• 依赖信息
• 元信息（比如作者、网页）
• package信息（比如版本）

每个package.xml文件必须包含的标签包括：

• <package> : 最高级tag，属性：format，用于指定格式
  
  • <name> ：package名称
  • <version> ：当前版本
  • <description>：package的基本描述
  • <maintainer>(至少一个)：维护者
  • <license>(至少一个)：协议
  • <buildtool_depend>(至少一个)：一般情况下只需要指定catkin作为编译工具，在需要交叉编译的情况下需要增加目标机器的编译工具。

可选标签包括：

• <package>
  
  • <url> (多个)：指定package的网址
  • <author> (多个)：作者
  • <build_depend> (多个)：编译时需要依赖的其它package，适用于静态库
  • <conflict> (多个)：声明本package与其它ROS package有冲突，不能同时部署
  • <replace> (多个)：声明本package是其它package的替换版本
  • <export>：用于添加额外的信息，比如需要嵌入的其它package的插件，或者一些说明信息。

插件：

<export>
  <rviz plugin="${prefix}/plugin_description.xml"/>
</export>

废弃信息：

<export>
  <deprecated>
    This package will be removed in ROS Hydro. Instead, use package
    FOO, which provides similar features with a different API.
  </deprecated>
</export>

meta package标记：

<export>
  <metapackage/>
</export>

以及在格式1和格式2有区别的标签：

格式1

• <package>
  
  • <run_depend> (多个)：运行时需要依赖的其它package，如动态链接库、可执行文件、Python模块、脚本文件等。
  • <test_depend> (多个)：进行单元测试时的依赖项，如前两个标签中已出现过，则不必再出现

格式2

• <package>
  
  • <build_export_depend>：用于帮助使用本package的其它包传递依赖声明
  • <buildtool_export_depend>：构建工具的依赖传递声明
  • <exec_depend>：相当于格式1的run_depend标签。
  • <depend>： 相当于build_depend + buildtool_depend + exec_depend，避免重复写三个声明。不建议对系统依赖使用，因为会强行依赖development级package。
  • <doc_depend>：构建文档所需要的依赖，当前没什么用，以后可能会有需要
  • <test_depend>：进行单元测试时的依赖项，此标签中的package 可以 在其它标签中出现

上述是对package.xml的基本说明，对于用户而言，如果通过catkin_create_package命令生成的包，往往已经自动生成了需要的全部标签，只需要在依赖有所变化的情况下更改（格式1）：

• <build_depend>
• <run_depend>

或者（格式2）：

• <depend>

CMakeList.txt

catkin基于CMake实现，CMakeList的语句与基本CMake一致，常用的包括：

• cmake_minimum_required()：CMake版本

    cmake_minimum_required(VERSION 2.8.3)

• project()：工程名

    project(your_package)

• find_package()：加载外部变量

    # 加载catkin中的变量，同时添加angles、roscpp、std_msgs的依赖
    find_package(catkin REQUIRED COMPONENTS angles roscpp std_msgs)
    # 加载Boost中的变量
    find_package(Boost REQUIRED COMPONENTS thread)

• include_directories()：添加头文件路径

    # 添加./include、${catkin_INCLUDE_DIRS}为头文件路径，如果有其它外部路径也在这里添加
    include_directories(include ${catkin_INCLUDE_DIRS})
    # Boost_INCLUDE_DIRS环境变量在上面find_package中加载
    include_directories(${Boost_INCLUDE_DIRS})

• add_library()：生成库

    # 生成库文件，可传入多个源文件
    add_library(your_library 
        libsrc1.cpp 
        libsrc2.cpp 
        libsrc_etc.cpp
    )

• add_executable()：生成可执行文件

    # 生成可执行文件，可以传入多个源文件
    add_executable(my_node 
        src0.cpp 
        src1.cpp 
        src2.cpp
    )

• add_dependencies()：添加依赖项，在使用ROS的message、service、action时注意添加，如下：

    # 添加对其它package消息的依赖，前提是已经通过find_package()引入了这个package
    add_dependencies(my_target ${catkin_EXPORTED_TARGETS})
    # 添加对本package消息的依赖
    add_dependencies(my_target ${${PROJECT_NAME}_EXPORTED_TARGETS})

• target_link_libraries()：链接库

    # 为可执行文件或库添加链接库
    target_link_libraries(my_node
        ${catkin_LIBRARIES}        # ROS基本库
        ${Boost_LIBRARIES}         # Boost库
    )

• install()：安装

    # 默认情况catkin会为每个package在./devel中建立目录，存放目标文件
    # 目标文件可以直接通过rosrun和roslaunch访问
    # 如需制定其它安装位置，则需通过install()命令
    install(TARGETS my_node0 my_node1
      ARCHIVE DESTINATION ${CATKIN_PACKAGE_LIB_DESTINATION}
      LIBRARY DESTINATION ${CATKIN_PACKAGE_LIB_DESTINATION}
      RUNTIME DESTINATION ${CATKIN_PACKAGE_BIN_DESTINATION}
    )

以上语句功能不详细叙述。
除此之外，catkin还为ROS设计了一些独有语句，包括：

• add_message_files(), add_service_files(), add_action_files()
  用于添加自定义的message、service和action文件。基本语法为：

    # 以message为例，service、action类似
    add_message_files(
        # 目录名
        DIRECTORY msg
        # 文件名
        FILES YourFirstMessage.msg YourSecondMessage.msg YourThirdMessage.msg
    )

• generate_messages()
  用于生成所有定义的message、service、action文件，需要添加本文件需要依赖的message文件包。
  一般情况下需要依赖std_msgs，如果用到了其它类型的msg，也要在这声明。如下：

    generate_messages(DEPENDENCIES std_msgs)

• catkin_package()

  catkin_package()是catkin提供的CMake宏，用于为catkin提供构建、生成pkg-config和CMake文件所需要的信息。
  必须在声明add_library()或add_executable()前调用
  有5个可选参数:

  • INCLUDE_DIRS - 声明给其它package的include路径
  • LIBRARIES - 声明给其它package的库
  • CATKIN_DEPENDS - 本包依赖的catkin package
  • DEPENDS - 本包依赖的非catkin package
  • CFG_EXTRAS - 其它配置参数

  比如:

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

• catkin_add_gtest(), catkin_add_nosetests(), add_rostest(), add_rostest_gtest()

meta package

Metapackages are specialized Packages in ROS (and catkin). They do not install files (other than their package.xml manifest) and they do not contain any tests, code, files, or other items usually found in packages.

A metapackage is used in a similar fashion as virtual packages are used in the debian packaging world. A metapackage simply references one or more related packages which are loosely grouped together.

Most of the metapackages in ROS are backwards compatible placeholders for converted rosbuild Stacks.

说白了，meta package就是ros为了兼容之前的编译工具rosbuild和stack的概念，硬造出来的空package。后面基于catkin构建的package是不需要meta package的。

meta package的package.xml里包含metapackage标签：

 <export>
   <metapackage />
 </export>

CMakeList.txt里应该只包含：

cmake_minimum_required(VERSION 2.8.3)
project(your_package)
find_package(catkin REQUIRED)
catkin_metapackage()

典型ROS应用：添加自定义message文件

在ROS中，为package添加自定义message（service、action）文件，或者构建纯message的package，主要需要进行以下几个工作：

修改package.xml

添加：
<build_depend>：message_generation
<run_depend>/<exec_depend>：message_runtime

修改CMakeList.txt

包括：

1. find_package()

添加构建时依赖message_generation

find_package(catkin REQUIRED COMPONENTS ... message_generation ...)

2. add_message()

添加.msg文件

add_message_files(
  DIRECTORY msg
  FILES YourFirstMessage.msg YourSecondMessage.msg YourThirdMessage.msg
)

3. generate_messages()

生成message代码，制定依赖

generate_messages(DEPENDENCIES std_msgs)

4. catkin_package()

添加运行时依赖message_runtime

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

5. add_dependencies()

为目标文件（add_executable(), add_library()中生成的）指定依赖

# 指定依赖本package
add_dependencies(my_target ${${PROJECT_NAME}_EXPORTED_TARGETS})

---

参考资料

1. rep-0127
2. rep-0140
3. package官方介绍
4. catkin官方教程