ament_cmake_python 用户文档

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

注解

在大多数情况下，纯 Python 包应使用 ament_python 构建类型。要创建一个 ament_python 包，请参阅 创建你的第一个 ROS 2 包。ament_cmake_python 仅在不可能的情况下才应使用，例如在混合使用 C/C++ 和 Python 代码时。

基础知识

基本项目概述

具有``ament_cmake``构建类型，并使用``ament_cmake_python``的名为"my_project"的软件包的概要如下：

.
└── 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>`__。在``CMakeLists.txt``旁边还可以有一个包含C/C++代码的``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}。

警告

在同一个 CMake 项目中调用 rosidl_generate_interfaces 和 ament_python_install_package 是不起作用的。请参阅此 Github 问题 了解更多信息。最佳实践是将消息生成分离到一个单独的包中。

然后，另一个正确依赖于 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必须使用每个测试文件的路径进行调用。超时时间可以根据需要缩短。

现在，您可以使用:doc:`标准的colcon测试命令<../Tutorials/Intermediate/Testing/CLI>`来调用您的测试。