rosdep.yaml syntax: source PACKAGE_MANAGER, fields

According to REP 111 [2], the basic syntax for a rosdep.yaml rule is:

ROSDEP_NAME:
  OS_NAME1:
    PACKAGE_MANAGER1:
      PACKAGE_ARGUMENTS_A
  OS_NAME2:
    PACKAGE_MANAGER2:
      PACKAGE_ARGUMENTS_A

The source package manager defines the PACKAGE_MANAGER and PACKAGE_ARGUMENTS fields as follows:

• PACKAGE_MANAGER is source
• PACKAGE_ARGUMENTS: the source package manager accepts a dictionary with three possible keys:
  • uri (string): the primary download uri for the rosdep manifest (required).
  • alternate-uri (string): a mirror download uri for the rosdep manifest (optional).
  • md5sum (string): md5sum hash of the rdmanifest for security and verification. (optional, recommended)

As defined by REP 111, the use of the source package manager is specific to a OS platform.

The use of the md5sum field is strongly recommended. It provides protection against thirdparty library installs being compromised either due to corruption or malicious intent. It also enables the downloaded file to be verified for completeness.

rosdep.yaml example source rule:

The following example is a plausible rosdep.yaml rule for installing the yaml-cpp library on an Ubuntu system. This rule references an external rosdep manifest file, as well as an mirror of this installation for additional robustness.

yaml-cpp:
  ubuntu:
    source:
      uri: 'https://kforge.ros.org/rosrelease/viewvc/sourcedeps/yaml-cpp/yaml-cpp-0.2.5.rdmanifest'
      alternate-uri: 'https://mirror-kforge.ros.org/rosrelease/viewvc/sourcedeps/yaml-cpp/yaml-cpp-0.2.5.rdmanifest'
      md5sum: 740a2193cea112f5ef682d9f69f9c7b1

.rdmanifest syntax

The rosdep manifest (.rdmanifest) file has 6 fields:

• uri (string): The uri of the tarball to download.
• md5sum (string): The expected md5sum of the tarball (recommended)
• alternate-uri (string): An optional alternate-uri for reliability (recommended)
• check-presence-script (multi-line string): a script that exits with return code zero if a package is already present, non-zero otherwise. This script is downloaded to a temporary file and executed with the user's account.
• install-script (multi-line string): a script that installs software library from tarball. The script is downloaded to a temporary file and executed with the user's account. The working directory set to the exec-path, which is generally the directory where the unpacked tarball is located.
• exec-path (string): relative path used to specify working directory of the install-script (optional). The path is interpreted to be relative to the directory the tarball is downloaded and unpacked to. exec-path is optional and defaults to '.', i.e. the directory of the tarball.
• depends (string list): list of rosdep dependencies that must be installed before checking or installing this rosdep.

check-presence-script and install-script

The check-presence-script and install-script are text-based scripts that are downloaded and executed by rosdep. rosdep will assign these scripts an executable permission and they may be written in any executable text format supported by the target platform.

For example, on POSIX-based systems, scripts can use a shebang to specify the desired interpreter of the script, such as #!/bin/sh or #!/usr/bin/env python.

The scripts are executed using the user's account. In the event that a script requires superuser access, it must explicitly invokes commands like sudo on its own. It is strongly recommended that the check-presence-script not use any superuser privileges as this interferes with automated verification of dependencies. This recommendation is only for the check-presence-script as it is expected that an install-script will need to use superuser permissions for final install steps, e.g. make install.

Source package manager implementation

In the event that rosdep determines that the source package manager is responsible for a rosdep dependency, the following steps are taken by the source package manager to verify a system dependency is installed.

1. Download the .rdmanifset file referenced by the uri rule. If the primary uri is unavailable, attempt to download the alternate-uri.
2. If md5sum is specified, validate the md5sum of the .rdmanifest file.
3. Verify that all rosdep dependencies specified in depends in the .rdmanifest are installed.
4. Download the check-presence-script specified in the .rdmanifest file.
5. Execute the check-presence-script with the current user's account.

If the script returns zero, the installation is assumed to be present. Otherwise, rosdep may determine that it is necessary to perform an installation of this dependency. If the source package manager is asked to install a dependency, the following steps are followed:

1. Download the tarball specified in the uri rule. If the primary uri is unavailable, attempt to download the alternate-uri.
2. If md5sum is specified, validate the md5sum of the tarball.
3. Unpack the tarball.
4. Download the install-script specified in the .rdmanifest file. The working directory of the install-script specified by exec-path, which defaults to the directory the tarball is unpacked to.
5. Execute the install-script with the current user's account.

.rdmanifest example

The following example demonstrates a plausible rosdep manifest file for the yaml-cpp library. This particular rosdep manifest file leverages the dpkg tool and thus will only work on Debian-based systems. A more generic rosdep manifest file could be written to work on a greater variety of platforms, or different rosdep manifest files could be written to support other platforms.

uri: 'https://kforge.ros.org/rosrelease/viewvc/sourcedeps/yaml-cpp/yaml-cpp-0.2.5.tar.gz'
md5sum: b17dc36055cd2259c88b2602601415d9
install-script: |
  #!/bin/bash
  set -o errexit
  mkdir -p build
  cd build
  cmake ..
  make
  echo "About to run checkinstall make install"
  sudo checkinstall -y --nodoc --pkgname=yaml-cpp-sourcedep make install
check-presence-script: |
  #!/bin/bash
  dpkg-query -W -f='${Package} ${Status}\n' yaml-cpp-sourcedep | awk '{\
  if ($4 =="installed")
    exit 0
  else
    print "yaml-cpp-sourcedep not installed"
    exit 1}'
exec-path: yaml-cpp-0.2.5
depends: [checkinstall ]