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 测试命令 调用测试。