Utiliser colcon pour créer des packages

Objectif : Construire un espace de travail ROS 2 avec colcon.

Niveau du tutoriel : Débutant

Durée : 20 minutes

Ceci est un bref tutoriel sur la façon de créer et de construire un espace de travail ROS 2 avec colcon. Il s’agit d’un didacticiel pratique et non conçu pour remplacer la documentation de base.

Arrière-plan

colcon est une itération sur les outils de compilation ROS catkin_make, catkin_make_isolated, catkin_tools et ament_tools. Pour plus d’informations sur la conception de colcon, consultez ce document.

Le code source se trouve dans l’organisation colcon GitHub.

Conditions préalables

Installer Colcon

sudo apt install python3-colcon-common-extensions

Installer ROS 2

Pour créer les exemples, vous devrez installer ROS 2.

Suivez les instructions d’installation.

Attention

Si vous installez à partir de packages Debian, ce didacticiel nécessite l”installation de bureau.

Bases

Un espace de travail ROS est un répertoire avec une structure particulière. Généralement, il existe un sous-répertoire src. À l’intérieur de ce sous-répertoire se trouve le code source des packages ROS. En règle générale, le répertoire démarre sinon vide.

colcon fait des builds hors source. Par défaut, il créera les répertoires suivants en tant que pairs du répertoire src :

  • Le répertoire build sera l’endroit où les fichiers intermédiaires sont stockés. Pour chaque package, un sous-dossier sera créé dans lequel, par ex. CMake est appelé.

  • Le répertoire install est l’endroit où chaque paquet sera installé. Par défaut, chaque package sera installé dans un sous-répertoire séparé.

  • Le répertoire log contient diverses informations de journalisation sur chaque invocation colcon.

Note

Contrairement à catkin, il n’y a pas de répertoire devel.

Créer un espace de travail

Tout d’abord, créez un répertoire (ros2_ws) pour contenir notre espace de travail :

mkdir -p ~/ros2_ws/src
cd ~/ros2_ws

À ce stade, l’espace de travail contient un seul répertoire vide src :

.
└── src

1 directory, 0 files

Ajouter des sources

Clonons le dépôt examples dans le répertoire src de l’espace de travail :

git clone https://github.com/ros2/examples src/examples -b rolling

L’espace de travail doit maintenant contenir le code source des exemples ROS 2 :

.
└── src
    └── examples
        ├── CONTRIBUTING.md
        ├── LICENSE
        ├── rclcpp
        ├── rclpy
        └── README.md

4 directories, 3 files

Sourcer une sous-couche

Il est important que nous ayons trouvé l’environnement pour une installation ROS 2 existante qui fournira à notre espace de travail les dépendances de construction nécessaires pour les exemples de packages. Ceci est réalisé en générant le script de configuration fourni par une installation binaire ou une installation source, c’est-à-dire. un autre espace de travail colcon (voir Installation). Nous appelons cet environnement une sous-couche.

Notre espace de travail, ros2_ws, sera une superposition au-dessus de l’installation ROS 2 existante. En général, il est recommandé d’utiliser une superposition lorsque vous prévoyez d’itérer sur un petit nombre de packages, plutôt que de placer tous vos packages dans le même espace de travail.

Construire l’espace de travail

Attention

Pour créer des packages sous Windows, vous devez être dans un environnement Visual Studio, voir Construire le code ROS 2 pour plus de détails.

A la racine de l’espace de travail, lancez colcon build. Étant donné que les types de construction tels que ament_cmake ne prennent pas en charge le concept de l’espace devel et nécessitent l’installation du paquet, colcon prend en charge l’option --symlink-install. Cela permet de modifier les fichiers installés en modifiant les fichiers dans l’espace source (par exemple, des fichiers Python ou d’autres ressources non compilées) pour une itération plus rapide.

colcon build --symlink-install

Une fois la construction terminée, nous devrions voir les répertoires build, install et log :

.
├── build
├── install
├── log
└── src

