[Documentation] [TitleIndex] [WordIndex

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

Using roscreate

Before we create a package, let's see how the roscreate-pkg command-line tool works. This creates a new ROS package. All ROS packages consist of the many similar files : manifests, CMakeLists.txt, mainpage.dox, and Makefiles. roscreate-pkg eliminates many tedious tasks of creating a new package by hand, and eliminates common errors caused by hand-typing build files and manifests.

To create a new package in the current directory:

# roscreate-pkg [package_name]

You can also specify dependencies of that package:

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

Creating a New ROS Package

Now we're going to go into your home or project directory and create our beginner_tutorials package. We are going to make it depend on std_msgs, roscpp, and rospy, which are common ROS packages.

Now go into the ~/fuerte_workspace/sandbox directory:

$ cd ~/fuerte_workspace/sandbox

Alternatively, if you use Fuerte or later release, you can simply do:

$ roscd
$ cd sandbox

Then create your package:

$ roscreate-pkg beginner_tutorials std_msgs rospy roscpp

You will see something similar to:

  • 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

You're going to want to spend some time looking at beginner_tutorials/manifest.xml. manifests play an important role in ROS as they define how Packages are built, run, and documented.

Now lets make sure that ROS can find your new package. It is often useful to call rospack profile after making changes to your path so that new directories will be found:

$ rospack profile
$ rospack find beginner_tutorials 
  • YOUR_PACKAGE_PATH/beginner_tutorials

If this fails, it means ROS can't find your new package, which may be an issue with your ROS_PACKAGE_PATH. Please consult the installation instructions for setup from SVN or from binaries, depending how you installed ROS. If you've created or added a package that's outside of the existing package paths, you will need to amend your ROS_PACKAGE_PATH environment variable to include that new location. Try re-sourcing your setup.sh in your fuerte_workspace.

Try moving to the directory for the package.

$ roscd beginner_tutorials 
$ pwd
  • YOUR_PACKAGE_PATH/beginner_tutorials

First-order package dependencies

When using roscreate-pkg earlier, a few package dependencies were provided. These first-order dependencies can now be reviewed with the rospack tool.

(Jan 9, 2013) There is a bug reported and already fixed in rospack in groovy; it may take some time to be reflected in the packages. If you see an issue similar to this with the next command, you can skip to the following command.

$ rospack depends1 beginner_tutorials 
  • std_msgs
    rospy
    roscpp

As you can see, rospack lists the same dependencies that were used as arguments when running roscreate-pkg. These dependencies for a package are stored in the manifest file. Take a look at the manifest file.

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

Indirect package dependencies

In many cases, a dependency will also have its own dependencies. For instance, rospy has other dependencies.

(Jan 9, 2013) There is a bug reported and already fixed in rospack in groovy; it may take some time to be reflected in the packages. If you see an issue similar to this with the next command, you can skip to the following command.

$ rospack depends1 rospy
  • roslib
    roslang

A package can have quite a few indirect dependencies. Luckily rospack can recursively determine all nested dependencies.

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

Note: in Fuerte, the list is much shorter:

  • std_msgs
    roslang
    rospy
    roscpp

ROS Client Libraries

You may be wondering what rospy and roscpp dependencies are from the previous examples. rospy and roscpp are Client Libraries. The client libraries allow different programming languages to communicate through ROS. rospy is the client library for Python. roscpp is the client library for C++.

Review

Lets just list some of the commands we've used so far:

  • roscreate-pkg = ros+create-pkg : generates all the files needed to create a ROS package
  • rospack = ros+pack(age) : provides information related to ROS packages
  • rosstack = ros+stack : provides information related to ROS stacks

Qu'est ce qu'un paquet catkin?

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

  • Le package doit contenir un fichier package.xml conformes à catkin.
  • Le fichier package.xml fournit les meta-informations sur le package.
  • Le package doit contenir aussi un http://wiki.ros.org/catkin/package.xml#Metapackages doivent avoir un fichier de CMakeLists.txt partout.

Il ne peut y avoir plus d'un paquet 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 paquets dans un catkin Workspace

La méthode recommandée pour l'utilisation des paquets catkin utilise un espace de travail catkin (catkin workspace), mais vous pouvez aussi construire des paquets catkin seuls. Un espace de travail trivial 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 espace de travail 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 pour catkin, et ce que vous pouvez faire avec, une fois créé. D'abord on va se rendre dans le répertoire des fichiers sources de l'espace de travail catkin (catkin workspace) 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 rempli avec les informations que vous avez donné à catkin_create_pkg. catkin_create_pkg exige que vous lui donniez un package_name et éventuellement une liste des dépendances 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 paquets ont été fournis. 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 paquet 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 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 remplis:

  •    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 enapprendre 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és 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é lors de la création de notre package ont été ajoutés pour nous en tant que build_depend, en plus de la déclaration par défaut buildtool_depend pour catkin (c'est le compilateur on est donc bien obligé de l'avoir, mais pour les versions antérieur à la groovy le compilateur s'appelle 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 paquet ROS, nous allons construire notre package ROS .

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


2017-10-21 12:41