Note: This tutorial assumes that you have completed the previous tutorials: Naviguer dans le système de fichier ROS.
(!) Please ask about problems and questions regarding this tutorial on answers.ros.org. Don't forget to include in your question the link to this page, the versions of your OS & ROS, and also add appropriate tags.

Créer un package ROS

Description: Ce tutoriel présente l'utilisation de roscreate-pkg ou catkin pour créer un nouveau package et rospack pour lister les dépendances des packages.

Tutorial Level: BEGINNER

Next Tutorial: Construire un package ROS

Utilisation de roscreate

Pour créer un package, la commande roscreate-pkg permet de créer un nouveau package au format ROS.

Tous les packages ROS sont constitués d'un certain nombre de fichiers, toujours sur le même modèle : manifests, CMakeLists.txt, mainpage.dox, et Makefiles. La commande roscreate-pkg simplifie les nombreuses étapes du processus laborieux de création à la main d'un package, et évite les erreurs courantes que l'on aurait eues en éditant à la main les fichiers de build et les manifestes correspondants.

Pour créer un nouveau package dans le répertoire courant, on peut taper:

# roscreate-pkg [package_name]

Mais on peut aussi préciser les dépendances de ce package par la commande:

# roscreate-pkg [package_name] [depend1] [depend2] [depend3]

Creation d'un nouveau package ROS

Maintenant nous allons nous rendre dans notre 'home' ou notre répertoire projet, pour créer un package beginner_tutorials que nous ferons dépendre de std_msgs, roscpp, and rospy, qui sont des packages ROS courants.

Pour se rendre dans le dossier ~/fuerte_workspace/sandbox on peut faire:

$ cd ~/fuerte_workspace/sandbox

Mais, pour les versions ROS Fuerte ou ultérieures, vous pouvez plus simplement faire:

$ roscd
$ cd sandbox

A partir de là, créez votre package:

$ roscreate-pkg beginner_tutorials std_msgs rospy roscpp

Vous obtiendrez une sortie ressemblant à ceci :

  • Creating package directory ~/fuerte_workspace/sandbox/beginner_tutorials
    Creating include directory ~/fuerte_workspace/sandbox/beginner_tutorials/include/beginner_tutorials
    Creating cpp source directory ~/ros/ros_tutorials/beginner_tutorials/src
    Creating python source directory ~/fuerte_workspace/sandbox/beginner_tutorials/src/beginner_tutorials
    Creating package file ~/fuerte_workspace/sandbox/beginner_tutorials/Makefile
    Creating package file ~/fuerte_workspace/sandbox/beginner_tutorials/manifest.xml
    Creating package file ~/fuerte_workspace/sandbox/beginner_tutorials/CMakeLists.txt
    Creating package file ~/fuerte_workspace/sandbox/beginner_tutorials/mainpage.dox
    
    Please edit beginner_tutorials/manifest.xml and mainpage.dox to finish creating your package

Vous voudrez sûrement passer un moment à regarder plus attentivement le fichier beginner_tutorials/manifest.xml. Les fichiers manifests jouent un rôle important pour ROS car ils définissent comment les packages sont construits, lancés et documentés.

Vérifions que ROS trouve bien notre nouveau package. Il est souvent utile d'appeler rospack profile après toute modification au 'path' pour s'assurer que les nouveaux chemins des répertoires sont bien trouvés:

$ rospack profile
$ rospack find beginner_tutorials 
  • YOUR_PACKAGE_PATH/beginner_tutorials

En cas d'erreur, cela implique que ROS ne parvient pas à trouver le nouveau package, ce qui provient probablement d'un problème avec la variable ROS_PACKAGE_PATH. Reportez-vous bien aux instructions d'installation de ROS, que celle-ci ait été faite depuis un repository SVN ou à partir d’exécutables binaires déjà compilés pour vous.

Dans le cas où votre nouveau package de trouve à un emplacement situé en dehors des chemins déjà déclarés pour des packages existants, il faudra amender votre adapter d'environnement ROS_PACKAGE_PATH pour y ajouter le nouveau chemin.

Ensuite, essayez de sourcer à nouveau votre setup.sh dans votre dossier fuerte_workspace.

Essayons d'aller dans le dossier du package.

$ roscd beginner_tutorials 
$ pwd
  • YOUR_PACKAGE_PATH/beginner_tutorials

Dépendances de premier ordre du package

Lorsque nous avons appelé roscreate-pkg précédemment, nous avons précisé quelques dépendances de packages. On peut refaire une passe sur ces dépendances de premier ordre avec l'outil rospack .

(9 Jan 2013) Il y a un bug reporté et déjà corrigé dans rospack en version groovy; cette correction peut prendre un certain temps à se propager dans les packages. Si vous observer un problème similaire à celui-ci avec la commande suivante, vous pouvez sauter à la commande qui suit.

