ament_cmake_python 用户文档

ament_cmake_python 是一个为包含 Python 代码的 ament_cmake 构建类型的包提供 CMake 函数的包。 有关更多信息，请参阅 ament_cmake 用户文档。

Pure Python packages should use the ament_python build type in most cases. To create an ament_python package, see Creating your first ROS 2 package. ament_cmake_python should only be used in cases where that is not possible, like when mixing C/C++ and Python code.

基础知识

基本项目大纲

名为“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

在同一个 CMake 项目中调用“rosidl_generate_interfaces”和“ament_python_install_package”不起作用。 有关详细信息，请参阅此“Github 问题 <https://github.com/ros2/rosidl_python/issues/141>”。最佳做法是 将消息生成分离到单独的包中。

然后，另一个正确依赖于“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 测试命令 调用测试。