rosdep sources list
===================

The :command:`rosdep` command-line tool is similar to other tools like
:command:`apt` that use a *sources list* to update a local index.

rosdep 2 loads *valid data sources* specified in the sources list in
order.  This follows the behavior of apt, which designates the "most
preferred source listed first."

Each rosdep entry from the data sources is combined into a single
rosdep database.  Entries from data sources listed higher in the
sources have higher precedence.  The first entry for a rosdep key
"wins".  Subsequent entries for the same key, even if they are
non-conflicting, are not merged.

A data source is considered *valid* if all of its tags match the local
tags.  A data source with no tags is always loaded.

Updating the local index
------------------------

A new local index can be generated by running ``rosdep update``.


Sources list file format
------------------------

*Sources list* files are loaded from
``/etc/ros/rosdep/sources.list.d``.  ``sudo rosdep init`` will create
a default configuration for you.

rosdep processes the files in this directory, sorted by filename in
ascending order.  Precedence is assigned to the files in the order
they are processed, with the first file having the highest
precendence.

A ``.list`` file lists *data sources*, with the most preferred data
source first.  The general format is::

    source-type url [tags...]

``source-type`` can be:

  ``yaml``

     ``rosdep.yaml`` file   

  ``gbpdistro``

    ``gbpdistro`` file.

``type``

    Type must be ``yaml`` or ``gbpdistro``.  In the future, more types may be supported.
           
``url``

    URL should point to the HTTP location of a rosdep YAML file. URL
    must contain an scheme (e.g. ``http://``), hostname, and path.

``tags``

    Tags are optional.  Currently, the OS name (e.g. ``ubuntu``), OS
    codename (e.g. ``lucid``), and ROS distribution codename
    (e.g. ``fuerte``) are supported.  These tags are all lower-case.

Lines that start with a ``#`` are considered to be comments.

Example file::

    yaml https://github.com/ros/rosdistro/raw/master/rosdep/base.yaml
    yaml https://github.com/ros/rosdistro/raw/master/rosdep/python.yaml
    gbpdistro https://github.com/ros/rosdistro/raw/master/releases/fuerte.yaml fuerte


Tags
----

The tags constrain the configurations that the source will be loaded
on. *All* tags must match the current configuration for the source to
be considered valid.  In the example above, the source will only be
valid for the ROS Fuerte distribution on an Ubuntu Lucid platform.


gbpdistro files
---------------

``gbpdistro`` refers to a ``git-buildpackage``-based toolchain
currently in use for building catkin-based ROS stacks.  End users are
not expected to write their own ``gbpdistro`` files and the
specification is unstable.