$ rospack depends1 beginner_tutorials 
  • std_msgs
    rospy
    roscpp

Comme vous pouvez le constater, rospack rend éxactement la même liste de dépendances que celle que nous avions fournie avec roscreate-pkg. Ces dépendances sont enregistrées au niveau du fichiher manifest du package. Allez jeter un œil à ce fichier manifest.

$ roscd beginner_tutorials
$ cat manifest.xml
  • <package>
    
    ...
    
      <depend package="std_msgs"/>
      <depend package="rospy"/>
      <depend package="roscpp"/>
    
    </package>

Dépendances indirectes du package

Dans la plupart des cas, chaque dépendance aura aussi d'autres dépendances. Par exemple, rospy a d'autres dépendances.

(9 Jan 2013) Il y a un bug reporté et déjà corrigé dans rospack en version groovy; cette correction peut prendre un certain temps à se propager dans les packages. Si vous observer un problème similaire à celui-ci avec la commande suivante, vous pouvez sauter à la commande qui suit.

$ rospack depends1 rospy
  • roslib
    roslang

Un même package peut ainsi avoir un certain nmbre de dépendances indirectes. Par chance, rospack permet de déterminer de façon récursive toutes les dépendances filles.

$ rospack depends beginner_tutorials
  • rospack
    roslib
    std_msgs
    rosgraph_msgs
    rosbuild
    roslang
    rospy
    cpp_common
    roscpp_traits
    rostime
    roscpp_serialization
    xmlrpcpp
    rosconsole
    roscpp

Note: en version Fuerte, la liste est bien plus courte:

  • std_msgs
    roslang
    rospy
    roscpp

Librairies des clients ROS

On peut se demander ce que sont ces dépendances rospy et roscpp dans l'exmple précédent. Ces librairies rospy et roscppsont en fait les Client Libraries. Ces librairies client permettent aux différents langages de programmation à communiquer dans ROS. rospy est la librairie client pour Python. roscpp est la librairie client pour le C++.

En résumé

Revenos sur quelques commandes que nous avons utilisées ici:

  • roscreate-pkg = ros+create-pkg : crée tous les fichiers nécessaires pour créer un package ROS
  • rospack = ros+pack(age) : fournit les informations relatives à un package ROS
  • rosstack = ros+stack : fournit les informations relatives à une stack ROS

Qu'est ce qu'un package catkin?