4 directories, 0 files

Exécuter des tests

Pour exécuter des tests pour les packages que nous venons de créer, exécutez ce qui suit :

colcon test

Sourcer l’environnement

Lorsque colcon a terminé la construction avec succès, la sortie sera dans le répertoire install. Avant de pouvoir utiliser l’un des exécutables ou bibliothèques installés, vous devez les ajouter à votre chemin et aux chemins de bibliothèque. colcon aura généré des fichiers bash/bat dans le répertoire install pour aider à configurer l’environnement. Ces fichiers ajouteront tous les éléments requis à votre chemin et aux chemins de bibliothèque, ainsi que toutes les commandes bash ou shell exportées par les packages.

. install/setup.bash

Essayez une démo

Avec l’environnement sourcé, nous pouvons exécuter des exécutables construits par colcon. Exécutons un nœud d’abonné à partir des exemples :

ros2 run examples_rclcpp_minimal_subscriber subscriber_member_function

Dans un autre terminal, lançons un nœud d’éditeur (n’oubliez pas de sourcer le script de configuration) :

ros2 run examples_rclcpp_minimal_publisher publisher_member_function

Vous devriez voir les messages de l’éditeur et de l’abonné avec des numéros incrémentés.

Créez votre propre forfait

colcon utilise la spécification package.xml définie dans REP 149 (format 2 est également pris en charge).

colcon prend en charge plusieurs types de construction. Les types de construction recommandés sont ament_cmake et ament_python. Les packages cmake purs sont également pris en charge.

Un exemple de construction ament_python est le package ament_index_python , où setup.py est le point d’entrée principal pour la construction.

Un package tel que demo_nodes_cpp utilise le type de construction ament_cmake et utilise CMake comme outil de construction.

Pour plus de commodité, vous pouvez utiliser l’outil ros2 pkg create pour créer un nouveau package basé sur un modèle.

Note

Pour les utilisateurs de catkin, c’est l’équivalent de catkin_create_package.

Configurer colcon_cd

La commande colcon_cd vous permet de changer rapidement le répertoire de travail courant de votre shell vers le répertoire d’un paquet. Par exemple, colcon_cd some_ros_package vous amènerait rapidement au répertoire ~/ros2_install/src/some_ros_package.

echo "source /usr/share/colcon_cd/function/colcon_cd.sh" >> ~/.bashrc
echo "export _colcon_cd_root=/opt/ros/rolling/" >> ~/.bashrc

Selon la manière dont vous avez installé colcon_cd et où se trouve votre espace de travail, les instructions ci-dessus peuvent varier, veuillez vous référer à la documentation pour plus de détails. Pour annuler cette opération sous Linux et macOS, localisez le script de démarrage du shell de votre système et supprimez les commandes source et export ajoutées.

Configuration de l’achèvement de l’onglet colcon

La commande colcon prend en charge la complétion de commande pour les shells bash et de type bash si le colcon -argcomplete est installé.

echo "source /usr/share/colcon_argcomplete/hook/colcon-argcomplete.bash" >> ~/.bashrc

Selon la manière dont vous avez installé colcon et l’endroit où se trouve votre espace de travail, les instructions ci-dessus peuvent varier, veuillez vous référer à `la documentation <https://colcon.readthedocs.io/en/released/user/installation.html> `__ pour plus de détails. Pour annuler cela sous Linux et macOS, localisez le script de démarrage du shell de votre système et supprimez la commande source ajoutée.

Conseils

  • Si vous ne souhaitez pas construire un package spécifique, placez un fichier vide nommé COLCON_IGNORE dans le répertoire et il ne sera pas indexé.

  • Si vous voulez éviter de configurer et de construire des tests dans les packages CMake, vous pouvez passer : --cmake-args -DBUILD_TESTING=0.

  • Si vous souhaitez exécuter un seul test particulier à partir d’un package :

    colcon test --packages-select YOUR_PKG_NAME --ctest-args -R YOUR_TEST_IN_PKG