ament_cmake_python 用户文档

“ament_cmake_python” 是一个包,为包含 Python 代码的“ament_cmake” 构建类型的包提供 CMake 函数。 看 ament_cmake user documentation 了解更多信息。

在大多数情况下,纯 Python 包应使用“ament_python”构建类型。

要创建“ament_python”包,请参阅:doc:创建您的第一个 ROS 2 包ament_cmake_python 只应在不可能的情况下使用,例如混合 C/C++ 和 Python 代码时。

基础知识

项目基本概要

名为“my_project”的包的轮廓,其构建类型为“ament_cmake”,使用“ament_cmake_python”,如下所示:

.
└── my_project
    ├── CMakeLists.txt
    ├── package.xml
    └── my_project
        ├── __init__.py
        └── my_script.py

__init__.py 文件可以为空,但需要它来让 Python 将包含它的目录视为包 <https://docs.python.org/3/tutorial/modules.html#packages> `__。 除了保存 C/C++ 代码的“CMakeLists.txt”之外,还可以有一个“src”或“include”目录。

使用ament_cmake_python

该包必须在其“package.xml”中声明对“ament_cmake_python”的依赖。

<buildtool_depend>ament_cmake_python</buildtool_depend>

“CMakeLists.txt” 应包含:

find_package(ament_cmake_python REQUIRED)
# ...
ament_python_install_package(${PROJECT_NAME})

“ament_python_install_package()” 的参数是包含 Python 文件的“CMakeLists.txt” 旁边的目录名称。 在本例中,它是“my_project”或“${PROJECT_NAME}”。

Warning

Calling rosidl_generate_interfaces and ament_python_install_package in the same CMake project does not work. See this Github issue for more info. It is best practice to instead separate out the message generation into a separate package.

然后,另一个正确依赖于“my_project”的Python包可以将其用作普通的Python模块:

from my_project.my_script import my_function

假设“my_script.py”包含一个名为“my_function()”的函数。

使用ament_cmake_pytest

包“ament_cmake_pytest”用于使测试可被“cmake”发现。 该包必须在其“package.xml”中声明对“ament_cmake_pytest”的测试依赖项。

<test_depend>ament_cmake_pytest</test_depend>

假设该包的文件结构如下所示,测试位于“tests”文件夹中。

.
├── CMakeLists.txt
├── my_project
│   └── my_script.py
├── package.xml
└── tests
    ├── test_a.py
    └── test_b.py

“CMakeLists.txt” 应包含:

if(BUILD_TESTING)
  find_package(ament_cmake_pytest REQUIRED)
  set(_pytest_tests
    tests/test_a.py
    tests/test_b.py
    # Add other test files here
  )
  foreach(_test_path ${_pytest_tests})
    get_filename_component(_test_name ${_test_path} NAME_WE)
    ament_add_pytest_test(${_test_name} ${_test_path}
      APPEND_ENV PYTHONPATH=${CMAKE_CURRENT_BINARY_DIR}
      TIMEOUT 60
      WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}
    )
  endforeach()
endif()

与支持自动测试发现的 ament_python 用法相比,必须使用每个测试文件的路径调用 ament_cmake_pytest。 可以根据需要减少超时。

现在,您可以使用 标准 colcon 测试命令 调用测试。