Skip to content

Latest commit

 

History

History
152 lines (119 loc) · 5.79 KB

rep-0144.rst

File metadata and controls

152 lines (119 loc) · 5.79 KB
Raw

REP: 144 Title: ROS Package Naming Author: Vincent Rabaud <[email protected]> Status: Draft Type: Informational Content-Type: text/x-rst Created: 28-Jan-2015 Post-History:

Abstract

This REP gives advice on how a ROS package should be named. It formalizes and extends conventions that were formerly described in [1].

Motivation

As the number of ROS packages increases, it is hard to quickly find a package and guess its functionality based on its name. Over time, the lack of naming conventions created problems like use of unexplained acronyms or packages with the same functionality but different names.

For now, ROS package names translate directly to packages in supported Operating Systems: therefore, there is a flat global namerspace in which rules have to be followed.

This REP proposes rules to name a ROS package properly. Some of those rules are mandatory, others merely advised.

Package Naming

Mandatory Rules

By habit, a package name is often used as a namespace (in C++ or any other language). Thus, the naming rules have to be strict.

  • alphanumerics are a-z0-9 only
  • alphabetics are a-z only
  • it must only consist of alphanumerics and _ separators. Other symbols might not be supported by some OSes (e.g. unicode characters) or would make it hard to follow OSes conventions/
  • they must be at least two characters long and must start with an alphabetic character. This rule is simply to force the name of the package to be more human understandable.

Global Rules

  • package names should be specific enough to identify what the package does. For example, a motion planner should not be called planner. If it implements the wavefront propagation algorithm, it might be called wavefront_planner. There's obviously tension between making a name specific and keeping it from becoming overly verbose
  • using catchall names such as utils should be avoided as they do not scope what goes into the package or what should be outside the package
  • a package name should not contain ros as it is redundant. Exceptions include core packages and ROS bindings of an upstream library (e.g. moveit_ros)
  • one of ROS's goals is to develop a canonical set of tools for making robots do interesting things. The package name should describe what the package does, not where it came from. Then again, as stated in the rules below, if a package is specialized by an entity (lab, company, ...), prepend the name of the entity. But once the package is commonly used, owned and maintained, that name can be dropped as the package becomes the reference
  • to check whether a name is taken, consult [2]. If you'd like your repository included in that list, see the tutorial at [3]

Naming Rules

The following rules define the different parts of the package name. The overall idea is to prepend a name with words that distinguish it from similar functional implementation (e.g.: lab, robot) but in order of importance (e.g.: python_robot_lab). Similarly, words that specialize this functionality are appended (e.g. msgs, config ...).

The rules to add those words should be followed in order. For prefixes:

  • if a package is specialized for a software project, prepend its name
  • if a package is specialized for a hardware piece, prepend its name
  • if a package is specialized for a robot, prepend its name
  • if a package is specialized by an entity (lab, company, ...), prepend the name of the entity. Once the package is commonly used, owned and maintained, that name can be dropped

For suffixes:

  • if a package is a driver, append driver
  • if a package contains any of a ROS message/service/action, append msgs
  • if a package is a plugin for a library, append <library_name>_plugins, e.g. pr2_gazebo_plugins

Special Suffixes:

  • a meta package for a robot should be named <name_of_the_robot>_robot, e.g. pr2_robot
  • a package containing the URDF and meshes of a robot should be named <name_of_the_robot>_description, e.g pr2_description
  • if a package is meant for test only, append tests

Special Cases

  • a package containing only a set of launch files should end with launch
  • a package containing only a set of launch files whose goal is to start a robot should end with bringup
  • a package containing one or more tutorials only should end with tutorials. If it is a set of tutorials for another package, it should contain that other package name: e.g. navigation and navigation_tutorials
  • a package containing one or more demos only should end with demos
  • third party libraries that are patched / integrated into ROS should not be named like their rosdep key as it creates a conflict across Ubuntu versions. If it is not specialized, name it generically <name_of_library>_ros

Examples

The following is a list of examples following the above rules:

  • A set of launch files for a wavefront planner, made for the PR2 by Willow Garage would have the following names when specializing the package more and more:
    • planner_launch
    • wavefront_planner_launch
    • pr2_wavefront_planner_launch
    • willow_garage_pr2_wavefront_planner_launch
  • OpenCV 3 package, packaged for ROS: `opencv3_ros`
  • a set of launch files for navigation tests: `navigation_launch_tests`

References

[1]ROS Pattern Conventions (http://wiki.ros.org/ROS/Patterns/Conventions#Packages)
[2]Browsing ROS Packages (http://www.ros.org/browse)
[3]Indexing Your ROS Repository for Documentation Generation (http://wiki.ros.org/rosdistro/Tutorials/Indexing%20Your%20ROS%20Repository%20for%20Documentation%20Generation)

Copyright

This document has been placed in the public domain.