documentation utilisateur ament_cmake_python

ament_cmake_python est un package qui fournit des fonctions CMake pour les packages du type de construction ament_cmake contenant du code Python. Voir la ament_cmake documentation utilisateur pour plus d’informations.

Note

Les packages Python purs doivent utiliser le type de construction ament_python dans la plupart des cas. Pour créer un package ament_python, consultez Creating your first ROS 2 package. ament_cmake_python ne doit être utilisé que dans les cas où cela n’est pas possible, comme lors du mélange de code C/C++ et Python.

Bases

Aperçu du projet de base

Le plan d’un paquet appelé « my_project » avec le type de construction ament_cmake qui utilise ament_cmake_python ressemble à :

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

Le fichier __init__.py peut être vide, mais il est nécessaire pour faire que Python traite le répertoire le contenant comme un package <https://docs.python.org/3/tutorial/modules.html#packages> `__. Il peut également y avoir un répertoire ``src` ou include à côté du CMakeLists.txt qui contient du code C/C++.

Utiliser ament_cmake_python

Le paquet doit déclarer une dépendance sur ament_cmake_python dans son package.xml.

<buildtool_depend>ament_cmake_python</buildtool_depend>

Le CMakeLists.txt doit contenir :

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

L’argument de ament_python_install_package() est le nom du répertoire à côté de CMakeLists.txt qui contient le fichier Python. Dans ce cas, il s’agit de my_project, ou ${PROJECT_NAME}.

Avertissement

L’appel de rosidl_generate_interfaces et ament_python_install_package dans le même projet CMake ne fonctionne pas. Voir ce problème Github pour plus d’informations. Il est préférable de séparer la génération de messages dans un package séparé.

Ensuite, un autre package Python qui dépend correctement de my_project peut l’utiliser comme un module Python normal :

from my_project.my_script import my_function

En supposant que my_script.py contient une fonction appelée my_function().

Utilisation de ament_cmake_pytest

Le package ament_cmake_pytest est utilisé pour rendre les tests détectables par cmake. Le paquet doit déclarer une dépendance de test sur ament_cmake_pytest dans son package.xml.

<test_depend>ament_cmake_pytest</test_depend>

Supposons que le paquet ait une structure de fichiers comme ci-dessous, avec des tests dans le dossier tests.

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

Le CMakeLists.txt doit contenir :

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()

Par rapport à l’utilisation d’ament_python, qui prend en charge la découverte automatique des tests, ament_cmake_pytest doit être appelé avec le chemin d’accès à chaque fichier de test. Le délai d’attente peut être réduit si nécessaire.

Maintenant, vous pouvez invoquer vos tests avec les commandes de test colcon standard.