Pour qu'un package puisse être considéré comme un package catkin il doit répondre à quelques exigences:

  • Le package doit contenir un fichier package.xml conforme à catkin.
    • Le fichier package.xml fournit les meta-informations sur le package.
  • Le package doit contenir aussi un fichier CMakeLists.txt quiappelle catkin.

    • Pour les metapackage catkin il et nécessaire d'avoir tous les fichiers CMakeLists.txt nécessaires.

  • Chaque package doit avoir son propre répertoire (Il ne peut y avoir plus d'un package dans chaque dossier)
    • Cela signifie qu'il n'y a pas de packages imbriqués ni plusieurs packages partagent le même répertoire.

Le package le plus simple possible pourrait ressembler à ceci:

  • my_package/
    CMakeLists.txt
    package.xml

Les packages dans un workspace catkin

Pour travailler avec des packages dans catkin, la méthode recommandée consiste à travailler dans un workspace (espace de travail) catkin, mais il est aussi possible de construire des packages catkin à part (en standalone).

Un workspace typique pourrait ressembler à ceci:

  • workspace_folder/        -- WORKSPACE
    src/                   -- SOURCE SPACE
    CMakeLists.txt       -- 'Toplevel' CMake file, provided by catkin
    package_1/
    CMakeLists.txt     -- CMakeLists.txt file for package_1
    package.xml        -- Package manifest for package_1
    ...
    package_n/
    CMakeLists.txt     -- CMakeLists.txt file for package_n
    package.xml        -- Package manifest for package_n

Avant de continuer avec ce tutoriel vous devez créer un workspace catkin vide en suivant ce tutoriel Creating a workspace for catkin

Création d'un package catkin

Ce tutorial montre comment utiliser le script catkin_create_pkg pour créer un nouveau package catkin, et ce que vous pouvez faire avec, une fois créé.

D'abord on va se rendre dans le répertoire des fichiers sources du workspace catkin que l'on a créé lors du tutorial Creating a workspace for catkin

  • # You should have created this in the Creating a Workspace Tutorial
    cd ~/catkin_ws/src

Maintenant, utilisons le script catkin_create_pkg pour créer un nouveau package appelé "beginner_tutorials" qui dépend de std_msgs, roscpp et Rospy:

  • catkin_create_pkg beginner_tutorials std_msgs rospy roscpp

Cela va créer un dossier beginner_tutorials qui contient un package.xml et un CMakeLists.txt , qui ont été partiellement remplis avec les informations que vous avez données à catkin_create_pkg. catkin_create_pkg demande que vous lui donniez un nom de package et éventuellement une liste des packages dont ce package dépend:

  • # This is an example, do not try to run this
    # catkin_create_pkg <package_name> [depend1] [depend2] [depend3]

catkin_create_pkg possède également des fonctionnalités plus avancées qui sont décrites dans le catkin/commands/catkin_create_pkg .

Dépendances du package

Dépendances de premier ordre

Lors de l'utilisation de catkin_create_pkg plus tôt, quelques dépendances des packages ont été fournies. Ces dépendances de premier ordre peuvent maintenant être examinées avec l'outil rospack.

(9 janvier 2013) Il y a http://answers.ros.org/question/51555/beginner-tutorials-segmentation-fault-with-rospack-depends1/?comment=51762#comment-51762 avec la commande suivante, vous pouvez passer à la prochaine commande.

  • rospack depends1 beginner_tutorials
    std_msgs
    rospy
    roscpp

Comme vous pouvez le voir, rospack énumère les mêmes dépendances qui ont été utilisées comme arguments lors de l'exécution catkin_create_pkg. Les dépendances d'un package sont stockées dans le fichier package.xml :

  • roscd beginner_tutorials
    cat package.xml
       1 <package>
       2 ...
       3 <buildtool_depend>catkin</buildtool_depend>
       4 <build_depend>roscpp</build_depend>
       5 <build_depend>rospy</build_depend>
       6 <build_depend>std_msgs</build_depend>
       7 ...
       8 </package>
    

Dépendances indirectes

Dans de nombreux cas, une dépendance aura aussi ses propres dépendances. Par exemple, Rospy a d'autres dépendances.

  • (9 janvier 2013) Il y a  [un bug](https://github.com/ros/rospack/issues/4) signalé et déjà fixé dans  [rospack](http://wiki.ros.org/rospack) en groovy, ce qui prend un certain temps jusqu'à ce que le changement se reflète sur votre ordinateur. Si vous voyez  [un problème semblable à celui-ci](http://answers.ros.org/question/51555/beginner-tutorials-segmentation-fault-with-rospack-depends1/?comment=51762#comment-51762) avec la commande suivante, vous pouvez passer à la prochaine commande.
    rospack depends1 rospy
    genpy
    rosgraph
    rosgraph_msgs
    roslib
    std_msgs

Un package peut avoir pas mal de dépendances indirectes. Heureusement rospack peut déterminer de façon récursive toutes les dépendances imbriquées.

  • rospack depends beginner_tutorials
    cpp_common
    rostime
    roscpp_traits
    roscpp_serialization
    genmsg
    genpy
    message_runtime
    rosconsole
    std_msgs
    rosgraph_msgs
    xmlrpcpp
    roscpp
    rosgraph
    catkin
    rospack
    roslib
    rospy

Personnalisation de votre Package

Dans cette partie du tutoriel on va regarder dans chaque fichier généré par catkin_create_pkg et décrire, ligne par ligne, chaque composante de ces fichiers et comment vous pouvez les personnaliser pour votre package.

Personnalisation du package.xml

Le fichier généré package.xml devrait déjà être dans votre nouveau package. Maintenant allons dans le fichier package.xml et regardons chaque élément.

Balise de description

Première ligne, la balise description :

  •    1 <description>The beginner_tutorials package</description>
    

Modifier la description comme vous voulez, mais, par convention, la première phrase doit être courte tout en couvrant le champ d'application du package. S'il est difficile de décrire le package en une seule phrase, alors il faudra peut-être la couper.

La balises du responsable

Vient ensuite le maintainer tag :

  •    1 <!-- One maintainer tag required, multiple allowed, one person per tag -->
       2 <!-- Example:  -->
       3 <!-- <maintainer email="jane.doe@example.com">Jane Doe</maintainer> -->
       4 <maintainer email="user@todo.todo">user</maintainer>
    

Il s'agit d'une balise requise et importante pour le fichier package.xml , car il permet aux autres de savoir qui contacter au sujet du package. Au moins un nom de mainteneur est requis, mais vous pouvez en avoir plus si vous voulez. Le nom du responsable va dans le corps de la balise, mais il y a aussi l'attribut email qui doit être rempli:

  •    1 <maintainer email="you@yourdomain.tld">Your Name</maintainer>
    

La balise licence

La balise licence est également requise :

  •    1 <!-- One license tag required, multiple allowed, one license per tag -->
       2 <!-- Commonly used license strings: -->
       3 <!--   BSD, MIT, Boost Software License, GPLv2, GPLv3, LGPLv2.1, LGPLv3 -->
       4 <license>TODO</license>
    

Vous devez choisir une licence et l'indiquer ici. Les licences open source les plus communes sont : BSD, MIT, Boost Software License, GPLv2, GPLv3, LGPLv2.1 et LGPLv3. Vous pouvez en apprendre plus sur la plupart d'entre elles à l' Open Source Initiative . Pour ce tutoriel, nous allons utiliser la licence BSD parce que la majorité des autres composants ROS l'utilisent déjà:

  •    1 <license>BSD</license>
    

Les balises de dépendances

La prochaine série de balises décrit les dépendances de votre package. Les dépendances sont divisées en 4 catégories :

  • build_depend, (dépendances pour la construction)
  • buildtool_depend, (dépendances pour les outils de construction)
  • run_depend, (dépendances pour l'exécution)
  • test_depend. (dépendances pour le test)

Pour une explication plus détaillée de ces balises consultez la documentation sur les dépendances catkin Catkin Dependencies

Comme nous avons passé std_msgs, roscpp, et rospy comme arguments à catkin_create_pkg, la déclaration des dépendances ressemblera à ceci:

  •    1 <!-- The *_depend tags are used to specify dependencies -->
       2 <!-- Dependencies can be catkin packages or system dependencies -->
       3 <!-- Examples: -->
       4 <!-- Use build_depend for packages you need at compile time: -->
       5 <!--   <build_depend>genmsg</build_depend> -->
       6 <!-- Use buildtool_depend for build tool packages: -->
       7 <!--   <buildtool_depend>catkin</buildtool_depend> -->
       8 <!-- Use run_depend for packages you need at runtime: -->
       9 <!--   <run_depend>python-yaml</run_depend> -->
      10 <!-- Use test_depend for packages you need only for testing: -->
      11 <!--   <test_depend>gtest</test_depend> -->
      12 <buildtool_depend>catkin</buildtool_depend>
      13 <build_depend>roscpp</build_depend>
      14 <build_depend>rospy</build_depend>
      15 <build_depend>std_msgs</build_depend>
    

Toutes les dépendances que l'on avait déclarées à la création de notre package ont été ajoutées pour nous en tant que build_depend, en plus de la déclaration par défaut de buildtool_depend pour catkin (c'est le compilateur on est donc bien obligé de l'avoir. Pour les versions antérieures à la groovy le compilateur se nomme rosmake). Dans ce cas, nous voulons que toutes les dépendances spécifiées soient accessibles au moment de la construction et au moment de l'exécution, nous allons ajouter un tag run_depend pour chacun d'eux ainsi (ndt : il s'avère que pour la groovy les dépendances d'exécution sont déjà présentes) :

  •    1 <buildtool_depend>catkin</buildtool_depend>
       2 <build_depend>roscpp</build_depend>
       3 <build_depend>rospy</build_depend>
       4 <build_depend>std_msgs</build_depend>
       5 <run_depend>roscpp</run_depend>
       6 <run_depend>rospy</run_depend>
       7 <run_depend>std_msgs</run_depend>
    

Le package.xml final

Comme vous pouvez le voir le package.xml final, sans commentaires et sans les tags inutilisés, est beaucoup plus concis:

  •    1 <?xml version="1.0"?>
       2 <package>
       3 <name>beginner_tutorials</name>
       4 <version>0.1.0</version>
       5 <description>The beginner_tutorials package</description>
       6 <maintainer email="you@yourdomain.tld">Your Name</maintainer>
       7 <license>BSD</license>
       8 <url type="website">http://wiki.ros.org/beginner_tutorials</url>
       9 <author email="you@yourdomain.tld">Jane Doe</author>
      10 <buildtool_depend>catkin</buildtool_depend>
      11 <build_depend>roscpp</build_depend>
      12 <build_depend>rospy</build_depend>
      13 <build_depend>std_msgs</build_depend>
      14 <run_depend>roscpp</run_depend>
      15 <run_depend>rospy</run_depend>
      16 <run_depend>std_msgs</run_depend>
      17 </package>
    

Personnalisation du CMakeLists.txt

Maintenant que le package.xml , qui contient des informations meta, a été adapté à votre package, vous êtes prêt à passer à la suite des tutoriels. Le fichier CMakeLists.txt créé par catkin_create_pkg sera abordé plus tard dans les didacticiels où vous écrirez du code ROS.

Maintenant que vous avez fait un nouveau package ROS, allons construire notre package ROS.

Wiki: fr/ROS/Tutorials/CreatingPackage (last edited 2019-11-03 21:55:33 by fangorn_fr)