Skip to content

Latest commit

 

History

History
175 lines (137 loc) · 7.08 KB

rep-0144.rst

File metadata and controls

175 lines (137 loc) · 7.08 KB
Raw

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

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 namespace 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

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.

Definitions

  • alphanumerics are a-z0-9 only
  • alphabetics are a-z only

For clarity these are both specifically exclusively lowercase.

Mandatory Rules

A name must:

  • only consist of lowercase alphanumerics and _ separators and start with an alphabetic character. This allows it to be used in generated symbols and functions in all supported languages. Lowercase is required because the names are used in directories and filenames and some platforms do not have case sensitive filesystems.
  • not use multiple _ separators consecutively. This allows generated symbols to use the __ separator to guarenteed the avoidance of collisions with symbols from other packages, for example in the message generators.
  • be at least two characters long. This rule is simply to force the name of the package to be more human understandable. It's recommended to be noteably longer, see below.

Global Guidelines

  • 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. 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)
  • The package name should describe what the package does, but also avoid naming collisions. Priority should be given to describing what the package does, but in an effort to avoid name collisions, packages which are primarily (at least to start with) used in a single project or organization should have a prefix with the project or organization name. One of ROS's goals is to develop a canonical set of tools for making robots do interesting things, however, as stated in the rules below, if a package is specialized by an entity (...), prepend the name of the entity. The preference is for packages to start namespaced and then once the package is commonly used, owned and maintained, that name can be dropped as the package becomes the reference. Exceptions for special situations where multiple organizations are collaborating on a package, or core packages, or official driver packages for hardware, and other special cases can be made. When prefixed by an entity the unprefixed name should follow the other rules about specificity and meaningful naming. This is a guideline, not a steadfast rule.
  • Do not use a name that's already been taken. 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, individual, ...), prepend the name of the entity. Once the package is commonly used, owned and maintained, that name can be dropped, but it should ideally start namespaced

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 (https://index.ros.org/packages/)
[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.